diff options
Diffstat (limited to 'Documentation')
34 files changed, 475 insertions, 1730 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 72dc90f8f4a..8de8a01a247 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -12,8 +12,6 @@ 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 diff --git a/Documentation/BK-usage/00-INDEX b/Documentation/BK-usage/00-INDEX deleted file mode 100644 index 82768784ea5..00000000000 --- a/Documentation/BK-usage/00-INDEX +++ /dev/null @@ -1,51 +0,0 @@ -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/Documentation/BK-usage/bk-kernel-howto.txt b/Documentation/BK-usage/bk-kernel-howto.txt deleted file mode 100644 index b7b9075d291..00000000000 --- a/Documentation/BK-usage/bk-kernel-howto.txt +++ /dev/null @@ -1,283 +0,0 @@ - - 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 <command>" or in X "bk helptool <command>" 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<rev>" 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 <parent>", 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/Documentation/BK-usage/bk-make-sum b/Documentation/BK-usage/bk-make-sum deleted file mode 100755 index 58ca46a0fcc..00000000000 --- a/Documentation/BK-usage/bk-make-sum +++ /dev/null @@ -1,34 +0,0 @@ -#!/bin/sh -e -# DIR=$HOME/BK/axp-2.5 -# cd $DIR - -LINUS_REPO=$1 -DIRBASE=`basename $PWD` - -{ -cat <<EOT -Please do a - - bk pull bk://gkernel.bkbits.net/$DIRBASE - -This will update the following files: - -EOT - -bk export -tpatch -hdu -r`bk repogca $LINUS_REPO`,+ | diffstat -p1 2>/dev/null - -cat <<EOT - -through these ChangeSets: - -EOT - -bk changes -L -d'$unless(:MERGE:){ChangeSet|:CSETREV:\n}' $LINUS_REPO | -bk -R prs -h -d'$unless(:MERGE:){<:P:@:HOST:> (:D: :I:)\n$each(:C:){ (:C:)\n}\n}' - - -} > /tmp/linus.txt - -cat <<EOT -Mail text in /tmp/linus.txt; please check and send using your favourite -mailer. -EOT diff --git a/Documentation/BK-usage/bksend b/Documentation/BK-usage/bksend deleted file mode 100755 index 836ca943694..00000000000 --- a/Documentation/BK-usage/bksend +++ /dev/null @@ -1,36 +0,0 @@ -#!/bin/sh -# A script to format BK changeset output in a manner that is easy to read. -# Andreas Dilger <adilger@turbolabs.com> 13/02/2002 -# -# Add diffstat output after Changelog <adilger@turbolabs.com> 21/02/2002 - -PROG=bksend - -usage() { - echo "usage: $PROG -r<rev>" - echo -e "\twhere <rev> 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/Documentation/BK-usage/bz64wrap b/Documentation/BK-usage/bz64wrap deleted file mode 100755 index be780876849..00000000000 --- a/Documentation/BK-usage/bz64wrap +++ /dev/null @@ -1,41 +0,0 @@ -#!/bin/sh - -# bz64wrap - the sending side of a bzip2 | base64 stream -# Andreas Dilger <adilger@clusterfs.com> 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/Documentation/BK-usage/cpcset b/Documentation/BK-usage/cpcset deleted file mode 100755 index b8faca97dab..00000000000 --- a/Documentation/BK-usage/cpcset +++ /dev/null @@ -1,36 +0,0 @@ -#!/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/Documentation/BK-usage/cset-to-linus b/Documentation/BK-usage/cset-to-linus deleted file mode 100755 index d28a96f8c61..00000000000 --- a/Documentation/BK-usage/cset-to-linus +++ /dev/null @@ -1,49 +0,0 @@ -#!/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 = <PIPE>) { - $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/Documentation/BK-usage/csets-to-patches b/Documentation/BK-usage/csets-to-patches deleted file mode 100755 index e2b81c35883..00000000000 --- a/Documentation/BK-usage/csets-to-patches +++ /dev/null @@ -1,44 +0,0 @@ -#!/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/Documentation/BK-usage/gcapatch b/Documentation/BK-usage/gcapatch deleted file mode 100755 index aaeb17dc7c7..00000000000 --- a/Documentation/BK-usage/gcapatch +++ /dev/null @@ -1,8 +0,0 @@ -#!/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/Documentation/BK-usage/unbz64wrap b/Documentation/BK-usage/unbz64wrap deleted file mode 100755 index 4fc3e73e9a8..00000000000 --- a/Documentation/BK-usage/unbz64wrap +++ /dev/null @@ -1,25 +0,0 @@ -#!/bin/sh - -# unbz64wrap - the receiving side of a bzip2 | base64 stream -# Andreas Dilger <adilger@clusterfs.com> 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/Documentation/Changes b/Documentation/Changes index caa6a5529b6..57542bc25ed 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -357,14 +357,14 @@ Quota-tools ---------- o <http://sourceforge.net/projects/linuxquota/> -Jade ----- -o <ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz> - DocBook Stylesheets ------------------- o <http://nwalsh.com/docbook/dsssl/> +XMLTO XSLT Frontend +------------------- +o <http://cyberelk.net/tim/xmlto/> + Intel P6 microcode ------------------ o <http://www.urbanmyth.org/microcode/> diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index e69d6865945..87da3478fad 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -7,11 +7,10 @@ # list of DOCBOOKS. DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ - kernel-hacking.xml kernel-locking.xml via-audio.xml \ - deviceiobook.xml procfs-guide.xml tulip-user.xml \ - writing_usb_driver.xml sis900.xml kernel-api.xml \ - journal-api.xml lsm.xml usb.xml gadget.xml libata.xml \ - mtdnand.xml librs.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 \ + gadget.xml libata.xml mtdnand.xml librs.xml ### # The build process is as follows (targets): @@ -42,14 +41,16 @@ MAN := $(patsubst %.xml, %.9, $(BOOKS)) mandocs: $(MAN) installmandocs: mandocs - $(MAKEMAN) install Documentation/DocBook/man + mkdir -p /usr/local/man/man9/ + install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/ ### #External programs used KERNELDOC = scripts/kernel-doc DOCPROC = scripts/basic/docproc -SPLITMAN = $(PERL) $(srctree)/scripts/split-man -MAKEMAN = $(PERL) $(srctree)/scripts/makeman + +XMLTOFLAGS = -m Documentation/DocBook/stylesheet.xsl +#XMLTOFLAGS += --skip-validation ### # DOCPROC is used for two purposes: @@ -96,45 +97,44 @@ $(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 = DB2PS $@ - cmd_db2ps = db2ps -o $(dir $@) $< +quiet_cmd_db2ps = XMLTO $@ + cmd_db2ps = xmlto ps $(XMLTOFLAGS) -o $(dir $@) $< %.ps : %.xml - @(which db2ps > /dev/null 2>&1) || \ - (echo "*** You need to install DocBook stylesheets ***"; \ + @(which xmlto > /dev/null 2>&1) || \ + (echo "*** You need to install xmlto ***"; \ exit 1) $(call cmd,db2ps) -quiet_cmd_db2pdf = DB2PDF $@ - cmd_db2pdf = db2pdf -o $(dir $@) $< +quiet_cmd_db2pdf = XMLTO $@ + cmd_db2pdf = xmlto pdf $(XMLTOFLAGS) -o $(dir $@) $< %.pdf : %.xml - @(which db2pdf > /dev/null 2>&1) || \ - (echo "*** You need to install DocBook stylesheets ***"; \ + @(which xmlto > /dev/null 2>&1) || \ + (echo "*** You need to install xmlto ***"; \ exit 1) $(call cmd,db2pdf) -quiet_cmd_db2html = DB2HTML $@ - cmd_db2html = db2html -o $(patsubst %.html,%,$@) $< && \ - echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/book1.html"> \ +quiet_cmd_db2html = XMLTO $@ + cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \ + echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \ Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@ %.html: %.xml - @(which db2html > /dev/null 2>&1) || \ - (echo "*** You need to install DocBook stylesheets ***"; \ + @(which xmlto > /dev/null 2>&1) || \ + (echo "*** You need to install xmlto ***"; \ exit 1) @rm -rf $@ $(patsubst %.html,%,$@) $(call cmd,db2html) @if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \ cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi -### -# 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 $< +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 $@ ### # Rules to generate postscripts and PNG imgages from .fig format files diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index 1bd20c86028..757cef8f849 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -49,13 +49,33 @@ !Iinclude/asm-i386/unaligned.h </sect1> -<!-- FIXME: - kernel/sched.c has no docs, which stuffs up the sgml. Comment - out until somebody adds docs. KAO <sect1><title>Delaying, scheduling, and timer routines</title> -X!Ekernel/sched.c +!Iinclude/linux/sched.h +!Ekernel/sched.c +!Ekernel/timer.c </sect1> -KAO --> + <sect1><title>Internal Functions</title> +!Ikernel/exit.c +!Ikernel/signal.c + </sect1> + + <sect1><title>Kernel objects manipulation</title> +<!-- +X!Iinclude/linux/kobject.h +--> +!Elib/kobject.c + </sect1> + + <sect1><title>Kernel utility functions</title> +!Iinclude/linux/kernel.h +<!-- This needs to clean up to make kernel-doc happy +X!Ekernel/printk.c + --> +!Ekernel/panic.c +!Ekernel/sys.c +!Ekernel/rcupdate.c + </sect1> + </chapter> <chapter id="adt"> @@ -81,7 +101,9 @@ KAO --> !Elib/vsprintf.c </sect1> <sect1><title>String Manipulation</title> -!Ilib/string.c +<!-- All functions are exported at now +X!Ilib/string.c + --> !Elib/string.c </sect1> <sect1><title>Bit Operations</title> @@ -98,6 +120,25 @@ KAO --> !Iinclude/asm-i386/uaccess.h !Iarch/i386/lib/usercopy.c </sect1> + <sect1><title>More Memory Management Functions</title> +!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 + </sect1> + </chapter> + + + <chapter id="ipc"> + <title>Kernel IPC facilities</title> + + <sect1><title>IPC utilities</title> +!Iipc/util.c + </sect1> </chapter> <chapter id="kfifo"> @@ -114,6 +155,10 @@ KAO --> <sect1><title>sysctl interface</title> !Ekernel/sysctl.c </sect1> + + <sect1><title>proc filesystem interface</title> +!Ifs/proc/base.c + </sect1> </chapter> <chapter id="debugfs"> @@ -127,6 +172,10 @@ KAO --> <chapter id="vfs"> <title>The Linux VFS</title> + <sect1><title>The Filesystem types</title> +!Iinclude/linux/fs.h +!Einclude/linux/fs.h + </sect1> <sect1><title>The Directory Cache</title> !Efs/dcache.c !Iinclude/linux/dcache.h @@ -142,13 +191,31 @@ KAO --> !Efs/locks.c !Ifs/locks.c </sect1> + <sect1><title>Other Functions</title> +!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 + </sect1> </chapter> <chapter id="netcore"> <title>Linux Networking</title> + <sect1><title>Networking Base Types</title> +!Iinclude/linux/net.h + </sect1> <sect1><title>Socket Buffer Functions</title> !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 </sect1> <sect1><title>Socket Filter</title> !Enet/core/filter.c @@ -158,6 +225,14 @@ KAO --> !Enet/core/gen_stats.c !Enet/core/gen_estimator.c </sect1> + <sect1><title>SUN RPC subsystem</title> +<!-- The !D functionality is not perfect, garbage has to be protected by comments +!Dnet/sunrpc/sunrpc_syms.c +--> +!Enet/sunrpc/xdr.c +!Enet/sunrpc/svcsock.c +!Enet/sunrpc/sched.c + </sect1> </chapter> <chapter id="netdev"> @@ -194,11 +269,26 @@ X!Ekernel/module.c !Iarch/i386/kernel/irq.c </sect1> + <sect1><title>Resources Management</title> +!Ekernel/resource.c + </sect1> + <sect1><title>MTRR Handling</title> !Earch/i386/kernel/cpu/mtrr/main.c </sect1> <sect1><title>PCI Support Library</title> !Edrivers/pci/pci.c +!Edrivers/pci/pci-driver.c +!Edrivers/pci/remove.c +!Edrivers/pci/pci-acpi.c +<!-- kerneldoc does not understand to __devinit +X!Edrivers/pci/search.c + --> +!Edrivers/pci/msi.c +!Edrivers/pci/bus.c +!Edrivers/pci/hotplug.c +!Edrivers/pci/probe.c +!Edrivers/pci/rom.c </sect1> <sect1><title>PCI Hotplug Support Library</title> !Edrivers/pci/hotplug/pci_hotplug_core.c @@ -223,6 +313,14 @@ X!Earch/i386/kernel/mca.c !Efs/devfs/base.c </chapter> + <chapter id="sysfs"> + <title>The Filesystem for Exporting Kernel Objects</title> +!Efs/sysfs/file.c +!Efs/sysfs/dir.c +!Efs/sysfs/symlink.c +!Efs/sysfs/bin.c + </chapter> + <chapter id="security"> <title>Security Framework</title> !Esecurity/security.c @@ -233,6 +331,61 @@ X!Earch/i386/kernel/mca.c !Ekernel/power/pm.c </chapter> + <chapter id="devdrivers"> + <title>Device drivers infrastructure</title> + <sect1><title>Device Drivers Base</title> +<!-- +X!Iinclude/linux/device.h +--> +!Edrivers/base/driver.c +!Edrivers/base/class_simple.c +!Edrivers/base/core.c +!Edrivers/base/firmware_class.c +!Edrivers/base/transport_class.c +!Edrivers/base/dmapool.c +<!-- Cannot be included, because + attribute_container_add_class_device_adapter + and attribute_container_classdev_to_container + exceed allowed 44 characters maximum +X!Edrivers/base/attribute_container.c +--> +!Edrivers/base/sys.c +<!-- +X!Edrivers/base/interface.c +--> +!Edrivers/base/platform.c +!Edrivers/base/bus.c + </sect1> + <sect1><title>Device Drivers Power Management</title> +!Edrivers/base/power/main.c +!Edrivers/base/power/resume.c +!Edrivers/base/power/suspend.c + </sect1> + <sect1><title>Device Drivers ACPI Support</title> +<!-- Internal functions only +X!Edrivers/acpi/sleep/main.c +X!Edrivers/acpi/sleep/wakeup.c +X!Edrivers/acpi/motherboard.c +X!Edrivers/acpi/bus.c +--> +!Edrivers/acpi/scan.c +<!-- No correct structured comments +X!Edrivers/acpi/pci_bind.c +--> + </sect1> + <sect1><title>Device drivers PnP support</title> +!Edrivers/pnp/core.c +<!-- No correct structured comments +X!Edrivers/pnp/system.c + --> +!Edrivers/pnp/card.c +!Edrivers/pnp/driver.c +!Edrivers/pnp/manager.c +!Edrivers/pnp/support.c + </sect1> + </chapter> + + <chapter id="blkdev"> <title>Block Devices</title> !Edrivers/block/ll_rw_blk.c @@ -250,7 +403,23 @@ X!Earch/i386/kernel/mca.c <chapter id="snddev"> <title>Sound Devices</title> +!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 <!-- FIXME: Removed for now since no structured comments in source X!Isound/sound_firmware.c --> @@ -258,6 +427,7 @@ X!Isound/sound_firmware.c <chapter id="uart16x50"> <title>16x50 UART Driver</title> +!Iinclude/linux/serial_core.h !Edrivers/serial/serial_core.c !Edrivers/serial/8250.c </chapter> @@ -310,9 +480,11 @@ X!Isound/sound_firmware.c <sect1><title>Frame Buffer Memory</title> !Edrivers/video/fbmem.c </sect1> +<!-- <sect1><title>Frame Buffer Console</title> -!Edrivers/video/console/fbcon.c +X!Edrivers/video/console/fbcon.c </sect1> +--> <sect1><title>Frame Buffer Colormap</title> !Edrivers/video/fbcmap.c </sect1> diff --git a/Documentation/DocBook/stylesheet.xsl b/Documentation/DocBook/stylesheet.xsl new file mode 100644 index 00000000000..e14c21dda40 --- /dev/null +++ b/Documentation/DocBook/stylesheet.xsl @@ -0,0 +1,5 @@ +<?xml version="1.0" encoding="UTF-8"?> +<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0"> +<param name="chunk.quietly">1</param> +<param name="funcsynopsis.style">ansi</param> +</stylesheet> diff --git a/Documentation/DocBook/tulip-user.tmpl b/Documentation/DocBook/tulip-user.tmpl deleted file mode 100644 index 6520d7a1b13..00000000000 --- a/Documentation/DocBook/tulip-user.tmpl +++ /dev/null @@ -1,327 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="TulipUserGuide"> - <bookinfo> - <title>Tulip Driver User's Guide</title> - - <authorgroup> - <author> - <firstname>Jeff</firstname> - <surname>Garzik</surname> - <affiliation> - <address> - <email>jgarzik@pobox.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2001</year> - <holder>Jeff Garzik</holder> - </copyright> - - <legalnotice> - <para> - 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. - </para> - - <para> - 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. - </para> - - <para> - 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 - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - - <toc></toc> - - <chapter id="intro"> - <title>Introduction</title> -<para> -The Tulip Ethernet Card Driver -is maintained by Jeff Garzik (<email>jgarzik@pobox.com</email>). -</para> - -<para> -The Tulip driver was developed by Donald Becker and changed by -Jeff Garzik, Takashi Manabe and a cast of thousands. -</para> - -<para> -For 2.4.x and later kernels, the Linux Tulip driver is available at -<ulink url="http://sourceforge.net/projects/tulip/">http://sourceforge.net/projects/tulip/</ulink> -</para> - -<para> - 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. -</para> - -<para> - The original author may be reached as becker@scyld.com, or C/O - Scyld Computing Corporation, - 410 Severn Ave., Suite 210, - Annapolis MD 21403 -</para> - -<para> - Additional information on Donald Becker's tulip.c - is available at <ulink url="http://www.scyld.com/network/tulip.html">http://www.scyld.com/network/tulip.html</ulink> -</para> - - </chapter> - - <chapter id="drvr-compat"> - <title>Driver Compatibility</title> - -<para> -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. -</para> - -<para> -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. -</para> - </chapter> - - <chapter id="board-settings"> - <title>Board-specific Settings</title> - -<para> -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. -</para> - -<para> -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. -</para> - </chapter> - - <chapter id="driver-operation"> - <title>Driver Operation</title> - -<sect1><title>Ring buffers</title> - -<para> -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. -</para> - -<para> -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. -</para> - -</sect1> - -<sect1><title>Synchronization</title> -<para> -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. -</para> - -<para> -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. -</para> - -<para> -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. -</para> - -</sect1> - - </chapter> - - <chapter id="errata"> - <title>Errata</title> - -<para> -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? -</para> - -<para> -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. -</para> - -<para> -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. -</para> - </chapter> - - <chapter id="changelog"> - <title>Driver Change History</title> - - <sect1><title>Version 0.9.14 (February 20, 2001)</title> - <itemizedlist> - <listitem><para>Fix PNIC problems (Manfred Spraul)</para></listitem> - <listitem><para>Add new PCI id for Accton comet</para></listitem> - <listitem><para>Support Davicom tulips</para></listitem> - <listitem><para>Fix oops in eeprom parsing</para></listitem> - <listitem><para>Enable workarounds for early PCI chipsets</para></listitem> - <listitem><para>IA64, hppa csr0 support</para></listitem> - <listitem><para>Support media types 5, 6</para></listitem> - <listitem><para>Interpret a bit more of the 21142 SROM extended media type 3</para></listitem> - <listitem><para>Add missing delay in eeprom reading</para></listitem> - </itemizedlist> - </sect1> - - <sect1><title>Version 0.9.11 (November 3, 2000)</title> - <itemizedlist> - <listitem><para>Eliminate extra bus accesses when sharing interrupts (prumpf)</para></listitem> - <listitem><para>Barrier following ownership descriptor bit flip (prumpf)</para></listitem> - <listitem><para>Endianness fixes for >14 addresses in setup frames (prumpf)</para></listitem> - <listitem><para>Report link beat to kernel/userspace via netif_carrier_*. (kuznet)</para></listitem> - <listitem><para>Better spinlocking in set_rx_mode.</para></listitem> - <listitem><para>Fix I/O resource request failure error messages (DaveM catch)</para></listitem> - <listitem><para>Handle DMA allocation failure.</para></listitem> - </itemizedlist> - </sect1> - - <sect1><title>Version 0.9.10 (September 6, 2000)</title> - <itemizedlist> - <listitem><para>Simple interrupt mitigation (via jamal)</para></listitem> - <listitem><para>More PCI ids</para></listitem> - </itemizedlist> - </sect1> - - <sect1><title>Version 0.9.9 (August 11, 2000)</title> - <itemizedlist> - <listitem><para>More PCI ids</para></listitem> - </itemizedlist> - </sect1> - - <sect1><title>Version 0.9.8 (July 13, 2000)</title> - <itemizedlist> - <listitem><para>Correct signed/unsigned comparison for dummy frame index</para></listitem> - <listitem><para>Remove outdated references to struct enet_statistics</para></listitem> - </itemizedlist> - </sect1> - - <sect1><title>Version 0.9.7 (June 17, 2000)</title> - <itemizedlist> - <listitem><para>Timer cleanups (Andrew Morton)</para></listitem> - <listitem><para>Alpha compile fix (somebody?)</para></listitem> - </itemizedlist> - </sect1> - - <sect1><title>Version 0.9.6 (May 31, 2000)</title> - <itemizedlist> - <listitem><para>Revert 21143-related support flag patch</para></listitem> - <listitem><para>Add HPPA/media-table debugging printk</para></listitem> - </itemizedlist> - </sect1> - - <sect1><title>Version 0.9.5 (May 30, 2000)</title> - <itemizedlist> - <listitem><para>HPPA support (willy@puffingroup)</para></listitem> - <listitem><para>CSR6 bits and tulip.h cleanup (Chris Smith)</para></listitem> - <listitem><para>Improve debugging messages a bit</para></listitem> - <listitem><para>Add delay after CSR13 write in t21142_start_nway</para></listitem> - <listitem><para>Remove unused ETHER_STATS code</para></listitem> - <listitem><para>Convert 'extern inline' to 'static inline' in tulip.h (Chris Smith)</para></listitem> - <listitem><para>Update DS21143 support flags in tulip_chip_info[]</para></listitem> - <listitem><para>Use spin_lock_irq, not _irqsave/restore, in tulip_start_xmit()</para></listitem> - <listitem><para>Add locking to set_rx_mode()</para></listitem> - <listitem><para>Fix race with chip setting DescOwned bit (Hal Murray)</para></listitem> - <listitem><para>Request 100% of PIO and MMIO resource space assigned to card</para></listitem> - <listitem><para>Remove error message from pci_enable_device failure</para></listitem> - </itemizedlist> - </sect1> - - <sect1><title>Version 0.9.4.3 (April 14, 2000)</title> - <itemizedlist> - <listitem><para>mod_timer fix (Hal Murray)</para></listitem> - <listitem><para>PNIC2 resuscitation (Chris Smith)</para></listitem> - </itemizedlist> - </sect1> - - <sect1><title>Version 0.9.4.2 (March 21, 2000)</title> - <itemizedlist> - <listitem><para>Fix 21041 CSR7, CSR13/14/15 handling</para></listitem> - <listitem><para>Merge some PCI ids from tulip 0.91x</para></listitem> - <listitem><para>Merge some HAS_xxx flags and flag settings from tulip 0.91x</para></listitem> - <listitem><para>asm/io.h fix (submitted by many) and cleanup</para></listitem> - <listitem><para>s/HAS_NWAY143/HAS_NWAY/</para></listitem> - <listitem><para>Cleanup 21041 mode reporting</para></listitem> - <listitem><para>Small code cleanups</para></listitem> - </itemizedlist> - </sect1> - - <sect1><title>Version 0.9.4.1 (March 18, 2000)</title> - <itemizedlist> - <listitem><para>Finish PCI DMA conversion (davem)</para></listitem> - <listitem><para>Do not netif_start_queue() at end of tulip_tx_timeout() (kuznet)</para></listitem> - <listitem><para>PCI DMA fix (kuznet)</para></listitem> - <listitem><para>eeprom.c code cleanup</para></listitem> - <listitem><para>Remove Xircom Tulip crud</para></listitem> - </itemizedlist> - </sect1> - </chapter> - -</book> diff --git a/Documentation/DocBook/via-audio.tmpl b/Documentation/DocBook/via-audio.tmpl deleted file mode 100644 index 36e642147d6..00000000000 --- a/Documentation/DocBook/via-audio.tmpl +++ /dev/null @@ -1,597 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="ViaAudioGuide"> - <bookinfo> - <title>Via 686 Audio Driver for Linux</title> - - <authorgroup> - <author> - <firstname>Jeff</firstname> - <surname>Garzik</surname> - </author> - </authorgroup> - - <copyright> - <year>1999-2001</year> - <holder>Jeff Garzik</holder> - </copyright> - - <legalnotice> - <para> - 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. - </para> - - <para> - 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. - </para> - - <para> - 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 - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - 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. - </para> - <para> - 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. - </para> - <para> - This driver supports any Linux kernel version after 2.4.10. - </para> - <para> - Please send bug reports to the mailing list <email>linux-via@gtf.org</email>. - To subscribe, e-mail <email>majordomo@gtf.org</email> with - </para> - <programlisting> - subscribe linux-via - </programlisting> - <para> - in the body of the message. - </para> - </chapter> - - <chapter id="install"> - <title>Driver Installation</title> - <para> - 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. - </para> - <para> - To make this driver the default audio driver, you can add the - following to your /etc/conf.modules file: - </para> - <programlisting> - alias sound via82cxxx_audio - </programlisting> - <para> - Note that soundcore and ac97_codec support modules - are also required for working audio, in addition to - the via82cxxx_audio module itself. - </para> - </chapter> - - <chapter id="reportbug"> - <title>Submitting a bug report</title> - <sect1 id="bugrepdesc"><title>Description of problem</title> - <para> - Describe the application you were using to play/record sound, and how - to reproduce the problem. - </para> - </sect1> - <sect1 id="bugrepdiag"><title>Diagnostic output</title> - <para> - 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: - </para> - <programlisting> - ./via-audio-diag -aps > diag-output.txt - </programlisting> - </sect1> - <sect1 id="bugrepdebug"><title>Driver debug output</title> - <para> - Define <constant>VIA_DEBUG</constant> 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: - </para> - <programlisting> - dmesg > /tmp/dmesg-output.txt - </programlisting> - </sect1> - <sect1 id="bugrepprintk"><title>Bigger kernel message buffer</title> - <para> - If you wish to increase the size of the buffer displayed by dmesg, then - change the <constant>LOG_BUF_LEN</constant> macro at the top of linux/kernel/printk.c, recompile - your kernel, and pass the <constant>LOG_BUF_LEN</constant> value to dmesg. Sample command line with - <constant>LOG_BUF_LEN</constant> == 32768: - </para> - <programlisting> - dmesg -s 32768 > /tmp/dmesg-output.txt - </programlisting> - </sect1> - </chapter> - - <chapter id="bugs"> - <title>Known Bugs And Assumptions</title> - <para> - <variablelist> - <varlistentry><term>Low volume</term> - <listitem> - <para> - Volume too low on many systems. Workaround: use mixer program - such as xmixer to increase volume. - </para> - </listitem></varlistentry> - - </variablelist> - - </para> - </chapter> - - <chapter id="thanks"> - <title>Thanks</title> - <para> - Via for providing e-mail support, specs, and NDA'd source code. - </para> - <para> - MandrakeSoft for providing hacking time. - </para> - <para> - AC97 mixer interface fixes and debugging by Ron Cemer <email>roncemer@gte.net</email>. - </para> - <para> - Rui Sousa <email>rui.sousa@conexant.com</email>, for bugfixing - MMAP support, and several other notable fixes that resulted from - his hard work and testing. - </para> - <para> - Adrian Cox <email>adrian@humboldt.co.uk</email>, for bugfixing - MMAP support, and several other notable fixes that resulted from - his hard work and testing. - </para> - <para> - Thomas Sailer for further bugfixes. - </para> - </chapter> - - <chapter id="notes"> - <title>Random Notes</title> - <para> - 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: - </para> - <programlisting> - /proc/driver/via/0/info - /proc/driver/via/0/ac97 - </programlisting> - <para> - 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. - </para> - <para> - GNU indent formatting options: - <programlisting> --kr -i8 -ts8 -br -ce -bap -sob -l80 -pcs -cs -ss -bs -di1 -nbc -lp -psl - </programlisting> - </para> - <para> - 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. - </para> - <para> - 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?) - </para> - </chapter> - - <chapter id="changelog"> - <title>Driver ChangeLog</title> - -<sect1 id="version191"><title> -Version 1.9.1 -</title> - <itemizedlist spacing="compact"> - <listitem> - <para> - DSP read/write bugfixes from Thomas Sailer. - </para> - </listitem> - - <listitem> - <para> - Add new PCI id for single-channel use of Via 8233. - </para> - </listitem> - - <listitem> - <para> - Other bug fixes, tweaks, new ioctls. - </para> - </listitem> - - </itemizedlist> -</sect1> - -<sect1 id="version1115"><title> -Version 1.1.15 -</title> - <itemizedlist spacing="compact"> - <listitem> - <para> - Support for variable fragment size and variable fragment number (Rui - Sousa) - </para> - </listitem> - - <listitem> - <para> - Fixes for the SPEED, STEREO, CHANNELS, FMT ioctls when in read & - write mode (Rui Sousa) - </para> - </listitem> - - <listitem> - <para> - Mmaped sound is now fully functional. (Rui Sousa) - </para> - </listitem> - - <listitem> - <para> - Make sure to enable PCI device before reading any of its PCI - config information. (fixes potential hotplug problems) - </para> - </listitem> - - <listitem> - <para> - Clean up code a bit and add more internal function documentation. - </para> - </listitem> - - <listitem> - <para> - AC97 codec access fixes (Adrian Cox) - </para> - </listitem> - - <listitem> - <para> - Big endian fixes (Adrian Cox) - </para> - </listitem> - - <listitem> - <para> - MIDI support (Adrian Cox) - </para> - </listitem> - - <listitem> - <para> - 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. - </para> - </listitem> - - <listitem> - <para> - Use new pci_request_regions and pci_disable_device functions in - kernel 2.4.6. - </para> - </listitem> - - </itemizedlist> -</sect1> - -<sect1 id="version1114"><title> -Version 1.1.14 -</title> - <itemizedlist spacing="compact"> - <listitem> - <para> - Use VM_RESERVE when available, to eliminate unnecessary page faults. - </para> - </listitem> - </itemizedlist> -</sect1> - -<sect1 id="version1112"><title> -Version 1.1.12 -</title> - <itemizedlist spacing="compact"> - <listitem> - <para> - mmap bug fixes from Linus. - </para> - </listitem> - </itemizedlist> -</sect1> - -<sect1 id="version1111"><title> -Version 1.1.11 -</title> - <itemizedlist spacing="compact"> - <listitem> - <para> - Many more bug fixes. mmap enabled by default, but may still be buggy. - </para> - </listitem> - - <listitem> - <para> - Uses new and spiffy method of mmap'ing the DMA buffer, based - on a suggestion from Linus. - </para> - </listitem> - </itemizedlist> -</sect1> - -<sect1 id="version1110"><title> -Version 1.1.10 -</title> - <itemizedlist spacing="compact"> - <listitem> - <para> - Many bug fixes. mmap enabled by default, but may still be buggy. - </para> - </listitem> - </itemizedlist> -</sect1> - -<sect1 id="version119"><title> -Version 1.1.9 -</title> - <itemizedlist spacing="compact"> - <listitem> - <para> - Redesign and rewrite audio playback implementation. (faster and smaller, hopefully) - </para> - </listitem> - - <listitem> - <para> - Implement recording and full duplex (DSP_CAP_DUPLEX) support. - </para> - </listitem> - - <listitem> - <para> - Make procfs support optional. - </para> - </listitem> - - <listitem> - <para> - Quick interrupt status check, to lessen overhead in interrupt - sharing situations. - </para> - </listitem> - - <listitem> - <para> - Add mmap(2) support. Disabled for now, it is still buggy and experimental. - </para> - </listitem> - - <listitem> - <para> - Surround all syscalls with a semaphore for cheap and easy SMP protection. - </para> - </listitem> - - <listitem> - <para> - Fix bug in channel shutdown (hardware channel reset) code. - </para> - </listitem> - - <listitem> - <para> - Remove unnecessary spinlocks (better performance). - </para> - </listitem> - - <listitem> - <para> - Eliminate "unknown AFMT" message by using a different method - of selecting the best AFMT_xxx sound sample format for use. - </para> - </listitem> - - <listitem> - <para> - Support for realtime hardware pointer position reporting - (DSP_CAP_REALTIME, SNDCTL_DSP_GETxPTR ioctls) - </para> - </listitem> - - <listitem> - <para> - Support for capture/playback triggering - (DSP_CAP_TRIGGER, SNDCTL_DSP_SETTRIGGER ioctls) - </para> - </listitem> - - <listitem> - <para> - SNDCTL_DSP_SETDUPLEX and SNDCTL_DSP_POST ioctls now handled. - </para> - </listitem> - - <listitem> - <para> - 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. - </para> - </listitem> - - <listitem> - <para> - Reviewed code to ensure that SMP and multiple audio devices - are fully supported. - </para> - </listitem> - - </itemizedlist> -</sect1> - -<sect1 id="version118"><title> -Version 1.1.8 -</title> - <itemizedlist spacing="compact"> - <listitem> - <para> - Clean up interrupt handler output. Fixes the following kernel error message: - </para> - <programlisting> - unhandled interrupt ... - </programlisting> - </listitem> - - <listitem> - <para> - Convert documentation to DocBook, so that PDF, HTML and PostScript (.ps) output is readily - available. - </para> - </listitem> - - </itemizedlist> -</sect1> - -<sect1 id="version117"><title> -Version 1.1.7 -</title> - <itemizedlist spacing="compact"> - <listitem> - <para> - Fix module unload bug where mixer device left registered - after driver exit - </para> - </listitem> - </itemizedlist> -</sect1> - -<sect1 id="version116"><title> -Version 1.1.6 -</title> - <itemizedlist spacing="compact"> - <listitem> - <para> - Rewrite via_set_rate to mimic ALSA basic AC97 rate setting - </para> - </listitem> - <listitem> - <para> - Remove much dead code - </para> - </listitem> - <listitem> - <para> - Complete spin_lock_irqsave -> spin_lock_irq conversion in via_dsp_ioctl - </para> - </listitem> - <listitem> - <para> - Fix build problem in via_dsp_ioctl - </para> - </listitem> - <listitem> - <para> - Optimize included headers to eliminate headers found in linux/sound - </para> - </listitem> - </itemizedlist> -</sect1> - -<sect1 id="version115"><title> -Version 1.1.5 -</title> - <itemizedlist spacing="compact"> - <listitem> - <para> - Disable some overly-verbose debugging code - </para> - </listitem> - <listitem> - <para> - Remove unnecessary sound locks - </para> - </listitem> - <listitem> - <para> - Fix some ioctls for better time resolution - </para> - </listitem> - <listitem> - <para> - Begin spin_lock_irqsave -> spin_lock_irq conversion in via_dsp_ioctl - </para> - </listitem> - </itemizedlist> -</sect1> - -<sect1 id="version114"><title> -Version 1.1.4 -</title> - <itemizedlist spacing="compact"> - <listitem> - <para> - Completed rewrite of driver. Eliminated SoundBlaster compatibility - completely, and now uses the much-faster scatter-gather DMA engine. - </para> - </listitem> - </itemizedlist> -</sect1> - - </chapter> - - <chapter id="intfunctions"> - <title>Internal Functions</title> -!Isound/oss/via82cxxx_audio.c - </chapter> - -</book> - - diff --git a/Documentation/RCU/RTFP.txt b/Documentation/RCU/RTFP.txt index 12250b342e1..9c6d450138e 100644 --- a/Documentation/RCU/RTFP.txt +++ b/Documentation/RCU/RTFP.txt @@ -108,8 +108,9 @@ 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], and a paper -describing how to make RCU safe for soft-realtime applications [Sarma04c]. +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]. Bibtex Entries @@ -341,6 +342,17 @@ 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}" @@ -373,6 +385,9 @@ 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 @@ -385,3 +400,13 @@ 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/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt index 551a803d82a..3bfb84b3b7d 100644 --- a/Documentation/RCU/UP.txt +++ b/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_kernel +may immediately invoke its function, and that the synchronize_rcu() 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_kernel() in +Quick Quiz: why is it -not- legal to invoke synchronize_rcu() in this case? Summary Permitting call_rcu() to immediately invoke its arguments or permitting -synchronize_kernel() to immediately return breaks RCU, even on a UP system. +synchronize_rcu() 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/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt index b3a568abe6b..8f3fb77c9cd 100644 --- a/Documentation/RCU/checklist.txt +++ b/Documentation/RCU/checklist.txt @@ -32,7 +32,10 @@ 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. + 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). 2. Do the RCU read-side critical sections make proper use of rcu_read_lock() and friends? These primitives are needed @@ -89,27 +92,34 @@ 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_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. + 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. Similarly, if the hlist macros are being used, the - hlist_del_rcu() and hlist_add_head_rcu() primitives - are required. + hlist_add_head_rcu() primitive is required. - c. Updates must ensure that initialization of a given + 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 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_kernel() blocks, it cannot be called from +6. Since synchronize_rcu() can block, it cannot be called from any sort of irq context. 7. If the updater uses call_rcu(), then the corresponding readers @@ -125,9 +135,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_kernel() is a bit slower than is call_rcu(), +8. Although synchronize_rcu() 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_kernel() + is important or the updaters cannot block, synchronize_rcu() should be used in preference to call_rcu(). 9. All RCU list-traversal primitives, which include @@ -155,3 +165,14 @@ 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/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt index bda6ead69bd..f8a54fa0d8a 100644 --- a/Documentation/RCU/listRCU.txt +++ b/Documentation/RCU/listRCU.txt @@ -32,6 +32,7 @@ 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); @@ -55,6 +56,7 @@ 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(); @@ -139,12 +141,15 @@ 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. +writers to exclude readers. Normally, the write_lock() calls would +be converted into spin_lock() calls. 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!). +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. 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! @@ -166,6 +171,7 @@ 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; @@ -199,8 +205,7 @@ 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_add_rcu(ne, e); - list_del(e); + list_replace_rcu(e, ne); call_rcu(&e->rcu, audit_free_rule, e); return 0; } diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt index 7e0c2ab6f2b..eb444006683 100644 --- a/Documentation/RCU/rcu.txt +++ b/Documentation/RCU/rcu.txt @@ -43,7 +43,9 @@ 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", "call_rcu", and "synchronize_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". o What guidelines should I follow when writing code that uses RCU? diff --git a/Documentation/aoe/aoe.txt b/Documentation/aoe/aoe.txt index 43e50108d0e..3a4dbe4663c 100644 --- a/Documentation/aoe/aoe.txt +++ b/Documentation/aoe/aoe.txt @@ -4,6 +4,16 @@ 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 @@ -35,14 +45,15 @@ 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. + untrusted networks should be ignored as a matter of security. See + also the aoe_iflist driver option described below. "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, so distribution maintainers are encouraged to create - scripts that use these devices. + counterparts. Using the commands in aoetools insulates users from + these implementation details. The block devices are named like this: @@ -66,7 +77,8 @@ 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. + in a convenient way. Users with aoetools can use the aoe-stat + command. root@makki root# sh Documentation/aoe/status.sh e10.0 eth3 up @@ -89,3 +101,23 @@ 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/Documentation/aoe/status.sh b/Documentation/aoe/status.sh index 6628116d4a9..751f3be514b 100644 --- a/Documentation/aoe/status.sh +++ b/Documentation/aoe/status.sh @@ -14,10 +14,6 @@ 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/Documentation/dontdiff b/Documentation/dontdiff index 734fcc87db2..9a33bb94f74 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -1,137 +1,140 @@ -.* +*.a +*.aux +*.bin +*.cpio +*.css +*.dvi +*.eps +*.gif +*.grep +*.grp +*.gz +*.html +*.jpeg +*.ko +*.log +*.lst +*.mod.c +*.o +*.orig +*.out +*.pdf +*.png +*.ps +*.rej +*.s +*.sgml +*.so +*.tex +*.ver +*.xml +*_MODULES +*_vga16.c +*cscope* *~ +.* +.cscope +53c700_d.h 53c8xx_d.h* -*.a +BitKeeper +COPYING +CREDITS +CVS +ChangeSet +Kerntypes +MODS.txt +Module.symvers +PENDING +SCCS +System.map* +TAGS aic7*reg.h* -aic7*seq.h* aic7*reg_print.c* -53c700_d.h +aic7*seq.h* aicasm aicdb.h* asm asm_offsets.* autoconf.h* -*.aux bbootsect -*.bin bin2c binkernel.spec -BitKeeper bootsect bsetup btfixupprep build bvmlinux bzImage* -ChangeSet classlist.h* -compile.h* comp*.log +compile.h* config config-* config_data.h* conmakehash consolemap_deftbl.c* -COPYING -CREDITS -.cscope -*cscope* +crc32table.h* cscope.* -*.out -*.css -CVS defkeymap.c* devlist.h* docproc dummy_sym.c* -*.dvi -*.eps +elfconfig.h* filelist fixdep fore200e_mkfirm fore200e_pca_fw.c* gen-devlist -gen_init_cpio -gen_crc32table -crc32table.h* -*.cpio gen-kdb_cmds.c* -gentbl +gen_crc32table +gen_init_cpio genksyms -*.gif -*.gz -*.html +gentbl ikconfig.h* initramfs_list -*.jpeg +kallsyms kconfig kconfig.tk -Kerntypes keywords.c* ksym.c* ksym.h* -kallsyms -mk_elfconfig -elfconfig.h* -modpost -pnmtologo -logo_*.c -*.log lex.c* +logo_*.c logo_*_clut224.c logo_*_mono.c lxdialog make_times_h map +maui_boot.h +mk_elfconfig mkdep -*_MODULES -MODS.txt +mktables +modpost modversions.h* -Module.symvers -*.mod.c -*.o -*.ko -*.orig -*.lst -*.grp -*.grep +offsets.h oui.c* -mktables -raid6tables.c -raid6int*.c -raid6altivec*.c -wanxlfw.inc -maui_boot.h -pss_boot.h -trix_boot.h -*.pdf parse.c* parse.h* -PENDING +pnmtologo ppc_defs.h* promcon_tbl.c* -*.png -*.ps -*.rej -SCCS +pss_boot.h +raid6altivec*.c +raid6int*.c +raid6tables.c setup -*.s -*.so -*.sgml sim710_d.h* sm_tbl* split-include -System.map* tags -TAGS -*.tex times.h* tkparse -*.ver +trix_boot.h version.h* -*_vga16.c vmlinux -vmlinux.lds vmlinux-* +vmlinux.lds vsyscall.lds +wanxlfw.inc +uImage zImage diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 56627c1546d..d3c52dd24a2 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -48,3 +48,18 @@ When: April 2005 Why: Replaced by ->compat_ioctl in file_operations and other method vecors. Who: Andi Kleen <ak@muc.de>, Christoph Hellwig <hch@lst.de> + +--------------------------- + +What: RCU API moves to EXPORT_SYMBOL_GPL +When: April 2006 +Files: include/linux/rcupdate.h, kernel/rcupdate.c +Why: Outside of Linux, the only implementations of anything even + vaguely resembling RCU that I am aware of are in DYNIX/ptx, + VM/XA, Tornado, and K42. I do not expect anyone to port binary + drivers or kernel modules from any of these, since the first two + are owned by IBM and the last two are open-source research OSes. + So these will move to GPL after a grace period to allow + people, who might be using implementations that I am not aware + of, to adjust to this upcoming change. +Who: Paul E. McKenney <paulmck@us.ibm.com> diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index a934baeeb33..1045da582b9 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -219,8 +219,12 @@ This may also be done to avoid internal deadlocks, but rarely. If the filesytem is called for sync then it must wait on any in-progress I/O and then start new I/O. -The filesystem should unlock the page synchronously, before returning -to the caller. +The filesystem should unlock the page synchronously, before returning to the +caller, unless ->writepage() returns special WRITEPAGE_ACTIVATE +value. WRITEPAGE_ACTIVATE means that page cannot really be written out +currently, and VM should stop calling ->writepage() on this page for some +time. VM does this by moving page to the head of the active list, hence the +name. Unless the filesystem is going to redirty_page_for_writepage(), unlock the page and return zero, writepage *must* run set_page_writeback() against the page, diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index cbe85c17176..6c98f2bd421 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -909,16 +909,6 @@ nr_free_inodes Represents the number of free inodes. Ie. The number of inuse inodes is (nr_inodes - nr_free_inodes). -super-nr and super-max ----------------------- - -Again, super block structures are allocated by the kernel, but not freed. The -file super-max contains the maximum number of super block handlers, where -super-nr shows the number of currently allocated ones. - -Every mounted file system needs a super block, so if you plan to mount lots of -file systems, you may want to increase these numbers. - aio-nr and aio-max-nr --------------------- diff --git a/Documentation/i386/zero-page.txt b/Documentation/i386/zero-page.txt index 67c053a099e..df28c741678 100644 --- a/Documentation/i386/zero-page.txt +++ b/Documentation/i386/zero-page.txt @@ -79,6 +79,6 @@ Offset Type Description 0x22c unsigned long ramdisk_max 0x230 16 bytes trampoline 0x290 - 0x2cf EDD_MBR_SIG_BUFFER (edd.S) -0x2d0 - 0x600 E820MAP -0x600 - 0x7ff EDDBUF (edd.S) for disk signature read sector -0x600 - 0x7eb EDDBUF (edd.S) for edd data +0x2d0 - 0xd00 E820MAP +0xd00 - 0xeff EDDBUF (edd.S) for disk signature read sector +0xd00 - 0xeeb EDDBUF (edd.S) for edd data diff --git a/Documentation/networking/DLINK.txt b/Documentation/networking/DLINK.txt index 083d24752b8..55d24433d15 100644 --- a/Documentation/networking/DLINK.txt +++ b/Documentation/networking/DLINK.txt @@ -178,10 +178,9 @@ Released 1994-06-13 7. ACKNOWLEDGMENTS. These drivers wouldn't have been done without the base - (and support) from Ross Biro <bir7@leland.stanford.edu>, - and D-Link Systems Inc. The driver relies upon GPL-ed - source from D-Link Systems Inc. and from Russel Nelson at - Crynwr Software <nelson@crynwr.com>. + (and support) from Ross Biro, and D-Link Systems Inc. + The driver relies upon GPL-ed source from D-Link Systems Inc. + and from Russel Nelson at Crynwr Software <nelson@crynwr.com>. Additional input also from: Donald Becker <becker@super.org>, Alan Cox <A.Cox@swansea.ac.uk> diff --git a/Documentation/networking/netdevices.txt b/Documentation/networking/netdevices.txt index 1509f3aff96..3c0a5ba614d 100644 --- a/Documentation/networking/netdevices.txt +++ b/Documentation/networking/netdevices.txt @@ -51,6 +51,8 @@ dev->hard_start_xmit: set_multicast_list Context: BHs disabled Notes: netif_queue_stopped() is guaranteed false + Interrupts must be enabled when calling hard_start_xmit. + (Interrupts must also be enabled when enabling the BH handler.) Return codes: o NETDEV_TX_OK everything ok. o NETDEV_TX_BUSY Cannot transmit packet, try later diff --git a/Documentation/pci.txt b/Documentation/pci.txt index 67514bf87cc..62b1dc5d97e 100644 --- a/Documentation/pci.txt +++ b/Documentation/pci.txt @@ -279,6 +279,7 @@ pci_for_each_dev_reverse() Superseded by pci_find_device_reverse() pci_for_each_bus() Superseded by pci_find_next_bus() pci_find_device() Superseded by pci_get_device() pci_find_subsys() Superseded by pci_get_subsys() +pci_find_slot() Superseded by pci_get_slot() pcibios_find_class() Superseded by pci_get_class() pci_find_class() Superseded by pci_get_class() pci_(read|write)_*_nodev() Superseded by pci_bus_(read|write)_*() diff --git a/Documentation/power/pci.txt b/Documentation/power/pci.txt index c85428e7ad9..35b1a7dae34 100644 --- a/Documentation/power/pci.txt +++ b/Documentation/power/pci.txt @@ -165,40 +165,9 @@ Description: These functions are intended for use by individual drivers, and are defined in struct pci_driver: - int (*save_state) (struct pci_dev *dev, u32 state); - int (*suspend) (struct pci_dev *dev, u32 state); + int (*suspend) (struct pci_dev *dev, pm_message_t state); int (*resume) (struct pci_dev *dev); - int (*enable_wake) (struct pci_dev *dev, u32 state, int enable); - - -save_state ----------- - -Usage: - -if (dev->driver && dev->driver->save_state) - dev->driver->save_state(dev,state); - -The driver should use this callback to save device state. It should take into -account the current state of the device and the requested state in order to -avoid any unnecessary operations. - -For example, a video card that supports all 4 states (D0-D3), all controller -context is preserved when entering D1, but the screen is placed into a low power -state (blanked). - -The driver can also interpret this function as a notification that it may be -entering a sleep state in the near future. If it knows that the device cannot -enter the requested state, either because of lack of support for it, or because -the device is middle of some critical operation, then it should fail. - -This function should not be used to set any state in the device or the driver -because the device may not actually enter the sleep state (e.g. another driver -later causes causes a global state transition to fail). - -Note that in intermediate low power states, a device's I/O and memory spaces may -be disabled and may not be available in subsequent transitions to lower power -states. + int (*enable_wake) (struct pci_dev *dev, pci_power_t state, int enable); suspend diff --git a/Documentation/s390/cds.txt b/Documentation/s390/cds.txt index d9397170fb3..f0be389c711 100644 --- a/Documentation/s390/cds.txt +++ b/Documentation/s390/cds.txt @@ -56,12 +56,16 @@ read_dev_chars() read device characteristics read_conf_data() +read_conf_data_lpm() read configuration data. ccw_device_get_ciw() get commands from extended sense data. ccw_device_start() +ccw_device_start_timeout() +ccw_device_start_key() +ccw_device_start_key_timeout() initiate an I/O request. ccw_device_resume() @@ -197,19 +201,21 @@ The read_dev_chars() function returns : operational. -read_conf_data() - Read Configuration Data +read_conf_data(), read_conf_data_lpm() - Read Configuration Data Retrieve the device dependent configuration data. Please have a look at your device dependent I/O commands for the device specific layout of the node -descriptor elements. +descriptor elements. read_conf_data_lpm() will retrieve the configuration data +for a specific path. -The function is meant to be called with an irq handler in place; that is, +The function is meant to be called with the device already enabled; that is, at earliest during set_online() processing. The function may be called enabled or disabled, but the device must not be locked -int read_conf_data(struct ccw_device, void **buffer, int *length, __u8 lpm); +int read_conf_data(struct ccw_device, void **buffer, int *length); +int read_conf_data_lpm(struct ccw_device, void **buffer, int *length, __u8 lpm); cdev - the ccw_device the data is requested for. buffer - Pointer to a buffer pointer. The read_conf_data() routine @@ -263,6 +269,25 @@ int ccw_device_start(struct ccw_device *cdev, unsigned long intparm, __u8 lpm, unsigned long flags); +int ccw_device_start_timeout(struct ccw_device *cdev, + struct ccw1 *cpa, + unsigned long intparm, + __u8 lpm, + unsigned long flags, + int expires); +int ccw_device_start_key(struct ccw_device *cdev, + struct ccw1 *cpa, + unsigned long intparm, + __u8 lpm, + __u8 key, + unsigned long flags); +int ccw_device_start_key_timeout(struct ccw_device *cdev, + struct ccw1 *cpa, + unsigned long intparm, + __u8 lpm, + __u8 key, + unsigned long flags, + int expires); cdev : ccw_device the I/O is destined for cpa : logical start address of channel program @@ -272,7 +297,12 @@ user_intparm : user specific interrupt information; will be presented particular I/O request. lpm : defines the channel path to be used for a specific I/O request. A value of 0 will make cio use the opm. +key : the storage key to use for the I/O (useful for operating on a + storage with a storage key != default key) flag : defines the action to be performed for I/O processing +expires : timeout value in jiffies. The common I/O layer will terminate + the running program after this and call the interrupt handler + with ERR_PTR(-ETIMEDOUT) as irb. Possible flag values are : @@ -327,6 +357,13 @@ current (last) I/O request. In case of a delayed status notification no special interrupt will be presented to indicate I/O completion as the I/O request was never started, even though ccw_device_start() returned with successful completion. +The irb may contain an error value, and the device driver should check for this +first: + +-ETIMEDOUT: the common I/O layer terminated the request after the specified + timeout value +-EIO: the common I/O layer terminated the request due to an error state + If the concurrent sense flag in the extended status word in the irb is set, the field irb->scsw.count describes the numer of device specific sense bytes available in the extended control word irb->scsw.ecw[0]. No device sensing by |