ext4: convert ext4.rst to restructuredtext format

Convert the existing ext4 documentation into rst format and link it in
with the rest of the kernel documentation.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Theodore Ts'o <tytso@mit.edu>

Documentation/filesystems/ext4/ext4.rst

@@ -1,6 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
 
-Ext4 Filesystem
-===============
+========================
+General Information
+========================
 
 Ext4 is an advanced level of the ext3 filesystem which incorporates
 scalability and reliability enhancements for supporting large filesystems
@@ -11,18 +13,18 @@ Mailing list:	linux-ext4@vger.kernel.org
 Web site:	http://ext4.wiki.kernel.org
 
 
-1. Quick usage instructions:
-===========================
+Quick usage instructions
+========================
 
 Note: More extensive information for getting started with ext4 can be
-      found at the ext4 wiki site at the URL:
-      http://ext4.wiki.kernel.org/index.php/Ext4_Howto
+found at the ext4 wiki site at the URL:
+http://ext4.wiki.kernel.org/index.php/Ext4_Howto
 
   - Compile and install the latest version of e2fsprogs (as of this
     writing version 1.41.3) from:
 
     http://sourceforge.net/project/showfiles.php?group_id=2406
-	
+
 	or
 
     https://www.kernel.org/pub/linux/kernel/people/tytso/e2fsprogs/
@@ -37,16 +39,16 @@ Note: More extensive information for getting started with ext4 can be
     you will need to merge your changes with the version from e2fsprogs
     1.41.x.
 
-  - Create a new filesystem using the ext4 filesystem type:
+  - Create a new filesystem using the ext4 filesystem type:::
 
-    	# mke2fs -t ext4 /dev/hda1
+        # mke2fs -t ext4 /dev/hda1
 
-    Or to configure an existing ext3 filesystem to support extents: 
+    Or to configure an existing ext3 filesystem to support extents:::
 
 	# tune2fs -O extents /dev/hda1
 
     If the filesystem was created with 128 byte inodes, it can be
-    converted to use 256 byte for greater efficiency via:
+    converted to use 256 byte for greater efficiency via:::
 
         # tune2fs -I 256 /dev/hda1
 
@@ -54,7 +56,7 @@ Note: More extensive information for getting started with ext4 can be
     filesystem back to ext3; so please do not do try this on production
     filesystems.)
 
-  - Mounting:
+  - Mounting:::
 
 	# mount -t ext4 /dev/hda1 /wherever
 
@@ -75,10 +77,11 @@ Note: More extensive information for getting started with ext4 can be
     the filesystem with a large journal can also be helpful for
     metadata-intensive workloads.
 
-2. Features
-===========
+Features
+========
 
-2.1 Currently available
+Currently Available
+-------------------
 
 * ability to use filesystems > 16TB (e2fsprogs support not available yet)
 * extent format reduces metadata overhead (RAM, IO for access, transactions)
@@ -103,7 +106,8 @@ Note: More extensive information for getting started with ext4 can be
 [1] Filesystems with a block size of 1k may see a limit imposed by the
 directory hash tree having a maximum depth of two.
 
-2.2 Candidate features for future inclusion
+Candidate Features for Future Inclusion
+---------------------------------------
 
 * online defrag (patches available but not well tested)
 * reduced mke2fs time via lazy itable initialization in conjunction with
@@ -122,12 +126,15 @@ grouping of bitmaps and inode tables.  Some test results available here:
  - http://www.bullopensource.org/ext4/20080818-ffsb/ffsb-write-2.6.27-rc1.html
  - http://www.bullopensource.org/ext4/20080818-ffsb/ffsb-readwrite-2.6.27-rc1.html
 
-3. Options
-==========
+Options
+=======
 
 When mounting an ext4 filesystem, the following option are accepted:
 (*) == default
 
+======================= =======================================================
+Mount Option            Description
+======================= =======================================================
 ro                   	Mount filesystem read only. Note that ext4 will
                      	replay the journal (and thus write to the
                      	partition) even when mounted "read only". The
@@ -387,33 +394,38 @@ i_version		Enable 64-bit inode version support. This option is
 dax			Use direct access (no page cache).  See
 			Documentation/filesystems/dax.txt.  Note that
 			this option is incompatible with data=journal.
+======================= =======================================================
 
 Data Mode
 =========
 There are 3 different data modes:
 
 * writeback mode
-In data=writeback mode, ext4 does not journal data at all.  This mode provides
-a similar level of journaling as that of XFS, JFS, and ReiserFS in its default
-mode - metadata journaling.  A crash+recovery can cause incorrect data to
-appear in files which were written shortly before the crash.  This mode will
-typically provide the best ext4 performance.
+
+  In data=writeback mode, ext4 does not journal data at all.  This mode provides
+  a similar level of journaling as that of XFS, JFS, and ReiserFS in its default
+  mode - metadata journaling.  A crash+recovery can cause incorrect data to
+  appear in files which were written shortly before the crash.  This mode will
+  typically provide the best ext4 performance.
 
 * ordered mode
