Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 489fcb91 authored by Darrick J. Wong's avatar Darrick J. Wong Committed by Theodore Ts'o
Browse files

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: default avatarDarrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: default avatarTheodore Ts'o <tytso@mit.edu>
parent a801e569

Documentation/filesystems/ext4/ext4.rst

+65 −48
Original line number Diff line number Diff line 
.. 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,8 +13,8 @@ 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:
@@ -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



    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,12 +394,14 @@ 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
@@ -400,20 +409,23 @@ 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.

  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.

  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,11 +453,13 @@ 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
@@ -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

============================= =================================================

 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 → 100644
+16 −0
Original line number Diff line number Diff line 
.. 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

+8 −0
Original line number Diff line number Diff line
@@ -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

=============