Merge branch 'docs' of git://git.lwn.net/linux-2.6

* 'docs' of git://git.lwn.net/linux-2.6:
  Add additional examples in Documentation/spinlocks.txt
  Move sched-rt-group.txt to scheduler/
  Documentation: move rpc-cache.txt to filesystems/
  Documentation: move nfsroot.txt to filesystems/
  Spell out behavior of atomic_dec_and_lock() in kerneldoc
  Fix a typo in highres.txt
  Fixes to the seq_file document
  Fill out information on patch tags in SubmittingPatches
  Add the seq_file documentation

11 files changed, 368 insertions, 11 deletions

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index fc8e7c7d182f..e8fb24671967 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -271,8 +271,6 @@ netlabel/
         - directory with information on the NetLabel subsystem.
 networking/
         - directory with info on various aspects of networking with Linux.
-nfsroot.txt
-        - short guide on setting up a diskless box with NFS root filesystem.
 nmi_watchdog.txt
         - info on NMI watchdog for SMP systems.
 nommu-mmap.txt
@@ -321,8 +319,6 @@ robust-futexes.txt
         - a description of what robust futexes are.
 rocket.txt
         - info on the Comtrol RocketPort multiport serial driver.
-rpc-cache.txt
-        - introduction to the caching mechanisms in the sunrpc layer.
 rt-mutex-design.txt
         - description of the RealTime mutex implementation design.
 rt-mutex.txt
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 47a539c7642d..1fc4e7144dce 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -328,7 +328,7 @@ now, but you can do this to mark internal company procedures or just
 point out some special detail about the sign-off. 
 
 
-13) When to use Acked-by:
+13) When to use Acked-by: and Cc:
 
 The Signed-off-by: tag indicates that the signer was involved in the
 development of the patch, or that he/she was in the patch's delivery path.
@@ -349,11 +349,59 @@ Acked-by: does not necessarily indicate acknowledgement of the entire patch.
 For example, if a patch affects multiple subsystems and has an Acked-by: from
 one subsystem maintainer then this usually indicates acknowledgement of just
 the part which affects that maintainer's code.  Judgement should be used here.
- When in doubt people should refer to the original discussion in the mailing
+When in doubt people should refer to the original discussion in the mailing
 list archives.
 
+If a person has had the opportunity to comment on a patch, but has not
+provided such comments, you may optionally add a "Cc:" tag to the patch.
+This is the only tag which might be added without an explicit action by the
+person it names.  This tag documents that potentially interested parties
+have been included in the discussion
 
-14) The canonical patch format
+
+14) Using Test-by: and Reviewed-by:
+
+A Tested-by: tag indicates that the patch has been successfully tested (in
+some environment) by the person named.  This tag informs maintainers that
+some testing has been performed, provides a means to locate testers for
+future patches, and ensures credit for the testers.
+
+Reviewed-by:, instead, indicates that the patch has been reviewed and found
+acceptable according to the Reviewer's Statement:
+
+        Reviewer's statement of oversight
+
+        By offering my Reviewed-by: tag, I state that:
+
+         (a) I have carried out a technical review of this patch to
+             evaluate its appropriateness and readiness for inclusion into
+             the mainline kernel.
+
+         (b) Any problems, concerns, or questions relating to the patch
+             have been communicated back to the submitter.  I am satisfied
+             with the submitter's response to my comments.
+
+         (c) While there may be things that could be improved with this
+             submission, I believe that it is, at this time, (1) a
+             worthwhile modification to the kernel, and (2) free of known
+             issues which would argue against its inclusion.
+
+         (d) While I have reviewed the patch and believe it to be sound, I
+             do not (unless explicitly stated elsewhere) make any
+             warranties or guarantees that it will achieve its stated
+             purpose or function properly in any given situation.
+
+A Reviewed-by tag is a statement of opinion that the patch is an
+appropriate modification of the kernel without any remaining serious
+technical issues.  Any interested reviewer (who has done the work) can
+offer a Reviewed-by tag for a patch.  This tag serves to give credit to
+reviewers and to inform maintainers of the degree of review which has been
+done on the patch.  Reviewed-by: tags, when supplied by reviewers known to
+understand the subject area and to perform thorough reviews, will normally
+increase the liklihood of your patch getting into the kernel.
+
+
+15) The canonical patch format
 
 The canonical patch subject line is:
 
