4 files changed, 761 insertions, 0 deletions

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/filesystems/nfsroot.txt b/Documentation/filesystems/nfsroot.txt
new file mode 100644
index 000000000000..31b329172343
--- /dev/null
+++ b/Documentation/filesystems/nfsroot.txt
@@ -0,0 +1,270 @@
+Mounting the root filesystem via NFS (nfsroot)
+===============================================
+
+Written 1996 by Gero Kuhlmann <gero@gkminix.han.de>
+Updated 1997 by Martin Mares <mj@atrey.karlin.mff.cuni.cz>
+Updated 2006 by Nico Schottelius <nico-kernel-nfsroot@schottelius.org>
+Updated 2006 by Horms <horms@verge.net.au>
+
+
+
+In order to use a diskless system, such as an X-terminal or printer server
+for example, it is necessary for the root filesystem to be present on a
+non-disk device. This may be an initramfs (see Documentation/filesystems/
+ramfs-rootfs-initramfs.txt), a ramdisk (see Documentation/initrd.txt) or a
+filesystem mounted via NFS. The following text describes on how to use NFS
+for the root filesystem. For the rest of this text 'client' means the
+diskless system, and 'server' means the NFS server.
+
+
+
+
+1.) Enabling nfsroot capabilities
+    -----------------------------
+
+In order to use nfsroot, NFS client support needs to be selected as
+built-in during configuration. Once this has been selected, the nfsroot
+option will become available, which should also be selected.
+
+In the networking options, kernel level autoconfiguration can be selected,
+along with the types of autoconfiguration to support. Selecting all of
+DHCP, BOOTP and RARP is safe.
+
+
+
+
+2.) Kernel command line
+    -------------------
+
+When the kernel has been loaded by a boot loader (see below) it needs to be
+told what root fs device to use. And in the case of nfsroot, where to find
+both the server and the name of the directory on the server to mount as root.
+This can be established using the following kernel command line parameters:
+
+
+root=/dev/nfs
+
+  This is necessary to enable the pseudo-NFS-device. Note that it's not a
+  real device but just a synonym to tell the kernel to use NFS instead of
+  a real device.
+
+
+nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]
+
+  If the `nfsroot' parameter is NOT given on the command line,
+  the default "/tftpboot/%s" will be used.
+
+  <server-ip>   Specifies the IP address of the NFS server.
+                The default address is determined by the `ip' parameter
+                (see below). This parameter allows the use of different
+                servers for IP autoconfiguration and NFS.
+
+  <root-dir>    Name of the directory on the server to mount as root.
+                If there is a "%s" token in the string, it will be
+                replaced by the ASCII-representation of the client's
+                IP address.
+
+  <nfs-options> Standard NFS options. All options are separated by commas.
+                The following defaults are used:
+                        port            = as given by server portmap daemon
+                        rsize           = 4096
+                        wsize           = 4096
+                        timeo           = 7
+                        retrans         = 3
+                        acregmin        = 3
+                        acregmax        = 60
+                        acdirmin        = 30
+                        acdirmax        = 60
+                        flags           = hard, nointr, noposix, cto, ac
+
+
+ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>
+
+  This parameter tells the kernel how to configure IP addresses of devices
+  and also how to set up the IP routing table. It was originally called
+  `nfsaddrs', but now the boot-time IP configuration works independently of
+  NFS, so it was renamed to `ip' and the old name remained as an alias for
+  compatibility reasons.
+
+  If this parameter is missing from the kernel command line, all fields are
+  assumed to be empty, and the defaults mentioned below apply. In general
+  this means that the kernel tries to configure everything using
+  autoconfiguration.
+
+  The <autoconf> parameter can appear alone as the value to the `ip'
+  parameter (without all the ':' characters before).  If the value is
+  "ip=off" or "ip=none", no autoconfiguration will take place, otherwise
+  autoconfiguration will take place.  The most common way to use this
+  is "ip=dhcp".
+
+  <client-ip>   IP address of the client.
+
+                Default:  Determined using autoconfiguration.
+
+  <server-ip>   IP address of the NFS server. If RARP is used to determine
+                the client address and this parameter is NOT empty only
+                replies from the specified server are accepted.
+
+                Only required for for NFS root. That is autoconfiguration
+                will not be triggered if it is missing and NFS root is not
+                in operation.
+
+                Default: Determined using autoconfiguration.
+                         The address of the autoconfiguration server is used.
+
+  <gw-ip>       IP address of a gateway if the server is on a different subnet.
+
+                Default: Determined using autoconfiguration.
+
+  <netmask>     Netmask for local network interface. If unspecified
+                the netmask is derived from the client IP address assuming
+                classful addressing.
+
+                Default:  Determined using autoconfiguration.
+
+  <hostname>    Name of the client. May be supplied by autoconfiguration,
+                but its absence will not trigger autoconfiguration.
+
+                Default: Client IP address is used in ASCII notation.
+
+  <device>      Name of network device to use.
+
+                Default: If the host only has one device, it is used.
+                         Otherwise the device is determined using
+                         autoconfiguration. This is done by sending
+                         autoconfiguration requests out of all devices,
+                         and using the device that received the first reply.
+
+  <autoconf>    Method to use for autoconfiguration. In the case of options
+                which specify multiple autoconfiguration protocols,
+                requests are sent using all protocols, and the first one
+                to reply is used.
+
+                Only autoconfiguration protocols that have been compiled
+                into the kernel will be used, regardless of the value of
+                this option.
+
+                  off or none: don't use autoconfiguration
+                                (do static IP assignment instead)
+                  on or any:   use any protocol available in the kernel
+                               (default)
+                  dhcp:        use DHCP
+                  bootp:       use BOOTP
+                  rarp:        use RARP
+                  both:        use both BOOTP and RARP but not DHCP
+                               (old option kept for backwards compatibility)
+
+                Default: any
+
+
+
+
+3.) Boot Loader
+    ----------
+
+To get the kernel into memory different approaches can be used.
+They depend on various facilities being available:
+
+
+3.1)  Booting from a floppy using syslinux
+
+        When building kernels, an easy way to create a boot floppy that uses
+        syslinux is to use the zdisk or bzdisk make targets which use
+        and bzimage images respectively. Both targets accept the
+        FDARGS parameter which can be used to set the kernel command line.
+
+        e.g.
+           make bzdisk FDARGS="root=/dev/nfs"
+
+        Note that the user running this command will need to have
+        access to the floppy drive device, /dev/fd0
+
+        For more information on syslinux, including how to create bootdisks
+        for prebuilt kernels, see http://syslinux.zytor.com/
+
+        N.B: Previously it was possible to write a kernel directly to
+             a floppy using dd, configure the boot device using rdev, and
+             boot using the resulting floppy. Linux no longer supports this
+             method of booting.
+
+3.2) Booting from a cdrom using isolinux
+
+        When building kernels, an easy way to create a bootable cdrom that
+        uses isolinux is to use the isoimage target which uses a bzimage
+        image. Like zdisk and bzdisk, this target accepts the FDARGS
+        parameter which can be used to set the kernel command line.
+
+        e.g.
+          make isoimage FDARGS="root=/dev/nfs"
+
+        The resulting iso image will be arch/<ARCH>/boot/image.iso
+        This can be written to a cdrom using a variety of tools including
+        cdrecord.
+
+        e.g.
+          cdrecord dev=ATAPI:1,0,0 arch/i386/boot/image.iso
+
+        For more information on isolinux, including how to create bootdisks
+        for prebuilt kernels, see http://syslinux.zytor.com/
+
+3.2) Using LILO
+        When using LILO all the necessary command line parameters may be
+        specified using the 'append=' directive in the LILO configuration
+        file.
+
+        However, to use the 'root=' directive you also need to create
+        a dummy root device, which may be removed after LILO is run.
+
+        mknod /dev/boot255 c 0 255
+
+        For information on configuring LILO, please refer to its documentation.
+
+3.3) Using GRUB
+        When using GRUB, kernel parameter are simply appended after the kernel
+        specification: kernel <kernel> <parameters>
+
+3.4) Using loadlin
+        loadlin may be used to boot Linux from a DOS command prompt without
+        requiring a local hard disk to mount as root. This has not been
+        thoroughly tested by the authors of this document, but in general
+        it should be possible configure the kernel command line similarly
+        to the configuration of LILO.
+
+        Please refer to the loadlin documentation for further information.
+
+3.5) Using a boot ROM
+        This is probably the most elegant way of booting a diskless client.
+        With a boot ROM the kernel is loaded using the TFTP protocol. The
+        authors of this document are not aware of any no commercial boot
+        ROMs that support booting Linux over the network. However, there
+        are two free implementations of a boot ROM, netboot-nfs and
+        etherboot, both of which are available on sunsite.unc.edu, and both
+        of which contain everything you need to boot a diskless Linux client.
+
+3.6) Using pxelinux
+        Pxelinux may be used to boot linux using the PXE boot loader
+        which is present on many modern network cards.
+
+        When using pxelinux, the kernel image is specified using
+        "kernel <relative-path-below /tftpboot>". The nfsroot parameters
+        are passed to the kernel by adding them to the "append" line.
+        It is common to use serial console in conjunction with pxeliunx,
+        see Documentation/serial-console.txt for more information.
+
+        For more information on isolinux, including how to create bootdisks
+        for prebuilt kernels, see http://syslinux.zytor.com/
+
+
+
+
+4.) Credits
+    -------
+
+  The nfsroot code in the kernel and the RARP support have been written
+  by Gero Kuhlmann <gero@gkminix.han.de>.
+
+  The rest of the IP layer autoconfiguration code has been written
+  by Martin Mares <mj@atrey.karlin.mff.cuni.cz>.
+
+  In order to write the initial version of nfsroot I would like to thank
+  Jens-Uwe Mager <jum@anubis.han.de> for his help.
diff --git a/Documentation/filesystems/rpc-cache.txt b/Documentation/filesystems/rpc-cache.txt
new file mode 100644
index 000000000000..8a382bea6808
--- /dev/null
+++ b/Documentation/filesystems/rpc-cache.txt
@@ -0,0 +1,202 @@
+        This document gives a brief introduction to the caching
+mechanisms in the sunrpc layer that is used, in particular,
+for NFS authentication.
+
+CACHES
+======
+The caching replaces the old exports table and allows for
+a wide variety of values to be caches.
+
+There are a number of caches that are similar in structure though
+quite possibly very different in content and use.  There is a corpus
+of common code for managing these caches.
+
+Examples of caches that are likely to be needed are:
+  - mapping from IP address to client name
+  - mapping from client name and filesystem to export options
+  - mapping from UID to list of GIDs, to work around NFS's limitation
+    of 16 gids.
+  - mappings between local UID/GID and remote UID/GID for sites that
+    do not have uniform uid assignment
+  - mapping from network identify to public key for crypto authentication.
+
+The common code handles such things as:
+   - general cache lookup with correct locking
+   - supporting 'NEGATIVE' as well as positive entries
+   - allowing an EXPIRED time on cache items, and removing
+     items after they expire, and are no longer in-use.
+   - making requests to user-space to fill in cache entries
+   - allowing user-space to directly set entries in the cache
+   - delaying RPC requests that depend on as-yet incomplete
+     cache entries, and replaying those requests when the cache entry
+     is complete.
+   - clean out old entries as they expire.
+
+Creating a Cache
+----------------
+
+1/ A cache needs a datum to store.  This is in the form of a
+   structure definition that must contain a
+     struct cache_head
+   as an element, usually the first.
+   It will also contain a key and some content.
+   Each cache element is reference counted and contains
+   expiry and update times for use in cache management.
+2/ A cache needs a "cache_detail" structure that
+   describes the cache.  This stores the hash table, some
+   parameters for cache management, and some operations detailing how
+   to work with particular cache items.
+   The operations requires are:
+        struct cache_head *alloc(void)
+                This simply allocates appropriate memory and returns
+                a pointer to the cache_detail embedded within the
+                structure
+        void cache_put(struct kref *)
+                This is called when the last reference to an item is
+                dropped.  The pointer passed is to the 'ref' field
+                in the cache_head.  cache_put should release any
+                references create by 'cache_init' and, if CACHE_VALID
+                is set, any references created by cache_update.
+                It should then release the memory allocated by
+                'alloc'.
+        int match(struct cache_head *orig, struct cache_head *new)
+                test if the keys in the two structures match.  Return
+                1 if they do, 0 if they don't.
+        void init(struct cache_head *orig, struct cache_head *new)
+                Set the 'key' fields in 'new' from 'orig'.  This may
+                include taking references to shared objects.
+        void update(struct cache_head *orig, struct cache_head *new)
+                Set the 'content' fileds in 'new' from 'orig'.
+        int cache_show(struct seq_file *m, struct cache_detail *cd,
+                        struct cache_head *h)
+                Optional.  Used to provide a /proc file that lists the
+                contents of a cache.  This should show one item,
+                usually on just one line.
+        int cache_request(struct cache_detail *cd, struct cache_head *h,
+                char **bpp, int *blen)
+                Format a request to be send to user-space for an item
+                to be instantiated.  *bpp is a buffer of size *blen.
+                bpp should be moved forward over the encoded message,
+                and  *blen should be reduced to show how much free
+                space remains.  Return 0 on success or <0 if not
+                enough room or other problem.
+        int cache_parse(struct cache_detail *cd, char *buf, int len)
+                A message from user space has arrived to fill out a
+                cache entry.  It is in 'buf' of length 'len'.
+                cache_parse should parse this, find the item in the
+                cache with sunrpc_cache_lookup, and update the item
+                with sunrpc_cache_update.
+
+
+3/ A cache needs to be registered using cache_register().  This
+   includes it on a list of caches that will be regularly
+   cleaned to discard old data.
+
+Using a cache
+-------------
+
+To find a value in a cache, call sunrpc_cache_lookup passing a pointer
+to the cache_head in a sample item with the 'key' fields filled in.
+This will be passed to ->match to identify the target entry.  If no
+entry is found, a new entry will be create, added to the cache, and
+marked as not containing valid data.
+
+The item returned is typically passed to cache_check which will check
+if the data is valid, and may initiate an up-call to get fresh data.
+cache_check will return -ENOENT in the entry is negative or if an up
+call is needed but not possible, -EAGAIN if an upcall is pending,
+or 0 if the data is valid;
+
+cache_check can be passed a "struct cache_req *".  This structure is
+typically embedded in the actual request and can be used to create a
+deferred copy of the request (struct cache_deferred_req).  This is
+done when the found cache item is not uptodate, but the is reason to
+believe that userspace might provide information soon.  When the cache
+item does become valid, the deferred copy of the request will be
+revisited (->revisit).  It is expected that this method will
+reschedule the request for processing.
+
+The value returned by sunrpc_cache_lookup can also be passed to
+sunrpc_cache_update to set the content for the item.  A second item is
+passed which should hold the content.  If the item found by _lookup
+has valid data, then it is discarded and a new item is created.  This
+saves any user of an item from worrying about content changing while
+it is being inspected.  If the item found by _lookup does not contain
+valid data, then the content is copied across and CACHE_VALID is set.
+
+Populating a cache
+------------------
+
+Each cache has a name, and when the cache is registered, a directory
+with that name is created in /proc/net/rpc
+
+This directory contains a file called 'channel' which is a channel
+for communicating between kernel and user for populating the cache.
+This directory may later contain other files of interacting
+with the cache.
+
+The 'channel' works a bit like a datagram socket. Each 'write' is
+passed as a whole to the cache for parsing and interpretation.
+Each cache can treat the write requests differently, but it is
+expected that a message written will contain:
+  - a key
+  - an expiry time
+  - a content.
+with the intention that an item in the cache with the give key
+should be create or updated to have the given content, and the
+expiry time should be set on that item.
+
+Reading from a channel is a bit more interesting.  When a cache
+lookup fails, or when it succeeds but finds an entry that may soon
+expire, a request is lodged for that cache item to be updated by
+user-space.  These requests appear in the channel file.
+
+Successive reads will return successive requests.
+If there are no more requests to return, read will return EOF, but a
+select or poll for read will block waiting for another request to be
+added.
+
+Thus a user-space helper is likely to:
+  open the channel.
+    select for readable
+    read a request
+    write a response
+  loop.
+
+If it dies and needs to be restarted, any requests that have not been
+answered will still appear in the file and will be read by the new
+instance of the helper.
+
+Each cache should define a "cache_parse" method which takes a message
+written from user-space and processes it.  It should return an error
+(which propagates back to the write syscall) or 0.
+
+Each cache should also define a "cache_request" method which
+takes a cache item and encodes a request into the buffer
+provided.
+
+Note: If a cache has no active readers on the channel, and has had not
+active readers for more than 60 seconds, further requests will not be
+added to the channel but instead all lookups that do not find a valid
+entry will fail.  This is partly for backward compatibility: The
+previous nfs exports table was deemed to be authoritative and a
+failed lookup meant a definite 'no'.
+
+request/response format
+-----------------------
+
+While each cache is free to use it's own format for requests
+and responses over channel, the following is recommended as
+appropriate and support routines are available to help:
+Each request or response record should be printable ASCII
+with precisely one newline character which should be at the end.
+Fields within the record should be separated by spaces, normally one.
+If spaces, newlines, or nul characters are needed in a field they
+much be quoted.  two mechanisms are available:
+1/ If a field begins '\x' then it must contain an even number of
+   hex digits, and pairs of these digits provide the bytes in the
+   field.
+2/ otherwise a \ in the field must be followed by 3 octal digits
+   which give the code for a byte.  Other characters are treated
+   as them selves.  At the very least, space, newline, nul, and
+   '\' must be quoted in this way.
diff --git a/Documentation/filesystems/seq_file.txt b/Documentation/filesystems/seq_file.txt
new file mode 100644
index 000000000000..7fb8e6dc62bf
--- /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 which 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 iterator 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.