Skip to content

Commit d8172c2

Browse files
committed
btrfs-progs: docs: fixups, references
Signed-off-by: David Sterba <[email protected]>
1 parent 7887e97 commit d8172c2

24 files changed

+157
-109
lines changed

CHANGES

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,8 @@ btrfs-progs-6.3.1 (2023-05-29)
3232
* mkfs: make option --rootdir more verbose and report start when filling
3333
from the given directory starts
3434
* experimental:
35-
* btrfstune: checksum switch logic reimplemented, conversion of all
36-
metadata and data now works, resume from various states also supported
35+
* btrfstune: checksum switch logic reimplemented, conversion of all
36+
metadata and data now works, resume from various states also supported
3737
* other:
3838
* more CI github actions test coverage
3939
* more kernel/userspace source code sync

Documentation/Feature-by-version.rst

Lines changed: 55 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ information look below.
77
The version states at which version a feature has been merged into the mainline
88
kernel. It does not tell anything about at which kernel version it is
99
considered mature enough for production use. For an estimation on stability of
10-
features see [[Status]] page.
10+
features see :doc:`Status<Status>` page.
1111

1212
6.x
1313
---
@@ -16,15 +16,15 @@ features see [[Status]] page.
1616
Send protocol update that adds new commands and extends existing
1717
functionality to write large data chunks. Compressed (and encrypted)
1818
extents can be optionally emitted and transferred as-is without the need
19-
to recompress (or reencrypt) on the receiving side.
19+
to re-compress (or re-encrypt) on the receiving side.
2020

2121
6.0 - sysfs exports commit stats
22-
The file /sys/fs/btrfs/FSID/commit_stats shows number of commits and
22+
The file :file:`/sys/fs/btrfs/FSID/commit_stats` shows number of commits and
2323
various time related statistics.
2424

2525
6.0 - sysfs exports chunk sizes
2626
Chunk size value can be read from
27-
/sys/fs/btrfs/FSID/allocation/PROFILE/chunk_size .
27+
:file:`/sys/fs/btrfs/FSID/allocation/PROFILE/chunk_size`.
2828

2929
6.0 - sysfs shows zoned mode among features
3030
The zoned mode has been supported since 5.10 and adding functionality.
@@ -33,7 +33,7 @@ features see [[Status]] page.
3333
6.0 - checksum implementation is logged at mount time
3434
When a filesystem is mounted the implementation backing the checksums
3535
is logged. The information is also accessible in
36-
/sys/fs/btrfs/FSID/checksum .
36+
:file:`/sys/fs/btrfs/FSID/checksum`.
3737

3838
6.1 - sysfs support to temporarily skip exact qgroup accounting
3939
Allow user override of qgroup accounting and make it temporarily out
@@ -56,14 +56,14 @@ features see [[Status]] page.
5656
features.
5757

5858
6.1 - discard stats available in sysfs
59-
The directory '/sys/fs/btrfs/FSID/discard' exports statistics and
59+
The directory :file:`/sys/fs/btrfs/FSID/discard` exports statistics and
6060
tunables related to discard.
6161

6262
6.1 - additional qgroup stats in sysfs
6363
The overall status of qgroups are exported in
64-
/sys/sys/fs/btrfs/FSID/qgroups/ .
64+
:file:`/sys/sys/fs/btrfs/FSID/qgroups/`.
6565

66-
6.1 - check that subperblock is unchanged at thaw time
66+
6.1 - check that super block is unchanged at thaw time
6767
Do full check of super block once a filesystem is thawed. This namely
6868
happens when system resumes from suspend or hibernation. Accidental
6969
change by other operating systems will be detected.
@@ -74,22 +74,22 @@ features see [[Status]] page.
7474

7575
6.3 - discard=async settings tuned
7676
The default IOPS limit has changed from 100 to 1000 and writing value 0
77-
to '/sys/fs/btrfs/FSID/discard/iops_limit' newly means to not do any
77+
to :file:`/sys/fs/btrfs/FSID/discard/iops_limit` newly means to not do any
7878
throttling.
7979

