1 ext4: convert ext4.rst to restructuredtext format
3 From: Darrick J. Wong <darrick.wong@oracle.com>
5 Convert the existing ext4 documentation into rst format and link it in
6 with the rest of the kernel documentation.
8 Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
9 Signed-off-by: Theodore Ts'o <tytso@mit.edu>
11 v2: fix build problems with virtualenv 1.4.9 packaging
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
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
24 +.. SPDX-License-Identifier: GPL-2.0
28 +========================
30 +========================
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
38 -1. Quick usage instructions:
39 -===========================
40 +Quick usage instructions
41 +========================
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
49 - Compile and install the latest version of e2fsprogs (as of this
50 writing version 1.41.3) from:
52 http://sourceforge.net/project/showfiles.php?group_id=2406
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
62 - - Create a new filesystem using the ext4 filesystem type:
63 + - Create a new filesystem using the ext4 filesystem type:::
65 - # mke2fs -t ext4 /dev/hda1
66 + # mke2fs -t ext4 /dev/hda1
68 - Or to configure an existing ext3 filesystem to support extents:
69 + Or to configure an existing ext3 filesystem to support extents:::
71 # tune2fs -O extents /dev/hda1
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:::
77 # tune2fs -I 256 /dev/hda1
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
86 # mount -t ext4 /dev/hda1 /wherever
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.
97 -2.1 Currently available
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.
107 -2.2 Candidate features for future inclusion
108 +Candidate Features for Future Inclusion
109 +---------------------------------------
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
122 When mounting an ext4 filesystem, the following option are accepted:
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 +======================= =======================================================
139 There are 3 different data modes:
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.
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.
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.
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
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.
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
187 @@ -425,10 +437,12 @@ Information about mounted ext4 file systems can be found in
190 Files in /proc/fs/ext4/<devname>
191 -..............................................................................
193 +================ =======
195 +================ =======
196 mb_groups details of multiblock allocator buddy cache of free blocks
197 -..............................................................................
198 +================ =======
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
206 -Files in /sys/fs/ext4/<devname>
207 +Files in /sys/fs/ext4/<devname>:
209 (see also Documentation/ABI/testing/sysfs-fs-ext4)
210 -..............................................................................
213 +============================= =================================================
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.
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.
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
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.
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 +============================= =================================================
248 @@ -518,8 +534,10 @@ through the system call interfaces. The list of all Ext4 specific ioctls are
249 shown in the table below.
251 Table of Ext4 specific ioctls
252 -..............................................................................
255 +============================= =================================================
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.
266 -..............................................................................
267 +============================= =================================================
271 diff --git a/Documentation/filesystems/ext4/index.rst b/Documentation/filesystems/ext4/index.rst
273 index 000000000000..1270b34f643f
275 +++ b/Documentation/filesystems/ext4/index.rst
277 +.. SPDX-License-Identifier: GPL-2.0
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
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
298 Linux Filesystems API
299 =====================
301 +The documentation in this section are provided by specific filesystem