mirror of
https://github.com/ukui/kernel.git
synced 2026-03-09 10:07:04 -07:00
merge by hand - fix up rejections in Documentation/DocBook/Makefile
This commit is contained in:
James Bottomley
2
CREDITS
2
CREDITS
@@ -339,7 +339,7 @@ W: http://tomas.nocrew.org/
|
||||
D: dsp56k device driver
|
||||
|
||||
N: Ross Biro
|
||||
E: bir7@leland.Stanford.Edu
|
||||
E: ross.biro@gmail.com
|
||||
D: Original author of the Linux networking code
|
||||
|
||||
N: Anton Blanchard
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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`,+
|
||||
|
||||
@@ -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
|
||||
@@ -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 -
|
||||
@@ -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"
|
||||
@@ -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 ""
|
||||
|
||||
@@ -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 = ();
|
||||
}
|
||||
|
||||
@@ -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 = ();
|
||||
}
|
||||
|
||||
@@ -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`,+
|
||||
@@ -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
|
||||
@@ -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/>
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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>
|
||||
|
||||
5
Documentation/DocBook/stylesheet.xsl
Normal file
5
Documentation/DocBook/stylesheet.xsl
Normal file
@@ -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>
|
||||
@@ -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>
|
||||
File diff suppressed because it is too large
Load Diff
@@ -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]"
|
||||
}
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user