8080
6.3 - block group allocation class heuristics
8181
Pack files by size (up to 128k, up to 8M, more) to avoid fragmentation
8282
in block groups, assuming that file size and life time is correlated,
8383
in particular this may help during balance. The stats about the number
8484
of used classes per block group type is exported in
85-
'/sys/fs/btrfs/FSID/allocation/\*/size_classes'.
85+
:file:`/sys/fs/btrfs/FSID/allocation/\*/size_classes`.
8686

8787
6.3 - in DEV_INFO ioctl export per-device FSID
88-
A seeding device could have a different FSID, available in syfs and now
88+
A seeding device could have a different FSID, available in sysfs and now
8989
available via DEV_INFO ioctl.
9090

9191
6.3 - send utimes cache, reduced stream size
92-
Utimes for directories are emitted into the send steram only when
92+
Utimes for directories are emitted into the send stream only when
9393
finalizing the directory, the cache also gains significant speedups (up
9494
to 10x).
9595

@@ -151,7 +151,7 @@ features see [[Status]] page.
151151
filesystem. Now supports: nologreplay, usebackuproot
152152

153153
5.9 - qgroups in sysfs
154-
The information about qgroup status and relations is exported in */sys/fs/UUID/qgroups*
154+
The information about qgroup status and relations is exported in :file:`/sys/fs/UUID/qgroups`
155155

156156
5.9 - FS_INFO ioctl
157157
Export more information: checksum type, checksum size, generation, metadata_uuid
@@ -163,24 +163,25 @@ features see [[Status]] page.
163163
5.11 - remove *inode_cache*
164164
Remove inode number caching feature (mount -o inode_cache)
165165

166-
5.11 - more rescue=
166+
5.11 - more rescue= modes
167167
Additional modes for mount option *rescue=*: ignorebadroots/ibadroots,
168-
ignoredatacsums/idatacsums. All are exported in sysfs.
168+
ignoredatacsums/idatacsums. All are exported in
169+
:file:`/sys/fs/btrfs/features/supported_rescue_options`.
169170

170171
5.12 - zoned mode
171172
Support for zoned devices with special allocation/write mode to
172-
fixed-size zones. See [[Zoned]].
173+
fixed-size zones. See :doc:`Zoned<Zoned-mode>`.
173174

174175
5.13 - supported_sectorsizes in sysfs
175-
List supported sector sizes in sysfs file /sys/fs/btrfs/features/supported_sectorsizes
176+
List supported sector sizes in sysfs file :file:`/sys/fs/btrfs/features/supported_sectorsizes`.
176177

177178
5.14 - sysfs scrub bw limit
178179
Tunable bandwidth limit
179-
(/sys/fs/btrfs/FSID/devinfo/DEVID/scrub_speed_max) for scrub (and
180+
:file:`/sys/fs/btrfs/FSID/devinfo/DEVID/scrub_speed_max` for scrub (and
180181
device replace) for a given device.
181182

182183
5.14 - sysfs device stats
183-
The device stats can be also found in /sys/fs/btrfs/FSID/devinfo/DEVID/error_stats.
184+
The device stats can be also found in :file:`/sys/fs/btrfs/FSID/devinfo/DEVID/error_stats`.
184185

185186
5.14 - cancellable resize, device delete
186187
The filesystem resize and device delete operations can be cancelled by
@@ -217,25 +218,25 @@ features see [[Status]] page.
217218

218219
5.17 - *no warning with flushoncommit*
219220
Mounting with *-o flushoncommit* does not trigger the (harmless)
220-
warning at each transaction commit
221+
warning at each transaction commit.
221222

222223
.. note::
223224
Also backported to 5.15.27 and 5.16.13
224225

225226
5.18 - zoned and DUP metadata
226-
DUP metadata works with zoned mode
227+
DUP metadata works with zoned mode.
227228

228229
5.18 - encoded data ioctl
229230
New ioctls to read and write pre-encoded data (i.e. no transformation
230-
and directly written as extents), now works for compressed data
231+
and directly written as extents), now works for compressed data.
231232

