diff --git a/[refs] b/[refs] index 125753287c01..55a831a472e4 100644 --- a/[refs] +++ b/[refs] @@ -1,2 +1,2 @@ --- -refs/heads/master: 2949ccf9379678df66ecf2ca70ed4656159eacdd +refs/heads/master: 06ef66081620e94fe35a518f98624b83a140096e diff --git a/trunk/CREDITS b/trunk/CREDITS index 3b7a1548aaf9..c9068febcffc 100644 --- a/trunk/CREDITS +++ b/trunk/CREDITS @@ -339,7 +339,7 @@ W: http://tomas.nocrew.org/ D: dsp56k device driver N: Ross Biro -E: ross.biro@gmail.com +E: bir7@leland.Stanford.Edu D: Original author of the Linux networking code N: Anton Blanchard @@ -882,12 +882,13 @@ S: Blacksburg, Virginia 24061 S: USA N: Randy Dunlap -E: rdunlap@xenotime.net +E: rddunlap@osdl.org W: http://www.xenotime.net/linux/linux.html W: http://www.linux-usb.org D: Linux-USB subsystem, USB core/UHCI/printer/storage drivers D: x86 SMP, ACPI, bootflag hacking -S: (ask for current address) +S: 12725 SW Millikan Way, Suite 400 +S: Beaverton, Oregon 97005 S: USA N: Bob Dunlop @@ -1880,13 +1881,6 @@ S: Schlehenweg 9 S: D-91080 Uttenreuth S: Germany -N: Jaya Kumar -E: jayalk@intworks.biz -W: http://www.intworks.biz -D: Arc monochrome LCD framebuffer driver, x86 reboot fixups -S: Gurgaon, India -S: Kuala Lumpur, Malaysia - N: Gabor Kuti M: seasons@falcon.sch.bme.hu M: seasons@makosteszta.sote.hu @@ -2380,10 +2374,9 @@ E: tmolina@cablespeed.com D: bug fixes, documentation, minor hackery N: James Morris -E: jmorris@redhat.com +E: jmorris@intercode.com.au W: http://www.intercode.com.au/jmorris/ -D: Netfilter, Linux Security Modules (LSM), SELinux, IPSec, -D: Crypto API, general networking, miscellaneous. +D: Netfilter, Linux Security Modules (LSM). S: PO Box 707 S: Spit Junction NSW 2088 S: Australia @@ -2483,9 +2476,13 @@ S: Potsdam, New York 13676 S: USA N: Dave Neuer -E: dave.neuer@pobox.com +E: dneuer@innovation-charter.com +E: mr_fred_smoothie@yahoo.com D: Helped implement support for Compaq's H31xx series iPAQs D: Other mostly minor tweaks & bugfixes +S: 325 E. Main St., Suite 3 +S: Carnegie, PA 15105 +S: USA N: Michael Neuffer E: mike@i-Connect.Net diff --git a/trunk/Documentation/00-INDEX b/trunk/Documentation/00-INDEX index f28a24e0279b..72dc90f8f4a7 100644 --- a/trunk/Documentation/00-INDEX +++ b/trunk/Documentation/00-INDEX @@ -12,6 +12,8 @@ Following translations are available on the WWW: 00-INDEX - this file. +BK-usage/ + - directory with info on BitKeeper. BUG-HUNTING - brute force method of doing binary search of patches to find bug. Changes @@ -138,8 +140,6 @@ java.txt - info on the in-kernel binary support for Java(tm). kbuild/ - directory with info about the kernel build process. -kdumpt.txt - - mini HowTo on getting the crash dump code to work. kernel-doc-nano-HOWTO.txt - mini HowTo on generation and location of kernel documentation files. kernel-docs.txt diff --git a/trunk/Documentation/BK-usage/00-INDEX b/trunk/Documentation/BK-usage/00-INDEX new file mode 100644 index 000000000000..82768784ea52 --- /dev/null +++ b/trunk/Documentation/BK-usage/00-INDEX @@ -0,0 +1,51 @@ +bk-kernel-howto.txt: Description of kernel workflow under BitKeeper + +bk-make-sum: Create summary of changesets in one repository and not +another, typically in preparation to be sent to an upstream maintainer. +Typical usage: + cd my-updated-repo + bk-make-sum ~/repo/original-repo + mv /tmp/linus.txt ../original-repo.txt + +bksend: Create readable text output containing summary of changes, GNU +patch of the changes, and BK metadata of changes (as needed for proper +importing into BitKeeper by an upstream maintainer). This output is +suitable for emailing BitKeeper changes. The recipient of this output +may pipe it directly to 'bk receive'. + +bz64wrap: helper script. Uncompressed input is piped to this script, +which compresses its input, and then outputs the uu-/base64-encoded +version of the compressed input. + +cpcset: Copy changeset between unrelated repositories. +Attempts to preserve changeset user, user address, description, in +addition to the changeset (the patch) itself. +Typical usage: + cd my-updated-repo + bk changes # looking for a changeset... + cpcset 1.1511 . ../another-repo + +csets-to-patches: Produces a delta of two BK repositories, in the form +of individual files, each containing a single cset as a GNU patch. +Output is several files, each with the filename "/tmp/rev-$REV.patch" +Typical usage: + cd my-updated-repo + bk changes -L ~/repo/original-repo 2>&1 | \ + perl csets-to-patches + +cset-to-linus: Produces a delta of two BK repositories, in the form of +changeset descriptions, with 'diffstat' output created for each +individual changset. +Typical usage: + cd my-updated-repo + bk changes -L ~/repo/original-repo 2>&1 | \ + perl cset-to-linus > summary.txt + +gcapatch: Generates patch containing changes in local repository. +Typical usage: + cd my-updated-repo + gcapatch > foo.patch + +unbz64wrap: Reverse an encoded, compressed data stream created by +bz64wrap into an uncompressed, typically text/plain output. + diff --git a/trunk/Documentation/BK-usage/bk-kernel-howto.txt b/trunk/Documentation/BK-usage/bk-kernel-howto.txt new file mode 100644 index 000000000000..b7b9075d2910 --- /dev/null +++ b/trunk/Documentation/BK-usage/bk-kernel-howto.txt @@ -0,0 +1,283 @@ + + Doing the BK Thing, Penguin-Style + + + + +This set of notes is intended mainly for kernel developers, occasional +or full-time, but sysadmins and power users may find parts of it useful +as well. It assumes at least a basic familiarity with CVS, both at a +user level (use on the cmd line) and at a higher level (client-server model). +Due to the author's background, an operation may be described in terms +of CVS, or in terms of how that operation differs from CVS. + +This is -not- intended to be BitKeeper documentation. Always run +"bk help " or in X "bk helptool " for reference +documentation. + + +BitKeeper Concepts +------------------ + +In the true nature of the Internet itself, BitKeeper is a distributed +system. When applied to revision control, this means doing away with +client-server, and changing to a parent-child model... essentially +peer-to-peer. On the developer's end, this also represents a +fundamental disruption in the standard workflow of changes, commits, +and merges. You will need to take a few minutes to think about +how to best work under BitKeeper, and re-optimize things a bit. +In some sense it is a bit radical, because it might described as +tossing changes out into a maelstrom and having them magically +land at the right destination... but I'm getting ahead of myself. + +Let's start with this progression: +Each BitKeeper source tree on disk is a repository unto itself. +Each repository has a parent (except the root/original, of course). +Each repository contains a set of a changesets ("csets"). +Each cset is one or more changed files, bundled together. + +Each tree is a repository, so all changes are checked into the local +tree. When a change is checked in, all modified files are grouped +into a logical unit, the changeset. Internally, BK links these +changesets in a tree, representing various converging and diverging +lines of development. These changesets are the bread and butter of +the BK system. + +After the concept of changesets, the next thing you need to get used +to is having multiple copies of source trees lying around. This -really- +takes some getting used to, for some people. Separate source trees +are the means in BitKeeper by which you delineate parallel lines +of development, both minor and major. What would be branches in +CVS become separate source trees, or "clones" in BitKeeper [heh, +or Star Wars] terminology. + +Clones and changesets are the tools from which most of the power of +BitKeeper is derived. As mentioned earlier, each clone has a parent, +the tree used as the source when the new clone was created. In a +CVS-like setup, the parent would be a remote server on the Internet, +and the child is your local clone of that tree. + +Once you have established a common baseline between two source trees -- +a common parent -- then you can merge changesets between those two +trees with ease. Merging changes into a tree is called a "pull", and +is analagous to 'cvs update'. A pull downloads all the changesets in +the remote tree you do not have, and merges them. Sending changes in +one tree to another tree is called a "push". Push sends all changes +in the local tree the remote does not yet have, and merges them. + +From these concepts come some initial command examples: + +1) bk clone -q http://linux.bkbits.net/linux-2.5 linus-2.5 +Download a 2.5 stock kernel tree, naming it "linus-2.5" in the local dir. +The "-q" disables listing every single file as it is downloaded. + +2) bk clone -ql linus-2.5 alpha-2.5 +Create a separate source tree for the Alpha AXP architecture. +The "-l" uses hard links instead of copying data, since both trees are +on the local disk. You can also replace the above with "bk lclone -q ..." + +You only clone a tree -once-. After cloning the tree lives a long time +on disk, being updating by pushes and pulls. + +3) cd alpha-2.5 ; bk pull http://gkernel.bkbits.net/alpha-2.5 +Download changes in "alpha-2.5" repository which are not present +in the local repository, and merge them into the source tree. + +4) bk -r co -q +Because every tree is a repository, files must be checked out before +they will be in their standard places in the source tree. + +5) bk vi fs/inode.c # example change... + bk citool # checkin, using X tool + bk push bk://gkernel@bkbits.net/alpha-2.5 # upload change +Typical example of a BK sequence that would replace the analagous CVS +situation, + vi fs/inode.c + cvs commit + +As this is just supposed to be a quick BK intro, for more in-depth +tutorials, live working demos, and docs, see http://www.bitkeeper.com/ + + + +BK and Kernel Development Workflow +---------------------------------- +Currently the latest 2.5 tree is available via "bk clone $URL" +and "bk pull $URL" at http://linux.bkbits.net/linux-2.5 +This should change in a few weeks to a kernel.org URL. + + +A big part of using BitKeeper is organizing the various trees you have +on your local disk, and organizing the flow of changes among those +trees, and remote trees. If one were to graph the relationships between +a desired BK setup, you are likely to see a few-many-few graph, like +this: + + linux-2.5 + | + merge-to-linus-2.5 + / | | + / | | + vm-hacks bugfixes filesys personal-hacks + \ | | / + \ | | / + \ | | / + testing-and-validation + +Since a "bk push" sends all changes not in the target tree, and +since a "bk pull" receives all changes not in the source tree, you want +to make sure you are only pushing specific changes to the desired tree, +not all changes from "peer parent" trees. For example, pushing a change +from the testing-and-validation tree would probably be a bad idea, +because it will push all changes from vm-hacks, bugfixes, filesys, and +personal-hacks trees into the target tree. + +One would typically work on only one "theme" at a time, either +vm-hacks or bugfixes or filesys, keeping those changes isolated in +their own tree during development, and only merge the isolated with +other changes when going upstream (to Linus or other maintainers) or +downstream (to your "union" trees, like testing-and-validation above). + +It should be noted that some of this separation is not just recommended +practice, it's actually [for now] -enforced- by BitKeeper. BitKeeper +requires that changesets maintain a certain order, which is the reason +that "bk push" sends all local changesets the remote doesn't have. This +separation may look like a lot of wasted disk space at first, but it +helps when two unrelated changes may "pollute" the same area of code, or +don't follow the same pace of development, or any other of the standard +reasons why one creates a development branch. + +Small development branches (clones) will appear and disappear: + + -------- A --------- B --------- C --------- D ------- + \ / + -----short-term devel branch----- + +While long-term branches will parallel a tree (or trees), with period +merge points. In this first example, we pull from a tree (pulls, +"\") periodically, such as what occurs when tracking changes in a +vendor tree, never pushing changes back up the line: + + -------- A --------- B --------- C --------- D ------- + \ \ \ + ----long-term devel branch----------------- + +And then a more common case in Linux kernel development, a long term +branch with periodic merges back into the tree (pushes, "/"): + + -------- A --------- B --------- C --------- D ------- + \ \ / \ + ----long-term devel branch----------------- + + + + + +Submitting Changes to Linus +--------------------------- +There's a bit of an art, or style, of submitting changes to Linus. +Since Linus's tree is now (you might say) fully integrated into the +distributed BitKeeper system, there are several prerequisites to +properly submitting a BitKeeper change. All these prereq's are just +general cleanliness of BK usage, so as people become experts at BK, feel +free to optimize this process further (assuming Linus agrees, of +course). + + + +0) Make sure your tree was originally cloned from the linux-2.5 tree +created by Linus. If your tree does not have this as its ancestor, it +is impossible to reliably exchange changesets. + + + +1) Pay attention to your commit text. The commit message that +accompanies each changeset you submit will live on forever in history, +and is used by Linus to accurately summarize the changes in each +pre-patch. Remember that there is no context, so + "fix for new scheduler changes" +would be too vague, but + "fix mips64 arch for new scheduler switch_to(), TIF_xxx semantics" +would be much better. + +You can and should use the command "bk comment -C" to update the +commit text, and improve it after the fact. This is very useful for +development: poor, quick descriptions during development, which get +cleaned up using "bk comment" before issuing the "bk push" to submit the +changes. + + + +2) Include an Internet-available URL for Linus to pull from, such as + + Pull from: http://gkernel.bkbits.net/net-drivers-2.5 + + + +3) Include a summary and "diffstat -p1" of each changeset that will be +downloaded, when Linus issues a "bk pull". The author auto-generates +these summaries using "bk changes -L ", to obtain a listing +of all the pending-to-send changesets, and their commit messages. + +It is important to show Linus what he will be downloading when he issues +a "bk pull", to reduce the time required to sift the changes once they +are downloaded to Linus's local machine. + +IMPORTANT NOTE: One of the features of BK is that your repository does +not have to be up to date, in order for Linus to receive your changes. +It is considered a courtesy to keep your repository fairly recent, to +lessen any potential merge work Linus may need to do. + + +4) Split up your changes. Each maintainer<->Linus situation is likely +to be slightly different here, so take this just as general advice. The +author splits up changes according to "themes" when merging with Linus. +Simultaneous pushes from local development go to special trees which +exist solely to house changes "queued" for Linus. Example of the trees: + + net-drivers-2.5 -- on-going net driver maintenance + vm-2.5 -- VM-related changes + fs-2.5 -- filesystem-related changes + +Linus then has much more freedom for pulling changes. He could (for +example) issue a "bk pull" on vm-2.5 and fs-2.5 trees, to merge their +changes, but hold off net-drivers-2.5 because of a change that needs +more discussion. + +Other maintainers may find that a single linus-pull-from tree is +adequate for passing BK changesets to him. + + + +Frequently Answered Questions +----------------------------- +1) How do I change the e-mail address shown in the changelog? +A. When you run "bk citool" or "bk commit", set environment + variables BK_USER and BK_HOST to the desired username + and host/domain name. + + +2) How do I use tags / get a diff between two kernel versions? +A. Pass the tags Linus uses to 'bk export'. + +ChangeSets are in a forward-progressing order, so it's pretty easy +to get a snapshot starting and ending at any two points in time. +Linus puts tags on each release and pre-release, so you could use +these two examples: + + bk export -tpatch -hdu -rv2.5.4,v2.5.5 | less + # creates patch-2.5.5 essentially + bk export -tpatch -du -rv2.5.5-pre1,v2.5.5 | less + # changes from pre1 to final + +A tag is just an alias for a specific changeset... and since changesets +are ordered, a tag is thus a marker for a specific point in time (or +specific state of the tree). + + +3) Is there an easy way to generate One Big Patch versus mainline, + for my long-lived kernel branch? +A. Yes. This requires BK 3.x, though. + + bk export -tpatch -r`bk repogca bk://linux.bkbits.net/linux-2.5`,+ + diff --git a/trunk/Documentation/BK-usage/bk-make-sum b/trunk/Documentation/BK-usage/bk-make-sum new file mode 100755 index 000000000000..58ca46a0fcc6 --- /dev/null +++ b/trunk/Documentation/BK-usage/bk-make-sum @@ -0,0 +1,34 @@ +#!/bin/sh -e +# DIR=$HOME/BK/axp-2.5 +# cd $DIR + +LINUS_REPO=$1 +DIRBASE=`basename $PWD` + +{ +cat </dev/null + +cat < (:D: :I:)\n$each(:C:){ (:C:)\n}\n}' - + +} > /tmp/linus.txt + +cat < 13/02/2002 +# +# Add diffstat output after Changelog 21/02/2002 + +PROG=bksend + +usage() { + echo "usage: $PROG -r" + echo -e "\twhere is of the form '1.23', '1.23..', '1.23..1.27'," + echo -e "\tor '+' to indicate the most recent revision" + + exit 1 +} + +case $1 in +-r) REV=$2; shift ;; +-r*) REV=`echo $1 | sed 's/^-r//'` ;; +*) echo "$PROG: no revision given, you probably don't want that";; +esac + +[ -z "$REV" ] && usage + +echo "You can import this changeset into BK by piping this whole message to:" +echo "'| bk receive [path to repository]' or apply the patch as usual." + +SEP="\n===================================================================\n\n" +echo -e $SEP +env PAGER=/bin/cat bk changes -r$REV +echo +bk export -tpatch -du -h -r$REV | diffstat +echo; echo +bk export -tpatch -du -h -r$REV +echo -e $SEP +bk send -wgzip_uu -r$REV - diff --git a/trunk/Documentation/BK-usage/bz64wrap b/trunk/Documentation/BK-usage/bz64wrap new file mode 100755 index 000000000000..be780876849f --- /dev/null +++ b/trunk/Documentation/BK-usage/bz64wrap @@ -0,0 +1,41 @@ +#!/bin/sh + +# bz64wrap - the sending side of a bzip2 | base64 stream +# Andreas Dilger Jan 2002 + + +PATH=$PATH:/usr/bin:/usr/local/bin:/usr/freeware/bin + +# A program to generate base64 encoding on stdout +BASE64_ENCODE="uuencode -m /dev/stdout" +BASE64_BEGIN= +BASE64_END= + +BZIP=NO +BASE64=NO + +# Test if we have the bzip program installed +bzip2 -c /dev/null > /dev/null 2>&1 && BZIP=YES + +# Test if uuencode can handle the -m (MIME) encoding option +$BASE64_ENCODE < /dev/null > /dev/null 2>&1 && BASE64=YES + +if [ $BASE64 = NO ]; then + BASE64_ENCODE=mimencode + BASE64_BEGIN="begin-base64 644 -" + BASE64_END="====" + + $BASE64_ENCODE < /dev/null > /dev/null 2>&1 && BASE64=YES +fi + +if [ $BZIP = NO -o $BASE64 = NO ]; then + echo "$0: can't use bz64 encoding: bzip2=$BZIP, $BASE64_ENCODE=$BASE64" + exit 1 +fi + +# Sadly, mimencode does not appear to have good "begin" and "end" markers +# like uuencode does, and it is picky about getting the right start/end of +# the base64 stream, so we handle this internally. +echo "$BASE64_BEGIN" +bzip2 -9 | $BASE64_ENCODE +echo "$BASE64_END" diff --git a/trunk/Documentation/BK-usage/cpcset b/trunk/Documentation/BK-usage/cpcset new file mode 100755 index 000000000000..b8faca97dab9 --- /dev/null +++ b/trunk/Documentation/BK-usage/cpcset @@ -0,0 +1,36 @@ +#!/bin/sh +# +# Purpose: Copy changeset patch and description from one +# repository to another, unrelated one. +# +# usage: cpcset [revision] [from-repository] [to-repository] +# + +REV=$1 +FROM=$2 +TO=$3 +TMPF=/tmp/cpcset.$$ + +rm -f $TMPF* + +CWD_SAVE=`pwd` +cd $FROM +bk changes -r$REV | \ + grep -v '^ChangeSet' | \ + sed -e 's/^ //g' > $TMPF.log + +USERHOST=`bk changes -r$REV | grep '^ChangeSet' | awk '{print $4}'` +export BK_USER=`echo $USERHOST | awk '-F@' '{print $1}'` +export BK_HOST=`echo $USERHOST | awk '-F@' '{print $2}'` + +bk export -tpatch -hdu -r$REV > $TMPF.patch && \ +cd $CWD_SAVE && \ +cd $TO && \ +bk import -tpatch -CFR -y"`cat $TMPF.log`" $TMPF.patch . && \ +bk commit -y"`cat $TMPF.log`" + +rm -f $TMPF* + +echo changeset $REV copied. +echo "" + diff --git a/trunk/Documentation/BK-usage/cset-to-linus b/trunk/Documentation/BK-usage/cset-to-linus new file mode 100755 index 000000000000..d28a96f8c618 --- /dev/null +++ b/trunk/Documentation/BK-usage/cset-to-linus @@ -0,0 +1,49 @@ +#!/usr/bin/perl -w + +use strict; + +my ($lhs, $rev, $tmp, $rhs, $s); +my @cset_text = (); +my @pipe_text = (); +my $have_cset = 0; + +while (<>) { + next if /^---/; + + if (($lhs, $tmp, $rhs) = (/^(ChangeSet\@)([^,]+)(, .*)$/)) { + &cset_rev if ($have_cset); + + $rev = $tmp; + $have_cset = 1; + + push(@cset_text, $_); + } + + elsif ($have_cset) { + push(@cset_text, $_); + } +} +&cset_rev if ($have_cset); +exit(0); + + +sub cset_rev { + my $empty_cset = 0; + + open PIPE, "bk export -tpatch -hdu -r $rev | diffstat -p1 2>/dev/null |" or die; + while ($s = ) { + $empty_cset = 1 if ($s =~ /0 files changed/); + push(@pipe_text, $s); + } + close(PIPE); + + if (! $empty_cset) { + print @cset_text; + print @pipe_text; + print "\n\n"; + } + + @pipe_text = (); + @cset_text = (); +} + diff --git a/trunk/Documentation/BK-usage/csets-to-patches b/trunk/Documentation/BK-usage/csets-to-patches new file mode 100755 index 000000000000..e2b81c35883f --- /dev/null +++ b/trunk/Documentation/BK-usage/csets-to-patches @@ -0,0 +1,44 @@ +#!/usr/bin/perl -w + +use strict; + +my ($lhs, $rev, $tmp, $rhs, $s); +my @cset_text = (); +my @pipe_text = (); +my $have_cset = 0; + +while (<>) { + next if /^---/; + + if (($lhs, $tmp, $rhs) = (/^(ChangeSet\@)([^,]+)(, .*)$/)) { + &cset_rev if ($have_cset); + + $rev = $tmp; + $have_cset = 1; + + push(@cset_text, $_); + } + + elsif ($have_cset) { + push(@cset_text, $_); + } +} +&cset_rev if ($have_cset); +exit(0); + + +sub cset_rev { + my $empty_cset = 0; + + system("bk export -tpatch -du -r $rev > /tmp/rev-$rev.patch"); + + if (! $empty_cset) { + print @cset_text; + print @pipe_text; + print "\n\n"; + } + + @pipe_text = (); + @cset_text = (); +} + diff --git a/trunk/Documentation/BK-usage/gcapatch b/trunk/Documentation/BK-usage/gcapatch new file mode 100755 index 000000000000..aaeb17dc7c7f --- /dev/null +++ b/trunk/Documentation/BK-usage/gcapatch @@ -0,0 +1,8 @@ +#!/bin/sh +# +# Purpose: Generate GNU diff of local changes versus canonical top-of-tree +# +# Usage: gcapatch > foo.patch +# + +bk export -tpatch -hdu -r`bk repogca bk://linux.bkbits.net/linux-2.5`,+ diff --git a/trunk/Documentation/BK-usage/unbz64wrap b/trunk/Documentation/BK-usage/unbz64wrap new file mode 100755 index 000000000000..4fc3e73e9a81 --- /dev/null +++ b/trunk/Documentation/BK-usage/unbz64wrap @@ -0,0 +1,25 @@ +#!/bin/sh + +# unbz64wrap - the receiving side of a bzip2 | base64 stream +# Andreas Dilger Jan 2002 + +# Sadly, mimencode does not appear to have good "begin" and "end" markers +# like uuencode does, and it is picky about getting the right start/end of +# the base64 stream, so we handle this explicitly here. + +PATH=$PATH:/usr/bin:/usr/local/bin:/usr/freeware/bin + +if mimencode -u < /dev/null > /dev/null 2>&1 ; then + SHOW= + while read LINE; do + case $LINE in + begin-base64*) SHOW=YES ;; + ====) SHOW= ;; + *) [ "$SHOW" ] && echo "$LINE" ;; + esac + done | mimencode -u | bunzip2 + exit $? +else + cat - | uudecode -o /dev/stdout | bunzip2 + exit $? +fi diff --git a/trunk/Documentation/Changes b/trunk/Documentation/Changes index afebdbcd553a..caa6a5529b6b 100644 --- a/trunk/Documentation/Changes +++ b/trunk/Documentation/Changes @@ -44,9 +44,9 @@ running, the suggested command should tell you. Again, keep in mind that this list assumes you are already functionally running a Linux 2.4 kernel. Also, not all tools are -necessary on all systems; obviously, if you don't have any ISDN -hardware, for example, you probably needn't concern yourself with -isdn4k-utils. +necessary on all systems; obviously, if you don't have any PCMCIA (PC +Card) hardware, for example, you probably needn't concern yourself +with pcmcia-cs. o Gnu C 2.95.3 # gcc --version o Gnu make 3.79.1 # make --version @@ -57,14 +57,13 @@ o e2fsprogs 1.29 # tune2fs o jfsutils 1.1.3 # fsck.jfs -V o reiserfsprogs 3.6.3 # reiserfsck -V 2>&1|grep reiserfsprogs o xfsprogs 2.6.0 # xfs_db -V -o pcmciautils 001 o pcmcia-cs 3.1.21 # cardmgr -V o quota-tools 3.09 # quota -V o PPP 2.4.0 # pppd --version o isdn4k-utils 3.1pre1 # isdnctrl 2>&1|grep version o nfs-utils 1.0.5 # showmount --version o procps 3.2.0 # ps --version -o oprofile 0.9 # oprofiled --version +o oprofile 0.5.3 # oprofiled --version Kernel compilation ================== @@ -187,20 +186,13 @@ architecture independent and any version from 2.0.0 onward should work correctly with this version of the XFS kernel code (2.6.0 or later is recommended, due to some significant improvements). -PCMCIAutils ------------ - -PCMCIAutils replaces pcmcia-cs (see below). It properly sets up -PCMCIA sockets at system startup and loads the appropriate modules -for 16-bit PCMCIA devices if the kernel is modularized and the hotplug -subsystem is used. Pcmcia-cs --------- PCMCIA (PC Card) support is now partially implemented in the main -kernel source. The "pcmciautils" package (see above) replaces pcmcia-cs -for newest kernels. +kernel source. Pay attention when you recompile your kernel ;-). +Also, be sure to upgrade to the latest pcmcia-cs release. Quota-tools ----------- @@ -357,26 +349,22 @@ Xfsprogs -------- o -Pcmciautils ------------ -o - Pcmcia-cs --------- -o +o Quota-tools ---------- o +Jade +---- +o + DocBook Stylesheets ------------------- o -XMLTO XSLT Frontend -------------------- -o - Intel P6 microcode ------------------ o diff --git a/trunk/Documentation/DocBook/Makefile b/trunk/Documentation/DocBook/Makefile index fa3e29ad8a46..a221039ee4c9 100644 --- a/trunk/Documentation/DocBook/Makefile +++ b/trunk/Documentation/DocBook/Makefile @@ -7,9 +7,10 @@ # list of DOCBOOKS. DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ - kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ - procfs-guide.xml writing_usb_driver.xml \ - sis900.xml kernel-api.xml journal-api.xml lsm.xml usb.xml \ + kernel-hacking.xml kernel-locking.xml via-audio.xml \ + deviceiobook.xml procfs-guide.xml tulip-user.xml \ + writing_usb_driver.xml scsidrivers.xml sis900.xml \ + kernel-api.xml journal-api.xml lsm.xml usb.xml \ gadget.xml libata.xml mtdnand.xml librs.xml ### @@ -41,16 +42,14 @@ MAN := $(patsubst %.xml, %.9, $(BOOKS)) mandocs: $(MAN) installmandocs: mandocs - mkdir -p /usr/local/man/man9/ - install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/ + $(MAKEMAN) install Documentation/DocBook/man ### #External programs used KERNELDOC = scripts/kernel-doc DOCPROC = scripts/basic/docproc - -XMLTOFLAGS = -m $(srctree)/Documentation/DocBook/stylesheet.xsl -#XMLTOFLAGS += --skip-validation +SPLITMAN = $(PERL) $(srctree)/scripts/split-man +MAKEMAN = $(PERL) $(srctree)/scripts/makeman ### # DOCPROC is used for two purposes: @@ -97,44 +96,45 @@ $(obj)/procfs-guide.xml: $(C-procfs-example2) # Rules to generate postscript, PDF and HTML # db2html creates a directory. Generate a html file used for timestamp -quiet_cmd_db2ps = XMLTO $@ - cmd_db2ps = xmlto ps $(XMLTOFLAGS) -o $(dir $@) $< +quiet_cmd_db2ps = DB2PS $@ + cmd_db2ps = db2ps -o $(dir $@) $< %.ps : %.xml - @(which xmlto > /dev/null 2>&1) || \ - (echo "*** You need to install xmlto ***"; \ + @(which db2ps > /dev/null 2>&1) || \ + (echo "*** You need to install DocBook stylesheets ***"; \ exit 1) $(call cmd,db2ps) -quiet_cmd_db2pdf = XMLTO $@ - cmd_db2pdf = xmlto pdf $(XMLTOFLAGS) -o $(dir $@) $< +quiet_cmd_db2pdf = DB2PDF $@ + cmd_db2pdf = db2pdf -o $(dir $@) $< %.pdf : %.xml - @(which xmlto > /dev/null 2>&1) || \ - (echo "*** You need to install xmlto ***"; \ + @(which db2pdf > /dev/null 2>&1) || \ + (echo "*** You need to install DocBook stylesheets ***"; \ exit 1) $(call cmd,db2pdf) -quiet_cmd_db2html = XMLTO $@ - cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \ - echo ' \ +quiet_cmd_db2html = DB2HTML $@ + cmd_db2html = db2html -o $(patsubst %.html,%,$@) $< && \ + echo ' \ Goto $(patsubst %.html,%,$(notdir $@))

