ext4-documentation-update.patch

   1 ext4: Documentation updates.
   2
   3 From: Jose R. Santos <jrs@us.ibm.com>
   4
   5 Some of the information in Documentation/filesystems/ext4.txt is out
   6 of date and in need of an update.
   7
   8 Signed-off-by: Jose R. Santos <jrs@us.ibm.com>
   9 Signed-off-by: "Theodore Ts'o" <tytso@mit.edu>
  10 diff --git a/Documentation/filesystems/ext4.txt b/Documentation/filesystems/ext4.txt
  11 index 0c5086d..77ed8fe 100644
  12 --- a/Documentation/filesystems/ext4.txt
  13 +++ b/Documentation/filesystems/ext4.txt
  14 @@ -13,72 +13,85 @@ Mailing list: linux-ext4@vger.kernel.org
  15  1. Quick usage instructions:
  16  ===========================
  17
  18 -  - Grab updated e2fsprogs from
  19 +  - Compile and install the latest version of e2fsprogs (at least
  20 +    1.41-WIP-0617) from:
  21 +
  22      ftp://ftp.kernel.org/pub/linux/kernel/people/tytso/e2fsprogs-interim/
  23 -    This is a patchset on top of e2fsprogs-1.39, which can be found at
  24 -    ftp://ftp.kernel.org/pub/linux/kernel/people/tytso/e2fsprogs/
  25
  26 -  - It's still mke2fs -j /dev/hda1
  27 +    or grab the latest git repository from:
  28 +
  29 +    git://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git
  30 +
  31 +  - Create a new filesystem using the ext4dev filesystem type:
  32 +
  33 +       # mke2fs -t ext4dev /dev/hda1
  34 +
  35 +    Or configure an existing ext3 filesystem to support extents and set
  36 +    the test_fs flag to indicate that it's ok for an in-development
  37 +    filesystem to touch this filesystem:
  38
  39 -  - mount /dev/hda1 /wherever -t ext4dev
  40 +       # tune2fs -O extents -E test_fs /dev/hda1
  41
  42 -  - To enable extents,
  43 +    If the filesystem was created with 128 byte inodes, it can be
  44 +    converted to use 256 byte for greater efficiency via:
  45
  46 -       mount /dev/hda1 /wherever -t ext4dev -o extents
  47 +        # tune2fs -I 256 /dev/hda1
  48
  49 -  - The filesystem is compatible with the ext3 driver until you add a file
  50 -    which has extents (ie: `mount -o extents', then create a file).
  51 +    (Note: we currently do not have tools to convert an ext4dev
  52 +    filesystem back to ext3; so please do not do try this on production
  53 +    filesystems.)
  54
  55 -    NOTE: The "extents" mount flag is temporary.  It will soon go away and
  56 -    extents will be enabled by the "-o extents" flag to mke2fs or tune2fs
  57 +  - Mounting:
  58 +
  59 +       # mount -t ext4dev /dev/hda1 /wherever
  60
  61    - When comparing performance with other filesystems, remember that
  62 -    ext3/4 by default offers higher data integrity guarantees than most.  So
  63 -    when comparing with a metadata-only journalling filesystem, use `mount -o
  64 -    data=writeback'.  And you might as well use `mount -o nobh' too along
  65 -    with it.  Making the journal larger than the mke2fs default often helps
  66 -    performance with metadata-intensive workloads.
  67 +    ext3/4 by default offers higher data integrity guarantees than most.
  68 +    So when comparing with a metadata-only journalling filesystem, such
  69 +    as ext3, use `mount -o data=writeback'.  And you might as well use
  70 +    `mount -o nobh' too along with it.  Making the journal larger than
  71 +    the mke2fs default often helps performance with metadata-intensive
  72 +    workloads.
  73
  74  2. Features
  75  ===========
  76
  77  2.1 Currently available
  78
  79 -* ability to use filesystems > 16TB
  80 +* ability to use filesystems > 16TB (e2fsprogs support not available yet)
  81  * extent format reduces metadata overhead (RAM, IO for access, transactions)
  82  * extent format more robust in face of on-disk corruption due to magics,
  83  * internal redunancy in tree
  84 -
  85 -2.1 Previously available, soon to be enabled by default by "mkefs.ext4":
  86 -
  87 -* dir_index and resize inode will be on by default
  88 -* large inodes will be used by default for fast EAs, nsec timestamps, etc
  89 +* improved file allocation (multi-block alloc, delayed alloc)
  90 +* fix 32000 subdirectory limit
  91 +* nsec timestamps for mtime, atime, ctime, create time
  92 +* inode version field on disk (NFSv4, Lustre)
  93 +* reduced e2fsck time via uninit_bg feature
  94 +* journal checksumming for robustness, performance
  95 +* persistent file preallocation (e.g for streaming media, databases)
  96 +* ability to pack bitmaps and inode tables into larger virtual groups via the
  97 +  flex_bg feature
  98 +* large file support
  99 +* Inode allocation using large virtual block groups via flex_bg
 100
 101  2.2 Candidate features for future inclusion
 102
 103 -There are several under discussion, whether they all make it in is
 104 -partly a function of how much time everyone has to work on them:
 105 +* Online defrag (patches available but not well tested)
 106 +* reduced mke2fs time via lazy itable initialization in conjuction with
 107 +  the uninit_bg feature (capability to do this is available in e2fsprogs
 108 +  but a kernel thread to do lazy zeroing of unused inode table blocks
 109 +  after filesystem is first mounted is required for safety)
 110
 111 -* improved file allocation (multi-block alloc, delayed alloc; basically done)
 112 -* fix 32000 subdirectory limit (patch exists, needs some e2fsck work)
 113 -* nsec timestamps for mtime, atime, ctime, create time (patch exists,
 114 -  needs some e2fsck work)
 115 -* inode version field on disk (NFSv4, Lustre; prototype exists)
 116 -* reduced mke2fs/e2fsck time via uninitialized groups (prototype exists)
 117 -* journal checksumming for robustness, performance (prototype exists)
 118 -* persistent file preallocation (e.g for streaming media, databases)
 119 +There are several others under discussion, whether they all make it in is
 120 +partly a function of how much time everyone has to work on them. Features like
 121 +metadata checksumming have been discussed and planned for a bit but no patches
 122 +exist yet so I'm not sure they're in the near-term roadmap.
 123
 124 -Features like metadata checksumming have been discussed and planned for
 125 -a bit but no patches exist yet so I'm not sure they're in the near-term
 126 -roadmap.
 127 +The big performance win will come with mballoc, delalloc and flex_bg
 128 +grouping of bitmaps and inode tables.  Some test results available here:
 129
 130 -The big performance win will come with mballoc and delalloc.  CFS has
 131 -been using mballoc for a few years already with Lustre, and IBM + Bull
 132 -did a lot of benchmarking on it.  The reason it isn't in the first set of
 133 -patches is partly a manageability issue, and partly because it doesn't
 134 -directly affect the on-disk format (outside of much better allocation)
 135 -so it isn't critical to get into the first round of changes.  I believe
 136 -Alex is working on a new set of patches right now.
 137 + - http://www.bullopensource.org/ext4/20080530/ffsb-write-2.6.26-rc2.html
 138 + - http://www.bullopensource.org/ext4/20080530/ffsb-readwrite-2.6.26-rc2.html
 139
 140  3. Options
 141  ==========
 142 @@ -224,7 +237,7 @@ stripe=n            Number of filesystem blocks that mballoc will try
 143                         disks *  RAID chunk size in file system blocks.
 144
 145  Data Mode
 146 ----------
 147 +=========
 148  There are 3 different data modes:
 149
 150  * writeback mode
 151 @@ -256,7 +269,8 @@ kernel source:      <file:fs/ext4/>
 152                 <file:fs/jbd2/>
 153
 154  programs:      http://e2fsprogs.sourceforge.net/
 155 -               http://ext2resize.sourceforge.net
 156
 157  useful links:  http://fedoraproject.org/wiki/ext3-devel
 158                 http://www.bullopensource.org/ext4/
 159 +               http://ext4.wiki.kernel.org/index.php/Main_Page
 160 +               http://fedoraproject.org/wiki/Features/Ext4