232233
5.18 - *removed balance ioctl v1*
233234
The support for ioctl BTRFS_IOC_BALANCE has been removed, superseded by
234-
BTRFS_IOC_BALANCE_V2m long time ago
235+
BTRFS_IOC_BALANCE_V2 long time ago.
235236

236237
5.18 - *cross-mount reflink works*
237-
the VFS limitation to reflink files on separate subvolume mounts of the
238-
same filesystem has been removed
238+
The VFS limitation to reflink files on separate subvolume mounts of the
239+
same filesystem has been removed.
239240

240241
5.18 - syslog error messages with filesystem state
241242
Messages are printed with a one letter tag ("state: X") that denotes in
@@ -281,7 +282,7 @@ features see [[Status]] page.
281282
Add possibility to set a threshold to automatically reclaim block groups
282283
also in non-zoned mode. By default completely empty block groups are
283284
reclaimed automatically but the threshold can be tuned in
284-
/sys/fs/btrfs/FSID/allocation/PROFILE/bg_reclaim_threshold .
285+
:file:`/sys/fs/btrfs/FSID/allocation/PROFILE/bg_reclaim_threshold`.
285286

286287
5.19 - tree-checker verifies metadata block ownership
287288
Additional check done by tree-checker to verify relationship between a
@@ -308,9 +309,10 @@ features see [[Status]] page.
308309

309310
4.4 - balance filter updates
310311
Enhanced syntax and new balance filters:
311-
* limit=min..max
312-
* usage=min..max
313-
* stripes=min..max
312+
313+
* limit=min..max
314+
* usage=min..max
315+
* stripes=min..max
314316

315317
4.5 - free space tree
316318
Improved implementation of free space cache (aka v2), using b-trees.
@@ -330,7 +332,7 @@ features see [[Status]] page.
330332

331333
4.6 - read features from control device
332334
The existing ioctl GET_SUPPORTED_FEATURES can be now used on the
333-
control device (/dev/btrfs-control) and returns the supported features
335+
control device (:file:`/dev/btrfs-control`) and returns the supported features
334336
without any mounted filesystem.
335337

336338
4.7 - delete device by id
@@ -384,7 +386,7 @@ features see [[Status]] page.
384386

385387
4.15 - *ref-verify*
386388
Debugging functionality to verify extent references. New mount option
387-
<i>ref-verify</i>, must be built with CONFIG_BTRFS_FS_REF_VERIFY.
389+
*ref-verify*, must be built with CONFIG_BTRFS_FS_REF_VERIFY.
388390

389391
4.15 - ZLIB level
390392
Allow to set the ZLIB compression level via mount option, e.g. like
@@ -395,23 +397,21 @@ features see [[Status]] page.
395397
An enhanced version of ioctl that can translate logical extent offset
396398
to inode numbers, "who owns this block". For certain use cases the V1
397399
performs bad and this is addressed by V2.
398-
[https://git.kernel.org/linus/d24a67b2d997c860a42516076f3315c2ad2d2884
399-
Read more.]
400+
See for more https://git.kernel.org/linus/d24a67b2d997c860a42516076f3315c2ad2d2884 .
400401

401402
4.15 - compression heuristics
402403
Apply a few heuristics to the data before they're compressed to decide
403404
if it's likely to gain any space savings. The methods: frequency
404405
sampling, repeated pattern detection, Shannon entropy calculation.
405406

406407
4.16 - fallocate: zero range
407-
Mode of the [http://man7.org/linux/man-pages/man2/fallocate.2.html
408-
*fallocate*] syscall to zero file range.
408+
Mode of the *fallocate* syscall to zero file range.
409409

410410
4.17 - *removed user transaction ioctl*
411-
deprecated in 4.14, see above
411+
Deprecated in 4.14, see above.
412412

413413
4.17 - *rmdir* on subvolumes
414-
Allow rmdir to delete an empty subvolume.
414+
Allow *rmdir* to delete an empty subvolume.
415415

