Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit f328c5e

Browse files
committedMay 31, 2023
btrfs-progs: docs: cumulative update
- formatting, typo fixes, corrections - cross references - enhancements - revised and colored status page Signed-off-by: David Sterba <dsterba@suse.com>
1 parent 99ed2a6 commit f328c5e

13 files changed

+248
-134
lines changed
 

‎Documentation/Common-features.rst

+8-3
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,13 @@ statx
1616
*stat*
1717

1818
fallocate modes
19-
the *fallocate* syscall allows to manipulate file extents like punching
20-
holes, preallocation or zeroing a range
19+
the *fallocate* syscall allows to manipulate file extents
20+
21+
Supported modes:
22+
23+
- keep size (FALLOC_FL_KEEP_SIZE)
24+
- hole punching (FALLOC_FL_PUNCH_HOLE)
25+
- zero range (FALLOC_FL_ZERO_RANGE)
2126

2227
FIEMAP
2328
an ioctl that enumerates file extents, related tool is :command:`filefrag`
@@ -39,7 +44,7 @@ xattr, acl
3944

4045
cross-rename
4146
mode of *renameat2* syscall that can atomically swap 2 directory
42-
entries (files/directories/subvolumes)
47+
entries (files/directories/subvolumes/symlinks) within the same filesystem
4348

4449

4550
File attributes, XFLAGS

‎Documentation/Custom-ioctls.rst

+3
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,6 @@ a command if available:
1919
which is also exported in :file:`/sys/fs/btrfs/`
2020

2121
- query/set a subset of features on a mounted filesystem
22+
23+
Programming documentaion of the ioctls is in the manual page
24+
:doc:`btrfs-ioctl(2)<btrfs-ioctl>`.

‎Documentation/Feature-by-version.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ features see [[Status]] page.
7171

7272
.. note::
7373
Disabled since 3.14 (and backported to some stable kernel versions)
74-
due to problems. Will be enabled in the future.
74+
due to problems. Has been completely removed in 5.6.
7575

7676
3.9 - lightweight send
7777
A mode of *send* that does not add the actual file data to the stream

‎Documentation/Interoperability.rst

+12
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,28 @@
33
Interoperability
44
================
55

6+
.. _interop-nfs:
7+
68
NFS
79
---
810

11+
.. _interop-samba:
12+
913
Samba
1014
-----
1115

16+
.. _interop-cgroups:
17+
1218
cgroups
1319
-------
1420

21+
.. _interop-fsverity:
22+
1523
fsverity
1624
--------
1725

26+
.. _interop-idmapped:
27+
1828
idmapped mounts
1929
---------------
2030

@@ -27,5 +37,7 @@ overlayfs
2737
SELinux
2838
-------
2939

40+
.. _interop-io-uring:
41+
3042
io_uring
3143
--------

‎Documentation/Source-repositories.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,6 @@ patch page to the command:
108108

109109
.. code-block:: bash
110110
111-
$ wget -O - '<nowiki>https://patchwork.kernel.org/patch/123456/mbox</nowiki>' | git am -
111+
$ wget -O - 'https://patchwork.kernel.org/patch/123456/mbox' | git am -
112112
113113
You may want to add *--reject*, or decide otherwise what to do with the patch.

‎Documentation/Status.rst

+162-86
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ in meeting your performance expectations for your specific workload.
1313
Combination of features can vary in performance, the table does not
1414
cover all possibilities.
1515

16-
**The table is based on the latest released linux kernel: 6.2**
16+
**The table is based on the latest released linux kernel: 6.3**
1717

1818
The columns for each feature reflect the status of the implementation
1919
in following ways:
@@ -30,187 +30,199 @@ in following ways:
3030
- **Unstable**: do not use for other then testing purposes, known
3131
severe problems, missing implementation of some core parts
3232

33+
.. role:: statusok
34+
.. role:: statusmok
35+
.. role:: statusunst
36+
3337
.. list-table::
3438
:header-rows: 1
3539