' > $@ %.html: %.xml - @(which xmlto > /dev/null 2>&1) || \ - (echo "*** You need to install xmlto ***"; \ + @(which db2html > /dev/null 2>&1) || \ + (echo "*** You need to install DocBook stylesheets ***"; \ exit 1) @rm -rf $@ $(patsubst %.html,%,$@) $(call cmd,db2html) @if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \ cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi -quiet_cmd_db2man = XMLTO $@ - cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; gzip -f $(obj)/man/*.9; fi -%.9 : %.xml - @(which xmlto > /dev/null 2>&1) || \ - (echo "*** You need to install xmlto ***"; \ - exit 1) - $(call cmd,db2man) - @touch $@ +### +# Rule to generate man files - output is placed in the man subdirectory + +%.9: %.xml +ifneq ($(KBUILD_SRC),) + $(Q)mkdir -p $(objtree)/Documentation/DocBook/man +endif + $(SPLITMAN) $< $(objtree)/Documentation/DocBook/man "$(VERSION).$(PATCHLEVEL).$(SUBLEVEL)" + $(MAKEMAN) convert $(objtree)/Documentation/DocBook/man $< ### # Rules to generate postscripts and PNG imgages from .fig format files diff --git a/trunk/Documentation/DocBook/kernel-api.tmpl b/trunk/Documentation/DocBook/kernel-api.tmpl index d650ce36485f..1bd20c860285 100644 --- a/trunk/Documentation/DocBook/kernel-api.tmpl +++ b/trunk/Documentation/DocBook/kernel-api.tmpl @@ -49,33 +49,13 @@ !Iinclude/asm-i386/unaligned.h + -!Elib/kobject.c - - - Kernel utility functions -!Iinclude/linux/kernel.h - -!Ekernel/panic.c -!Ekernel/sys.c -!Ekernel/rcupdate.c +X!Ekernel/sched.c - +KAO --> @@ -101,9 +81,7 @@ X!Ekernel/printk.c !Elib/vsprintf.c String Manipulation - +!Ilib/string.c !Elib/string.c Bit Operations @@ -120,25 +98,6 @@ X!Ilib/string.c !Iinclude/asm-i386/uaccess.h !Iarch/i386/lib/usercopy.c - More Memory Management Functions -!Iinclude/linux/rmap.h -!Emm/readahead.c -!Emm/filemap.c -!Emm/memory.c -!Emm/vmalloc.c -!Emm/mempool.c -!Emm/page-writeback.c -!Emm/truncate.c - - - - - - Kernel IPC facilities - - IPC utilities -!Iipc/util.c - @@ -155,10 +114,6 @@ X!Ilib/string.c sysctl interface !Ekernel/sysctl.c - - proc filesystem interface -!Ifs/proc/base.c - @@ -172,10 +127,6 @@ X!Ilib/string.c The Linux VFS - The Filesystem types -!Iinclude/linux/fs.h -!Einclude/linux/fs.h - The Directory Cache !Efs/dcache.c !Iinclude/linux/dcache.h @@ -191,31 +142,13 @@ X!Ilib/string.c !Efs/locks.c !Ifs/locks.c - Other Functions -!Efs/mpage.c -!Efs/namei.c -!Efs/buffer.c -!Efs/bio.c -!Efs/seq_file.c -!Efs/filesystems.c -!Efs/fs-writeback.c -!Efs/block_dev.c - Linux Networking - Networking Base Types -!Iinclude/linux/net.h - Socket Buffer Functions !Iinclude/linux/skbuff.h -!Iinclude/net/sock.h -!Enet/socket.c !Enet/core/skbuff.c -!Enet/core/sock.c -!Enet/core/datagram.c -!Enet/core/stream.c Socket Filter !Enet/core/filter.c @@ -225,14 +158,6 @@ X!Ilib/string.c !Enet/core/gen_stats.c !Enet/core/gen_estimator.c - SUN RPC subsystem - -!Enet/sunrpc/xdr.c -!Enet/sunrpc/svcsock.c -!Enet/sunrpc/sched.c - @@ -266,11 +191,7 @@ X!Ekernel/module.c Hardware Interfaces Interrupt Handling -!Ikernel/irq/manage.c - - - Resources Management -!Ekernel/resource.c +!Iarch/i386/kernel/irq.c MTRR Handling @@ -278,17 +199,6 @@ X!Ekernel/module.c PCI Support Library !Edrivers/pci/pci.c -!Edrivers/pci/pci-driver.c -!Edrivers/pci/remove.c -!Edrivers/pci/pci-acpi.c - -!Edrivers/pci/msi.c -!Edrivers/pci/bus.c -!Edrivers/pci/hotplug.c -!Edrivers/pci/probe.c -!Edrivers/pci/rom.c PCI Hotplug Support Library !Edrivers/pci/hotplug/pci_hotplug_core.c @@ -313,14 +223,6 @@ X!Earch/i386/kernel/mca.c !Efs/devfs/base.c - - The Filesystem for Exporting Kernel Objects -!Efs/sysfs/file.c -!Efs/sysfs/dir.c -!Efs/sysfs/symlink.c -!Efs/sysfs/bin.c - - Security Framework !Esecurity/security.c @@ -331,60 +233,6 @@ X!Earch/i386/kernel/mca.c !Ekernel/power/pm.c - - Device drivers infrastructure - Device Drivers Base - -!Edrivers/base/driver.c -!Edrivers/base/core.c -!Edrivers/base/firmware_class.c -!Edrivers/base/transport_class.c -!Edrivers/base/dmapool.c - -!Edrivers/base/sys.c - -!Edrivers/base/platform.c -!Edrivers/base/bus.c - - Device Drivers Power Management -!Edrivers/base/power/main.c -!Edrivers/base/power/resume.c -!Edrivers/base/power/suspend.c - - Device Drivers ACPI Support - -!Edrivers/acpi/scan.c - - - Device drivers PnP support -!Edrivers/pnp/core.c - -!Edrivers/pnp/card.c -!Edrivers/pnp/driver.c -!Edrivers/pnp/manager.c -!Edrivers/pnp/support.c - - - - Block Devices !Edrivers/block/ll_rw_blk.c @@ -402,23 +250,7 @@ X!Edrivers/pnp/system.c Sound Devices -!Iinclude/sound/core.h !Esound/sound_core.c -!Iinclude/sound/pcm.h -!Esound/core/pcm.c -!Esound/core/device.c -!Esound/core/info.c -!Esound/core/rawmidi.c -!Esound/core/sound.c -!Esound/core/memory.c -!Esound/core/pcm_memory.c -!Esound/core/init.c -!Esound/core/isadma.c -!Esound/core/control.c -!Esound/core/pcm_lib.c -!Esound/core/hwdep.c -!Esound/core/pcm_native.c -!Esound/core/memalloc.c @@ -426,7 +258,6 @@ X!Isound/sound_firmware.c 16x50 UART Driver -!Iinclude/linux/serial_core.h !Edrivers/serial/serial_core.c !Edrivers/serial/8250.c @@ -479,11 +310,9 @@ X!Isound/sound_firmware.c Frame Buffer Memory !Edrivers/video/fbmem.c - Frame Buffer Colormap !Edrivers/video/fbcmap.c diff --git a/trunk/Documentation/DocBook/libata.tmpl b/trunk/Documentation/DocBook/libata.tmpl index 375ae760dc1e..cf2fce7707da 100644 --- a/trunk/Documentation/DocBook/libata.tmpl +++ b/trunk/Documentation/DocBook/libata.tmpl @@ -14,7 +14,7 @@ - 2003-2005 + 2003 Jeff Garzik @@ -44,38 +44,30 @@ - - Introduction + + Thanks - libATA is a library used inside the Linux kernel to support ATA host - controllers and devices. libATA provides an ATA driver API, class - transports for ATA and ATAPI devices, and SCSI<->ATA translation - for ATA devices according to the T10 SAT specification. + The bulk of the ATA knowledge comes thanks to long conversations with + Andre Hedrick (www.linux-ide.org). - This Guide documents the libATA driver API, library functions, library - internals, and a couple sample ATA low-level drivers. + Thanks to Alan Cox for pointing out similarities + between SATA and SCSI, and in general for motivation to hack on + libata. + + + libata's device detection + method, ata_pio_devchk, and in general all the early probing was + based on extensive study of Hale Landis's probe/reset code in his + ATADRVR driver (www.ata-atapi.com). libata Driver API - - struct ata_port_operations is defined for every low-level libata - hardware driver, and it controls how the low-level driver - interfaces with the ATA and SCSI layers. - - - FIS-based drivers will hook into the system with ->qc_prep() and - ->qc_issue() high-level hooks. Hardware which behaves in a manner - similar to PCI IDE hardware may utilize several generic helpers, - defining at a bare minimum the bus I/O addresses of the ATA shadow - register blocks. - struct ata_port_operations - Disable ATA port void (*port_disable) (struct ata_port *); @@ -84,19 +76,8 @@ void (*port_disable) (struct ata_port *); Called from ata_bus_probe() and ata_bus_reset() error paths, as well as when unregistering from the SCSI module (rmmod, hot unplug). - This function should do whatever needs to be done to take the - port out of use. In most cases, ata_port_disable() can be used - as this hook. - - - Called from ata_bus_probe() on a failed probe. - Called from ata_bus_reset() on a failed bus reset. - Called from ata_scsi_release(). - - - Post-IDENTIFY device configuration void (*dev_config) (struct ata_port *, struct ata_device *); @@ -106,17 +87,7 @@ void (*dev_config) (struct ata_port *, struct ata_device *); found. Typically used to apply device-specific fixups prior to issue of SET FEATURES - XFER MODE, and prior to operation. - - Called by ata_device_add() after ata_dev_identify() determines - a device is present. - - - This entry may be specified as NULL in ata_port_operations. - - - - Set PIO/DMA mode void (*set_piomode) (struct ata_port *, struct ata_device *); void (*set_dmamode) (struct ata_port *, struct ata_device *); @@ -137,9 +108,6 @@ void (*post_set_mode) (struct ata_port *ap); ->set_dma_mode() is only called if DMA is possible. - - - Taskfile read/write void (*tf_load) (struct ata_port *ap, struct ata_taskfile *tf); void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf); @@ -150,13 +118,8 @@ void (*tf_read) (struct ata_port *ap, struct ata_taskfile *tf); registers / DMA buffers. ->tf_read() is called to read the hardware registers / DMA buffers, to obtain the current set of taskfile register values. - Most drivers for taskfile-based hardware (PIO or MMIO) use - ata_tf_load() and ata_tf_read() for these hooks. - - - ATA command execute void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf); @@ -164,53 +127,19 @@ void (*exec_command)(struct ata_port *ap, struct ata_taskfile *tf); causes an ATA command, previously loaded with ->tf_load(), to be initiated in hardware. - Most drivers for taskfile-based hardware use ata_exec_command() - for this hook. - - - Per-cmd ATAPI DMA capabilities filter - -int (*check_atapi_dma) (struct ata_queued_cmd *qc); - - - -Allow low-level driver to filter ATA PACKET commands, returning a status -indicating whether or not it is OK to use DMA for the supplied PACKET -command. - - - This hook may be specified as NULL, in which case libata will - assume that atapi dma can be supported. - - - - - Read specific ATA shadow registers u8 (*check_status)(struct ata_port *ap); -u8 (*check_altstatus)(struct ata_port *ap); -u8 (*check_err)(struct ata_port *ap); +void (*dev_select)(struct ata_port *ap, unsigned int device); - Reads the Status/AltStatus/Error ATA shadow register from - hardware. On some hardware, reading the Status register has - the side effect of clearing the interrupt condition. - Most drivers for taskfile-based hardware use - ata_check_status() for this hook. + Reads the Status ATA shadow register from hardware. On some + hardware, this has the side effect of clearing the interrupt + condition. - - Note that because this is called from ata_device_add(), at - least a dummy function that clears device interrupts must be - provided for all drivers, even if the controller doesn't - actually have a taskfile status register. - - - - Select ATA device on bus void (*dev_select)(struct ata_port *ap, unsigned int device); @@ -218,19 +147,9 @@ void (*dev_select)(struct ata_port *ap, unsigned int device); Issues the low-level hardware command(s) that causes one of N hardware devices to be considered 'selected' (active and - available for use) on the ATA bus. This generally has no - meaning on FIS-based devices. + available for use) on the ATA bus. - - Most drivers for taskfile-based hardware use - ata_std_dev_select() for this hook. Controllers which do not - support second drives on a port (such as SATA contollers) will - use ata_noop_dev_select(). - - - - Reset ATA bus void (*phy_reset) (struct ata_port *ap); @@ -241,54 +160,19 @@ void (*phy_reset) (struct ata_port *ap); for device presence (PATA and SATA), typically a soft reset (SRST) will be performed. Drivers typically use the helper functions ata_bus_reset() or sata_phy_reset() for this hook. - Many SATA drivers use sata_phy_reset() or call it from within - their own phy_reset() functions. - - - Control PCI IDE BMDMA engine void (*bmdma_setup) (struct ata_queued_cmd *qc); void (*bmdma_start) (struct ata_queued_cmd *qc); -void (*bmdma_stop) (struct ata_port *ap); -u8 (*bmdma_status) (struct ata_port *ap); -When setting up an IDE BMDMA transaction, these hooks arm -(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop) -the hardware's DMA engine. ->bmdma_status is used to read the standard -PCI IDE DMA Status register. + When setting up an IDE BMDMA transaction, these hooks arm + (->bmdma_setup) and fire (->bmdma_start) the hardware's DMA + engine. - -These hooks are typically either no-ops, or simply not implemented, in -FIS-based drivers. - - -Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup() -hook. ata_bmdma_setup() will write the pointer to the PRD table to -the IDE PRD Table Address register, enable DMA in the DMA Command -register, and call exec_command() to begin the transfer. - - -Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start() -hook. ata_bmdma_start() will write the ATA_DMA_START flag to the DMA -Command register. - - -Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop() -hook. ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA -command register. - - -Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status() hook. - - - - - High-level taskfile hooks void (*qc_prep) (struct ata_queued_cmd *qc); int (*qc_issue) (struct ata_queued_cmd *qc); @@ -306,30 +190,20 @@ int (*qc_issue) (struct ata_queued_cmd *qc); ->qc_issue is used to make a command active, once the hardware and S/G tables have been prepared. IDE BMDMA drivers use the helper function ata_qc_issue_prot() for taskfile protocol-based - dispatch. More advanced drivers implement their own ->qc_issue. + dispatch. More advanced drivers roll their own ->qc_issue + implementation, using this as the "issue new ATA command to + hardware" hook. - - ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and - ->bmdma_start() as necessary to initiate a transfer. - - - - Timeout (error) handling void (*eng_timeout) (struct ata_port *ap); -This is a high level error handling function, called from the -error handling thread, when a command times out. Most newer -hardware will implement its own error handling code here. IDE BMDMA -drivers may use the helper function ata_eng_timeout(). + This is a high level error handling function, called from the + error handling thread, when a command times out. - - - Hardware interrupt handling irqreturn_t (*irq_handler)(int, void *, struct pt_regs *); void (*irq_clear) (struct ata_port *); @@ -341,25 +215,7 @@ void (*irq_clear) (struct ata_port *); before the interrupt handler is registered, to be sure hardware is quiet. - - The second argument, dev_instance, should be cast to a pointer - to struct ata_host_set. - - - Most legacy IDE drivers use ata_interrupt() for the - irq_handler hook, which scans all ports in the host_set, - determines which queued command was active (if any), and calls - ata_host_intr(ap,qc). - - - Most legacy IDE drivers use ata_bmdma_irq_clear() for the - irq_clear() hook, which simply clears the interrupt and error - flags in the DMA status register. - - - - SATA phy read/write u32 (*scr_read) (struct ata_port *ap, unsigned int sc_reg); void (*scr_write) (struct ata_port *ap, unsigned int sc_reg, @@ -369,12 +225,8 @@ void (*scr_write) (struct ata_port *ap, unsigned int sc_reg, Read and write standard SATA phy registers. Currently only used if ->phy_reset hook called the sata_phy_reset() helper function. - sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE. - - - Init and shutdown int (*port_start) (struct ata_port *ap); void (*port_stop) (struct ata_port *ap); @@ -385,32 +237,18 @@ void (*host_stop) (struct ata_host_set *host_set); ->port_start() is called just after the data structures for each port are initialized. Typically this is used to alloc per-port DMA buffers / tables / rings, enable DMA engines, and similar - tasks. Some drivers also use this entry point as a chance to - allocate driver-private memory for ap->private_data. + tasks. - Many drivers use ata_port_start() as this hook or call - it from their own port_start() hooks. ata_port_start() - allocates space for a legacy IDE PRD table and returns. + ->host_stop() is called when the rmmod or hot unplug process + begins. The hook must stop all hardware interrupts, DMA + engines, etc. ->port_stop() is called after ->host_stop(). It's sole function is to release DMA/memory resources, now that they are no longer - actively being used. Many drivers also free driver-private - data from port at this time. - - - Many drivers use ata_port_stop() as this hook, which frees the - PRD table. + actively being used. - - ->host_stop() is called after all ->port_stop() calls -have completed. The hook must finalize hardware shutdown, release DMA -and other resources, etc. - This hook may be specified as NULL, in which case it is not called. - - - @@ -441,24 +279,4 @@ and other resources, etc. !Idrivers/scsi/sata_sil.c - - Thanks - - The bulk of the ATA knowledge comes thanks to long conversations with - Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA - and SCSI specifications. - - - Thanks to Alan Cox for pointing out similarities - between SATA and SCSI, and in general for motivation to hack on - libata. - - - libata's device detection - method, ata_pio_devchk, and in general all the early probing was - based on extensive study of Hale Landis's probe/reset code in his - ATADRVR driver (www.ata-atapi.com). - - - diff --git a/trunk/Documentation/DocBook/scsidrivers.tmpl b/trunk/Documentation/DocBook/scsidrivers.tmpl new file mode 100644 index 000000000000..d058e65daf19 --- /dev/null +++ b/trunk/Documentation/DocBook/scsidrivers.tmpl @@ -0,0 +1,193 @@ + + + + + + SCSI Subsystem Interfaces + + + + Douglas + Gilbert + +

+ dgilbert@interlog.com +
+ + + + 2003-08-11 + + + 2002 + 2003 + Douglas Gilbert + + + + + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later + version. + + + + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + + + + You should have received a copy of the GNU General Public + License along with this program; if not, write to the Free + Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, + MA 02111-1307 USA + + + + For more details see the file COPYING in the source + distribution of Linux. + + + + + + + + + Introduction + +This document outlines the interface between the Linux scsi mid level +and lower level drivers. Lower level drivers are variously called HBA +(host bus adapter) drivers, host drivers (HD) or pseudo adapter drivers. +The latter alludes to the fact that a lower level driver may be a +bridge to another IO subsystem (and the "ide-scsi" driver is an example +of this). There can be many lower level drivers active in a running +system, but only one per hardware type. For example, the aic7xxx driver +controls adaptec controllers based on the 7xxx chip series. Most lower +level drivers can control one or more scsi hosts (a.k.a. scsi initiators). + + +This document can been found in an ASCII text file in the linux kernel +source: Documentation/scsi/scsi_mid_low_api.txt . +It currently hold a little more information than this document. The +drivers/scsi/hosts.h and +drivers/scsi/scsi.h headers contain descriptions of members +of important structures for the scsi subsystem. + + + + + Driver structure + +Traditionally a lower level driver for the scsi subsystem has been +at least two files in the drivers/scsi directory. For example, a +driver called "xyz" has a header file "xyz.h" and a source file +"xyz.c". [Actually there is no good reason why this couldn't all +be in one file.] Some drivers that have been ported to several operating +systems (e.g. aic7xxx which has separate files for generic and +OS-specific code) have more than two files. Such drivers tend to have +their own directory under the drivers/scsi directory. + + +scsi_module.c is normally included at the end of a lower +level driver. For it to work a declaration like this is needed before +it is included: + + static Scsi_Host_Template driver_template = DRIVER_TEMPLATE; + /* DRIVER_TEMPLATE should contain pointers to supported interface + functions. Scsi_Host_Template is defined hosts.h */ + #include "scsi_module.c" + + + +The scsi_module.c assumes the name "driver_template" is appropriately +defined. It contains 2 functions: + + + init_this_scsi_driver() called during builtin and module driver + initialization: invokes mid level's scsi_register_host() + + + exit_this_scsi_driver() called during closedown: invokes + mid level's scsi_unregister_host() + + + + +When a new, lower level driver is being added to Linux, the following +files (all found in the drivers/scsi directory) will need some attention: +Makefile, Config.help and Config.in . It is probably best to look at what +an existing lower level driver does in this regard. + + + + + Interface Functions +!EDocumentation/scsi/scsi_mid_low_api.txt + + + + Locks + +Each Scsi_Host instance has a spin_lock called Scsi_Host::default_lock +which is initialized in scsi_register() [found in hosts.c]. Within the +same function the Scsi_Host::host_lock pointer is initialized to point +at default_lock with the scsi_assign_lock() function. Thereafter +lock and unlock operations performed by the mid level use the +Scsi_Host::host_lock pointer. + + +Lower level drivers can override the use of Scsi_Host::default_lock by +using scsi_assign_lock(). The earliest opportunity to do this would +be in the detect() function after it has invoked scsi_register(). It +could be replaced by a coarser grain lock (e.g. per driver) or a +lock of equal granularity (i.e. per host). Using finer grain locks +(e.g. per scsi device) may be possible by juggling locks in +queuecommand(). + + + + + Changes since lk 2.4 series + +io_request_lock has been replaced by several finer grained locks. The lock +relevant to lower level drivers is Scsi_Host::host_lock and there is one +per scsi host. + + +The older error handling mechanism has been removed. This means the +lower level interface functions abort() and reset() have been removed. + + +In the 2.4 series the scsi subsystem configuration descriptions were +aggregated with the configuration descriptions from all other Linux +subsystems in the Documentation/Configure.help file. In the 2.5 series, +the scsi subsystem now has its own (much smaller) drivers/scsi/Config.help +file. + + + + + Credits + +The following people have contributed to this document: + + +Mike Anderson andmike@us.ibm.com + + +James Bottomley James.Bottomley@steeleye.com + + +Patrick Mansfield patmans@us.ibm.com + + + + + + diff --git a/trunk/Documentation/DocBook/stylesheet.xsl b/trunk/Documentation/DocBook/stylesheet.xsl deleted file mode 100644 index 64be9f7ee3bb..000000000000 --- a/trunk/Documentation/DocBook/stylesheet.xsl +++ /dev/null @@ -1,6 +0,0 @@ - - -1 -ansi -80 - diff --git a/trunk/Documentation/DocBook/tulip-user.tmpl b/trunk/Documentation/DocBook/tulip-user.tmpl new file mode 100644 index 000000000000..6520d7a1b132 --- /dev/null +++ b/trunk/Documentation/DocBook/tulip-user.tmpl @@ -0,0 +1,327 @@ + + + + + + Tulip Driver User's Guide + + + + Jeff + Garzik + +
+ jgarzik@pobox.com +
+ + + + + + 2001 + Jeff Garzik + + + + + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later + version. + + + + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + + + + You should have received a copy of the GNU General Public + License along with this program; if not, write to the Free + Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, + MA 02111-1307 USA + + + + For more details see the file COPYING in the source + distribution of Linux. + + + + + + + + Introduction + +The Tulip Ethernet Card Driver +is maintained by Jeff Garzik (jgarzik@pobox.com). + + + +The Tulip driver was developed by Donald Becker and changed by +Jeff Garzik, Takashi Manabe and a cast of thousands. + + + +For 2.4.x and later kernels, the Linux Tulip driver is available at +http://sourceforge.net/projects/tulip/ + + + + This driver is for the Digital "Tulip" Ethernet adapter interface. + It should work with most DEC 21*4*-based chips/ethercards, as well as + with work-alike chips from Lite-On (PNIC) and Macronix (MXIC) and ASIX. + + + + The original author may be reached as becker@scyld.com, or C/O + Scyld Computing Corporation, + 410 Severn Ave., Suite 210, + Annapolis MD 21403 + + + + Additional information on Donald Becker's tulip.c + is available at http://www.scyld.com/network/tulip.html + + + + + + Driver Compatibility + + +This device driver is designed for the DECchip "Tulip", Digital's +single-chip ethernet controllers for PCI (now owned by Intel). +Supported members of the family +are the 21040, 21041, 21140, 21140A, 21142, and 21143. Similar work-alike +chips from Lite-On, Macronics, ASIX, Compex and other listed below are also +supported. + + + +These chips are used on at least 140 unique PCI board designs. The great +number of chips and board designs supported is the reason for the +driver size and complexity. Almost of the increasing complexity is in the +board configuration and media selection code. There is very little +increasing in the operational critical path length. + + + + + Board-specific Settings + + +PCI bus devices are configured by the system at boot time, so no jumpers +need to be set on the board. The system BIOS preferably should assign the +PCI INTA signal to an otherwise unused system IRQ line. + + + +Some boards have EEPROMs tables with default media entry. The factory default +is usually "autoselect". This should only be overridden when using +transceiver connections without link beat e.g. 10base2 or AUI, or (rarely!) +for forcing full-duplex when used with old link partners that do not do +autonegotiation. + + + + + Driver Operation + +Ring buffers + + +The Tulip can use either ring buffers or lists of Tx and Rx descriptors. +This driver uses statically allocated rings of Rx and Tx descriptors, set at +compile time by RX/TX_RING_SIZE. This version of the driver allocates skbuffs +for the Rx ring buffers at open() time and passes the skb->data field to the +Tulip as receive data buffers. When an incoming frame is less than +RX_COPYBREAK bytes long, a fresh skbuff is allocated and the frame is +copied to the new skbuff. When the incoming frame is larger, the skbuff is +passed directly up the protocol stack and replaced by a newly allocated +skbuff. + + + +The RX_COPYBREAK value is chosen to trade-off the memory wasted by +using a full-sized skbuff for small frames vs. the copying costs of larger +frames. For small frames the copying cost is negligible (esp. considering +that we are pre-loading the cache with immediately useful header +information). For large frames the copying cost is non-trivial, and the +larger copy might flush the cache of useful data. A subtle aspect of this +choice is that the Tulip only receives into longword aligned buffers, thus +the IP header at offset 14 isn't longword aligned for further processing. +Copied frames are put into the new skbuff at an offset of "+2", thus copying +has the beneficial effect of aligning the IP header and preloading the +cache. + + + + +Synchronization + +The driver runs as two independent, single-threaded flows of control. One +is the send-packet routine, which enforces single-threaded use by the +dev->tbusy flag. The other thread is the interrupt handler, which is single +threaded by the hardware and other software. + + + +The send packet thread has partial control over the Tx ring and 'dev->tbusy' +flag. It sets the tbusy flag whenever it's queuing a Tx packet. If the next +queue slot is empty, it clears the tbusy flag when finished otherwise it sets +the 'tp->tx_full' flag. + + + +The interrupt handler has exclusive control over the Rx ring and records stats +from the Tx ring. (The Tx-done interrupt can't be selectively turned off, so +we can't avoid the interrupt overhead by having the Tx routine reap the Tx +stats.) After reaping the stats, it marks the queue entry as empty by setting +the 'base' to zero. Iff the 'tp->tx_full' flag is set, it clears both the +tx_full and tbusy flags. + + + + + + + + Errata + + +The old DEC databooks were light on details. +The 21040 databook claims that CSR13, CSR14, and CSR15 should each be the last +register of the set CSR12-15 written. Hmmm, now how is that possible? + + + +The DEC SROM format is very badly designed not precisely defined, leading to +part of the media selection junkheap below. Some boards do not have EEPROM +media tables and need to be patched up. Worse, other boards use the DEC +design kit media table when it isn't correct for their board. + + + +We cannot use MII interrupts because there is no defined GPIO pin to attach +them. The MII transceiver status is polled using an kernel timer. + + + + + Driver Change History + + Version 0.9.14 (February 20, 2001) + + Fix PNIC problems (Manfred Spraul) + Add new PCI id for Accton comet + Support Davicom tulips + Fix oops in eeprom parsing + Enable workarounds for early PCI chipsets + IA64, hppa csr0 support + Support media types 5, 6 + Interpret a bit more of the 21142 SROM extended media type 3 + Add missing delay in eeprom reading + + + + Version 0.9.11 (November 3, 2000) + + Eliminate extra bus accesses when sharing interrupts (prumpf) + Barrier following ownership descriptor bit flip (prumpf) + Endianness fixes for >14 addresses in setup frames (prumpf) + Report link beat to kernel/userspace via netif_carrier_*. (kuznet) + Better spinlocking in set_rx_mode. + Fix I/O resource request failure error messages (DaveM catch) + Handle DMA allocation failure. + + + + Version 0.9.10 (September 6, 2000) + + Simple interrupt mitigation (via jamal) + More PCI ids + + + + Version 0.9.9 (August 11, 2000) + + More PCI ids + + + + Version 0.9.8 (July 13, 2000) + + Correct signed/unsigned comparison for dummy frame index + Remove outdated references to struct enet_statistics + + + + Version 0.9.7 (June 17, 2000) + + Timer cleanups (Andrew Morton) + Alpha compile fix (somebody?) + + + + Version 0.9.6 (May 31, 2000) + + Revert 21143-related support flag patch + Add HPPA/media-table debugging printk + + + + Version 0.9.5 (May 30, 2000) + + HPPA support (willy@puffingroup) + CSR6 bits and tulip.h cleanup (Chris Smith) + Improve debugging messages a bit + Add delay after CSR13 write in t21142_start_nway + Remove unused ETHER_STATS code + Convert 'extern inline' to 'static inline' in tulip.h (Chris Smith) + Update DS21143 support flags in tulip_chip_info[] + Use spin_lock_irq, not _irqsave/restore, in tulip_start_xmit() + Add locking to set_rx_mode() + Fix race with chip setting DescOwned bit (Hal Murray) + Request 100% of PIO and MMIO resource space assigned to card + Remove error message from pci_enable_device failure + + + + Version 0.9.4.3 (April 14, 2000) + + mod_timer fix (Hal Murray) + PNIC2 resuscitation (Chris Smith) + + + + Version 0.9.4.2 (March 21, 2000) + + Fix 21041 CSR7, CSR13/14/15 handling + Merge some PCI ids from tulip 0.91x + Merge some HAS_xxx flags and flag settings from tulip 0.91x + asm/io.h fix (submitted by many) and cleanup + s/HAS_NWAY143/HAS_NWAY/ + Cleanup 21041 mode reporting + Small code cleanups + + + + Version 0.9.4.1 (March 18, 2000) + + Finish PCI DMA conversion (davem) + Do not netif_start_queue() at end of tulip_tx_timeout() (kuznet) + PCI DMA fix (kuznet) + eeprom.c code cleanup + Remove Xircom Tulip crud + + + + + diff --git a/trunk/Documentation/DocBook/via-audio.tmpl b/trunk/Documentation/DocBook/via-audio.tmpl new file mode 100644 index 000000000000..36e642147d6b --- /dev/null +++ b/trunk/Documentation/DocBook/via-audio.tmpl @@ -0,0 +1,597 @@ + + + + + + Via 686 Audio Driver for Linux + + + + Jeff + Garzik + + + + + 1999-2001 + Jeff Garzik + + + + + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later + version. + + + + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + + + + You should have received a copy of the GNU General Public + License along with this program; if not, write to the Free + Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, + MA 02111-1307 USA + + + + For more details see the file COPYING in the source + distribution of Linux. + + + + + + + + Introduction + + The Via VT82C686A "super southbridge" chips contain + AC97-compatible audio logic which features dual 16-bit stereo + PCM sound channels (full duplex), plus a third PCM channel intended for use + in hardware-assisted FM synthesis. + + + The current Linux kernel audio driver for this family of chips + supports audio playback and recording, but hardware-assisted + FM features, and hardware buffer direct-access (mmap) + support are not yet available. + + + This driver supports any Linux kernel version after 2.4.10. + + + Please send bug reports to the mailing list linux-via@gtf.org. + To subscribe, e-mail majordomo@gtf.org with + + + subscribe linux-via + + + in the body of the message. + + + + + Driver Installation + + To use this audio driver, select the + CONFIG_SOUND_VIA82CXXX option in the section Sound during kernel configuration. + Follow the usual kernel procedures for rebuilding the kernel, + or building and installing driver modules. + + + To make this driver the default audio driver, you can add the + following to your /etc/conf.modules file: + + + alias sound via82cxxx_audio + + + Note that soundcore and ac97_codec support modules + are also required for working audio, in addition to + the via82cxxx_audio module itself. + + + + + Submitting a bug report + Description of problem + + Describe the application you were using to play/record sound, and how + to reproduce the problem. + + + Diagnostic output + + Obtain the via-audio-diag diagnostics program from + http://sf.net/projects/gkernel/ and provide a dump of the + audio chip's registers while the problem is occurring. Sample command line: + + + ./via-audio-diag -aps > diag-output.txt + + + Driver debug output + + Define VIA_DEBUG at the beginning of the driver, then capture and email + the kernel log output. This can be viewed in the system kernel log (if + enabled), or via the dmesg program. Sample command line: + + + dmesg > /tmp/dmesg-output.txt + + + Bigger kernel message buffer + + If you wish to increase the size of the buffer displayed by dmesg, then + change the LOG_BUF_LEN macro at the top of linux/kernel/printk.c, recompile + your kernel, and pass the LOG_BUF_LEN value to dmesg. Sample command line with + LOG_BUF_LEN == 32768: + + + dmesg -s 32768 > /tmp/dmesg-output.txt + + + + + + Known Bugs And Assumptions + + + Low volume + + + Volume too low on many systems. Workaround: use mixer program + such as xmixer to increase volume. + + + + + + + + + + Thanks + + Via for providing e-mail support, specs, and NDA'd source code. + + + MandrakeSoft for providing hacking time. + + + AC97 mixer interface fixes and debugging by Ron Cemer roncemer@gte.net. + + + Rui Sousa rui.sousa@conexant.com, for bugfixing + MMAP support, and several other notable fixes that resulted from + his hard work and testing. + + + Adrian Cox adrian@humboldt.co.uk, for bugfixing + MMAP support, and several other notable fixes that resulted from + his hard work and testing. + + + Thomas Sailer for further bugfixes. + + + + + Random Notes + + Two /proc pseudo-files provide diagnostic information. This is generally + not useful to most users. Power users can disable CONFIG_SOUND_VIA82CXXX_PROCFS, + and remove the /proc support code. Once + version 2.0.0 is released, the /proc support code will be disabled by + default. Available /proc pseudo-files: + + + /proc/driver/via/0/info + /proc/driver/via/0/ac97 + + + This driver by default supports all PCI audio devices which report + a vendor id of 0x1106, and a device id of 0x3058. Subsystem vendor + and device ids are not examined. + + + GNU indent formatting options: + +-kr -i8 -ts8 -br -ce -bap -sob -l80 -pcs -cs -ss -bs -di1 -nbc -lp -psl + + + + Via has graciously donated e-mail support and source code to help further + the development of this driver. Their assistance has been invaluable + in the design and coding of the next major version of this driver. + + + The Via audio chip apparently provides a second PCM scatter-gather + DMA channel just for FM data, but does not have a full hardware MIDI + processor. I haven't put much thought towards a solution here, but it + might involve using SoftOSS midi wave table, or simply disabling MIDI + support altogether and using the FM PCM channel as a second (input? output?) + + + + + Driver ChangeLog + + +Version 1.9.1 + + + + + DSP read/write bugfixes from Thomas Sailer. + + + + + + Add new PCI id for single-channel use of Via 8233. + + + + + + Other bug fixes, tweaks, new ioctls. + + + + + + + +Version 1.1.15 + + + + + Support for variable fragment size and variable fragment number (Rui + Sousa) + + + + + + Fixes for the SPEED, STEREO, CHANNELS, FMT ioctls when in read & + write mode (Rui Sousa) + + + + + + Mmaped sound is now fully functional. (Rui Sousa) + + + + + + Make sure to enable PCI device before reading any of its PCI + config information. (fixes potential hotplug problems) + + + + + + Clean up code a bit and add more internal function documentation. + + + + + + AC97 codec access fixes (Adrian Cox) + + + + + + Big endian fixes (Adrian Cox) + + + + + + MIDI support (Adrian Cox) + + + + + + Detect and report locked-rate AC97 codecs. If your hardware only + supports 48Khz (locked rate), then your recording/playback software + must upsample or downsample accordingly. The hardware cannot do it. + + + + + + Use new pci_request_regions and pci_disable_device functions in + kernel 2.4.6. + + + + + + + +Version 1.1.14 + + + + + Use VM_RESERVE when available, to eliminate unnecessary page faults. + + + + + + +Version 1.1.12 + + + + + mmap bug fixes from Linus. + + + + + + +Version 1.1.11 + + + + + Many more bug fixes. mmap enabled by default, but may still be buggy. + + + + + + Uses new and spiffy method of mmap'ing the DMA buffer, based + on a suggestion from Linus. + + + + + + +Version 1.1.10 + + + + + Many bug fixes. mmap enabled by default, but may still be buggy. + + + + + + +Version 1.1.9 + + + + + Redesign and rewrite audio playback implementation. (faster and smaller, hopefully) + + + + + + Implement recording and full duplex (DSP_CAP_DUPLEX) support. + + + + + + Make procfs support optional. + + + + + + Quick interrupt status check, to lessen overhead in interrupt + sharing situations. + + + + + + Add mmap(2) support. Disabled for now, it is still buggy and experimental. + + + + + + Surround all syscalls with a semaphore for cheap and easy SMP protection. + + + + + + Fix bug in channel shutdown (hardware channel reset) code. + + + + + + Remove unnecessary spinlocks (better performance). + + + + + + Eliminate "unknown AFMT" message by using a different method + of selecting the best AFMT_xxx sound sample format for use. + + + + + + Support for realtime hardware pointer position reporting + (DSP_CAP_REALTIME, SNDCTL_DSP_GETxPTR ioctls) + + + + + + Support for capture/playback triggering + (DSP_CAP_TRIGGER, SNDCTL_DSP_SETTRIGGER ioctls) + + + + + + SNDCTL_DSP_SETDUPLEX and SNDCTL_DSP_POST ioctls now handled. + + + + + + Rewrite open(2) and close(2) logic to allow only one user at + a time. All other open(2) attempts will sleep until they succeed. + FIXME: open(O_RDONLY) and open(O_WRONLY) should be allowed to succeed. + + + + + + Reviewed code to ensure that SMP and multiple audio devices + are fully supported. + + + + + + + +Version 1.1.8 + + + + + Clean up interrupt handler output. Fixes the following kernel error message: + + + unhandled interrupt ... + + + + + + Convert documentation to DocBook, so that PDF, HTML and PostScript (.ps) output is readily + available. + + + + + + + +Version 1.1.7 + + + + + Fix module unload bug where mixer device left registered + after driver exit + + + + + + +Version 1.1.6 + + + + + Rewrite via_set_rate to mimic ALSA basic AC97 rate setting + + + + + Remove much dead code + + + + + Complete spin_lock_irqsave -> spin_lock_irq conversion in via_dsp_ioctl + + + + + Fix build problem in via_dsp_ioctl + + + + + Optimize included headers to eliminate headers found in linux/sound + + + + + + +Version 1.1.5 + + + + + Disable some overly-verbose debugging code + + + + + Remove unnecessary sound locks + + + + + Fix some ioctls for better time resolution + + + + + Begin spin_lock_irqsave -> spin_lock_irq conversion in via_dsp_ioctl + + + + + + +Version 1.1.4 + + + + + Completed rewrite of driver. Eliminated SoundBlaster compatibility + completely, and now uses the much-faster scatter-gather DMA engine. + + + + + + + + + Internal Functions +!Isound/oss/via82cxxx_audio.c + + + + + diff --git a/trunk/Documentation/IPMI.txt b/trunk/Documentation/IPMI.txt index 84d3d4d10c17..90d10e708ca3 100644 --- a/trunk/Documentation/IPMI.txt +++ b/trunk/Documentation/IPMI.txt @@ -25,10 +25,9 @@ subject and I can't cover it all here! Configuration ------------- -The Linux IPMI driver is modular, which means you have to pick several +The LinuxIPMI driver is modular, which means you have to pick several things to have it work right depending on your hardware. Most of -these are available in the 'Character Devices' menu then the IPMI -menu. +these are available in the 'Character Devices' menu. No matter what, you must pick 'IPMI top-level message handler' to use IPMI. What you do beyond that depends on your needs and hardware. @@ -36,30 +35,33 @@ IPMI. What you do beyond that depends on your needs and hardware. The message handler does not provide any user-level interfaces. Kernel code (like the watchdog) can still use it. If you need access from userland, you need to select 'Device interface for IPMI' if you -want access through a device driver. - -The driver interface depends on your hardware. If your system -properly provides the SMBIOS info for IPMI, the driver will detect it -and just work. If you have a board with a standard interface (These -will generally be either "KCS", "SMIC", or "BT", consult your hardware -manual), choose the 'IPMI SI handler' option. A driver also exists -for direct I2C access to the IPMI management controller. Some boards -support this, but it is unknown if it will work on every board. For -this, choose 'IPMI SMBus handler', but be ready to try to do some -figuring to see if it will work on your system if the SMBIOS/APCI -information is wrong or not present. It is fairly safe to have both -these enabled and let the drivers auto-detect what is present. +want access through a device driver. Another interface is also +available, you may select 'IPMI sockets' in the 'Networking Support' +main menu. This provides a socket interface to IPMI. You may select +both of these at the same time, they will both work together. + +The driver interface depends on your hardware. If you have a board +with a standard interface (These will generally be either "KCS", +"SMIC", or "BT", consult your hardware manual), choose the 'IPMI SI +handler' option. A driver also exists for direct I2C access to the +IPMI management controller. Some boards support this, but it is +unknown if it will work on every board. For this, choose 'IPMI SMBus +handler', but be ready to try to do some figuring to see if it will +work. + +There is also a KCS-only driver interface supplied, but it is +depracated in favor of the SI interface. You should generally enable ACPI on your system, as systems with IPMI -can have ACPI tables describing them. +should have ACPI tables describing them. If you have a standard interface and the board manufacturer has done their job correctly, the IPMI controller should be automatically -detected (via ACPI or SMBIOS tables) and should just work. Sadly, -many boards do not have this information. The driver attempts -standard defaults, but they may not work. If you fall into this -situation, you need to read the section below named 'The SI Driver' or -"The SMBus Driver" on how to hand-configure your system. +detect (via ACPI or SMBIOS tables) and should just work. Sadly, many +boards do not have this information. The driver attempts standard +defaults, but they may not work. If you fall into this situation, you +need to read the section below named 'The SI Driver' on how to +hand-configure your system. IPMI defines a standard watchdog timer. You can enable this with the 'IPMI Watchdog Timer' config option. If you compile the driver into @@ -71,18 +73,6 @@ closed (by default it is disabled on close). Go into the 'Watchdog Cards' menu, enable 'Watchdog Timer Support', and enable the option 'Disable watchdog shutdown on close'. -IPMI systems can often be powered off using IPMI commands. Select -'IPMI Poweroff' to do this. The driver will auto-detect if the system -can be powered off by IPMI. It is safe to enable this even if your -system doesn't support this option. This works on ATCA systems, the -Radisys CPI1 card, and any IPMI system that supports standard chassis -management commands. - -If you want the driver to put an event into the event log on a panic, -enable the 'Generate a panic event to all BMCs on a panic' option. If -you want the whole panic string put into the event log using OEM -events, enable the 'Generate OEM events containing the panic string' -option. Basic Design ------------ @@ -90,7 +80,7 @@ Basic Design The Linux IPMI driver is designed to be very modular and flexible, you only need to take the pieces you need and you can use it in many different ways. Because of that, it's broken into many chunks of -code. These chunks (by module name) are: +code. These chunks are: ipmi_msghandler - This is the central piece of software for the IPMI system. It handles all messages, message timing, and responses. The @@ -103,26 +93,18 @@ ipmi_devintf - This provides a userland IOCTL interface for the IPMI driver, each open file for this device ties in to the message handler as an IPMI user. -ipmi_si - A driver for various system interfaces. This supports KCS, -SMIC, and BT interfaces. Unless you have an SMBus interface or your -own custom interface, you probably need to use this. +ipmi_si - A driver for various system interfaces. This supports +KCS, SMIC, and may support BT in the future. Unless you have your own +custom interface, you probably need to use this. ipmi_smb - A driver for accessing BMCs on the SMBus. It uses the I2C kernel driver's SMBus interfaces to send and receive IPMI messages over the SMBus. -ipmi_watchdog - IPMI requires systems to have a very capable watchdog -timer. This driver implements the standard Linux watchdog timer -interface on top of the IPMI message handler. - -ipmi_poweroff - Some systems support the ability to be turned off via -IPMI commands. +af_ipmi - A network socket interface to IPMI. This doesn't take up +a character device in your system. -These are all individually selectable via configuration options. - -Note that the KCS-only interface has been removed. The af_ipmi driver -is no longer supported and has been removed because it was impossible -to do 32 bit emulation on 64-bit kernels with it. +Note that the KCS-only interface ahs been removed. Much documentation for the interface is in the include files. The IPMI include files are: @@ -442,7 +424,7 @@ at module load time (for a module) with: modprobe ipmi_smb.o addr=,[,,[,...]] dbg=,... - [defaultprobe=1] [dbg_probe=1] + [defaultprobe=0] [dbg_probe=1] The addresses are specified in pairs, the first is the adapter ID and the second is the I2C address on that adapter. @@ -550,67 +532,3 @@ Once you open the watchdog timer, you must write a 'V' character to the device to close it, or the timer will not stop. This is a new semantic for the driver, but makes it consistent with the rest of the watchdog drivers in Linux. - - -Panic Timeouts --------------- - -The OpenIPMI driver supports the ability to put semi-custom and custom -events in the system event log if a panic occurs. if you enable the -'Generate a panic event to all BMCs on a panic' option, you will get -one event on a panic in a standard IPMI event format. If you enable -the 'Generate OEM events containing the panic string' option, you will -also get a bunch of OEM events holding the panic string. - - -The field settings of the events are: -* Generator ID: 0x21 (kernel) -* EvM Rev: 0x03 (this event is formatting in IPMI 1.0 format) -* Sensor Type: 0x20 (OS critical stop sensor) -* Sensor #: The first byte of the panic string (0 if no panic string) -* Event Dir | Event Type: 0x6f (Assertion, sensor-specific event info) -* Event Data 1: 0xa1 (Runtime stop in OEM bytes 2 and 3) -* Event data 2: second byte of panic string -* Event data 3: third byte of panic string -See the IPMI spec for the details of the event layout. This event is -always sent to the local management controller. It will handle routing -the message to the right place - -Other OEM events have the following format: -Record ID (bytes 0-1): Set by the SEL. -Record type (byte 2): 0xf0 (OEM non-timestamped) -byte 3: The slave address of the card saving the panic -byte 4: A sequence number (starting at zero) -The rest of the bytes (11 bytes) are the panic string. If the panic string -is longer than 11 bytes, multiple messages will be sent with increasing -sequence numbers. - -Because you cannot send OEM events using the standard interface, this -function will attempt to find an SEL and add the events there. It -will first query the capabilities of the local management controller. -If it has an SEL, then they will be stored in the SEL of the local -management controller. If not, and the local management controller is -an event generator, the event receiver from the local management -controller will be queried and the events sent to the SEL on that -device. Otherwise, the events go nowhere since there is nowhere to -send them. - - -Poweroff --------- - -If the poweroff capability is selected, the IPMI driver will install -a shutdown function into the standard poweroff function pointer. This -is in the ipmi_poweroff module. When the system requests a powerdown, -it will send the proper IPMI commands to do this. This is supported on -several platforms. - -There is a module parameter named "poweroff_control" that may either be zero -(do a power down) or 2 (do a power cycle, power the system off, then power -it on in a few seconds). Setting ipmi_poweroff.poweroff_control=x will do -the same thing on the kernel command line. The parameter is also available -via the proc filesystem in /proc/ipmi/poweroff_control. Note that if the -system does not support power cycling, it will always to the power off. - -Note that if you have ACPI enabled, the system will prefer using ACPI to -power off. diff --git a/trunk/Documentation/RCU/RTFP.txt b/trunk/Documentation/RCU/RTFP.txt index 9c6d450138ea..12250b342e1f 100644 --- a/trunk/Documentation/RCU/RTFP.txt +++ b/trunk/Documentation/RCU/RTFP.txt @@ -108,9 +108,8 @@ year saw a paper describing an RCU implementation of System V IPC 2004 has seen a Linux-Journal article on use of RCU in dcache [McKenney04a], a performance comparison of locking to RCU on several different CPUs [McKenney04b], a dissertation describing use of RCU in a -number of operating-system kernels [PaulEdwardMcKenneyPhD], a paper -describing how to make RCU safe for soft-realtime applications [Sarma04c], -and a paper describing SELinux performance with RCU [JamesMorris04b]. +number of operating-system kernels [PaulEdwardMcKenneyPhD], and a paper +describing how to make RCU safe for soft-realtime applications [Sarma04c]. Bibtex Entries @@ -342,17 +341,6 @@ Dipankar Sarma" ,pages="18-26" } -@techreport{Friedberg03a -,author="Stuart A. Friedberg" -,title="Lock-Free Wild Card Search Data Structure and Method" -,institution="US Patent and Trademark Office" -,address="Washington, DC" -,year="2003" -,number="US Patent 6,662,184 (contributed under GPL)" -,month="December" -,pages="112" -} - @article{McKenney04a ,author="Paul E. McKenney and Dipankar Sarma and Maneesh Soni" ,title="Scaling dcache with {RCU}" @@ -385,9 +373,6 @@ in Operating System Kernels" ,school="OGI School of Science and Engineering at Oregon Health and Sciences University" ,year="2004" -,note="Available: -\url{http://www.rdrop.com/users/paulmck/RCU/RCUdissertation.2004.07.14e1.pdf} -[Viewed October 15, 2004]" } @Conference{Sarma04c @@ -400,13 +385,3 @@ Oregon Health and Sciences University" ,month="June" ,pages="182-191" } - -@unpublished{JamesMorris04b -,Author="James Morris" -,Title="Recent Developments in {SELinux} Kernel Performance" -,month="December" -,year="2004" -,note="Available: -\url{http://www.livejournal.com/users/james_morris/2153.html} -[Viewed December 10, 2004]" -} diff --git a/trunk/Documentation/RCU/UP.txt b/trunk/Documentation/RCU/UP.txt index 3bfb84b3b7db..551a803d82a8 100644 --- a/trunk/Documentation/RCU/UP.txt +++ b/trunk/Documentation/RCU/UP.txt @@ -2,11 +2,11 @@ RCU on Uniprocessor Systems A common misconception is that, on UP systems, the call_rcu() primitive -may immediately invoke its function, and that the synchronize_rcu() +may immediately invoke its function, and that the synchronize_kernel primitive may return immediately. The basis of this misconception is that since there is only one CPU, it should not be necessary to wait for anything else to get done, since there are no other CPUs for -anything else to be happening on. Although this approach will -sort- -of- +anything else to be happening on. Although this approach will sort of work a surprising amount of the time, it is a very bad idea in general. This document presents two examples that demonstrate exactly how bad an idea this is. @@ -44,14 +44,14 @@ its arguments would cause it to fail to make the fundamental guarantee underlying RCU, namely that call_rcu() defers invoking its arguments until all RCU read-side critical sections currently executing have completed. -Quick Quiz: why is it -not- legal to invoke synchronize_rcu() in +Quick Quiz: why is it -not- legal to invoke synchronize_kernel() in this case? Summary Permitting call_rcu() to immediately invoke its arguments or permitting -synchronize_rcu() to immediately return breaks RCU, even on a UP system. +synchronize_kernel() to immediately return breaks RCU, even on a UP system. So do not do it! Even on a UP system, the RCU infrastructure -must- respect grace periods. diff --git a/trunk/Documentation/RCU/checklist.txt b/trunk/Documentation/RCU/checklist.txt index 8f3fb77c9cd3..b3a568abe6b1 100644 --- a/trunk/Documentation/RCU/checklist.txt +++ b/trunk/Documentation/RCU/checklist.txt @@ -32,10 +32,7 @@ over a rather long period of time, but improvements are always welcome! them -- even x86 allows reads to be reordered), and be prepared to explain why this added complexity is worthwhile. If you choose #c, be prepared to explain how this single task does not - become a major bottleneck on big multiprocessor machines (for - example, if the task is updating information relating to itself - that other tasks can read, there by definition can be no - bottleneck). + become a major bottleneck on big multiprocessor machines. 2. Do the RCU read-side critical sections make proper use of rcu_read_lock() and friends? These primitives are needed @@ -92,34 +89,27 @@ over a rather long period of time, but improvements are always welcome! "_rcu()" list-traversal primitives, such as the list_for_each_entry_rcu(). - b. If the list macros are being used, the list_add_tail_rcu() - and list_add_rcu() primitives must be used in order - to prevent weakly ordered machines from misordering - structure initialization and pointer planting. + b. If the list macros are being used, the list_del_rcu(), + list_add_tail_rcu(), and list_del_rcu() primitives must + be used in order to prevent weakly ordered machines from + misordering structure initialization and pointer planting. Similarly, if the hlist macros are being used, the - hlist_add_head_rcu() primitive is required. + hlist_del_rcu() and hlist_add_head_rcu() primitives + are required. - c. If the list macros are being used, the list_del_rcu() - primitive must be used to keep list_del()'s pointer - poisoning from inflicting toxic effects on concurrent - readers. Similarly, if the hlist macros are being used, - the hlist_del_rcu() primitive is required. - - The list_replace_rcu() primitive may be used to - replace an old structure with a new one in an - RCU-protected list. - - d. Updates must ensure that initialization of a given + c. Updates must ensure that initialization of a given structure happens before pointers to that structure are publicized. Use the rcu_assign_pointer() primitive when publicizing a pointer to a structure that can be traversed by an RCU read-side critical section. + [The rcu_assign_pointer() primitive is in process.] + 5. If call_rcu(), or a related primitive such as call_rcu_bh(), is used, the callback function must be written to be called from softirq context. In particular, it cannot block. -6. Since synchronize_rcu() can block, it cannot be called from +6. Since synchronize_kernel() blocks, it cannot be called from any sort of irq context. 7. If the updater uses call_rcu(), then the corresponding readers @@ -135,9 +125,9 @@ over a rather long period of time, but improvements are always welcome! such cases is a must, of course! And the jury is still out on whether the increased speed is worth it. -8. Although synchronize_rcu() is a bit slower than is call_rcu(), +8. Although synchronize_kernel() is a bit slower than is call_rcu(), it usually results in simpler code. So, unless update performance - is important or the updaters cannot block, synchronize_rcu() + is important or the updaters cannot block, synchronize_kernel() should be used in preference to call_rcu(). 9. All RCU list-traversal primitives, which include @@ -165,14 +155,3 @@ over a rather long period of time, but improvements are always welcome! you -must- use the "_rcu()" variants of the list macros. Failing to do so will break Alpha and confuse people reading your code. - -11. Note that synchronize_rcu() -only- guarantees to wait until - all currently executing rcu_read_lock()-protected RCU read-side - critical sections complete. It does -not- necessarily guarantee - that all currently running interrupts, NMIs, preempt_disable() - code, or idle loops will complete. Therefore, if you do not have - rcu_read_lock()-protected read-side critical sections, do -not- - use synchronize_rcu(). - - If you want to wait for some of these other things, you might - instead need to use synchronize_irq() or synchronize_sched(). diff --git a/trunk/Documentation/RCU/listRCU.txt b/trunk/Documentation/RCU/listRCU.txt index f8a54fa0d8ab..bda6ead69bd0 100644 --- a/trunk/Documentation/RCU/listRCU.txt +++ b/trunk/Documentation/RCU/listRCU.txt @@ -32,7 +32,6 @@ implementation of audit_filter_task() might be as follows: enum audit_state state; read_lock(&auditsc_lock); - /* Note: audit_netlink_sem held by caller. */ list_for_each_entry(e, &audit_tsklist, list) { if (audit_filter_rules(tsk, &e->rule, NULL, &state)) { read_unlock(&auditsc_lock); @@ -56,7 +55,6 @@ This means that RCU can be easily applied to the read side, as follows: enum audit_state state; rcu_read_lock(); - /* Note: audit_netlink_sem held by caller. */ list_for_each_entry_rcu(e, &audit_tsklist, list) { if (audit_filter_rules(tsk, &e->rule, NULL, &state)) { rcu_read_unlock(); @@ -141,15 +139,12 @@ Normally, the write_lock() and write_unlock() would be replaced by a spin_lock() and a spin_unlock(), but in this case, all callers hold audit_netlink_sem, so no additional locking is required. The auditsc_lock can therefore be eliminated, since use of RCU eliminates the need for -writers to exclude readers. Normally, the write_lock() calls would -be converted into spin_lock() calls. +writers to exclude readers. The list_del(), list_add(), and list_add_tail() primitives have been replaced by list_del_rcu(), list_add_rcu(), and list_add_tail_rcu(). The _rcu() list-manipulation primitives add memory barriers that are -needed on weakly ordered CPUs (most of them!). The list_del_rcu() -primitive omits the pointer poisoning debug-assist code that would -otherwise cause concurrent readers to fail spectacularly. +needed on weakly ordered CPUs (most of them!). So, when readers can tolerate stale data and when entries are either added or deleted, without in-place modification, it is very easy to use RCU! @@ -171,7 +166,6 @@ otherwise, the added fields would need to be filled in): struct audit_newentry *ne; write_lock(&auditsc_lock); - /* Note: audit_netlink_sem held by caller. */ list_for_each_entry(e, list, list) { if (!audit_compare_rule(rule, &e->rule)) { e->rule.action = newaction; @@ -205,7 +199,8 @@ RCU ("read-copy update") its name. The RCU code is as follows: audit_copy_rule(&ne->rule, &e->rule); ne->rule.action = newaction; ne->rule.file_count = newfield_count; - list_replace_rcu(e, ne); + list_add_rcu(ne, e); + list_del(e); call_rcu(&e->rcu, audit_free_rule, e); return 0; } diff --git a/trunk/Documentation/RCU/rcu.txt b/trunk/Documentation/RCU/rcu.txt index eb444006683e..7e0c2ab6f2bd 100644 --- a/trunk/Documentation/RCU/rcu.txt +++ b/trunk/Documentation/RCU/rcu.txt @@ -43,9 +43,7 @@ o If I am running on a uniprocessor kernel, which can only do one o How can I see where RCU is currently used in the Linux kernel? - Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu", - "rcu_read_lock_bh", "rcu_read_unlock_bh", "call_rcu_bh", - "synchronize_rcu", and "synchronize_net". + Search for "rcu_read_lock", "call_rcu", and "synchronize_kernel". o What guidelines should I follow when writing code that uses RCU? diff --git a/trunk/Documentation/SubmittingDrivers b/trunk/Documentation/SubmittingDrivers index c3cca924e94b..de3b252e717d 100644 --- a/trunk/Documentation/SubmittingDrivers +++ b/trunk/Documentation/SubmittingDrivers @@ -13,14 +13,13 @@ Allocating Device Numbers ------------------------- Major and minor numbers for block and character devices are allocated -by the Linux assigned name and number authority (currently this is -Torben Mathiasen). The site is http://www.lanana.org/. This +by the Linux assigned name and number authority (currently better +known as H Peter Anvin). The site is http://www.lanana.org/. This also deals with allocating numbers for devices that are not going to be submitted to the mainstream kernel. -See Documentation/devices.txt for more information on this. -If you don't use assigned numbers then when your device is submitted it will -be given an assigned number even if that is different from values you may +If you don't use assigned numbers then when you device is submitted it will +get given an assigned number even if that is different from values you may have shipped to customers before. Who To Submit Drivers To @@ -33,8 +32,7 @@ Linux 2.2: If the code area has a general maintainer then please submit it to the maintainer listed in MAINTAINERS in the kernel file. If the maintainer does not respond or you cannot find the appropriate - maintainer then please contact the 2.2 kernel maintainer: - Marc-Christian Petersen . + maintainer then please contact Alan Cox Linux 2.4: The same rules apply as 2.2. The final contact point for Linux 2.4 @@ -50,7 +48,7 @@ What Criteria Determine Acceptance Licensing: The code must be released to us under the GNU General Public License. We don't insist on any kind - of exclusive GPL licensing, and if you wish the driver + of exclusively GPL licensing, and if you wish the driver to be useful to other communities such as BSD you may well wish to release under multiple licenses. diff --git a/trunk/Documentation/SubmittingPatches b/trunk/Documentation/SubmittingPatches index 6761a7b241a5..9838d32b2fe7 100644 --- a/trunk/Documentation/SubmittingPatches +++ b/trunk/Documentation/SubmittingPatches @@ -35,7 +35,7 @@ not in any lower subdirectory. To create a patch for a single file, it is often sufficient to do: - SRCTREE= linux-2.6 + SRCTREE= linux-2.4 MYFILE= drivers/net/mydriver.c cd $SRCTREE @@ -48,18 +48,17 @@ To create a patch for multiple files, you should unpack a "vanilla", or unmodified kernel source tree, and generate a diff against your own source tree. For example: - MYSRC= /devel/linux-2.6 + MYSRC= /devel/linux-2.4 - tar xvfz linux-2.6.12.tar.gz - mv linux-2.6.12 linux-2.6.12-vanilla - diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ - linux-2.6.12-vanilla $MYSRC > /tmp/patch + tar xvfz linux-2.4.0-test11.tar.gz + mv linux linux-vanilla + wget http://www.moses.uklinux.net/patches/dontdiff + diff -uprN -X dontdiff linux-vanilla $MYSRC > /tmp/patch + rm -f dontdiff "dontdiff" is a list of files which are generated by the kernel during the build process, and should be ignored in any diff(1)-generated -patch. The "dontdiff" file is included in the kernel tree in -2.6.12 and later. For earlier kernel versions, you can get it -from . +patch. dontdiff is maintained by Tigran Aivazian Make sure your patch does not include any extra files which do not belong in a patch submission. Make sure to review your patch -after- @@ -67,20 +66,18 @@ generated it with diff(1), to ensure accuracy. If your changes produce a lot of deltas, you may want to look into splitting them into individual patches which modify things in -logical stages. This will facilitate easier reviewing by other +logical stages, this will facilitate easier reviewing by other kernel developers, very important if you want your patch accepted. -There are a number of scripts which can aid in this: +There are a number of scripts which can aid in this; Quilt: http://savannah.nongnu.org/projects/quilt Randy Dunlap's patch scripts: -http://www.xenotime.net/linux/scripts/patching-scripts-002.tar.gz +http://developer.osdl.org/rddunlap/scripts/patching-scripts.tgz Andrew Morton's patch scripts: -http://www.zip.com.au/~akpm/linux/patches/patch-scripts-0.20 - - +http://www.zip.com.au/~akpm/linux/patches/patch-scripts-0.16 2) Describe your changes. @@ -135,6 +132,21 @@ which require discussion or do not have a clear advantage should usually be sent first to linux-kernel. Only after the patch is discussed should the patch then be submitted to Linus. +For small patches you may want to CC the Trivial Patch Monkey +trivial@rustcorp.com.au set up by Rusty Russell; which collects "trivial" +patches. Trivial patches must qualify for one of the following rules: + Spelling fixes in documentation + Spelling fixes which could break grep(1). + Warning fixes (cluttering with useless warnings is bad) + Compilation fixes (only if they are actually correct) + Runtime fixes (only if they actually fix things) + Removing use of deprecated functions/macros (eg. check_region). + Contact detail and documentation fixes + Non-portable code replaced by portable code (even in arch-specific, + since people copy, as long as it's trivial) + Any fix by the author/maintainer of the file. (ie. patch monkey + in re-transmission mode) + 5) Select your CC (e-mail carbon copy) list. @@ -166,8 +178,6 @@ patches. Trivial patches must qualify for one of the following rules: since people copy, as long as it's trivial) Any fix by the author/maintainer of the file. (ie. patch monkey in re-transmission mode) -URL: - @@ -261,7 +271,7 @@ patch, which certifies that you wrote it or otherwise have the right to pass it on as a open-source patch. The rules are pretty simple: if you can certify the below: - Developer's Certificate of Origin 1.1 + Developer's Certificate of Origin 1.0 By making a contribution to this project, I certify that: @@ -281,32 +291,15 @@ can certify the below: person who certified (a), (b) or (c) and I have not modified it. - (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. - then you just add a line saying - Signed-off-by: Random J Developer + Signed-off-by: Random J Developer Some people also put extra tags at the end. They'll just be ignored for now, but you can do this to mark internal company procedures or just point out some special detail about the sign-off. - -12) More references for submitting patches - -Andrew Morton, "The perfect patch" (tpp). - - -Jeff Garzik, "Linux kernel patch submission format." - - - - ----------------------------------- SECTION 2 - HINTS, TIPS, AND TRICKS ----------------------------------- @@ -375,5 +368,7 @@ and 'extern __inline__'. 4) Don't over-design. Don't try to anticipate nebulous future cases which may or may not -be useful: "Make it as simple as you can, and no simpler." +be useful: "Make it as simple as you can, and no simpler" + + diff --git a/trunk/Documentation/aoe/aoe.txt b/trunk/Documentation/aoe/aoe.txt index 3a4dbe4663c9..43e50108d0e2 100644 --- a/trunk/Documentation/aoe/aoe.txt +++ b/trunk/Documentation/aoe/aoe.txt @@ -4,16 +4,6 @@ The EtherDrive (R) HOWTO for users of 2.6 kernels is found at ... It has many tips and hints! -The aoetools are userland programs that are designed to work with this -driver. The aoetools are on sourceforge. - - http://aoetools.sourceforge.net/ - -The scripts in this Documentation/aoe directory are intended to -document the use of the driver and are not necessary if you install -the aoetools. - - CREATING DEVICE NODES Users of udev should find the block device nodes created @@ -45,15 +35,14 @@ USING DEVICE NODES "echo eth2 eth4 > /dev/etherd/interfaces" tells the aoe driver to limit ATA over Ethernet traffic to eth2 and eth4. AoE traffic from - untrusted networks should be ignored as a matter of security. See - also the aoe_iflist driver option described below. + untrusted networks should be ignored as a matter of security. "echo > /dev/etherd/discover" tells the driver to find out what AoE devices are available. These character devices may disappear and be replaced by sysfs - counterparts. Using the commands in aoetools insulates users from - these implementation details. + counterparts, so distribution maintainers are encouraged to create + scripts that use these devices. The block devices are named like this: @@ -77,8 +66,7 @@ USING SYSFS through which we are communicating with the remote AoE device. There is a script in this directory that formats this information - in a convenient way. Users with aoetools can use the aoe-stat - command. + in a convenient way. root@makki root# sh Documentation/aoe/status.sh e10.0 eth3 up @@ -101,23 +89,3 @@ USING SYSFS e4.7 eth1 up e4.8 eth1 up e4.9 eth1 up - - Use /sys/module/aoe/parameters/aoe_iflist (or better, the driver - option discussed below) instead of /dev/etherd/interfaces to limit - AoE traffic to the network interfaces in the given - whitespace-separated list. Unlike the old character device, the - sysfs entry can be read from as well as written to. - - It's helpful to trigger discovery after setting the list of allowed - interfaces. The aoetools package provides an aoe-discover script - for this purpose. You can also directly use the - /dev/etherd/discover special file described above. - -DRIVER OPTIONS - - There is a boot option for the built-in aoe driver and a - corresponding module parameter, aoe_iflist. Without this option, - all network interfaces may be used for ATA over Ethernet. Here is a - usage example for the module parameter. - - modprobe aoe_iflist="eth1 eth3" diff --git a/trunk/Documentation/aoe/status.sh b/trunk/Documentation/aoe/status.sh index 751f3be514b8..6628116d4a9f 100644 --- a/trunk/Documentation/aoe/status.sh +++ b/trunk/Documentation/aoe/status.sh @@ -14,6 +14,10 @@ test ! -d "$sysd/block" && { echo "$me Error: sysfs is not mounted" 1>&2 exit 1 } +test -z "`lsmod | grep '^aoe'`" && { + echo "$me Error: aoe module is not loaded" 1>&2 + exit 1 +} for d in `ls -d $sysd/block/etherd* 2>/dev/null | grep -v p` end; do # maybe ls comes up empty, so we use "end" diff --git a/trunk/Documentation/basic_profiling.txt b/trunk/Documentation/basic_profiling.txt index 8764e9f70821..65e3dc2d4437 100644 --- a/trunk/Documentation/basic_profiling.txt +++ b/trunk/Documentation/basic_profiling.txt @@ -27,13 +27,9 @@ dump output readprofile -m /boot/System.map > captured_profile Oprofile -------- - -Get the source (see Changes for required version) from -http://oprofile.sourceforge.net/ and add "idle=poll" to the kernel command -line. - +Get the source (I use 0.8) from http://oprofile.sourceforge.net/ +and add "idle=poll" to the kernel command line Configure with CONFIG_PROFILING=y and CONFIG_OPROFILE=y & reboot on new kernel - ./configure --with-kernel-support make install @@ -50,7 +46,7 @@ start opcontrol --start stop opcontrol --stop dump output opreport > output_file -To only report on the kernel, run opreport -l /boot/vmlinux > output_file +To only report on the kernel, run opreport /boot/vmlinux > output_file A reset is needed to clear old statistics, which survive a reboot. diff --git a/trunk/Documentation/block/ioprio.txt b/trunk/Documentation/block/ioprio.txt deleted file mode 100644 index 96ccf681075e..000000000000 --- a/trunk/Documentation/block/ioprio.txt +++ /dev/null @@ -1,176 +0,0 @@ -Block io priorities -=================== - - -Intro ------ - -With the introduction of cfq v3 (aka cfq-ts or time sliced cfq), basic io -priorities is supported for reads on files. This enables users to io nice -processes or process groups, similar to what has been possible to cpu -scheduling for ages. This document mainly details the current possibilites -with cfq, other io schedulers do not support io priorities so far. - -Scheduling classes ------------------- - -CFQ implements three generic scheduling classes that determine how io is -served for a process. - -IOPRIO_CLASS_RT: This is the realtime io class. This scheduling class is given -higher priority than any other in the system, processes from this class are -given first access to the disk every time. Thus it needs to be used with some -care, one io RT process can starve the entire system. Within the RT class, -there are 8 levels of class data that determine exactly how much time this -process needs the disk for on each service. In the future this might change -to be more directly mappable to performance, by passing in a wanted data -rate instead. - -IOPRIO_CLASS_BE: This is the best-effort scheduling class, which is the default -for any process that hasn't set a specific io priority. The class data -determines how much io bandwidth the process will get, it's directly mappable -to the cpu nice levels just more coarsely implemented. 0 is the highest -BE prio level, 7 is the lowest. The mapping between cpu nice level and io -nice level is determined as: io_nice = (cpu_nice + 20) / 5. - -IOPRIO_CLASS_IDLE: This is the idle scheduling class, processes running at this -level only get io time when no one else needs the disk. The idle class has no -class data, since it doesn't really apply here. - -Tools ------ - -See below for a sample ionice tool. Usage: - -# ionice -c -n -p - -If pid isn't given, the current process is assumed. IO priority settings -are inherited on fork, so you can use ionice to start the process at a given -level: - -# ionice -c2 -n0 /bin/ls - -will run ls at the best-effort scheduling class at the highest priority. -For a running process, you can give the pid instead: - -# ionice -c1 -n2 -p100 - -will change pid 100 to run at the realtime scheduling class, at priority 2. - ----> snip ionice.c tool <--- - -#include -#include -#include -#include -#include -#include -#include - -extern int sys_ioprio_set(int, int, int); -extern int sys_ioprio_get(int, int); - -#if defined(__i386__) -#define __NR_ioprio_set 289 -#define __NR_ioprio_get 290 -#elif defined(__ppc__) -#define __NR_ioprio_set 273 -#define __NR_ioprio_get 274 -#elif defined(__x86_64__) -#define __NR_ioprio_set 251 -#define __NR_ioprio_get 252 -#elif defined(__ia64__) -#define __NR_ioprio_set 1274 -#define __NR_ioprio_get 1275 -#else -#error "Unsupported arch" -#endif - -_syscall3(int, ioprio_set, int, which, int, who, int, ioprio); -_syscall2(int, ioprio_get, int, which, int, who); - -enum { - IOPRIO_CLASS_NONE, - IOPRIO_CLASS_RT, - IOPRIO_CLASS_BE, - IOPRIO_CLASS_IDLE, -}; - -enum { - IOPRIO_WHO_PROCESS = 1, - IOPRIO_WHO_PGRP, - IOPRIO_WHO_USER, -}; - -#define IOPRIO_CLASS_SHIFT 13 - -const char *to_prio[] = { "none", "realtime", "best-effort", "idle", }; - -int main(int argc, char *argv[]) -{ - int ioprio = 4, set = 0, ioprio_class = IOPRIO_CLASS_BE; - int c, pid = 0; - - while ((c = getopt(argc, argv, "+n:c:p:")) != EOF) { - switch (c) { - case 'n': - ioprio = strtol(optarg, NULL, 10); - set = 1; - break; - case 'c': - ioprio_class = strtol(optarg, NULL, 10); - set = 1; - break; - case 'p': - pid = strtol(optarg, NULL, 10); - break; - } - } - - switch (ioprio_class) { - case IOPRIO_CLASS_NONE: - ioprio_class = IOPRIO_CLASS_BE; - break; - case IOPRIO_CLASS_RT: - case IOPRIO_CLASS_BE: - break; - case IOPRIO_CLASS_IDLE: - ioprio = 7; - break; - default: - printf("bad prio class %d\n", ioprio_class); - return 1; - } - - if (!set) { - if (!pid && argv[optind]) - pid = strtol(argv[optind], NULL, 10); - - ioprio = ioprio_get(IOPRIO_WHO_PROCESS, pid); - - printf("pid=%d, %d\n", pid, ioprio); - - if (ioprio == -1) - perror("ioprio_get"); - else { - ioprio_class = ioprio >> IOPRIO_CLASS_SHIFT; - ioprio = ioprio & 0xff; - printf("%s: prio %d\n", to_prio[ioprio_class], ioprio); - } - } else { - if (ioprio_set(IOPRIO_WHO_PROCESS, pid, ioprio | ioprio_class << IOPRIO_CLASS_SHIFT) == -1) { - perror("ioprio_set"); - return 1; - } - - if (argv[optind]) - execvp(argv[optind], &argv[optind]); - } - - return 0; -} - ----> snip ionice.c tool <--- - - -March 11 2005, Jens Axboe diff --git a/trunk/Documentation/cciss.txt b/trunk/Documentation/cciss.txt index c8f9a73111da..d599beb9df8a 100644 --- a/trunk/Documentation/cciss.txt +++ b/trunk/Documentation/cciss.txt @@ -17,7 +17,6 @@ This driver is known to work with the following cards: * SA P600 * SA P800 * SA E400 - * SA E300 If nodes are not already created in the /dev/cciss directory, run as root: diff --git a/trunk/Documentation/cdrom/sbpcd b/trunk/Documentation/cdrom/sbpcd index b3ba63f4ce3e..d1825dffca34 100644 --- a/trunk/Documentation/cdrom/sbpcd +++ b/trunk/Documentation/cdrom/sbpcd @@ -419,7 +419,6 @@ into the file "track01": */ #include #include -#include #include static struct cdrom_tochdr hdr; @@ -430,7 +429,7 @@ static int datafile, drive; static int i, j, limit, track, err; static char filename[32]; -int main(int argc, char *argv[]) +main(int argc, char *argv[]) { /* * open /dev/cdrom @@ -517,7 +516,6 @@ entry[track+1].cdte_addr.lba=entry[track].cdte_addr.lba+300; } arg.addr.lba++; } - return 0; } /*===================== end program ========================================*/ @@ -566,16 +564,15 @@ Appendix -- the "cdtester" utility: #include #include #include -#include #include #ifdef AZT_PRIVATE_IOCTLS #include -#endif /* AZT_PRIVATE_IOCTLS */ +#endif AZT_PRIVATE_IOCTLS #ifdef SBP_PRIVATE_IOCTLS #include #include -#endif /* SBP_PRIVATE_IOCTLS */ +#endif SBP_PRIVATE_IOCTLS struct cdrom_tochdr hdr; struct cdrom_tochdr tocHdr; @@ -593,7 +590,7 @@ union struct cdrom_msf msf; unsigned char buf[CD_FRAMESIZE_RAW]; } azt; -#endif /* AZT_PRIVATE_IOCTLS */ +#endif AZT_PRIVATE_IOCTLS int i, i1, i2, i3, j, k; unsigned char sequence=0; unsigned char command[80]; @@ -741,7 +738,7 @@ void display(int size,unsigned char *buffer) } } -int main(int argc, char *argv[]) +main(int argc, char *argv[]) { printf("\nTesting tool for a CDROM driver's audio functions V0.1\n"); printf("(C) 1995 Eberhard Moenkeberg \n"); @@ -1049,13 +1046,12 @@ int main(int argc, char *argv[]) rc=ioctl(drive,CDROMAUDIOBUFSIZ,j); printf("%d frames granted.\n",rc); break; -#endif /* SBP_PRIVATE_IOCTLS */ +#endif SBP_PRIVATE_IOCTLS default: printf("unknown command: \"%s\".\n",command); break; } } - return 0; } /*==========================================================================*/ diff --git a/trunk/Documentation/cpu-freq/cpufreq-stats.txt b/trunk/Documentation/cpu-freq/cpufreq-stats.txt deleted file mode 100644 index e2d1e760b4ba..000000000000 --- a/trunk/Documentation/cpu-freq/cpufreq-stats.txt +++ /dev/null @@ -1,128 +0,0 @@ - - CPU frequency and voltage scaling statictics in the Linux(TM) kernel - - - L i n u x c p u f r e q - s t a t s d r i v e r - - - information for users - - - - Venkatesh Pallipadi - -Contents -1. Introduction -2. Statistics Provided (with example) -3. Configuring cpufreq-stats - - -1. Introduction - -cpufreq-stats is a driver that provices CPU frequency statistics for each CPU. -This statistics is provided in /sysfs as a bunch of read_only interfaces. This -interface (when configured) will appear in a seperate directory under cpufreq -in /sysfs (/devices/system/cpu/cpuX/cpufreq/stats/) for each CPU. -Various statistics will form read_only files under this directory. - -This driver is designed to be independent of any particular cpufreq_driver -that may be running on your CPU. So, it will work with any cpufreq_driver. - - -2. Statistics Provided (with example) - -cpufreq stats provides following statistics (explained in detail below). -- time_in_state -- total_trans -- trans_table - -All the statistics will be from the time the stats driver has been inserted -to the time when a read of a particular statistic is done. Obviously, stats -driver will not have any information about the the frequcny transitions before -the stats driver insertion. - --------------------------------------------------------------------------------- -:/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l -total 0 -drwxr-xr-x 2 root root 0 May 14 16:06 . -drwxr-xr-x 3 root root 0 May 14 15:58 .. --r--r--r-- 1 root root 4096 May 14 16:06 time_in_state --r--r--r-- 1 root root 4096 May 14 16:06 total_trans --r--r--r-- 1 root root 4096 May 14 16:06 trans_table --------------------------------------------------------------------------------- - -- time_in_state -This gives the amount of time spent in each of the frequencies supported by -this CPU. The cat output will have "