diff options
Diffstat (limited to 'Documentation/DocBook')
| -rw-r--r-- | Documentation/DocBook/Makefile | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/filesystems.tmpl (renamed from Documentation/DocBook/journal-api.tmpl) | 252 | ||||
| -rw-r--r-- | Documentation/DocBook/kernel-api.tmpl | 60 |
3 files changed, 161 insertions, 153 deletions
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 66e1cf733571..db9499adbed4 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -9,7 +9,7 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ procfs-guide.xml writing_usb_driver.xml \ - kernel-api.xml journal-api.xml lsm.xml usb.xml \ + kernel-api.xml filesystems.xml lsm.xml usb.xml \ gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ genericirq.xml diff --git a/Documentation/DocBook/journal-api.tmpl b/Documentation/DocBook/filesystems.tmpl index 2077f9a28c19..39fa2aba7f9b 100644 --- a/Documentation/DocBook/journal-api.tmpl +++ b/Documentation/DocBook/filesystems.tmpl @@ -2,39 +2,11 @@ <!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="LinuxJBDAPI"> +<book id="Linux-filesystems-API"> <bookinfo> - <title>The Linux Journalling API</title> - <authorgroup> - <author> - <firstname>Roger</firstname> - <surname>Gammans</surname> - <affiliation> - <address> - <email>rgammans@computer-surgery.co.uk</email> - </address> - </affiliation> - </author> - </authorgroup> - - <authorgroup> - <author> - <firstname>Stephen</firstname> - <surname>Tweedie</surname> - <affiliation> - <address> - <email>sct@redhat.com</email> - </address> - </affiliation> - </author> - </authorgroup> + <title>Linux Filesystems API</title> - <copyright> - <year>2002</year> - <holder>Roger Gammans</holder> - </copyright> - -<legalnotice> + <legalnotice> <para> This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public @@ -42,21 +14,21 @@ 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. @@ -66,17 +38,113 @@ <toc></toc> - <chapter id="Overview"> + <chapter id="vfs"> + <title>The Linux VFS</title> + <sect1><title>The Filesystem types</title> +!Iinclude/linux/fs.h + </sect1> + <sect1><title>The Directory Cache</title> +!Efs/dcache.c +!Iinclude/linux/dcache.h + </sect1> + <sect1><title>Inode Handling</title> +!Efs/inode.c +!Efs/bad_inode.c + </sect1> + <sect1><title>Registration and Superblocks</title> +!Efs/super.c + </sect1> + <sect1><title>File Locks</title> +!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="proc"> + <title>The proc filesystem</title> + + <sect1><title>sysctl interface</title> +!Ekernel/sysctl.c + </sect1> + + <sect1><title>proc filesystem interface</title> +!Ifs/proc/base.c + </sect1> + </chapter> + + <chapter id="sysfs"> + <title>The Filesystem for Exporting Kernel Objects</title> +!Efs/sysfs/file.c +!Efs/sysfs/symlink.c +!Efs/sysfs/bin.c + </chapter> + + <chapter id="debugfs"> + <title>The debugfs filesystem</title> + + <sect1><title>debugfs interface</title> +!Efs/debugfs/inode.c +!Efs/debugfs/file.c + </sect1> + </chapter> + + <chapter id="LinuxJDBAPI"> + <chapterinfo> + <title>The Linux Journalling API</title> + + <authorgroup> + <author> + <firstname>Roger</firstname> + <surname>Gammans</surname> + <affiliation> + <address> + <email>rgammans@computer-surgery.co.uk</email> + </address> + </affiliation> + </author> + </authorgroup> + + <authorgroup> + <author> + <firstname>Stephen</firstname> + <surname>Tweedie</surname> + <affiliation> + <address> + <email>sct@redhat.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2002</year> + <holder>Roger Gammans</holder> + </copyright> + </chapterinfo> + + <title>The Linux Journalling API</title> + + <sect1> <title>Overview</title> - <sect1> + <sect2> <title>Details</title> <para> -The journalling layer is easy to use. You need to +The journalling layer is easy to use. You need to first of all create a journal_t data structure. There are two calls to do this dependent on how you decide to allocate the physical -media on which the journal resides. The journal_init_inode() call +media on which the journal resides. The journal_init_inode() call is for journals stored in filesystem inodes, or the journal_init_dev() -call can be use for journal stored on a raw device (in a continuous range +call can be use for journal stored on a raw device (in a continuous range of blocks). A journal_t is a typedef for a struct pointer, so when you are finally finished make sure you call journal_destroy() on it to free up any used kernel memory. @@ -91,27 +159,26 @@ need to call journal_create(). <para> Most of the time however your journal file will already have been created, but before you load it you must call journal_wipe() to empty the journal file. -Hang on, you say , what if the filesystem wasn't cleanly umount()'d . Well, it is the +Hang on, you say , what if the filesystem wasn't cleanly umount()'d . Well, it is the job of the client file system to detect this and skip the call to journal_wipe(). </para> <para> In either case the next call should be to journal_load() which prepares the -journal file for use. Note that journal_wipe(..,0) calls journal_skip_recovery() +journal file for use. Note that journal_wipe(..,0) calls journal_skip_recovery() for you if it detects any outstanding transactions in the journal and similarly journal_load() will call journal_recover() if necessary. I would advise reading fs/ext3/super.c for examples on this stage. -[RGG: Why is the journal_wipe() call necessary - doesn't this needlessly -complicate the API. Or isn't a good idea for the journal layer to hide +[RGG: Why is the journal_wipe() call necessary - doesn't this needlessly +complicate the API. Or isn't a good idea for the journal layer to hide dirty mounts from the client fs] </para> <para> -Now you can go ahead and start modifying the underlying +Now you can go ahead and start modifying the underlying filesystem. Almost. </para> - <para> You still need to actually journal your filesystem changes, this @@ -138,10 +205,10 @@ individual buffers (blocks). Before you start to modify a buffer you need to call journal_get_{create,write,undo}_access() as appropriate, this allows the journalling layer to copy the unmodified data if it needs to. After all the buffer may be part of a previously uncommitted -transaction. +transaction. At this point you are at last ready to modify a buffer, and once you are have done so you need to call journal_dirty_{meta,}data(). -Or if you've asked for access to a buffer you now know is now longer +Or if you've asked for access to a buffer you now know is now longer required to be pushed back on the device you can call journal_forget() in much the same way as you might have used bforget() in the past. </para> @@ -156,7 +223,6 @@ Then at umount time , in your put_super() (2.4) or write_super() (2.5) you can then call journal_destroy() to clean up your in-core journal object. </para> - <para> Unfortunately there a couple of ways the journal layer can cause a deadlock. The first thing to note is that each task can only have @@ -164,19 +230,19 @@ a single outstanding transaction at any one time, remember nothing commits until the outermost journal_stop(). This means you must complete the transaction at the end of each file/inode/address etc. operation you perform, so that the journalling system isn't re-entered -on another journal. Since transactions can't be nested/batched +on another journal. Since transactions can't be nested/batched across differing journals, and another filesystem other than yours (say ext3) may be modified in a later syscall. </para> <para> -The second case to bear in mind is that journal_start() can -block if there isn't enough space in the journal for your transaction +The second case to bear in mind is that journal_start() can +block if there isn't enough space in the journal for your transaction (based on the passed nblocks param) - when it blocks it merely(!) needs to -wait for transactions to complete and be committed from other tasks, -so essentially we are waiting for journal_stop(). So to avoid +wait for transactions to complete and be committed from other tasks, +so essentially we are waiting for journal_stop(). So to avoid deadlocks you must treat journal_start/stop() as if they -were semaphores and include them in your semaphore ordering rules to prevent +were semaphores and include them in your semaphore ordering rules to prevent deadlocks. Note that journal_extend() has similar blocking behaviour to journal_start() so you can deadlock here just as easily as on journal_start(). </para> @@ -184,7 +250,7 @@ journal_start() so you can deadlock here just as easily as on journal_start(). <para> Try to reserve the right number of blocks the first time. ;-). This will be the maximum number of blocks you are going to touch in this transaction. -I advise having a look at at least ext3_jbd.h to see the basis on which +I advise having a look at at least ext3_jbd.h to see the basis on which ext3 uses to make these decisions. </para> @@ -193,13 +259,13 @@ Another wriggle to watch out for is your on-disk block allocation strategy. why? Because, if you undo a delete, you need to ensure you haven't reused any of the freed blocks in a later transaction. One simple way of doing this is make sure any blocks you allocate only have checkpointed transactions -listed against them. Ext3 does this in ext3_test_allocatable(). +listed against them. Ext3 does this in ext3_test_allocatable(). </para> <para> Lock is also providing through journal_{un,}lock_updates(), ext3 uses this when it wants a window with a clean and stable fs for a moment. -eg. +eg. </para> <programlisting> @@ -230,19 +296,19 @@ extend it like this:- struct journal_callback for_jbd; // Stuff for myfs allocated together. myfs_inode* i_commited; - + } </programlisting> <para> -this would be useful if you needed to know when data was committed to a +this would be useful if you needed to know when data was committed to a particular inode. </para> -</sect1> + </sect2> -<sect1> -<title>Summary</title> + <sect2> + <title>Summary</title> <para> Using the journal is a matter of wrapping the different context changes, being each mount, each modification (transaction) and each changed buffer @@ -260,15 +326,15 @@ an example. if (clean) journal_wipe(); journal_load(); - foreach(transaction) { /*transactions must be + foreach(transaction) { /*transactions must be completed before - a syscall returns to + a syscall returns to userspace*/ handle_t * xct=journal_start(my_jnrl); foreach(bh) { journal_get_{create,write,undo}_access(xact,bh); - if ( myfs_modify(bh) ) { /* returns true + if ( myfs_modify(bh) ) { /* returns true if makes changes */ journal_dirty_{meta,}data(xact,bh); } else { @@ -279,55 +345,57 @@ an example. } journal_destroy(my_jrnl); </programlisting> -</sect1> + </sect2> -</chapter> + </sect1> - <chapter id="adt"> + <sect1> <title>Data Types</title> - <para> + <para> The journalling layer uses typedefs to 'hide' the concrete definitions of the structures used. As a client of the JBD layer you can just rely on the using the pointer as a magic cookie of some sort. - + Obviously the hiding is not enforced as this is 'C'. - </para> - <sect1><title>Structures</title> + </para> + <sect2><title>Structures</title> !Iinclude/linux/jbd.h - </sect1> -</chapter> + </sect2> + </sect1> - <chapter id="calls"> + <sect1> <title>Functions</title> - <para> + <para> The functions here are split into two groups those that affect a journal as a whole, and those which are used to manage transactions -</para> - <sect1><title>Journal Level</title> + </para> + <sect2><title>Journal Level</title> !Efs/jbd/journal.c !Ifs/jbd/recovery.c - </sect1> - <sect1><title>Transasction Level</title> -!Efs/jbd/transaction.c - </sect1> -</chapter> -<chapter> + </sect2> + <sect2><title>Transasction Level</title> +!Efs/jbd/transaction.c + </sect2> + </sect1> + <sect1> <title>See also</title> <para> - <citation> + <citation> <ulink url="ftp://ftp.uk.linux.org/pub/linux/sct/fs/jfs/journal-design.ps.gz"> - Journaling the Linux ext2fs Filesystem,LinuxExpo 98, Stephen Tweedie + Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen Tweedie </ulink> - </citation> - </para> - <para> + </citation> + </para> + <para> <citation> <ulink url="http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html"> - Ext3 Journalling FileSystem , OLS 2000, Dr. Stephen Tweedie + Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen Tweedie </ulink> </citation> - </para> -</chapter> + </para> + </sect1> + + </chapter> </book> diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index 2b5ac604948c..a166675c4303 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -182,66 +182,6 @@ X!Ilib/string.c </sect1> </chapter> - <chapter id="vfs"> - <title>The Linux VFS</title> - <sect1><title>The Filesystem types</title> -!Iinclude/linux/fs.h - </sect1> - <sect1><title>The Directory Cache</title> -!Efs/dcache.c -!Iinclude/linux/dcache.h - </sect1> - <sect1><title>Inode Handling</title> -!Efs/inode.c -!Efs/bad_inode.c - </sect1> - <sect1><title>Registration and Superblocks</title> -!Efs/super.c - </sect1> - <sect1><title>File Locks</title> -!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="proc"> - <title>The proc filesystem</title> - - <sect1><title>sysctl interface</title> -!Ekernel/sysctl.c - </sect1> - - <sect1><title>proc filesystem interface</title> -!Ifs/proc/base.c - </sect1> - </chapter> - - <chapter id="sysfs"> - <title>The Filesystem for Exporting Kernel Objects</title> -!Efs/sysfs/file.c -!Efs/sysfs/symlink.c -!Efs/sysfs/bin.c - </chapter> - - <chapter id="debugfs"> - <title>The debugfs filesystem</title> - - <sect1><title>debugfs interface</title> -!Efs/debugfs/inode.c -!Efs/debugfs/file.c - </sect1> - </chapter> - <chapter id="relayfs"> <title>relay interface support</title> |