3640
* - Feature
3741
- Stability
3842
- Performance
3943
- Notes
40-
* - discard (synchronous)
41-
- OK
44+
* - :doc:`discard (synchronous)<Trim>`
45+
- :statusok:`OK`
4246
-
4347
- mounted with `-o discard` (has performance implications), also see `fstrim`
44-
* - discard (asynchronous)
45-
- OK
48+
* - :doc:`discard (asynchronous)<Trim>`
49+
- :statusok:`OK`
4650
-
47-
- mounted with `-o discard=async` (improved performance)"
51+
- mounted with `-o discard=async` (improved performance)
4852
* - Autodefrag
49-
- OK
53+
- :statusok:`OK`
5054
-
5155
-
52-
* - Defrag
53-
- mostly OK
56+
* - :doc:`Defrag<Defragmentation>`
57+
- :statusmok:`mostly OK`
5458
-
5559
- extents get unshared (see below)
56-
* - Compression
57-
- OK (4.14)
60+
* - :doc:`Compression<Compression>`
61+
- :statusok:`OK`
5862
-
5963
-
60-
* - Out-of-band dedupe
61-
- OK
62-
- mostly OK
64+
* - :doc:`Out-of-band dedupe<Deduplication>`
65+
- :statusok:`OK`
66+
- :statusmok:`mostly OK`
6367
- (reflink), heavily referenced extents have a noticeable performance hit (see below)
64-
* - File range cloning
65-
- OK
66-
- mostly OK
68+
* - :doc:`File range cloning<Reflink>`
69+
- :statusok:`OK`
70+
- :statusmok:`mostly OK`
6771
- (reflink), heavily referenced extents have a noticeable performance hit (see below)
68-
* - More checksumming algorithms
69-
- OK
72+
* - :doc:`More checksumming algorithms<Checksumming>`
73+
- :statusok:`OK`
7074
- OK
7175
-
72-
* - Auto-repair
73-
- OK
76+
* - :doc:`Auto-repair<Auto-repair>`
77+
- :statusok:`OK`
7478
- OK
7579
- automatically repair from a correct spare copy if possible (DUP, RAID1, RAID10, RAID56)
76-
* - Scrub
77-
- OK
80+
* - :doc:`Scrub<Scrub>`
81+
- :statusok:`OK`
7882
- OK
7983
-
8084
* - Scrub + RAID56
81-
- mostly OK
85+
- :statusmok:`mostly OK`
8286
- mostly OK
8387
-
8488
* - nodatacow
85-
- OK
89+
- :statusok:`OK`
8690
- OK
8791
-
88-
* - Device replace
89-
- mostly OK
92+
* - :doc:`Device replace<Volume-management>`
93+
- :statusmok:`mostly OK`
9094
- mostly OK
9195
- (see below)
9296
* - Degraded mount
93-
- OK (4.14)
97+
- :statusok:`OK`
9498
- n/a
9599
-
96-
* - Single (block group profile)
97-
- OK
100+
* - :ref:`Single (block group profile)<mkfs-section-profiles>`
101+
- :statusok:`OK`
98102
- OK
99103
-
100-
* - DUP (block group profile)
101-
- OK
104+
* - :ref:`DUP (block group profile)<mkfs-section-profiles>`
105+
- :statusok:`OK`
102106
- OK
103107
-
104-
* - RAID0
105-
- OK
108+
* - :ref:`RAID0<mkfs-section-profiles>`
109+
- :statusok:`OK`
106110
- OK
107111
-
108-
* - RAID1
109-
- OK
112+
* - :ref:`RAID1<mkfs-section-profiles>`
113+
- :statusok:`OK`
110114
- mostly OK
111115
- reading from mirrors in parallel can be optimized further (see below)
112-
* - RAID1C3
113-
- OK
116+
* - :ref:`RAID1C3<mkfs-section-profiles>`
117+
- :statusok:`OK`
114118
- mostly OK
115119
- reading from mirrors in parallel can be optimized further (see below)
116-
* - RAID1C4
117-
- OK
120+
* - :ref:`RAID1C4<mkfs-section-profiles>`
121+
- :statusok:`OK`
118122
- mostly OK
119123
- reading from mirrors in parallel can be optimized further (see below)
120-
* - RAID10
121-
- OK
124+
* - :ref:`RAID10<mkfs-section-profiles>`
125+
- :statusok:`OK`
122126
- mostly OK
123127
- reading from mirrors in parallel can be optimized further (see below)
124-
* - RAID56
125-
- unstable
128+
* - :ref:`RAID56<mkfs-section-profiles>`
129+
- :statusunst:`unstable`
126130
- n/a
127131
- (see below)
128132
* - Mixed block groups
129-
- OK
133+
- :statusok:`OK`
130134
- OK
131135
-
132-
* - Filesystem resize
133-
- OK
136+
* - :doc:`Filesystem resize<Resize>`
137+
- :statusok:`OK`
134138
- OK
135139
- shrink, grow
136-
* - Balance
137-
- OK
140+
* - :doc:`Balance<Balance>`
141+
- :statusok:`OK`
138142
- OK
139143
- balance + qgroups can be slow when there are many snapshots
140144
* - Offline UUID change
141-
- OK
145+
- :statusok:`OK`
142146
- OK
143147
-
144148
* - Metadata UUID change
145-
- OK
149+
- :statusok:`OK`
146150
- OK
147151
-
148-
* - Subvolumes, snapshots
149-
- OK
152+
* - :doc:`Subvolumes, snapshots<Subvolumes>`
153+
- :statusok:`OK`
150154
- OK
151155
-
152-
* - Send
153-
- OK
156+
* - :doc:`Send<Send-receive>`
157+
- :statusok:`OK`
154158
- OK
155159
-
156-
* - Receive
157-
- OK
160+
* - :doc:`Receive<Send-receive>`
161+
- :statusok:`OK`
158162
- OK
159163
-
160-
* - Seeding
161-
- OK
164+
* - :doc:`Seeding<Seeding-device>`
165+
- :statusok:`OK`
162166
- OK
163167
-
164-
* - Quotas, qgroups
165-
- mostly OK
168+
* - :doc:`Quotas, qgroups<Qgroups>`
169+
- :statusmok:`mostly OK`
166170
- mostly OK
167171
- qgroups with many snapshots slows down balance
168-
* - Swapfile
169-
- OK
172+
* - :doc:`Swapfile<Swapfile>`
173+
- :statusok:`OK`
170174
- n/a
171175
- with some limitations
172-
* - NFS
173-
- OK
176+
* - :ref:`NFS<interop-nfs>`
177+
- :statusok:`OK`
174178
- OK
175179
-
176-
* - cgroups
177-
- OK
180+
* - :ref:`cgroups<interop-cgroups>`
181+
- :statusok:`OK`
178182
- OK
179183
- IO controller
180-
* - Samba
181-
- OK
184+
* - :ref:`Samba<interop-samba>`
185+
- :statusok:`OK`
182186
- OK
183187
- compression, server-side copies, snapshots
184-
* - io_uring
185-
- OK
188+
* - :ref:`io_uring<interop-io-uring>`
189+
- :statusok:`OK`
186190
- OK
187191
-
188-
* - fsverity
189-
- OK
192+
* - :ref:`fsverity<interop-fsverity>`
193+
- :statusok:`OK`
190194
- OK
191195
-
192-
* - idmapped mount
193-
- OK
196+
* - :ref:`idmapped mount<interop-idmapped>`
197+
- :statusok:`OK`
194198
- OK
195199
-
196-
* - Free space tree
197-
- OK (4.9)
200+
* - :ref:`Free space tree<mkfs-feature-free-space-tree>`
201+
- :statusok:`OK`
198202
-
199203
-
200-
* - no-holes
201-
- OK
202-
- OK
204+
* - Block group tree
205+
- :statusok:`OK`
203206
-
204-
* - skinny-metadata
205-
- OK
207+
-
208+
* - :ref:`no-holes<mkfs-feature-no-holes>`
209+
- :statusok:`OK`
206210
- OK
207211
-
208-
* - extended-refs
212+
* - :ref:`skinny-metadata<mkfs-feature-skinny-metadata>`
213+
- :statusok:`OK`
209214
- OK
215+
-
216+
* - :ref:`extended-refs<mkfs-feature-extended-refs>`
217+
- :statusok:`OK`
210218
- OK
211219
-
212-
* - zoned mode
220+
* - :doc:`Subpage block size<Subpage>`
221+
- :statusmok:`mostly OK`
213222
- mostly OK
223+
-
224+
* - :doc:`Zoned mode<Zoned-mode>`
225+
- :statusmok:`mostly OK`
214226
- mostly OK
215227
- there are known bugs, use only for testing
216228

