RepoMirrors
/
btrfs-progs
mirror of https://github.com/kdave/btrfs-progs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

btrfs-progs: docs: fixups, references 

Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
David Sterba 2023-06-01 20:46:06 +02:00
parent 7887e978ba
commit d8172c2fbc
24 changed files with 157 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
CHANGES
View File

@ -32,8 +32,8 @@ btrfs-progs-6.3.1 (2023-05-29)
* mkfs: make option --rootdir more verbose and report start when filling
from the given directory starts
* experimental:
* btrfstune: checksum switch logic reimplemented, conversion of all
metadata and data now works, resume from various states also supported
* btrfstune: checksum switch logic reimplemented, conversion of all
metadata and data now works, resume from various states also supported
* other:
* more CI github actions test coverage
* more kernel/userspace source code sync

105
Documentation/Feature-by-version.rst
View File

@ -7,7 +7,7 @@ information look below.
The version states at which version a feature has been merged into the mainline
kernel. It does not tell anything about at which kernel version it is
considered mature enough for production use. For an estimation on stability of
features see [[Status]] page.
features see :doc:`Status<Status>` page.
6.x
---
@ -16,15 +16,15 @@ features see [[Status]] page.
Send protocol update that adds new commands and extends existing
functionality to write large data chunks. Compressed (and encrypted)
extents can be optionally emitted and transferred as-is without the need
to recompress (or reencrypt) on the receiving side.
to re-compress (or re-encrypt) on the receiving side.
6.0 - sysfs exports commit stats
The file /sys/fs/btrfs/FSID/commit_stats shows number of commits and
The file :file:`/sys/fs/btrfs/FSID/commit_stats` shows number of commits and
various time related statistics.
6.0 - sysfs exports chunk sizes
Chunk size value can be read from
/sys/fs/btrfs/FSID/allocation/PROFILE/chunk_size .
:file:`/sys/fs/btrfs/FSID/allocation/PROFILE/chunk_size`.
6.0 - sysfs shows zoned mode among features
The zoned mode has been supported since 5.10 and adding functionality.
@ -33,7 +33,7 @@ features see [[Status]] page.
6.0 - checksum implementation is logged at mount time
When a filesystem is mounted the implementation backing the checksums
is logged. The information is also accessible in
/sys/fs/btrfs/FSID/checksum .
:file:`/sys/fs/btrfs/FSID/checksum`.
6.1 - sysfs support to temporarily skip exact qgroup accounting
Allow user override of qgroup accounting and make it temporarily out
@ -56,14 +56,14 @@ features see [[Status]] page.
features.
6.1 - discard stats available in sysfs
The directory '/sys/fs/btrfs/FSID/discard' exports statistics and
The directory :file:`/sys/fs/btrfs/FSID/discard` exports statistics and
tunables related to discard.
6.1 - additional qgroup stats in sysfs
The overall status of qgroups are exported in
/sys/sys/fs/btrfs/FSID/qgroups/ .
:file:`/sys/sys/fs/btrfs/FSID/qgroups/`.
6.1 - check that subperblock is unchanged at thaw time
6.1 - check that super block is unchanged at thaw time
Do full check of super block once a filesystem is thawed. This namely
happens when system resumes from suspend or hibernation. Accidental
change by other operating systems will be detected.
@ -74,7 +74,7 @@ features see [[Status]] page.
6.3 - discard=async settings tuned
The default IOPS limit has changed from 100 to 1000 and writing value 0
to '/sys/fs/btrfs/FSID/discard/iops_limit' newly means to not do any
to :file:`/sys/fs/btrfs/FSID/discard/iops_limit` newly means to not do any
throttling.
6.3 - block group allocation class heuristics
@ -82,14 +82,14 @@ features see [[Status]] page.
in block groups, assuming that file size and life time is correlated,
in particular this may help during balance. The stats about the number
of used classes per block group type is exported in
'/sys/fs/btrfs/FSID/allocation/\*/size_classes'.
:file:`/sys/fs/btrfs/FSID/allocation/\*/size_classes`.
6.3 - in DEV_INFO ioctl export per-device FSID
A seeding device could have a different FSID, available in syfs and now
A seeding device could have a different FSID, available in sysfs and now
available via DEV_INFO ioctl.
6.3 - send utimes cache, reduced stream size
Utimes for directories are emitted into the send steram only when
Utimes for directories are emitted into the send stream only when
finalizing the directory, the cache also gains significant speedups (up
to 10x).
@ -151,7 +151,7 @@ features see [[Status]] page.
filesystem. Now supports: nologreplay, usebackuproot
5.9 - qgroups in sysfs
The information about qgroup status and relations is exported in */sys/fs/UUID/qgroups*
The information about qgroup status and relations is exported in :file:`/sys/fs/UUID/qgroups`
5.9 - FS_INFO ioctl
Export more information: checksum type, checksum size, generation, metadata_uuid
@ -163,24 +163,25 @@ features see [[Status]] page.
5.11 - remove *inode_cache*
Remove inode number caching feature (mount -o inode_cache)
5.11 - more rescue=
5.11 - more rescue= modes
Additional modes for mount option *rescue=*: ignorebadroots/ibadroots,
ignoredatacsums/idatacsums. All are exported in sysfs.
ignoredatacsums/idatacsums. All are exported in
:file:`/sys/fs/btrfs/features/supported_rescue_options`.
5.12 - zoned mode
Support for zoned devices with special allocation/write mode to
fixed-size zones. See [[Zoned]].
fixed-size zones. See :doc:`Zoned<Zoned-mode>`.
5.13 - supported_sectorsizes in sysfs
List supported sector sizes in sysfs file /sys/fs/btrfs/features/supported_sectorsizes
List supported sector sizes in sysfs file :file:`/sys/fs/btrfs/features/supported_sectorsizes`.
5.14 - sysfs scrub bw limit
Tunable bandwidth limit
(/sys/fs/btrfs/FSID/devinfo/DEVID/scrub_speed_max) for scrub (and
:file:`/sys/fs/btrfs/FSID/devinfo/DEVID/scrub_speed_max` for scrub (and
device replace) for a given device.
5.14 - sysfs device stats
The device stats can be also found in /sys/fs/btrfs/FSID/devinfo/DEVID/error_stats.
The device stats can be also found in :file:`/sys/fs/btrfs/FSID/devinfo/DEVID/error_stats`.
5.14 - cancellable resize, device delete
The filesystem resize and device delete operations can be cancelled by
@ -217,25 +218,25 @@ features see [[Status]] page.
5.17 - *no warning with flushoncommit*
Mounting with *-o flushoncommit* does not trigger the (harmless)
warning at each transaction commit
warning at each transaction commit.
.. note::
Also backported to 5.15.27 and 5.16.13
5.18 - zoned and DUP metadata
DUP metadata works with zoned mode
DUP metadata works with zoned mode.
5.18 - encoded data ioctl
New ioctls to read and write pre-encoded data (i.e. no transformation
and directly written as extents), now works for compressed data
and directly written as extents), now works for compressed data.
5.18 - *removed balance ioctl v1*
The support for ioctl BTRFS_IOC_BALANCE has been removed, superseded by
BTRFS_IOC_BALANCE_V2m long time ago
BTRFS_IOC_BALANCE_V2 long time ago.
5.18 - *cross-mount reflink works*
the VFS limitation to reflink files on separate subvolume mounts of the
same filesystem has been removed
The VFS limitation to reflink files on separate subvolume mounts of the
same filesystem has been removed.
5.18 - syslog error messages with filesystem state
Messages are printed with a one letter tag ("state: X") that denotes in
@ -281,7 +282,7 @@ features see [[Status]] page.
Add possibility to set a threshold to automatically reclaim block groups
also in non-zoned mode. By default completely empty block groups are
reclaimed automatically but the threshold can be tuned in
/sys/fs/btrfs/FSID/allocation/PROFILE/bg_reclaim_threshold .
:file:`/sys/fs/btrfs/FSID/allocation/PROFILE/bg_reclaim_threshold`.
5.19 - tree-checker verifies metadata block ownership
Additional check done by tree-checker to verify relationship between a
@ -308,9 +309,10 @@ features see [[Status]] page.
4.4 - balance filter updates
Enhanced syntax and new balance filters:
* limit=min..max
* usage=min..max
* stripes=min..max
* limit=min..max
* usage=min..max
* stripes=min..max
4.5 - free space tree
Improved implementation of free space cache (aka v2), using b-trees.
@ -330,7 +332,7 @@ features see [[Status]] page.
4.6 - read features from control device
The existing ioctl GET_SUPPORTED_FEATURES can be now used on the
control device (/dev/btrfs-control) and returns the supported features
control device (:file:`/dev/btrfs-control`) and returns the supported features
without any mounted filesystem.
4.7 - delete device by id
@ -384,7 +386,7 @@ features see [[Status]] page.
4.15 - *ref-verify*
Debugging functionality to verify extent references. New mount option
<i>ref-verify</i>, must be built with CONFIG_BTRFS_FS_REF_VERIFY.
*ref-verify*, must be built with CONFIG_BTRFS_FS_REF_VERIFY.
4.15 - ZLIB level
Allow to set the ZLIB compression level via mount option, e.g. like
@ -395,8 +397,7 @@ features see [[Status]] page.
An enhanced version of ioctl that can translate logical extent offset
to inode numbers, "who owns this block". For certain use cases the V1
performs bad and this is addressed by V2.
[https://git.kernel.org/linus/d24a67b2d997c860a42516076f3315c2ad2d2884
Read more.]
See for more https://git.kernel.org/linus/d24a67b2d997c860a42516076f3315c2ad2d2884 .
4.15 - compression heuristics
Apply a few heuristics to the data before they're compressed to decide
@ -404,14 +405,13 @@ features see [[Status]] page.
sampling, repeated pattern detection, Shannon entropy calculation.
4.16 - fallocate: zero range
Mode of the [http://man7.org/linux/man-pages/man2/fallocate.2.html
*fallocate*] syscall to zero file range.
Mode of the *fallocate* syscall to zero file range.
4.17 - *removed user transaction ioctl*
deprecated in 4.14, see above
Deprecated in 4.14, see above.
4.17 - *rmdir* on subvolumes
Allow rmdir to delete an empty subvolume.
Allow *rmdir* to delete an empty subvolume.
4.18 - XFLAGS ioctl
Add support for ioctl FS_IOC_FSSETXATTR/FS_IOC_FSGETXATTR, successor of
@ -470,7 +470,7 @@ features see [[Status]] page.
Support for metadata blocks larger than page size
.. note::
Default nodesize is 16k since btrfs-progs 3.12
Default nodesize is 16KiB since btrfs-progs 3.12
3.4 - error handling
Generic infrastructure for graceful error handling (EIO)
@ -487,54 +487,59 @@ features see [[Status]] page.
3.6 - send/receive
Ability to transfer one filesystem via a data stream (full or
incremental) and apply the changes on a remote filesystem.
3.7 - extrefs
Hardlink count limit is lifted to 64k
Hardlink count limit is lifted to 65536.
.. note::
Default since btrfs-progs 3.12
3.7 - hole punching
Implement the FALLOC_FL_PUNCH_HOLE mode of *fallocate*
Implement the FALLOC_FL_PUNCH_HOLE mode of *fallocate*.
3.8 - device replace
Efficient replacement of existing device (add/remove in one go)
Efficient replacement of existing device (add/remove in one go).
3.9 - raid 5/6 *(incomplete)*
Basic support for RAID5/6 profiles, no crash resiliency, replace and scrub support
Basic support for RAID5/6 profiles, no crash resiliency, replace and
scrub support.
3.9 - snapshot-aware defrag
Defrag does not break links between shared extents (snapshots, reflinked files)
Defrag does not break links between shared extents (snapshots,
reflinked files).
.. note::
Disabled since 3.14 (and backported to some stable kernel versions)
due to problems. Has been completely removed in 5.6.
3.9 - lightweight send
A mode of *send* that does not add the actual file data to the stream
A mode of *send* that does not add the actual file data to the stream.
3.9 - on-line label set/get
Label editable on mounted filesystems
Label editable on mounted filesystems.
3.10 - skinny metadata
Reduced metadata size (format change) of extents
Reduced metadata size (format change) of extents.
.. note::
Default since btrfs-progs 3.18
3.10 - qgroup rescan
Sync qgroups with existing filesystem data
Sync qgroups with existing filesystem data.
3.12 - UUID tree
A map of subvolume/UUID that vastly speeds up send/receive
A map of subvolume/UUID that vastly speeds up send/receive.
3.12 - out-of-bound deduplication
Support for deduplicating extents on a given set of files.
3.14 - no-holes
No extent representation for file holes (format change), may reduce overall metadata consumption
No extent representation for file holes (format change), may reduce
overall metadata consumption
3.14 - feature bits in sysfs
/sys/fs/btrfs exports various bits about filesystem capabilities and feature support
:file:`/sys/fs/btrfs` exports various bits about filesystem
capabilities and feature support
3.16 - O_TMPFILE
Mode of open() to safely create a temporary file

