convert-ext4.rst-into-restructuredtext-format

   1 ext4: convert ext4.rst to restructuredtext format
   2
   3 From: Darrick J. Wong <darrick.wong@oracle.com>
   4
   5 Convert the existing ext4 documentation into rst format and link it in
   6 with the rest of the kernel documentation.
   7
   8 Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
   9 Signed-off-by: Theodore Ts'o <tytso@mit.edu>
  10 ---
  11 v2: fix build problems with virtualenv 1.4.9 packaging
  12 ---
  13  Documentation/filesystems/ext4/ext4.rst  |  113 +++++++++++++++++-------------
  14  Documentation/filesystems/ext4/index.rst |   16 ++++
  15  Documentation/filesystems/index.rst      |    8 ++
  16  3 files changed, 89 insertions(+), 48 deletions(-)
  17  create mode 100644 Documentation/filesystems/ext4/index.rst
  18
  19 diff --git a/Documentation/filesystems/ext4/ext4.rst b/Documentation/filesystems/ext4/ext4.rst
  20 index 7f628b9f7c4b..47f614c47f56 100644
  21 --- a/Documentation/filesystems/ext4/ext4.rst
  22 +++ b/Documentation/filesystems/ext4/ext4.rst
  23 @@ -1,6 +1,8 @@
  24 +.. SPDX-License-Identifier: GPL-2.0
  25
  26 -Ext4 Filesystem
  27 -===============
  28 +========================
  29 +General Information
  30 +========================
  31
  32  Ext4 is an advanced level of the ext3 filesystem which incorporates
  33  scalability and reliability enhancements for supporting large filesystems
  34 @@ -11,18 +13,18 @@ Mailing list:       linux-ext4@vger.kernel.org
  35  Web site:      http://ext4.wiki.kernel.org
  36
  37
  38 -1. Quick usage instructions:
  39 -===========================
  40 +Quick usage instructions
  41 +========================
  42
  43  Note: More extensive information for getting started with ext4 can be
  44 -      found at the ext4 wiki site at the URL:
  45 -      http://ext4.wiki.kernel.org/index.php/Ext4_Howto
  46 +found at the ext4 wiki site at the URL:
  47 +http://ext4.wiki.kernel.org/index.php/Ext4_Howto
  48
  49    - Compile and install the latest version of e2fsprogs (as of this
  50      writing version 1.41.3) from:
  51
  52      http://sourceforge.net/project/showfiles.php?group_id=2406
  53 -
  54 +
  55         or
  56
  57      https://www.kernel.org/pub/linux/kernel/people/tytso/e2fsprogs/
  58 @@ -37,16 +39,16 @@ Note: More extensive information for getting started with ext4 can be
  59      you will need to merge your changes with the version from e2fsprogs
  60      1.41.x.
  61
  62 -  - Create a new filesystem using the ext4 filesystem type:
  63 +  - Create a new filesystem using the ext4 filesystem type:::
  64
  65 -       # mke2fs -t ext4 /dev/hda1
  66 +        # mke2fs -t ext4 /dev/hda1
  67
  68 -    Or to configure an existing ext3 filesystem to support extents:
  69 +    Or to configure an existing ext3 filesystem to support extents:::
  70
  71         # tune2fs -O extents /dev/hda1
  72
  73      If the filesystem was created with 128 byte inodes, it can be
  74 -    converted to use 256 byte for greater efficiency via:
  75 +    converted to use 256 byte for greater efficiency via:::
  76
  77          # tune2fs -I 256 /dev/hda1
  78
  79 @@ -54,7 +56,7 @@ Note: More extensive information for getting started with ext4 can be
  80      filesystem back to ext3; so please do not do try this on production
  81      filesystems.)
  82
  83 -  - Mounting:
  84 +  - Mounting:::
  85
  86         # mount -t ext4 /dev/hda1 /wherever
  87
  88 @@ -75,10 +77,11 @@ Note: More extensive information for getting started with ext4 can be
  89      the filesystem with a large journal can also be helpful for
  90      metadata-intensive workloads.
  91
  92 -2. Features
  93 -===========
  94 +Features
  95 +========
  96
  97 -2.1 Currently available
  98 +Currently Available
  99 +-------------------
 100
 101  * ability to use filesystems > 16TB (e2fsprogs support not available yet)
 102  * extent format reduces metadata overhead (RAM, IO for access, transactions)
 103 @@ -103,7 +106,8 @@ Note: More extensive information for getting started with ext4 can be
 104  [1] Filesystems with a block size of 1k may see a limit imposed by the
 105  directory hash tree having a maximum depth of two.
 106
 107 -2.2 Candidate features for future inclusion
 108 +Candidate Features for Future Inclusion
 109 +---------------------------------------
 110
 111  * online defrag (patches available but not well tested)
 112  * reduced mke2fs time via lazy itable initialization in conjunction with
 113 @@ -122,12 +126,15 @@ grouping of bitmaps and inode tables.  Some test results available here:
 114   - http://www.bullopensource.org/ext4/20080818-ffsb/ffsb-write-2.6.27-rc1.html
 115   - http://www.bullopensource.org/ext4/20080818-ffsb/ffsb-readwrite-2.6.27-rc1.html
 116
 117 -3. Options
 118 -==========
 119 +Options
 120 +=======
 121
 122  When mounting an ext4 filesystem, the following option are accepted:
 123  (*) == default
 124
 125 +======================= =======================================================
 126 +Mount Option            Description
 127 +======================= =======================================================
 128  ro                     Mount filesystem read only. Note that ext4 will
 129                         replay the journal (and thus write to the
 130                         partition) even when mounted "read only". The
 131 @@ -387,33 +394,38 @@ i_version         Enable 64-bit inode version support. This option is
 132  dax                    Use direct access (no page cache).  See
 133                         Documentation/filesystems/dax.txt.  Note that
 134                         this option is incompatible with data=journal.
 135 +======================= =======================================================
 136
 137  Data Mode
 138  =========
 139  There are 3 different data modes:
 140
 141  * writeback mode
 142 -In data=writeback mode, ext4 does not journal data at all.  This mode provides
 143 -a similar level of journaling as that of XFS, JFS, and ReiserFS in its default
 144 -mode - metadata journaling.  A crash+recovery can cause incorrect data to
 145 -appear in files which were written shortly before the crash.  This mode will
 146 -typically provide the best ext4 performance.
 147 +
 148 +  In data=writeback mode, ext4 does not journal data at all.  This mode provides
 149 +  a similar level of journaling as that of XFS, JFS, and ReiserFS in its default
 150 +  mode - metadata journaling.  A crash+recovery can cause incorrect data to
 151 +  appear in files which were written shortly before the crash.  This mode will
 152 +  typically provide the best ext4 performance.
 153
 154  * ordered mode
 155 -In data=ordered mode, ext4 only officially journals metadata, but it logically
 156 -groups metadata information related to data changes with the data blocks into a
 157 -single unit called a transaction.  When it's time to write the new metadata
 158 -out to disk, the associated data blocks are written first.  In general,
 159 -this mode performs slightly slower than writeback but significantly faster than journal mode.
 160 +
 161 +  In data=ordered mode, ext4 only officially journals metadata, but it logically
 162 +  groups metadata information related to data changes with the data blocks into
 163 +  a single unit called a transaction.  When it's time to write the new metadata
 164 +  out to disk, the associated data blocks are written first.  In general, this
 165 +  mode performs slightly slower than writeback but significantly faster than
 166 +  journal mode.
 167
 168  * journal mode
 169 -data=journal mode provides full data and metadata journaling.  All new data is
 170 -written to the journal first, and then to its final location.
 171 -In the event of a crash, the journal can be replayed, bringing both data and
 172 -metadata into a consistent state.  This mode is the slowest except when data
 173 -needs to be read from and written to disk at the same time where it
 174 -outperforms all others modes.  Enabling this mode will disable delayed
 175 -allocation and O_DIRECT support.
 176 +
 177 +  data=journal mode provides full data and metadata journaling.  All new data is
 178 +  written to the journal first, and then to its final location.  In the event of
 179 +  a crash, the journal can be replayed, bringing both data and metadata into a
 180 +  consistent state.  This mode is the slowest except when data needs to be read
 181 +  from and written to disk at the same time where it outperforms all others
 182 +  modes.  Enabling this mode will disable delayed allocation and O_DIRECT
 183 +  support.
 184
 185  /proc entries
 186  =============
 187 @@ -425,10 +437,12 @@ Information about mounted ext4 file systems can be found in
 188  in table below.
 189
 190  Files in /proc/fs/ext4/<devname>
 191 -..............................................................................
 192 +
 193 +================ =======
 194   File            Content
 195 +================ =======
 196   mb_groups       details of multiblock allocator buddy cache of free blocks
 197 -..............................................................................
 198 +================ =======
 199
 200  /sys entries
 201  ============
 202 @@ -439,28 +453,30 @@ Information about mounted ext4 file systems can be found in
 203  /sys/fs/ext4/dm-0).   The files in each per-device directory are shown
 204  in table below.
 205
 206 -Files in /sys/fs/ext4/<devname>
 207 +Files in /sys/fs/ext4/<devname>:
 208 +
 209  (see also Documentation/ABI/testing/sysfs-fs-ext4)
 210 -..............................................................................
 211 - File                         Content
 212
 213 +============================= =================================================
 214 +File                          Content
 215 +============================= =================================================
 216   delayed_allocation_blocks    This file is read-only and shows the number of
 217                                blocks that are dirty in the page cache, but
 218                                which do not have their location in the
 219                                filesystem allocated yet.
 220
 221 - inode_goal                   Tuning parameter which (if non-zero) controls
 222 +inode_goal                    Tuning parameter which (if non-zero) controls
 223                                the goal inode used by the inode allocator in
 224                                preference to all other allocation heuristics.
 225                                This is intended for debugging use only, and
 226                                should be 0 on production systems.
 227
 228 - inode_readahead_blks         Tuning parameter which controls the maximum
 229 +inode_readahead_blks          Tuning parameter which controls the maximum
 230                                number of inode table blocks that ext4's inode
 231                                table readahead algorithm will pre-read into
 232                                the buffer cache
 233
 234 - lifetime_write_kbytes        This file is read-only and shows the number of
 235 +lifetime_write_kbytes         This file is read-only and shows the number of
 236                                kilobytes of data that have been written to this
 237                                filesystem since it was created.
 238
 239 @@ -508,7 +524,7 @@ Files in /sys/fs/ext4/<devname>
 240                                in the file system. If there is not enough space
 241                                for the reserved space when mounting the file
 242                                mount will _not_ fail.
 243 -..............................................................................
 244 +============================= =================================================
 245
 246  Ioctls
 247  ======
 248 @@ -518,8 +534,10 @@ through the system call interfaces. The list of all Ext4 specific ioctls are
 249  shown in the table below.
 250
 251  Table of Ext4 specific ioctls
 252 -..............................................................................
 253 - Ioctl                       Description
 254 +
 255 +============================= =================================================
 256 +Ioctl                        Description
 257 +============================= =================================================
 258   EXT4_IOC_GETFLAGS           Get additional attributes associated with inode.
 259                               The ioctl argument is an integer bitfield, with
 260                               bit values described in ext4.h. This ioctl is an
 261 @@ -610,8 +628,7 @@ Table of Ext4 specific ioctls
 262                               normal user by accident.
 263                               The data blocks of the previous boot loader
 264                               will be associated with the given inode.
 265 -
 266 -..............................................................................
 267 +============================= =================================================
 268
 269  References
 270  ==========
 271 diff --git a/Documentation/filesystems/ext4/index.rst b/Documentation/filesystems/ext4/index.rst
 272 new file mode 100644
 273 index 000000000000..1270b34f643f
 274 --- /dev/null
 275 +++ b/Documentation/filesystems/ext4/index.rst
 276 @@ -0,0 +1,16 @@
 277 +.. SPDX-License-Identifier: GPL-2.0
 278 +
 279 +====
 280 +ext4
 281 +====
 282 +
 283 +General usage and on-disk artifacts writen by ext4.  More documentation may
 284 +be ported from the wiki as time permits.  This should be considered the
 285 +canonical source of information as the details here have been reviewed by
 286 +the ext4 community.
 287 +
 288 +.. toctree::
 289 +   :maxdepth: 5
 290 +   :numbered:
 291 +
 292 +   ext4
 293 diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
 294 index 53b89d0edc15..7c57b3927308 100644
 295 --- a/Documentation/filesystems/index.rst
 296 +++ b/Documentation/filesystems/index.rst
 297 @@ -2,6 +2,14 @@
 298  Linux Filesystems API
 299  =====================
 300
 301 +The documentation in this section are provided by specific filesystem
 302 +subprojects.
 303 +
 304 +.. toctree::
 305 +   :maxdepth: 2
 306 +
 307 +   ext4/index
 308 +
 309  The Linux VFS
 310  =============
 311
 312