@@ -223,6 +235,70 @@ Please open an issue if:
223235
- a reference could be enhanced by an actual link to documentation
224236
(wiki, manual pages)
225237

238+
Subpage block size
239+
------------------
240+
241+
Most commonly used page sizes are 4KiB, 16KiB and 64KiB. All combinations with
242+
a 4KiB sector size filesystems are supported. Some features are not compatible
243+
with subpage or require another feature to work:
244+
245+
.. list-table::
246+
:header-rows: 1
247+
248+
* - Feature
249+
- Status
250+
- Notes
251+
* - Inline files
252+
- unsupported
253+
- The max_inline mount option value is ignored
254+
* - Free space cache v1
255+
- unsupported
256+
- Free space tree is mandatory
257+
* - Compression
258+
- partial support
259+
- Only page-aligned ranges can be compressed
260+
261+
262+
Zoned mode
263+
----------
264+
265+
.. list-table::
266+
:header-rows: 1
267+
268+
* - Feature
269+
- Status
270+
- Notes
271+
* - Boot
272+
- incompatible
273+
- The blocks where partition table is stored is used for super block
274+
* - Mixed block groups
275+
- incompatible
276+
- Interleaving data and metadata would lead to out of order write
277+
* - NODATACOW
278+
- incompatible
279+
- In-place overwrite
280+
* - fallocate
281+
- incompatible
282+
- Preallocation of blocks would require an out of order write
283+
* - Free space cache v1
284+
- incompatible
285+
- Cache data are updated in a NODATACOW-way
286+
* - Free space tree
287+
- supported
288+
-
289+
* - fstrim
290+
- not implemented
291+
- This would require free space v1
292+
* - single profile
293+
- supported
294+
- Both data and metadata
295+
* - DUP profile
296+
- partial support
297+
- Only for metadata
298+
* - RAID (all)
299+
- not implemented
300+
- This requires raid-stripe-tree feature which is still work in progress
301+
226302

