btrfs-progs: docs: describe filesystem features

Signed-off-by: David Sterba <dsterba@suse.com>

diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc
index 467f11b..a1f364e 100644 (file)
--- a/Documentation/btrfs-man5.asciidoc
+++ b/Documentation/btrfs-man5.asciidoc
@@ -12,9 +12,12 @@ tools.  Currently covers:
 
 1. mount options
 
-2. file attributes
+2. filesystem features
+
+3. file attributes
+
+4. control device
 
-3. control device
 
 MOUNT OPTIONS
 -------------
@@ -406,6 +409,91 @@ NOTE: This option has replaced 'recovery'.
 Allow subvolumes to be deleted by their respective owner. Otherwise, only the
 root user can do that.
 
+FILESYSTEM FEATURES
+-------------------
+
+The basic set of filesystem features gets extended over time. The backward
+compatibility is maintained and the features are optional, need to be
+explicitly asked for so accidental use will not create incompatibilities.
+
+There are several classes and the respective tools to manage the features:
+
+at mkfs time only::
+This is namely for core structures, like the b-tree nodesize, see
+`mkfs.btrfs`(8) for more details.
+
+after mkfs, on an unmounted filesystem::
+Features that may optimize internal structures or add new structures to support
+new functionality, see `btrfstune`(8). The command *btrfs inspect-internal
+dump-super device* will dump a superblock, you can map the value of
+'incompat_flags' to the features listed below
+
+after mkfs, on a mounted filesystem::
+The features of a filesystem (with a given UUID) are listed in
+`/sys/fs/btrfs/UUID/features/`, one file per feature. The status of is stored
+insid the file. The value '1' is for enabled, '0' means the feature was had
+been enabled at the mount time and turned off afterwards.
++
+Whether a particular feature can be turned on a mounted filesystem can be found
+in the directory `/sys/fs/btrfs/features/`, one file per feature. The value '1'
+means the feature can be enabled.
+
+List of features (see also `mkfs.btrfs`(8) section 'FILESYSTEM FEATURES'):
+
+big_metadata::
+(since: 3.4)
++
+the filesystem uses 'nodesize' bigger than the page size
+compress_lzo::
+(since: 2.6.38)
++
+the 'lzo' compression has been used on the filesystem, either as a mount option
+or via *btrfs filesystem defrag*.
+
+default_subvol::
+(since: 2.6.34)
++
+the default subvolume has been set on the filesystem
+
+extended_iref::
+(since: 3.7)
++
+increased hardlink limit per file in a directory to 65536, older kernels
+supported a varying number of hardlinks depending on the sum of all file name
+sizes that can be stored into one metadata block
+
+mixed_backref::
+(since: 2.6.31)
++
+the last major disk format change, improved backreferences
+
+mixed_groups::
+(since: 2.6.37)
++
+mixed data and metadata block groups, ie. the data and metadata are not
+separated and occupy the same block groups, this mode is suitable for small
+volumes as there are no constraints how the remaining space should be used
+(compared to the split mode, where empty metadata space cannot be used for data
+and vice versa)
++
+on the other hand, the final layout is quite unpredictable and possibly highly
+fragmented, which means worse performance
+
+no_holes::
+(since: 3.14)
+improved representation of file extents where holes are not explicitly
+stored as an extent, saves a few percent of metadata if sparse files are used
+
+raid56::
+(since: 3.9)
++
+the filesystem contains or contained a raid56 profile of block groups
++
+skinny_metadata::
+(since: 3.10)
++
+reduced-size metadata for extent references, saves a few percent of metadata
+
 FILE ATTRIBUTES
 ---------------
 The btrfs filesystem supports setting the following file attributes using the

diff --git a/Documentation/btrfstune.asciidoc b/Documentation/btrfstune.asciidoc
index 68fec4c..1e9aa70 100644 (file)
--- a/Documentation/btrfstune.asciidoc
+++ b/Documentation/btrfstune.asciidoc
@@ -17,7 +17,11 @@ parameters. The filesystem must be unmounted.
 The common usecase is to enable features that were not enabled at mkfs time.
 Please make sure that you have kernel support for the features.  You can find a
 complete list of features and kernel version of their introduction at
-https://btrfs.wiki.kernel.org/index.php/Changelog#By_feature .
+https://btrfs.wiki.kernel.org/index.php/Changelog#By_feature .  Also, the
+manual page `mkfs.btrfs`(8) contains more details about the features.
+
+Some of the features could be enabled on a mounted filesytem. Please refer to
+the respective section in `btrfs`(5).
 
 OPTIONS
 -------
@@ -26,14 +30,24 @@ Enable seeding on a given device. Value 1 will enable seeding, 0 will disable it
 A seeding filesystem is forced to be mounted read-only. A new device can be added
 to the filesystem and will capture all writes keeping the seeding device intact.
 -r::
+(since kernel: 3.7)
++
 Enable extended inode refs (hardlink limit per file in a directory is 65536),
-enabled by mkfs feature 'extref'. Since kernel 3.7.
+enabled by mkfs feature 'extref'.
 -x::
+(since kernel: 3.10)
++
 Enable skinny metadata extent refs (more efficient representation of extents),
-enabled by mkfs feature 'skinny-metadata'. Since kernel 3.10.
+enabled by mkfs feature 'skinny-metadata'.
++
+All newly created extents will use the new representation. To completely switch
+the entire filesystem, run a full balance of the metadata. Please refer to
+`btrfs-balance`(8).
 -n::
+(since kernel: 3.14)
++
 Enable no-holes feature (more efficient representation of file holes), enabled
-by mkfs feature 'no-holes'. Since kernel 3.14.
+by mkfs feature 'no-holes'.
 -f::
 Allow dangerous changes, e.g. clear the seeding flag or change fsid. Make sure
 that you are aware of the dangers.
@@ -72,4 +86,6 @@ will become deprecated and removed afterwards.
 
 SEE ALSO
 --------
+`btrfs`(5),
+`btrfs-balance`(8),
 `mkfs.btrfs`(8)

diff --git a/Documentation/mkfs.btrfs.asciidoc b/Documentation/mkfs.btrfs.asciidoc
index 5d79e24..98fe694 100644 (file)
--- a/Documentation/mkfs.btrfs.asciidoc
+++ b/Documentation/mkfs.btrfs.asciidoc
@@ -185,7 +185,12 @@ initramfs/initrd systems.
 FILESYSTEM FEATURES
 -------------------
 
+Features that can be enabled during creation time. See also `btrfs`(5) section
+'FILESYSTEM FEATURES'.
+
 *mixed-bg*::
+(kernel support since 2.6.37)
++
 mixed data and metadata block groups, also set by option '--mixed'
 
 *extref*::
@@ -196,6 +201,8 @@ supported a varying number of hardlinks depending on the sum of all file name
 sizes that can be stored into one metadata block
 
 *raid56*::
+(kernel support since 3.9)
++
 extended format for RAID5/6, also enabled if raid5 or raid6 block groups
 are selected
 
@@ -205,6 +212,8 @@ are selected
 reduced-size metadata for extent references, saves a few percent of metadata
 
 *no-holes*::
+(kernel support since 3.14)
++
 improved representation of file extents where holes are not explicitly
 stored as an extent, saves a few percent of metadata if sparse files are used
 
@@ -351,4 +360,6 @@ further details.
 
 SEE ALSO
 --------
-`btrfs`(8), `wipefs`(8)
+`btrfs`(5),
+`btrfs`(8),
+`wipefs`(8)