diff options
authorLinus Torvalds <>2008-04-11 13:24:16 -0700
committerLinus Torvalds <>2008-04-11 13:24:16 -0700
commit14897e35fdc045fff9baabf0354570da22386706 (patch)
parentb0fac02370cffad956ff3de5e8ed4df7e7b875d7 (diff)
parent14dadf1d5eb5bea2dd115852cfee880505c1c169 (diff)
Merge branch 'docs' of git://
* 'docs' of git:// 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
-rw-r--r--Documentation/filesystems/nfsroot.txt (renamed from Documentation/nfsroot.txt)0
-rw-r--r--Documentation/filesystems/rpc-cache.txt (renamed from Documentation/rpc-cache.txt)0
-rw-r--r--Documentation/scheduler/sched-rt-group.txt (renamed from Documentation/sched-rt-group.txt)0
15 files changed, 380 insertions, 20 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.
- directory with info on various aspects of networking with Linux.
- - short guide on setting up a diskless box with NFS root filesystem.
- info on NMI watchdog for SMP systems.
@@ -321,8 +319,6 @@ robust-futexes.txt
- a description of what robust futexes are.
- info on the Comtrol RocketPort multiport serial driver.
- - introduction to the caching mechanisms in the sunrpc layer.
- description of the RealTime mutex implementation design.
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.
- info on Novell Netware(tm) filesystem using NCP protocol.
+ - short guide on setting up a diskless box with NFS root filesystem.
- info and mount options for the NTFS filesystem (Windows NT).
@@ -82,6 +84,10 @@ relay.txt
- info on relay, for efficient streaming from kernel to user space.
- description of the ROMFS filesystem.
+ - introduction to the caching mechanisms in the sunrpc layer.
+ - how to use the seq_file API
- a description of shared subtrees for namespaces.
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 <>
+ This file is originally from the Driver Porting series at
+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
+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
+ 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
+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.
+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
+ 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
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] 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.
- How and why the scheduler's nice levels are implemented.
+ - real-time group scheduling.
- 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
+Most of the time, you can simply turn:
+ static spinlock_t xxx_lock = SPIN_LOCK_UNLOCKED;
+ static DEFINE_SPINLOCK(xxx_lock);
+Static structure member variables go from:
+ struct foo bar {
+ };
+ 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.
diff --git a/fs/Kconfig b/fs/Kconfig
index d7312825592b..c509123bea49 100644
--- a/fs/Kconfig
+++ b/fs/Kconfig
@@ -1744,10 +1744,10 @@ config ROOT_NFS
If you want your Linux box to mount its whole root file system (the
one containing the directory /) from some other computer over the
net via NFS (presumably because your box doesn't have a hard disk),
- say Y. Read <file:Documentation/nfsroot.txt> for details. It is
- likely that in this case, you also want to say Y to "Kernel level IP
- autoconfiguration" so that your box can discover its network address
- at boot time.
+ say Y. Read <file:Documentation/filesystems/nfsroot.txt> for
+ details. It is likely that in this case, you also want to say Y to
+ "Kernel level IP autoconfiguration" so that your box can discover
+ its network address at boot time.
Most people say N here.
diff --git a/include/linux/spinlock.h b/include/linux/spinlock.h
index 576a5f77d3bd..1129ee0a7180 100644
--- a/include/linux/spinlock.h
+++ b/include/linux/spinlock.h
@@ -341,6 +341,9 @@ static inline void double_spin_unlock(spinlock_t *l1, spinlock_t *l2,
* atomic_dec_and_lock - lock on reaching reference count zero
* @atomic: the atomic counter
* @lock: the spinlock in question
+ *
+ * Decrements @atomic by 1. If the result is 0, returns true and locks
+ * @lock. Returns false for all other cases.
extern int _atomic_dec_and_lock(atomic_t *atomic, spinlock_t *lock);
#define atomic_dec_and_lock(atomic, lock) \
diff --git a/net/ipv4/Kconfig b/net/ipv4/Kconfig
index 9c7e5ffb223d..4670683b4688 100644
--- a/net/ipv4/Kconfig
+++ b/net/ipv4/Kconfig
@@ -160,7 +160,7 @@ config IP_PNP_DHCP
If unsure, say Y. Note that if you want to use DHCP, a DHCP server
must be operating on your network. Read
- <file:Documentation/nfsroot.txt> for details.
+ <file:Documentation/filesystems/nfsroot.txt> for details.
bool "IP: BOOTP support"
@@ -175,7 +175,7 @@ config IP_PNP_BOOTP
does BOOTP itself, providing all necessary information on the kernel
command line, you can say N here. If unsure, say Y. Note that if you
want to use BOOTP, a BOOTP server must be operating on your network.
- Read <file:Documentation/nfsroot.txt> for details.
+ Read <file:Documentation/filesystems/nfsroot.txt> for details.
config IP_PNP_RARP
bool "IP: RARP support"
@@ -187,8 +187,8 @@ config IP_PNP_RARP
discovered automatically at boot time using the RARP protocol (an
older protocol which is being obsoleted by BOOTP and DHCP), say Y
here. Note that if you want to use RARP, a RARP server must be
- operating on your network. Read <file:Documentation/nfsroot.txt> for
- details.
+ operating on your network. Read
+ <file:Documentation/filesystems/nfsroot.txt> for details.
# not yet ready..
# bool ' IP: ARP support' CONFIG_IP_PNP_ARP
diff --git a/net/ipv4/ipconfig.c b/net/ipv4/ipconfig.c
index 7c992fbbc2c3..4824fe8996bf 100644
--- a/net/ipv4/ipconfig.c
+++ b/net/ipv4/ipconfig.c
@@ -1411,7 +1411,7 @@ late_initcall(ip_auto_config);
* Decode any IP configuration options in the "ip=" or "nfsaddrs=" kernel
- * command line parameter. See Documentation/nfsroot.txt.
+ * command line parameter. See Documentation/filesystems/nfsroot.txt.
static int __init ic_proto_name(char *name)