227303
Details that do not fit the table
228304
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -275,10 +351,10 @@ continue to be mountable and usable by newer kernels.
275351
The core of the on-disk format that comprises building blocks of the
276352
filesystem:
277353

278-
- layout of the main data structures, eg. superblock, b-tree nodes,
354+
- layout of the main data structures, e.g. superblock, b-tree nodes,
279355
b-tree keys, block headers
280356
- the COW mechanism, based on the original design of Ohad Rodeh's paper
281-
"Shadowing and clones"
357+
"B-trees, Shadowing and Clones" (http://sylab-srv.cs.fiu.edu/lib/exe/fetch.php?media=paperclub:shadow_btree.pdf)
282358

283359
Newly introduced features build on top of the above and could add
284360
specific structures. If a backward compatibility is not possible to

‎Documentation/Subpage.rst

+15-30
Original file line numberDiff line numberDiff line change
@@ -10,54 +10,39 @@ pages, like 64KiB on 64bit ARM or PowerPC. This means filesystems created
1010
with 64KiB sector size cannot be mounted on a system with 4KiB page size.
1111

1212
While with subpage support, systems with 64KiB page size can create (still needs
13-
"-s 4k" option for :command:`mkfs.btrfs`) and mount filesystems with 4KiB sectorsize,
14-
allowing us to push 4KiB sectorsize as default sectorsize for all platforms in the
15-
near future.
13+
"-s 4k" option for :command:`mkfs.btrfs`) and mount filesystems with 4KiB sectorsize.
1614

