GitHub-Mirror/Star64_linux
2
0
Fork 0
mirror of https://github.com/Fishwaldo/Star64_linux.git synced 2025-04-01 03:54:02 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

ext4: convert ext4.rst to restructuredtext format

Browse source 
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 2018-07-29 15:36:00 -04:00 • committed by Theodore Ts'o
parent a801e56997
commit 489fcb9124
3 changed files with 90 additions and 49 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

115
Documentation/filesystems/ext4/ext4.rst
View file

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

16
Documentation/filesystems/ext4/index.rst Normal file
View 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

8
Documentation/filesystems/index.rst
View file

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