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>
This commit is contained in:
Darrick J. Wong
Theodore Ts'o
parent
a801e56997
commit
489fcb9124
@ -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>
|
||||
(see also Documentation/ABI/testing/sysfs-fs-ext4)
|
||||
..............................................................................
|
||||
File Content
|
||||
Files in /sys/fs/ext4/<devname>:
|
||||
|
||||
(see also Documentation/ABI/testing/sysfs-fs-ext4)
|
||||
|
||||
============================= =================================================
|
||||
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
|
||||
==========
|
||||
|
||||
16
Documentation/filesystems/ext4/index.rst
Normal file
16
Documentation/filesystems/ext4/index.rst
Normal file
@ -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
|
||||
@ -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
|
||||
=============
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user