1715
Requirements, limitations
1816
-------------------------
1917

2018
The initial subpage support has been added in v5.15, although it's still
21-
considered as experimental at the time of writing (v5.18), most features are
22-
already working without problems.
19+
considered as experimental, most features are already working without problems.
2320

2421
End users can mount filesystems with 4KiB sectorsize and do their usual
2522
workload, while should not notice any obvious change, as long as the initial
2623
mount succeeded (there are cases a mount will be rejected though).
2724

2825
The following features has some limitations for subpage:
2926

30-
- RAID56 support
31-
This support is already queued for v5.19 cycle.
32-
Any fs with RAID56 chunks will be rejected at mount time for now.
27+
- Supported page sizes: 4KiB, 8KiB, 16KiB, 32KiB, 64KiB
3328

34-
- Support for page size other than 64KiB
35-
The support for other page sizes (16KiB, 32KiB and more) are already queued
36-
for v5.19 cycle.
37-
Initially the subpage support is only for 64KiB support, but the design makes
38-
it pretty easy to enable support for other page sizes.
29+
- Supported filesystem sector sizes on a given host are exported in
30+
:file:`/sys/fs/btrfs/features/supported_sectorsizes`
3931

40-
- No inline extent creation
41-
This is an artificial limit, to prevent mixed inline and regular extents.
32+
- No inline extents
4233

43-
It's possible to create mixed inline and regular extents even with
44-
non-subpage mount for certain corner cases, it's way easier to create such
45-
mixed extents for subpage.
34+
This is an artificial limitation, to prevent mixed inline and regular extents.
4635

4736
Thus max_inline mount option will be silently ignored for subpage mounts,
4837
and it always acts as "max_inline=0".
4938

50-
- Compression write is limited to page aligned ranges
51-
Compression write for subpage is introduced in v5.16, with the limitation
52-
that only page aligned range can be compressed.
53-
This limitation is due to how btrfs handles delayed allocation.
39+
- Compression writes are limited to page aligned ranges
40+
41+
Compression write for subpage has been introduced in v5.16, with the
42+
limitation that only page aligned range can be compressed. This limitation
43+
is due to how btrfs handles delayed allocation.
5444

5545
- No support for v1 space cache
56-
V1 space cache is considered deprecated, and we're defaulting to v2 cache
57-
in btrfs-progs already.
58-
The old v1 cache has quite some hard coded page size usage, and consider it
59-
is already deprecated, we force v2 cache for subpage.
60-
61-
- Slightly higher memory usage for scrub
62-
This is due to how we allocate pages for scrub, and will be fixed in the coming
63-
releases soon.
46+
47+
The old v1 cache has quite some hard coded page size usage, and considering
48+
it already deprecated, we force v2 cache for subpage.

‎Documentation/_static/style.css

+18
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,21 @@
11
.wy-nav-content {
22
max-width: 1200px !important;
33
}
4+
5+
.green {
6+
color: green;
7+
}
8+
9+
.statusok {
10+
color: green;
11+
}
12+
13+
.statusmok {
14+
/* color: orange; */
15+
/* color: #ffae42; */
16+
color: darkorange;
17+
}
18+
19+
.statusunst {
20+
color: red;
21+
}

‎Documentation/btrfs-device.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ The :command:`btrfs device` command group is used to manage devices of the btrfs
1414
DEVICE MANAGEMENT
1515
-----------------
1616

17-
.. include ch-volume-management-intro.rst
17+
.. include:: ch-volume-management-intro.rst
1818

1919
SUBCOMMAND
2020
----------

‎Documentation/btrfs-ioctl.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
btrfs-ioctl(3)
1+
btrfs-ioctl(2)
22
==============
33

44
NAME

‎Documentation/ch-flexibility.rst