416416
4.18 - XFLAGS ioctl
417417
Add support for ioctl FS_IOC_FSSETXATTR/FS_IOC_FSGETXATTR, successor of
@@ -470,7 +470,7 @@ features see [[Status]] page.
470470
Support for metadata blocks larger than page size
471471

472472
.. note::
473-
Default nodesize is 16k since btrfs-progs 3.12
473+
Default nodesize is 16KiB since btrfs-progs 3.12
474474

475475
3.4 - error handling
476476
Generic infrastructure for graceful error handling (EIO)
@@ -487,54 +487,59 @@ features see [[Status]] page.
487487
3.6 - send/receive
488488
Ability to transfer one filesystem via a data stream (full or
489489
incremental) and apply the changes on a remote filesystem.
490+
490491
3.7 - extrefs
491-
Hardlink count limit is lifted to 64k
492+
Hardlink count limit is lifted to 65536.
492493

493494
.. note::
494495
Default since btrfs-progs 3.12
495496

496497
3.7 - hole punching
497-
Implement the FALLOC_FL_PUNCH_HOLE mode of *fallocate*
498+
Implement the FALLOC_FL_PUNCH_HOLE mode of *fallocate*.
498499

499500
3.8 - device replace
500-
Efficient replacement of existing device (add/remove in one go)
501+
Efficient replacement of existing device (add/remove in one go).
501502

502503
3.9 - raid 5/6 *(incomplete)*
503-
Basic support for RAID5/6 profiles, no crash resiliency, replace and scrub support
504+
Basic support for RAID5/6 profiles, no crash resiliency, replace and
505+
scrub support.
504506

505507
3.9 - snapshot-aware defrag
506-
Defrag does not break links between shared extents (snapshots, reflinked files)
508+
Defrag does not break links between shared extents (snapshots,
509+
reflinked files).
507510

508511
.. note::
509512
Disabled since 3.14 (and backported to some stable kernel versions)
510513
due to problems. Has been completely removed in 5.6.
511514

512515
3.9 - lightweight send
513-
A mode of *send* that does not add the actual file data to the stream
516+
A mode of *send* that does not add the actual file data to the stream.
514517

515518
3.9 - on-line label set/get
516-
Label editable on mounted filesystems
519+
Label editable on mounted filesystems.
517520

518521
3.10 - skinny metadata
519-
Reduced metadata size (format change) of extents
522+
Reduced metadata size (format change) of extents.
520523

521524
.. note::
522525
Default since btrfs-progs 3.18
523526

524527
3.10 - qgroup rescan
525-
Sync qgroups with existing filesystem data
528+
Sync qgroups with existing filesystem data.
526529

527530
3.12 - UUID tree
528-
A map of subvolume/UUID that vastly speeds up send/receive
531+
A map of subvolume/UUID that vastly speeds up send/receive.
529532

530533
3.12 - out-of-bound deduplication
531534
Support for deduplicating extents on a given set of files.
532535

533536
3.14 - no-holes
534-
No extent representation for file holes (format change), may reduce overall metadata consumption
537+
No extent representation for file holes (format change), may reduce
538+
overall metadata consumption
535539

536540
3.14 - feature bits in sysfs
537-
/sys/fs/btrfs exports various bits about filesystem capabilities and feature support
541+
:file:`/sys/fs/btrfs` exports various bits about filesystem
542+
capabilities and feature support
538543

539544
3.16 - O_TMPFILE
540545
Mode of open() to safely create a temporary file

Documentation/Kernel-by-version.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1260,10 +1260,10 @@ Fixes:
12601260
3.10 (Jun 2013)
12611261
^^^^^^^^^^^^^^^
12621262