-In data=ordered mode, ext4 only officially journals metadata, but it logically
-groups metadata information related to data changes with the data blocks into a
-single unit called a transaction.  When it's time to write the new metadata
-out to disk, the associated data blocks are written first.  In general,
-this mode performs slightly slower than writeback but significantly faster than journal mode.
+
+  In data=ordered mode, ext4 only officially journals metadata, but it logically
+  groups metadata information related to data changes with the data blocks into
+  a single unit called a transaction.  When it's time to write the new metadata
+  out to disk, the associated data blocks are written first.  In general, this
+  mode performs slightly slower than writeback but significantly faster than
+  journal mode.
 
 * journal mode
-data=journal mode provides full data and metadata journaling.  All new data is
-written to the journal first, and then to its final location.
-In the event of a crash, the journal can be replayed, bringing both data and
-metadata into a consistent state.  This mode is the slowest except when data
-needs to be read from and written to disk at the same time where it
-outperforms all others modes.  Enabling this mode will disable delayed
-allocation and O_DIRECT support.
+
+  data=journal mode provides full data and metadata journaling.  All new data is
+  written to the journal first, and then to its final location.  In the event of
+  a crash, the journal can be replayed, bringing both data and metadata into a
+  consistent state.  This mode is the slowest except when data needs to be read
+  from and written to disk at the same time where it outperforms all others
+  modes.  Enabling this mode will disable delayed allocation and O_DIRECT
+  support.
 
 /proc entries
 =============
@@ -425,10 +437,12 @@ Information about mounted ext4 file systems can be found in
 in table below.
 
 Files in /proc/fs/ext4/<devname>
-..............................................................................
+
+================ =======
  File            Content
+================ =======
  mb_groups       details of multiblock allocator buddy cache of free blocks
-..............................................................................
+================ =======
 
 /sys entries
 ============
@@ -439,28 +453,30 @@ Information about mounted ext4 file systems can be found in
 /sys/fs/ext4/dm-0).   The files in each per-device directory are shown
 in table below.
 
-Files in /sys/fs/ext4/<devname>
+Files in /sys/fs/ext4/<devname>:
+
 (see also Documentation/ABI/testing/sysfs-fs-ext4)
-..............................................................................
- File                         Content
 
+============================= =================================================
+File                          Content
+============================= =================================================
  delayed_allocation_blocks    This file is read-only and shows the number of
                               blocks that are dirty in the page cache, but
                               which do not have their location in the
                               filesystem allocated yet.
 
- inode_goal                   Tuning parameter which (if non-zero) controls
+inode_goal                    Tuning parameter which (if non-zero) controls
                               the goal inode used by the inode allocator in
                               preference to all other allocation heuristics.
                               This is intended for debugging use only, and
                               should be 0 on production systems.
 
- inode_readahead_blks         Tuning parameter which controls the maximum
+inode_readahead_blks          Tuning parameter which controls the maximum
                               number of inode table blocks that ext4's inode
                               table readahead algorithm will pre-read into
                               the buffer cache
 
- lifetime_write_kbytes        This file is read-only and shows the number of
+lifetime_write_kbytes         This file is read-only and shows the number of
                               kilobytes of data that have been written to this
                               filesystem since it was created.
 
@@ -508,7 +524,7 @@ Files in /sys/fs/ext4/<devname>
                               in the file system. If there is not enough space
                               for the reserved space when mounting the file
                               mount will _not_ fail.
-..............................................................................
+============================= =================================================
 
 Ioctls
 ======
@@ -518,8 +534,10 @@ through the system call interfaces. The list of all Ext4 specific ioctls are
 shown in the table below.
 
 Table of Ext4 specific ioctls
-..............................................................................
- Ioctl			      Description
+
+============================= =================================================
+Ioctl			      Description
+============================= =================================================
  EXT4_IOC_GETFLAGS	      Get additional attributes associated with inode.
 			      The ioctl argument is an integer bitfield, with
 			      bit values described in ext4.h. This ioctl is an
@@ -610,8 +628,7 @@ Table of Ext4 specific ioctls
 			      normal user by accident.
 			      The data blocks of the previous boot loader
 			      will be associated with the given inode.
-
-..............................................................................
+============================= =================================================
 
 References
 ==========

Documentation/filesystems/ext4/index.rst

@@ -0,0 +1,16 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+ext4
+====
+
+General usage and on-disk artifacts writen by ext4.  More documentation may
+be ported from the wiki as time permits.  This should be considered the
+canonical source of information as the details here have been reviewed by
+the ext4 community.
+
+.. toctree::
+   :maxdepth: 5
+   :numbered:
+
+   ext4

Documentation/filesystems/index.rst

@@ -2,6 +2,14 @@
 Linux Filesystems API
 =====================
 
+The documentation in this section are provided by specific filesystem
+subprojects.
+
+.. toctree::
+   :maxdepth: 2
+
+   ext4/index
+
 The Linux VFS
 =============