diff --git a/Documentation/filesystems/00-INDEX b/Documentation/filesystems/00-INDEX
index e68021c08fbd..52cd611277a3 100644
--- a/Documentation/filesystems/00-INDEX
+++ b/Documentation/filesystems/00-INDEX
@@ -66,6 +66,8 @@ mandatory-locking.txt
         - info on the Linux implementation of Sys V mandatory file locking.
 ncpfs.txt
         - info on Novell Netware(tm) filesystem using NCP protocol.
+nfsroot.txt
+        - short guide on setting up a diskless box with NFS root filesystem.
 ntfs.txt
         - info and mount options for the NTFS filesystem (Windows NT).
 ocfs2.txt
@@ -82,6 +84,10 @@ relay.txt
         - info on relay, for efficient streaming from kernel to user space.
 romfs.txt
         - description of the ROMFS filesystem.
+rpc-cache.txt
+        - introduction to the caching mechanisms in the sunrpc layer.
+seq_file.txt
+        - how to use the seq_file API
 sharedsubtree.txt
         - a description of shared subtrees for namespaces.
 smbfs.txt
diff --git a/Documentation/nfsroot.txt b/Documentation/filesystems/nfsroot.txt
index 31b329172343..31b329172343 100644
--- a/Documentation/nfsroot.txt
+++ b/Documentation/filesystems/nfsroot.txt
diff --git a/Documentation/rpc-cache.txt b/Documentation/filesystems/rpc-cache.txt
index 8a382bea6808..8a382bea6808 100644
--- a/Documentation/rpc-cache.txt
+++ b/Documentation/filesystems/rpc-cache.txt
diff --git a/Documentation/filesystems/seq_file.txt b/Documentation/filesystems/seq_file.txt
new file mode 100644
index 000000000000..cc6cdb95b73a
--- /dev/null
+++ b/Documentation/filesystems/seq_file.txt
@@ -0,0 +1,283 @@
+The seq_file interface
+
+        Copyright 2003 Jonathan Corbet <corbet@lwn.net>
+        This file is originally from the LWN.net Driver Porting series at
+        http://lwn.net/Articles/driver-porting/
+
+
+There are numerous ways for a device driver (or other kernel component) to
+provide information to the user or system administrator.  One useful
+technique is the creation of virtual files, in debugfs, /proc or elsewhere.
+Virtual files can provide human-readable output that is easy to get at
+without any special utility programs; they can also make life easier for
+script writers. It is not surprising that the use of virtual files has
+grown over the years.
+
+Creating those files correctly has always been a bit of a challenge,
+however. It is not that hard to make a virtual file which returns a
+string. But life gets trickier if the output is long - anything greater
+than an application is likely to read in a single operation.  Handling
+multiple reads (and seeks) requires careful attention to the reader's
+position within the virtual file - that position is, likely as not, in the
+middle of a line of output. The kernel has traditionally had a number of
+implementations that got this wrong.
+
+The 2.6 kernel contains a set of functions (implemented by Alexander Viro)
+which are designed to make it easy for virtual file creators to get it
+right.
+
+The seq_file interface is available via <linux/seq_file.h>. There are
+three aspects to seq_file:
+
+     * An iterator interface which lets a virtual file implementation
+       step through the objects it is presenting.
+
+     * Some utility functions for formatting objects for output without
+       needing to worry about things like output buffers.
+
+     * A set of canned file_operations which implement most operations on
+       the virtual file.
+
+We'll look at the seq_file interface via an extremely simple example: a
+loadable module which creates a file called /proc/sequence. The file, when
+read, simply produces a set of increasing integer values, one per line. The
+sequence will continue until the user loses patience and finds something
+better to do. The file is seekable, in that one can do something like the
+following:
+
+    dd if=/proc/sequence of=out1 count=1
+    dd if=/proc/sequence skip=1 out=out2 count=1
+
+Then concatenate the output files out1 and out2 and get the right
+result. Yes, it is a thoroughly useless module, but the point is to show
+how the mechanism works without getting lost in other details.  (Those
+wanting to see the full source for this module can find it at
+http://lwn.net/Articles/22359/).
+
+
+The iterator interface
+
+Modules implementing a virtual file with seq_file must implement a simple
+iterator object that allows stepping through the data of interest.
+Iterators must be able to move to a specific position - like the file they
+implement - but the interpretation of that position is up to the iterator
+itself. A seq_file implementation that is formatting firewall rules, for
+example, could interpret position N as the Nth rule in the chain.
+Positioning can thus be done in whatever way makes the most sense for the
+generator of the data, which need not be aware of how a position translates
+to an offset in the virtual file. The one obvious exception is that a
+position of zero should indicate the beginning of the file.
+
+The /proc/sequence iterator just uses the count of the next number it
+will output as its position.
+
+Four functions must be implemented to make the iterator work. The first,
+called start() takes a position as an argument and returns an iterator
+which will start reading at that position. For our simple sequence example,
+the start() function looks like:
+
+        static void *ct_seq_start(struct seq_file *s, loff_t *pos)
+        {
+                loff_t *spos = kmalloc(sizeof(loff_t), GFP_KERNEL);
+                if (! spos)
+                        return NULL;
+                *spos = *pos;
+                return spos;
+        }
+
+The entire data structure for this iterator is a single loff_t value
+holding the current position. There is no upper bound for the sequence
+iterator, but that will not be the case for most other seq_file
+implementations; in most cases the start() function should check for a
+"past end of file" condition and return NULL if need be.
+
+For more complicated applications, the private field of the seq_file
+structure can be used. There is also a special value whch can be returned
+by the start() function called SEQ_START_TOKEN; it can be used if you wish
+to instruct your show() function (described below) to print a header at the
+top of the output. SEQ_START_TOKEN should only be used if the offset is
+zero, however.
+
+The next function to implement is called, amazingly, next(); its job is to
+move the iterator forward to the next position in the sequence.  The
+example module can simply increment the position by one; more useful
+modules will do what is needed to step through some data structure. The
+next() function returns a new iterator, or NULL if the sequence is
+complete. Here's the example version:
+
+        static void *ct_seq_next(struct seq_file *s, void *v, loff_t *pos)
+        {
+                loff_t *spos = v;
+                *pos = ++*spos;
+                return spos;
+        }
+
+The stop() function is called when iteration is complete; its job, of
+course, is to clean up. If dynamic memory is allocated for the iterator,
+stop() is the place to free it.
+
+        static void ct_seq_stop(struct seq_file *s, void *v)
+        {
+                kfree(v);
+        }
+
+Finally, the show() function should format the object currently pointed to
+by the iterator for output. It should return zero, or an error code if
+something goes wrong. The example module's show() function is:
+
+        static int ct_seq_show(struct seq_file *s, void *v)
+        {
+                loff_t *spos = v;
+                seq_printf(s, "%lld\n", (long long)*spos);
+                return 0;
+        }
+
+We will look at seq_printf() in a moment. But first, the definition of the
+seq_file iterator is finished by creating a seq_operations structure with
+the four functions we have just defined:
+
+        static const struct seq_operations ct_seq_ops = {
+                .start = ct_seq_start,
+                .next  = ct_seq_next,
+                .stop  = ct_seq_stop,
+                .show  = ct_seq_show
+        };
+
+This structure will be needed to tie our iterator to the /proc file in
+a little bit.
+
+It's worth noting that the interator value returned by start() and
+manipulated by the other functions is considered to be completely opaque by
+the seq_file code. It can thus be anything that is useful in stepping
+through the data to be output. Counters can be useful, but it could also be
+a direct pointer into an array or linked list. Anything goes, as long as
+the programmer is aware that things can happen between calls to the
+iterator function. However, the seq_file code (by design) will not sleep
+between the calls to start() and stop(), so holding a lock during that time
+is a reasonable thing to do. The seq_file code will also avoid taking any
+other locks while the iterator is active.
+
+
+Formatted output
+
+The seq_file code manages positioning within the output created by the
+iterator and getting it into the user's buffer. But, for that to work, that
+output must be passed to the seq_file code. Some utility functions have
+been defined which make this task easy.
+
+Most code will simply use seq_printf(), which works pretty much like
+printk(), but which requires the seq_file pointer as an argument. It is
+common to ignore the return value from seq_printf(), but a function
+producing complicated output may want to check that value and quit if
+something non-zero is returned; an error return means that the seq_file
+buffer has been filled and further output will be discarded.
+
+For straight character output, the following functions may be used:
+
+        int seq_putc(struct seq_file *m, char c);
+        int seq_puts(struct seq_file *m, const char *s);
+        int seq_escape(struct seq_file *m, const char *s, const char *esc);
+
+The first two output a single character and a string, just like one would
+expect. seq_escape() is like seq_puts(), except that any character in s
+which is in the string esc will be represented in octal form in the output.
+
+There is also a function for printing filenames:
+
+        int seq_path(struct seq_file *m, struct path *path, char *esc);
+
+Here, path indicates the file of interest, and esc is a set of characters
+which should be escaped in the output.
+
+
+Making it all work
+
+So far, we have a nice set of functions which can produce output within the
+seq_file system, but we have not yet turned them into a file that a user
+can see. Creating a file within the kernel requires, of course, the
+creation of a set of file_operations which implement the operations on that
+file. The seq_file interface provides a set of canned operations which do
+most of the work. The virtual file author still must implement the open()
+method, however, to hook everything up. The open function is often a single
+line, as in the example module:
+
+        static int ct_open(struct inode *inode, struct file *file)
+        {
+                return seq_open(file, &ct_seq_ops);
+        }
+
+Here, the call to seq_open() takes the seq_operations structure we created
+before, and gets set up to iterate through the virtual file.
+
+On a successful open, seq_open() stores the struct seq_file pointer in
+file->private_data. If you have an application where the same iterator can
+be used for more than one file, you can store an arbitrary pointer in the
+private field of the seq_file structure; that value can then be retrieved
+by the iterator functions.
+
+The other operations of interest - read(), llseek(), and release() - are
+all implemented by the seq_file code itself. So a virtual file's
+file_operations structure will look like:
+
+        static const struct file_operations ct_file_ops = {
+                .owner   = THIS_MODULE,
+                .open    = ct_open,
+                .read    = seq_read,
+                .llseek  = seq_lseek,
+                .release = seq_release
+        };
+
+There is also a seq_release_private() which passes the contents of the
+seq_file private field to kfree() before releasing the structure.
+
+The final step is the creation of the /proc file itself. In the example
+code, that is done in the initialization code in the usual way:
+
+        static int ct_init(void)
+        {
+                struct proc_dir_entry *entry;
+
+                entry = create_proc_entry("sequence", 0, NULL);
+                if (entry)
+                        entry->proc_fops = &ct_file_ops;
+                return 0;
+        }
+
+        module_init(ct_init);
+
+And that is pretty much it.
+
+
+seq_list
+
+If your file will be iterating through a linked list, you may find these
+routines useful:
+
+        struct list_head *seq_list_start(struct list_head *head,
+                                         loff_t pos);
+        struct list_head *seq_list_start_head(struct list_head *head,
+                                              loff_t pos);
+        struct list_head *seq_list_next(void *v, struct list_head *head,
+                                        loff_t *ppos);
+
+These helpers will interpret pos as a position within the list and iterate
+accordingly.  Your start() and next() functions need only invoke the
+seq_list_* helpers with a pointer to the appropriate list_head structure.  
+
+
+The extra-simple version
+
+For extremely simple virtual files, there is an even easier interface.  A
+module can define only the show() function, which should create all the
+output that the virtual file will contain. The file's open() method then
+calls:
+
+        int single_open(struct file *file,
+                        int (*show)(struct seq_file *m, void *p),
+                        void *data);
+
+When output time comes, the show() function will be called once. The data
+value given to single_open() can be found in the private field of the
+seq_file structure. When using single_open(), the programmer should use
+single_release() instead of seq_release() in the file_operations structure
+to avoid a memory leak.
diff --git a/Documentation/hrtimers/highres.txt b/Documentation/hrtimers/highres.txt
index ce0e9a91e157..a73ecf5b4bdb 100644
--- a/Documentation/hrtimers/highres.txt
+++ b/Documentation/hrtimers/highres.txt
@@ -98,7 +98,7 @@ System-level global event devices are used for the Linux periodic tick. Per-CPU
 event devices are used to provide local CPU functionality such as process
 accounting, profiling, and high resolution timers.
 
-The management layer assignes one or more of the folliwing functions to a clock
+The management layer assigns one or more of the following functions to a clock
 event device:
       - system global periodic tick (jiffies update)
       - cpu local update_process_times
diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt
index 32e9297ef747..dafd001bf833 100644
--- a/Documentation/kernel-parameters.txt
+++ b/Documentation/kernel-parameters.txt
@@ -844,7 +844,7 @@ and is between 256 and 4096 characters. It is defined in the file
                         arch/alpha/kernel/core_marvel.c.
 
         ip=             [IP_PNP]
-                        See Documentation/nfsroot.txt.
+                        See Documentation/filesystems/nfsroot.txt.
 
         ip2=            [HW] Set IO/IRQ pairs for up to 4 IntelliPort boards
                         See comment before ip2_setup() in
@@ -1198,10 +1198,10 @@ and is between 256 and 4096 characters. It is defined in the file
                         file if at all.
 
         nfsaddrs=       [NFS]
-                        See Documentation/nfsroot.txt.
+                        See Documentation/filesystems/nfsroot.txt.
 
         nfsroot=        [NFS] nfs root filesystem for disk-less boxes.
-                        See Documentation/nfsroot.txt.
+                        See Documentation/filesystems/nfsroot.txt.
 
         nfs.callback_tcpport=
                         [NFS] set the TCP port on which the NFSv4 callback
diff --git a/Documentation/scheduler/00-INDEX b/Documentation/scheduler/00-INDEX
index b5f5ca069b2d..fc234d093fbf 100644
--- a/Documentation/scheduler/00-INDEX
+++ b/Documentation/scheduler/00-INDEX
@@ -12,5 +12,7 @@ sched-domains.txt
         - information on scheduling domains.
 sched-nice-design.txt
         - How and why the scheduler's nice levels are implemented.
+sched-rt-group.txt
+        - real-time group scheduling.
 sched-stats.txt
         - information on schedstats (Linux Scheduler Statistics).
diff --git a/Documentation/sched-rt-group.txt b/Documentation/scheduler/sched-rt-group.txt
index 1c6332f4543c..1c6332f4543c 100644
--- a/Documentation/sched-rt-group.txt
+++ b/Documentation/scheduler/sched-rt-group.txt
diff --git a/Documentation/spinlocks.txt b/Documentation/spinlocks.txt
index 471e75389778..619699dde593 100644
--- a/Documentation/spinlocks.txt
+++ b/Documentation/spinlocks.txt
@@ -5,6 +5,28 @@ Please use DEFINE_SPINLOCK()/DEFINE_RWLOCK() or
 __SPIN_LOCK_UNLOCKED()/__RW_LOCK_UNLOCKED() as appropriate for static
 initialization.
 
+Most of the time, you can simply turn:
+
+        static spinlock_t xxx_lock = SPIN_LOCK_UNLOCKED;
+
+into:
+
+        static DEFINE_SPINLOCK(xxx_lock);
+
+Static structure member variables go from:
+
+        struct foo bar {
+                .lock   =       SPIN_LOCK_UNLOCKED;
+        };
+
+to:
+
+        struct foo bar {
+                .lock   =       __SPIN_LOCK_UNLOCKED(bar.lock);
+        };
+
+Declaration of static rw_locks undergo a similar transformation.
+
 Dynamic initialization, when necessary, may be performed as
 demonstrated below.