6
Documentation/Kernel-by-version.rst
View File

@ -1260,10 +1260,10 @@ Fixes:
3.10 (Jun 2013)
^^^^^^^^^^^^^^^
* reduced size of metadata by so-called '''[[Feature:Skinny_Metadata|skinny extents]]''' [http://git.kernel.org/linus/3173a18f70554fe7880bb2d85c7da566e364eb3c]
* reduced size of metadata by so-called :ref:`skinny extents<mkfs-feature-skinny-metadata>` [http://git.kernel.org/linus/3173a18f70554fe7880bb2d85c7da566e364eb3c]
* enhanced syslog message format [http://permalink.gmane.org/gmane.comp.file-systems.btrfs/24330]
* the mount option ''subvolrootid'' is deprecated
* lots of stability improvements, removed <big>many</big> <small>BUG_ONs</small> <!-- a big thing! -->
* lots of stability improvements, removed many< BUG_ONs
* qgroups are automatically created when quotas are enabled [http://git.kernel.org/linus/7708f029dca5f1b9e9d6ea01ab10cd83e4c74ff2]
* qgroups are able to ''rescan'' current filesystem and sync the quota state with the existing subvolumes
* enhanced ''send/recv '' format for multiplexing more data into one stream [http://git.kernel.org/linus/c2c71324ecb471c932bc1ff59e46ffcf82f274fc]
@ -1281,7 +1281,7 @@ Fixes:
^^^^^^^^^^^^^^^
* Major performance improvement for send/receive with large numbers of subvolumes
* Support for batch [[deduplication]] (userspace tools required)
* Support for batch :doc:`deduplication<Deduplication>` (userspace tools required)
* new mount option ''commit'' to set the commit interval
* Lots of stability and bugfix patches

2
Documentation/Source-repositories.rst
View File

@ -27,7 +27,7 @@ There are:
* snapshots of *for-next*, that contain all of the above (e.g. for-next-20200512)
Note that the branches get rebased. The base point for patches depend on the
development phase. See [[Developer%27s_FAQ#Development_schedule]].
development phase. See :ref:`development schedule<devfaq-development-schedule>`.
Independent changes can be based on the *linus/master* branch, changes that
could depend on patches that have been added to one of the queues should use
that as a base.

2
Documentation/Status.rst
View File

@ -232,8 +232,6 @@ Please open an issue if:
- a particular feature combination that has a different status and is
worth mentioning separately
- you know of a bug that lowers the feature status
- a reference could be enhanced by an actual link to documentation
(wiki, manual pages)
Subpage block size
------------------

3
Documentation/btrfs-convert.rst
View File

@ -41,7 +41,8 @@ OPTIONS
-O|--features <feature1>[,<feature2>...]
A list of filesystem features enabled the at time of conversion. Not all features
are supported by old kernels. To disable a feature, prefix it with *^*.
Description of the features is in section *FILESYSTEM FEATURES* of
Description of the features is in section
:ref:`FILESYSTEM FEATURES<man-mkfs-filesystem-features>` of
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`.
To see all available features that btrfs-convert supports run:

10
Documentation/btrfs-device.rst
View File

@ -112,9 +112,9 @@ scan [options] [<device> [<device>...]]
stats [options] <path>|<device>
Read and print the device IO error statistics for all devices of the given
filesystem identified by *path* or for a single *device>. The filesystem must
be mounted. See section *DEVICE STATS* for more information about the reported
statistics and the meaning.
filesystem identified by *path* or for a single *device*. The filesystem must
be mounted. See section :ref:`DEVICE STATS<man-device-device-stats>`
for more information about the reported statistics and the meaning.
``Options``
@ -195,6 +195,8 @@ usage [options] <path> [<path>...]::
If conflicting options are passed, the last one takes precedence.
.. _man-device-device-stats:
DEVICE STATS
------------
@ -228,7 +230,7 @@ generation_errs
parent node).
Since kernel 5.14 the device stats are also available in textual form in
*/sys/fs/btrfs/FSID/devinfo/DEVID/error_stats*.
:file:`/sys/fs/btrfs/FSID/devinfo/DEVID/error_stats`.
EXIT STATUS
-----------

2
Documentation/btrfs-filesystem.rst
View File

@ -351,7 +351,7 @@ usage [options] <path> [<path>...]
filesystem)
* *Multiple profiles* -- what block group types (data, metadata) have
more than one profile (single, raid1, ...), see :doc:`btrfs(5)<btrfs-man5>` section
*FILESYSTEMS WITH MULTIPLE BLOCK GROUP PROFILES*.
:ref:`FILESYSTEMS WITH MULTIPLE PROFILES<man-btrfs5-filesystem-with-multiple-profiles>`.
And on a zoned filesystem there are two more lines in the *Device* section:

14
Documentation/btrfs-man5.rst
View File

@ -23,12 +23,15 @@ tools. Currently covers:
#. RAID56 status and recommended practices
#. storage model, hardware considerations
.. _man-btrfs5-mount-option:
MOUNT OPTIONS
-------------
.. include:: ch-mount-options.rst
.. _man-btrfs5-filesystem-features:
FILESYSTEM FEATURES
-------------------
@ -59,7 +62,8 @@ after mkfs, on a mounted filesystem
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 :doc:`mkfs.btrfs(8)<mkfs.btrfs>` section *FILESYSTEM FEATURES*):
List of features (see also :doc:`mkfs.btrfs(8)<mkfs.btrfs>` section
:ref:`FILESYSTEM FEATURES<man-mkfs-filesystem-features>`):
big_metadata
(since: 3.4)
@ -189,6 +193,8 @@ SWAPFILE SUPPORT
.. include:: ch-swapfile.rst
.. _man-mkfs-checksum-algorithms:
CHECKSUM ALGORITHMS
-------------------
@ -204,6 +210,8 @@ SYSFS INTERFACE
.. include:: ch-sysfs.rst
.. _man-btrfs5-fileysstem-exclusive-operations:
FILESYSTEM EXCLUSIVE OPERATIONS
-------------------------------
@ -245,6 +253,8 @@ FILE ATTRIBUTES
.. include:: ch-file-attributes.rst
.. _man-btrfs5-zoned-mode:
ZONED MODE
----------
@ -294,6 +304,7 @@ work and a workaround would need to be used to mount a multi-device filesystem.
The mount option *device* can trigger the device scanning during mount, see
also :command:`btrfs device scan`.
.. _man-btrfs5-filesystem-with-multiple-profiles:
FILESYSTEM WITH MULTIPLE PROFILES
---------------------------------
@ -359,6 +370,7 @@ that report space usage: :command:`filesystem df`, :command:`device usage`. The
Multiple profiles: yes (data, metadata)
.. _man-btrfs5-seeding-device:
SEEDING DEVICE
--------------

5
Documentation/btrfs-quota.rst
View File

@ -16,7 +16,8 @@ of a btrfs filesystem. The quota groups (qgroups) are managed by the subcommand
.. note::
Qgroups are different than the traditional user quotas and designed
to track shared and exclusive data per-subvolume. Please refer to the section
*HIERARCHICAL QUOTA GROUP CONCEPTS* for a detailed description.
:ref:`HIERARCHICAL QUOTA GROUP CONCEPTS<man-quota-hierarchical-quota-group-concepts>`
for a detailed description.
PERFORMANCE IMPLICATIONS
^^^^^^^^^^^^^^^^^^^^^^^^
@ -33,6 +34,8 @@ the core of the filesystem operation. Qgroup users have hit various corner cases
over time, such as incorrect accounting or system instability. The situation is
gradually improving and issues found and fixed.
.. _man-quota-hierarchical-quota-group-concepts:
HIERARCHICAL QUOTA GROUP CONCEPTS
---------------------------------

9
Documentation/btrfs.rst
View File

@ -11,11 +11,12 @@ DESCRIPTION
The :command:`btrfs` utility is a toolbox for managing btrfs filesystems. There are
command groups to work with subvolumes, devices, for whole filesystem or other
specific actions. See section *COMMANDS*.
specific actions. See section :ref:`COMMANDS<man-btrfs8-commands>`.
There are also standalone tools for some tasks like :command:`btrfs-convert` or
:command:`btrfstune` that were separate historically and/or haven't been merged to the
main utility. See section *STANDALONE TOOLS* for more details.
main utility. See section :ref:`STANDALONE TOOLS<man-btrfs8-standalone-tools>`
for more details.
For other topics (mount options, etc) please refer to the separate manual
page :doc:`btrfs(5)<btrfs-man5>`.
@ -68,6 +69,8 @@ The remaining options are relevant only for the main tool:
--version
print version string
.. _man-btrfs8-commands:
COMMANDS
--------
@ -131,6 +134,8 @@ subvolume
Create/delete/list/manage btrfs subvolume.
See :doc:`btrfs-subvolume(8)<btrfs-subvolume>` for details.
.. _man-btrfs8-standalone-tools:
STANDALONE TOOLS
----------------

9
Documentation/btrfstune.rst
View File

@ -15,8 +15,8 @@ parameters. The filesystem must be unmounted.
The common use case 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 . Also, the
manual page :doc:`mkfs.btrfs(8)<mkfs.btrfs>` contains more details about the features.
:doc:`Feature by version<Feature-by-version>` page. Also, the manual page
:doc:`mkfs.btrfs(8)<mkfs.btrfs>` contains more details about the features.
Some of the features could be also enabled on a mounted filesystem by other
means. Please refer to the *FILESYSTEM FEATURES* in :doc:`btrfs(5)<btrfs-man5>`.
@ -81,7 +81,8 @@ OPTIONS
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. See also section *SEEDING DEVICE*
keeping the seeding device intact. See also section
:ref:`SEEDING DEVICE<man-btrfs5-seeding-device>`
in :doc:`btrfs(5)<btrfs-man5>`.
.. warning::
@ -113,7 +114,7 @@ OPTIONS
.. warning::
Cancelling or interrupting a UUID change operation will make
the filesystem temporarily unmountable. To fix it, rerun
*btrfstune -u* and let it complete.
:command:`btrfstune -u` and let it complete.
-x
(since kernel: 3.10)

3
Documentation/ch-balance-filters.rst
View File

@ -80,4 +80,5 @@ Profile names, used in *profiles* and *convert* are one of: *raid0*, *raid1*,
*raid1c3*, *raid1c4*, *raid10*, *raid5*, *raid6*, *dup*, *single*. The mixed
data/metadata profiles can be converted in the same way, but it's conversion
between mixed and non-mixed is not implemented. For the constraints of the
profiles please refer to :doc:`mkfs.btrfs(8)<mkfs.btrfs>`, section *PROFILES*.
profiles please refer to :doc:`mkfs.btrfs(8)<mkfs.btrfs>` section
:ref:`PROFILES<man-mkfs-profiles>`.

3
Documentation/ch-balance-intro.rst
View File

@ -1,6 +1,7 @@
The primary purpose of the balance feature is to spread block groups across
all devices so they match constraints defined by the respective profiles. See
:doc:`mkfs.btrfs(8)<mkfs.btrfs>` section *PROFILES* for more details.
:doc:`mkfs.btrfs(8)<mkfs.btrfs>` section :ref:`PROFILES<man-mkfs-profiles>`
for more details.
The scope of the balancing process can be further tuned by use of filters that
can select the block groups to process. Balance works only on a mounted
filesystem. Extent sharing is preserved and reflinks are not broken.

2
Documentation/ch-bootloaders.rst
View File

@ -1,7 +1,7 @@
GRUB2 (https://www.gnu.org/software/grub) has the most advanced support of
booting from BTRFS with respect to features.
U-boot (https://www.denx.de/wiki/U-Boot/) has decent support for booting but
U-Boot (https://www.denx.de/wiki/U-Boot/) has decent support for booting but
not all BTRFS features are implemented, check the documentation.
In general, the first 1MiB on each device is unused with the exception of

3
Documentation/ch-compression.rst
View File

@ -38,7 +38,8 @@ How to enable compression
Typically the compression can be enabled on the whole filesystem, specified for
the mount point. Note that the compression mount options are shared among all
mounts of the same filesystem, either bind mounts or subvolume mounts.
Please refer to section *MOUNT OPTIONS*.
Please refer to :doc:`btrfs(5)<btrfs-man5>` section
:ref:`MOUNT OPTIONS<man-btrfs5-mount-option>`.
.. code-block:: shell

2
Documentation/ch-flexibility.rst
View File

@ -8,7 +8,7 @@ or enabling some features on-the-fly.
* **block group profile change on-the-fly** -- the block group profiles can be
changed on a mounted filesystem by running the balance operation and
specifying the conversion filters (see :doc:`balance<Balance>`.)
specifying the conversion filters (see :doc:`balance<Balance>`)
* **resize** -- the space occupied by the filesystem on each device can be
resized up (grow) or down (shrink) as long as the amount of data can be still

4
Documentation/ch-fs-limits.rst
View File

@ -21,7 +21,7 @@ maximum number of inodes
inode numbers
minimum number: 256 (for subvolumes), regular files and directories: 257,
maximum number: (2\:sup:`64` - 256)
maximum number: (2\ :sup:`64` - 256)
The inode numbers that can be assigned to user created files are from
the whole 64bit space except first 256 and last 256 in that range that
@ -42,7 +42,7 @@ maximum number of subvolumes
maximum number of hardlinks of a file in a directory
65536 when the *extref* feature is turned on during mkfs (default), roughly
100 otherwise
100 otherwise and depends on file name length that fits into one metadata node
minimum filesystem size
the minimal size of each device depends on the *mixed-bg* feature, without that

31
Documentation/ch-sysfs.rst
View File

@ -1,6 +1,6 @@
Btrfs has a sysfs interface to provide extra knobs.
The top level path is `/sys/fs/btrfs/`, and the main directory layout is the following:
The top level path is :file:`/sys/fs/btrfs/`, and the main directory layout is the following:
============================= =================================== ========
Relative Path Description Version
@ -16,16 +16,16 @@ features/ All supported features 3.14+
<UUID>/discard/ Discard stats and tunables 6.1+
============================= =================================== ========
For `/sys/fs/btrfs/features/` directory, each file means a supported feature
For :file:`/sys/fs/btrfs/features/` directory, each file means a supported feature
for the current kernel.
For `/sys/fs/btrfs/<UUID>/features/` directory, each file means an enabled
For :file:`/sys/fs/btrfs/<UUID>/features/` directory, each file means an enabled
feature for the mounted filesystem.
The features shares the same name in section *FILESYSTEM FEATURES*.
The features shares the same name in section
:ref:`FILESYSTEM FEATURES<man-btrfs5-filesystem-features>`.
Files in `/sys/fs/btrfs/<UUID>/` directory are:
Files in :file:`/sys/fs/btrfs/<UUID>/` directory are:
bg_reclaim_threshold
(RW, since: 5.19)
@ -37,7 +37,8 @@ checksum
(RO, since: 5.5)
The checksum used for the mounted filesystem.
This includes both the checksum type (see section *CHECKSUM ALGORITHMS*)
This includes both the checksum type (see section
:ref:`CHECKSUM ALGORITHMS<man-mkfs-checksum-algorithms>`)
and the implemented driver (mostly shows if it's hardware accelerated).
clone_alignment
@ -58,7 +59,9 @@ exclusive_operation
(RO, since: 5.10)
Shows the running exclusive operation.
Check section *FILESYSTEM EXCLUSIVE OPERATIONS* for details.
Check section
:ref:`FILESYSTEM EXCLUSIVE OPERATIONS<man-btrfs5-fileysstem-exclusive-operations>`
for details.
generation
(RO, since: 5.11)
@ -100,7 +103,7 @@ sectorsize
Shows the sectorsize of the mounted filesystem.
Files and directories in `/sys/fs/btrfs/<UUID>/allocations` directory are:
Files and directories in :file:`/sys/fs/btrfs/<UUID>/allocations` directory are:
global_rsv_reserved
(RO, since: 3.14)
@ -118,7 +121,7 @@ global_rsv_size
Space info accounting for the 3 chunk types.
Mostly for debug purposes.
Files in `/sys/fs/btrfs/<UUID>/allocations/{data,metadata,system}` directory are:
Files in :file:`/sys/fs/btrfs/<UUID>/allocations/{data,metadata,system}` directory are:
bg_reclaim_threshold
(RW, since: 5.19)
@ -133,7 +136,7 @@ chunk_size
Shows the chunk size. Can be changed for data and metadata.
Cannot be set for zoned devices.
Files in `/sys/fs/btrfs/<UUID>/devinfo/<DEVID>` directory are:
Files in :file:`/sys/fs/btrfs/<UUID>/devinfo/<DEVID>` directory are:
error_stats:
(RO, since: 5.14)
@ -175,7 +178,7 @@ writeable
Show if the device is writeable.
Files in `/sys/fs/btrfs/<UUID>/qgroups/` directory are:
Files in :file:`/sys/fs/btrfs/<UUID>/qgroups/` directory are:
enabled
(RO, since: 6.1)
@ -206,7 +209,7 @@ drop_subtree_threshold
Lower value can reduce qgroup workload, at the cost of extra qgroup rescan
to re-calculate the numbers.
Files in `/sys/fs/btrfs/<UUID>/<LEVEL>_<ID>/` directory are:
Files in :file:`/sys/fs/btrfs/<UUID>/<LEVEL>_<ID>/` directory are:
exclusive
(RO, since: 5.9)
@ -249,7 +252,7 @@ rsv_meta_prealloc
Shows the reserved bytes for preallocated metadata.
Files in `/sys/fs/btrfs/<UUID>/discard/` directory are:
Files in :file:`/sys/fs/btrfs/<UUID>/discard/` directory are:
discardable_bytes
(RO, since: 6.1)

2
Documentation/dev/Developer-s-FAQ.rst
View File

@ -482,6 +482,8 @@ You may also read a perspective from Linux Foundation that shares a similar
view:
https://www.linuxfoundation.org/blog/copyright-notices-in-open-source-software-projects/
.. _devfaq-development-schedule:
Development schedule
--------------------

2
Documentation/dev/dev-btrfs-design.rst
View File

@ -456,7 +456,7 @@ The Btrfs snapshotting implementation is based on the ideas he
presented.
Btrfsck
~~~~~~~
-------
The filesystem checking utility is a crucial tool, but it can be a major
bottleneck in getting systems back online after something has gone

2
Documentation/index.rst
View File

@ -12,9 +12,9 @@ Welcome to BTRFS documentation!
man-index
Administration
Hardware
CHANGES
Feature-by-version
Kernel-by-version
CHANGES
Contributors
Glossary
INSTALL

38
Documentation/mkfs.btrfs.rst
View File

@ -15,7 +15,8 @@ as well. Multiple devices are grouped by UUID of the filesystem.
Before mounting such filesystem, the kernel module must know all the devices
either via preceding execution of :command:`btrfs device scan` or using the *device*
mount option. See section *MULTIPLE DEVICES* for more details.
mount option. See section :ref:`MULTIPLE DEVICES<man-mkfs-multiple-devices>`
for more details.
The default block group profiles for data and metadata depend on number of
devices and possibly other factors. It's recommended to use specific profiles
@ -35,14 +36,16 @@ OPTIONS
--csum <type>, --checksum <type>
Specify the checksum algorithm. Default is *crc32c*. Valid values are *crc32c*,
*xxhash*, *sha256* or *blake2*. To mount such filesystem kernel must support the
checksums as well. See *CHECKSUM ALGORITHMS* in :doc:`btrfs(5)<btrfs-man5>`.
checksums as well. See section :ref:`CHECKSUM ALGORITHMS<man-mkfs-checksum-algorithms>`
in :doc:`btrfs(5)<btrfs-man5>`.
-d|--data <profile>
Specify the profile for the data block groups. Valid values are *raid0*,
*raid1*, *raid1c3*, *raid1c4*, *raid5*, *raid6*, *raid10* or *single* or *dup*
(case does not matter).
See *DUP PROFILES ON A SINGLE DEVICE* for more details.
See section :ref:`DUP PROFILES ON A SINGLE DEVICE<man-mkfs-dup-profiles-on-a-single-device>`
for more details.
On multiple devices, the default was *raid0* until version 5.7, while it is
*single* since version 5.8. You can still select *raid0* manually, but it was not
@ -62,7 +65,7 @@ OPTIONS
.. note::
Up to version 5.14 there was a detection of a SSD device (more precisely
if it's a rotational device, determined by the contents of file
*/sys/block/DEV/queue/rotational*) that used to select *single*. This has
:file:`/sys/block/DEV/queue/rotational`) that used to select *single*. This has
changed in version 5.15 to be always *dup*.
Note that the rotational status can be arbitrarily set by the underlying block
@ -71,7 +74,8 @@ OPTIONS
etc). It's recommended to always set the options *--data/--metadata* to avoid
confusion and unexpected results.
See *DUP PROFILES ON A SINGLE DEVICE* for more details.
See section :ref:`DUP PROFILES ON A SINGLE DEVICE<man-mkfs-dup-profiles-on-a-single-device>`
for more details.
On multiple devices the default is *raid1*.
@ -154,8 +158,9 @@ OPTIONS
A list of filesystem features turned on at mkfs time. Not all features are
supported by old kernels. To disable a feature, prefix it with *^*.
See section *FILESYSTEM FEATURES* for more details. To see all available
features that :command:`mkfs.btrfs` supports run:
See section :ref:`FILESYSTEM FEATURES<man-mkfs-filesystem-features>`
for more details. To see all available features that
:command:`mkfs.btrfs` supports run:
.. code-block:: bash
@ -199,6 +204,8 @@ The default unit is *byte*. All size parameters accept suffixes in the 1024
base. The recognized suffixes are: *k*, *m*, *g*, *t*, *p*, *e*, both uppercase
and lowercase.
.. _man-mkfs-multiple-devices:
MULTIPLE DEVICES
----------------
@ -230,11 +237,13 @@ devices to scan at the time of mount.
.. warning::
RAID5/6 has known problems and should not be used in production.
.. _man-mkfs-filesystem-features:
FILESYSTEM FEATURES
-------------------
Features that can be enabled during creation time. See also :doc:`btrfs(5)<btrfs-man5>` section
*FILESYSTEM FEATURES*.
:ref:`FILESYSTEM FEATURES<man-btrfs5-filesystem-features>`.
mixed-bg
(kernel support since 2.6.37)
@ -275,8 +284,9 @@ zoned
(kernel support since 5.12)
zoned mode, data allocation and write friendly to zoned/SMR/ZBC/ZNS devices,
see *ZONED MODE* in :doc:`btrfs(5)<btrfs-man5>`, the mode is automatically selected when
a zoned device is detected
see :ref:`ZONED MODE<man-btrfs5-zoned-mode>` in
:doc:`btrfs(5)<btrfs-man5>`, the mode is automatically selected when a
zoned device is detected
quota
(kernel support since 3.4)
@ -332,7 +342,9 @@ RAID
profile
when used in connection with block groups refers to the allocation strategy
and constraints, see the section *PROFILES* for more details
and constraints, see the section :ref:`PROFILES<man-mkfs-profiles>` for more details
.. _man-mkfs-profiles:
PROFILES
--------
@ -456,6 +468,8 @@ C1 QD PB D1
PD B2 PC PA
======== ======== ======== ========
.. _man-mkfs-dup-profiles-on-a-single-device:
DUP PROFILES ON A SINGLE DEVICE
-------------------------------
@ -508,7 +522,7 @@ to be created and could end up in the following situation:
# mkfs.btrfs -f -n 65536 /dev/loop0
btrfs-progs v3.19-rc2-405-g976307c
See http://btrfs.wiki.kernel.org for more information.
See https://btrfs.readthedocs.io for more information.
Performing full device TRIM (512.00MiB) ...
Label: (null)

3
INSTALL
View File

@ -36,7 +36,6 @@ Generating documentation:
- sphinx
Please note that the package names may differ according to the distribution.
See https://btrfs.wiki.kernel.org/index.php/Btrfs_source_repositories#Dependencies .
Building from sources
@ -122,4 +121,4 @@ versions on a 32bit host is recommended.
References:
* https://btrfs.readthedocs.io
* https://btrfs.wiki.kernel.org
* https://btrfs.wiki.kernel.org (outdated)