Skip to content

Commit

Permalink
btrfs-progs: docs: update sysfs descriptions
Browse files Browse the repository at this point in the history 
Add sections for each directory so it's more visible where the sections
start and end. Update formatting, enhance descriptions.

Signed-off-by: David Sterba <[email protected]>
  • Loading branch information
@kdave
kdave committed Feb 14, 2025
1 parent ea421ec commit 2f09d42
Showing 1 changed file with 77 additions and 27 deletions.
104 changes: 77 additions & 27 deletions Documentation/ch-sysfs.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,26 +5,31 @@ The top level path is :file:`/sys/fs/btrfs/`, and the main directory layout is t
============================= =================================== ========
Relative Path Description Version
============================= =================================== ========
features/ All supported features 3.14+
<UUID>/ Mounted fs UUID 3.14+
<UUID>/allocation/ Space allocation info 3.14+
<UUID>/features/ Features of the filesystem 3.14+
<UUID>/devices/<DEVID>/ Symlink to each block device sysfs 5.6+
<UUID>/devinfo/<DEVID>/ Btrfs specific info for each device 5.6+
<UUID>/qgroups/ Global qgroup info 5.9+
<UUID>/qgroups/<LEVEL>_<ID>/ Info for each qgroup 5.9+
<UUID>/discard/ Discard stats and tunables 6.1+
features/ All supported features 3.14
<UUID>/ Mounted fs UUID 3.14
<UUID>/allocation/ Space allocation info 3.14
<UUID>/bdi/ Backing device info (writeback) 5.9
<UUID>/devices/<DEVID>/ Symlink to each block device sysfs 5.6
<UUID>/devinfo/<DEVID>/ Btrfs specific info for each device 5.6
<UUID>/discard/ Discard stats and tunables 6.1
<UUID>/features/ Features of the filesystem 3.14
<UUID>/qgroups/ Global qgroup info 5.9
<UUID>/qgroups/<LEVEL>_<ID>/ Info for each qgroup 5.9
============================= =================================== ========

For :file:`/sys/fs/btrfs/features/` directory, each file means a supported feature
for the current kernel.
of the current kernel. Most files have value 0. Otherwise it depends on the file,
value *1* typically means the feature can be turned on a mounted filesystem.

For :file:`/sys/fs/btrfs/<UUID>/features/` directory, each file means an enabled
feature for the mounted filesystem.
feature on the mounted filesystem.

The features shares the same name in section
The features share the same name in section
:ref:`FILESYSTEM FEATURES<man-btrfs5-filesystem-features>`.

UUID
^^^^

Files in :file:`/sys/fs/btrfs/<UUID>/` directory are:

bg_reclaim_threshold
Expand Down Expand Up @@ -88,7 +93,7 @@ label
metadata_uuid
(RO, since: 5.0)

Shows the metadata uuid of the mounted filesystem.
Shows the metadata UUID of the mounted filesystem.
Check `metadata_uuid` feature for more details.

nodesize
Expand All @@ -107,20 +112,24 @@ read_policy
(RW, since: 5.11)

Shows the current balance policy for reads.
Currently only "pid" (balance using pid value) is supported.
Currently only ``pid`` (balance using the process id (pid) value) is
supported. More balancing policies are available in experimental
build, namely round-robin.

sectorsize
(RO, since: 3.14)

Shows the sectorsize of the mounted filesystem.


temp_fsid
(RO, since 6.7)

Indicate that this filesystem got assigned a temporary FSID at mount time,
making possible to mount devices with the same FSID.

UUID/allocations
^^^^^^^^^^^^^^^^

Files and directories in :file:`/sys/fs/btrfs/<UUID>/allocations` directory are:

global_rsv_reserved
Expand All @@ -136,8 +145,10 @@ global_rsv_size
`data/`, `metadata/` and `system/` directories
(RO, since: 5.14)

Space info accounting for the 3 chunk types.
Mostly for debug purposes.
Space info accounting for the 3 block group types.