1263-
* reduced size of metadata by so-called '''[[Feature:Skinny_Metadata|skinny extents]]''' [http://git.kernel.org/linus/3173a18f70554fe7880bb2d85c7da566e364eb3c]
1263+
* reduced size of metadata by so-called :ref:`skinny extents<mkfs-feature-skinny-metadata>` [http://git.kernel.org/linus/3173a18f70554fe7880bb2d85c7da566e364eb3c]
12641264
* enhanced syslog message format [http://permalink.gmane.org/gmane.comp.file-systems.btrfs/24330]
12651265
* the mount option ''subvolrootid'' is deprecated
1266-
* lots of stability improvements, removed <big>many</big> <small>BUG_ONs</small> <!-- a big thing! -->
1266+
* lots of stability improvements, removed many< BUG_ONs
12671267
* qgroups are automatically created when quotas are enabled [http://git.kernel.org/linus/7708f029dca5f1b9e9d6ea01ab10cd83e4c74ff2]
12681268
* qgroups are able to ''rescan'' current filesystem and sync the quota state with the existing subvolumes
12691269
* enhanced ''send/recv '' format for multiplexing more data into one stream [http://git.kernel.org/linus/c2c71324ecb471c932bc1ff59e46ffcf82f274fc]
@@ -1281,7 +1281,7 @@ Fixes:
12811281
^^^^^^^^^^^^^^^
12821282

12831283
* Major performance improvement for send/receive with large numbers of subvolumes
1284-
* Support for batch [[deduplication]] (userspace tools required)
1284+
* Support for batch :doc:`deduplication<Deduplication>` (userspace tools required)
12851285
* new mount option ''commit'' to set the commit interval
12861286
* Lots of stability and bugfix patches
12871287

Documentation/Source-repositories.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ There are:
2727
* snapshots of *for-next*, that contain all of the above (e.g. for-next-20200512)
2828

2929
Note that the branches get rebased. The base point for patches depend on the
30-
development phase. See [[Developer%27s_FAQ#Development_schedule]].
30+
development phase. See :ref:`development schedule<devfaq-development-schedule>`.
3131
Independent changes can be based on the *linus/master* branch, changes that
3232
could depend on patches that have been added to one of the queues should use
3333
that as a base.

Documentation/Status.rst

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -232,8 +232,6 @@ Please open an issue if:
232232
- a particular feature combination that has a different status and is
233233
worth mentioning separately
234234
- you know of a bug that lowers the feature status
235-
- a reference could be enhanced by an actual link to documentation
236-
(wiki, manual pages)
237235

238236
Subpage block size
239237
------------------

Documentation/btrfs-convert.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,8 @@ OPTIONS
4141
-O|--features <feature1>[,<feature2>...]
4242
A list of filesystem features enabled the at time of conversion. Not all features
4343
are supported by old kernels. To disable a feature, prefix it with *^*.
44-
Description of the features is in section *FILESYSTEM FEATURES* of
44+
Description of the features is in section
45+
:ref:`FILESYSTEM FEATURES<man-mkfs-filesystem-features>` of
4546
:doc:`mkfs.btrfs(8)<mkfs.btrfs>`.
4647

4748
To see all available features that btrfs-convert supports run:

Documentation/btrfs-device.rst

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -112,9 +112,9 @@ scan [options] [<device> [<device>...]]
112112

113113
stats [options] <path>|<device>
114114
Read and print the device IO error statistics for all devices of the given
115-
filesystem identified by *path* or for a single *device>. The filesystem must
116-
be mounted. See section *DEVICE STATS* for more information about the reported
117-
statistics and the meaning.
115+
filesystem identified by *path* or for a single *device*. The filesystem must
116+
be mounted. See section :ref:`DEVICE STATS<man-device-device-stats>`
117+
for more information about the reported statistics and the meaning.
118118

119119
``Options``
120120

@@ -195,6 +195,8 @@ usage [options] <path> [<path>...]::
195195

196196
If conflicting options are passed, the last one takes precedence.
197197

198+
.. _man-device-device-stats:
199+
198200
DEVICE STATS
199201
------------
200202

@@ -228,7 +230,7 @@ generation_errs
228230
parent node).
229231

230232
Since kernel 5.14 the device stats are also available in textual form in
231-
*/sys/fs/btrfs/FSID/devinfo/DEVID/error_stats*.
233+
:file:`/sys/fs/btrfs/FSID/devinfo/DEVID/error_stats`.
232234

233235
EXIT STATUS
234236
-----------

0 commit comments

Comments
 (0)