+6-2
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,16 @@ or enabling some features on-the-fly.
44

55
* **dynamic inode creation** -- there's no fixed space or tables for tracking
66
inodes so the number of inodes that can be created is bounded by the metadata
7-
space and it's utilization
7+
space and its utilization
88

99
* **block group profile change on-the-fly** -- the block group profiles can be
1010
changed on a mounted filesystem by running the balance operation and
11-
specifying the conversion filters
11+
specifying the conversion filters (see :doc:`balance<Balance>`.)
1212

1313
* **resize** -- the space occupied by the filesystem on each device can be
1414
resized up (grow) or down (shrink) as long as the amount of data can be still
1515
contained on the device
16+
17+
* **device management** -- devices can be added, removed or replaced without
18+
requiring recreating the filesystem (mkfs), new redundancy options available
19+
on more devices can be also utilized by rebalancing

‎Documentation/ch-zoned-intro.rst

+10-9
Original file line numberDiff line numberDiff line change
@@ -17,15 +17,16 @@ to set various zone sizes.
1717
Requirements, limitations
1818
^^^^^^^^^^^^^^^^^^^^^^^^^
1919

20-
* all devices must have the same zone size
21-
* maximum zone size is 8GiB
22-
* minimum zone size is 4MiB
23-
* mixing zoned and non-zoned devices is possible, the zone writes are emulated,
24-
but this is namely for testing
25-
* the super block is handled in a special way and is at different locations than on a non-zoned filesystem:
26-
* primary: 0B (and the next two zones)
27-
* secondary: 512GiB (and the next two zones)
28-
* tertiary: 4TiB (4096GiB, and the next two zones)
20+
* all devices must have the same zone size
21+
* maximum zone size is 8GiB
22+
* minimum zone size is 4MiB
23+
* mixing zoned and non-zoned devices is possible, the zone writes are emulated,
24+
but this is namely for testing
25+
* the super block is handled in a special way and is at different locations than on a non-zoned filesystem:
26+
27+
* primary: 0B (and the next two zones)
28+
* secondary: 512GiB (and the next two zones)
29+
* tertiary: 4TiB (4096GiB, and the next two zones)
2930

3031
Incompatible features
3132
^^^^^^^^^^^^^^^^^^^^^

‎Documentation/mkfs.btrfs.rst

+10
Original file line numberDiff line numberDiff line change
@@ -241,6 +241,8 @@ mixed-bg
241241

242242
mixed data and metadata block groups, also set by option *--mixed*
243243

244+
.. _mkfs-feature-extended-refs:
245+
244246
extref
245247
(default since btrfs-progs 3.12, kernel support since 3.7)
246248

@@ -254,11 +256,15 @@ raid56
254256
extended format for RAID5/6, also enabled if RAID5 or RAID6 block groups
255257
are selected
256258

259+
.. _mkfs-feature-skinny-metadata:
260+
257261
skinny-metadata
258262
(default since btrfs-progs 3.18, kernel support since 3.10)
259263

260264
reduced-size metadata for extent references, saves a few percent of metadata
261265

266+
.. _mkfs-feature-no-holes:
267+
262268
no-holes
263269
(default since btrfs-progs 5.15, kernel support since 3.14)
264270

@@ -278,6 +284,8 @@ quota
278284
Enable quota support (qgroups). The qgroup accounting will be consistent,
279285
can be used together with *--rootdir*. See also :doc:`btrfs-quota(8)<btrfs-quota>`.
280286

287+
.. _mkfs-feature-free-space-tree:
288+
281289
free-space-tree
282290
(default since btrfs-progs 5.15, kernel support since 4.5)
283291

@@ -289,6 +297,8 @@ block-group-tree
289297

290298
Enable the block group tree to greatly reduce mount time for large filesystems.
291299

300+
.. _mkfs-section-profiles:
301+
292302
BLOCK GROUPS, CHUNKS, RAID
293303
--------------------------
294304

0 commit comments

Comments
 (0)
Please sign in to comment.