UUID/allocations/{data,metadata,system}
"""""""""""""""""""""""""""""""""""""""

Files in :file:`/sys/fs/btrfs/<UUID>/allocations/{data,metadata,system}` directory are:

Expand All @@ -152,13 +163,20 @@ bytes_*
(RO)

Values of the corresponding data structures for the given block group
type and profile.
type and profile that are used internally and may change rapidly depending
on the load.

Complete list: bytes_may_use, bytes_pinned, bytes_readonly,
bytes_reserved, bytes_used, bytes_zone_unusable

chunk_size
(RW, since: 6.0)

Shows the chunk size. Can be changed for data and metadata.
Cannot be set for zoned devices.
Shows the chunk size. Can be changed for data and metadata (independently)
and cannot be set for system block group type.
Cannot be set for zoned devices as it depends on the fixed device zone size.
Upper bound is 10% of the filesystem size, the value must be multiple of 256MiB
and greater than 0.

size_classes
(RO, since: 6.3)
Expand All @@ -173,6 +191,27 @@ size_classes
medium 282
large 93
UUID/bdi
^^^^^^^^

Symlink to the sysfs directory of the backing device info (BDI), which is
related to writeback process and infrastructure.

UUID/devices
^^^^^^^^^^^^

Files in :file:`/sys/fs/btrfs/<UUID>/devices` directory are symlinks named
after device nodes (e.g. sda, dm-0) and pointing to their sysfs directory.

UUID/devinfo
^^^^^^^^^^^^

The directory contains subdirectories named after device ids (numeric values). Each
subdirectory has information about the device of the given *devid*.

UUID/devinfo/DEVID
""""""""""""""""""

Files in :file:`/sys/fs/btrfs/<UUID>/devinfo/<DEVID>` directory are:

error_stats:
Expand All @@ -192,25 +231,25 @@ fsid:
(RO, since: 5.17)

Shows the fsid which the device belongs to.
It can be different than the `<UUID>` if it's a seed device.
It can be different than the ``UUID`` if it's a seed device.

in_fs_metadata
(RO, since: 5.6)

Shows whether we have found the device.
Should always be 1, as if this turns to 0, the `<DEVID>` directory
Should always be 1, as if this turns to 0, the :file:`DEVID` directory
would get removed automatically.

missing
(RO, since: 5.6)

Shows whether the device is missing.
Shows whether the device is considered missing by the kernel module.

replace_target
(RO, since: 5.6)

Shows whether the device is the replace target.
If no dev-replace is running, this value should be 0.
If no device replace is running, this value is 0.

scrub_speed_max
(RW, since: 5.14)
Expand All @@ -223,13 +262,16 @@ writeable

Show if the device is writeable.

UUID/qgroups
^^^^^^^^^^^^

Files in :file:`/sys/fs/btrfs/<UUID>/qgroups/` directory are:

enabled
(RO, since: 6.1)

Shows if qgroup is enabled.
Also, if qgroup is disabled, the `qgroups` directory would
Also, if qgroup is disabled, the :file:`qgroups` directory will
be removed automatically.

inconsistent
Expand All @@ -249,12 +291,17 @@ drop_subtree_threshold
we will not trigger qgroup account at all, but mark qgroup inconsistent to
avoid the huge workload.

Default value is 8, where no subtree drop can trigger qgroup.
Default value is 3, which means that trees of low height will be accounted
properly as this is sufficiently fast. The value was 8 until 6.13 where
no subtree drop can trigger qgroup rescan making it less useful.

Lower value can reduce qgroup workload, at the cost of extra qgroup rescan
to re-calculate the numbers.

Files in :file:`/sys/fs/btrfs/<UUID>/<LEVEL>_<ID>/` directory are:
UUID/qgroups/LEVEL_ID
"""""""""""""""""""""

Files in each :file:`/sys/fs/btrfs/<UUID>/qgroups/<LEVEL>_<ID>/` directory are:

exclusive
(RO, since: 5.9)
Expand Down Expand Up @@ -297,6 +344,9 @@ rsv_meta_prealloc

Shows the reserved bytes for preallocated metadata.

UUID/discard
^^^^^^^^^^^^

Files in :file:`/sys/fs/btrfs/<UUID>/discard/` directory are:

discardable_bytes
Expand Down

0 comments on commit 2f09d42

Please sign in to comment.