korg/btrfs-progs
0
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/kdave/btrfs-progs.git synced 2024-11-23 12:14:24 +08:00
Code Issues Packages Projects Releases Wiki Activity

btrfs-progs: docs: typo fixups and formatting updates

Browse Source 
Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
David Sterba 2022-12-22 18:44:20 +01:00
parent b80c1d0c7f
commit 4f7bf100a9
20 changed files with 66 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Documentation/Deduplication.rst
View File

@ -64,7 +64,7 @@ a source file, destination file and the range. The blocks from both files are
compared for exact match before merging to the same range (i.e. there's no
hash based comparison). Pages representing the extents in memory are locked
prior to deduplication and prevent concurrent modification by buffered writes
or mmaped writes. Blocks are compared byte by byte and not using any hash-based
or mmapped writes. Blocks are compared byte by byte and not using any hash-based
approach, i.e. the existing checksums are not used.
Limitations, compatibility

2
Documentation/Experimental.rst
View File

@ -36,5 +36,5 @@ for larger code blocks.
Each feature should be tracked in an issue with label **experimental** (list of
active issues https://github.com/kdave/btrfs-progs/labels/experimental), with a
description and a todo list items. Individual tasks can be tracked in other
description and a TODO list items. Individual tasks can be tracked in other
issues if needed.

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

@ -19,7 +19,7 @@ features see [[Status]] page.
Automatic repair of broken data from a good copy
3.2 - root backups
Save a few previous versions of the most imporant tree roots at commit time, used by *-o recovery*
Save a few previous versions of the most important tree roots at commit time, used by *-o recovery*
3.3 - integrity checker
Optional infrastructure to verify integrity of written metadata blocks
@ -57,14 +57,14 @@ features see [[Status]] page.
.. note::
Default since btrfs-progs 3.12
3.7 - hole puching
3.7 - hole punching
Implement the FALLOC_FL_PUNCH_HOLE mode of *fallocate*
3.8 - device replace
Efficient replacement of existing device (add/remove in one go)
3.9 - raid 5/6 *(incomplete)*
Basic support for RAD5/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)
@ -88,10 +88,10 @@ features see [[Status]] page.
3.10 - qgroup rescan
Sync qgroups with existing filesystem data
3.12 - uuid tree
3.12 - UUID tree
A map of subvolume/UUID that vastly speeds up send/receive
3.12 - out-of-bound dedup
3.12 - out-of-bound deduplication
Support for deduplicating extents on a given set of files.
3.14 - no-holes
@ -106,10 +106,10 @@ features see [[Status]] page.
3.16 - search ioctl v2
The extended SEARCH_TREE ioctl able to get more than a 4k data
3.18 - auto blockgroup reclaim
Automatically remove blockgroups (aka. chunks) that become completely empty.
3.18 - auto block group reclaim
Automatically remove block groups (aka. chunks) that become completely empty.
3.19 - raid56: scrub, replace
3.19 - RAID56: scrub, replace
Scrub and device replace works on RAID56 filesystems.
4.x
@ -145,7 +145,7 @@ features see [[Status]] page.
big-endian machines, x86* is ok
4.5 - balance filter updates
Conversion to data/DUP profile possible through balance filters -- on single-device filesytem.
Conversion to data/DUP profile possible through balance filters -- on single-device filesystem.
.. note::
mkfs.btrfs allows creating DUP on single device in the non-mixed mode since 4.4
@ -172,7 +172,7 @@ features see [[Status]] page.
.. note::
mkfs.btrfs allows creating DUP on multiple devices since 4.5.1
4.12 - raid56: auto repair
4.12 - RAID56: auto repair
Scrub will attempt auto-repair (similar to raid1/raid10)
4.13 - statx
@ -189,7 +189,7 @@ features see [[Status]] page.
4.14 - improved degraded mount
Allow degraded mount based on the chunk constraints, not device number
constraints. Eg. when one device is missing but the remaining one holds
constraints. E.g. when one device is missing but the remaining one holds
all *single* chunks.
4.14 - *deprecated user transaction ioctl*
@ -211,14 +211,14 @@ features see [[Status]] page.
Debugging functionality to verify extent references. New mount option
<i>ref-verify</i>, 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
*compress=zlib:9*. The levels match the default zlib compression
4.15 - ZLIB level
Allow to set the ZLIB compression level via mount option, e.g. like
*compress=zlib:9*. The levels match the default ZLIB compression
levels. The default is 3.
4.15 - v2 of LOGICAL_INO ioctl
An enhanced version of ioctl that can translate logical extent offset
to inode numbers, "who owns this block". For certain usecases the V1
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.]
@ -267,7 +267,7 @@ features see [[Status]] page.
INO_LOOKUP ioctl.
4.19 - defrag ro/rw
Allow to run defrag on files that are normally accesible for
Allow to run defrag on files that are normally accessible for
read-write, but are currently opened in read-only mode.
5.x
@ -288,9 +288,9 @@ features see [[Status]] page.
Unregister devices previously added by the scan ioctl, same effect as
if the kernel module is reloaded.
5.1 - zstd level
Allow to set the zstd compression level via mount option, e.g. like
*compress=zstd:9*. The levels match the default zstd compression
5.1 - ZSTD level
Allow to set the ZSTD compression level via mount option, e.g. like
*compress=zstd:9*. The levels match the default ZSTD compression
levels. The default is 3, maximum is 15.
5.2 - pre-write checks
@ -315,7 +315,7 @@ features see [[Status]] page.
5.7 - faster balance cancel
More cancellation points in balance that will shorten the time to stop
processing once <tt>btrfs balance cancel</tt> is called.
processing once ``btrfs balance cancel`` is called.
5.7 - *removed flag BTRFS_SUBVOL_CREATE_ASYNC*
Remove support of flag BTRFS_SUBVOL_CREATE_ASYNC from subvolume creation ioctl.
@ -335,7 +335,7 @@ features see [[Status]] page.
5.10 - exclusive ops in sysfs
Export which filesystem exclusive operation is running (balance,
resize, device add/delete/relpace, ...)
resize, device add/delete/replace, ...)
5.11 - remove *inode_cache*
Remove inode number caching feature (mount -o inode_cache)
@ -375,7 +375,7 @@ features see [[Status]] page.
files. https://www.kernel.org/doc/html/latest/filesystems/fsverity.html
5.15 - idmapped mount
Support mount with uid/gid mapped according to another namespace.
Support mount with UID/GID mapped according to another namespace.
https://lwn.net/Articles/837566/
5.16 - ZNS in zoned
@ -393,7 +393,7 @@ features see [[Status]] page.
Since kernel 5.17.7 and btrfs-progs 5.17.1
5.17 - *no warning with flushoncommit*
Mounting with *-o flushoncommit* does not triggher the (harmless)
Mounting with *-o flushoncommit* does not trigger the (harmless)
warning at each transaction commit
.. note::
@ -439,7 +439,7 @@ features see [[Status]] page.
types (data, metadata, system).
5.19 - automatically repair device number mismatch
Device information is storead in two places, the number in the super
Device information is stored in two places, the number in the super
block and items in the device tree. When this is goes out of sync, e.g.
by device removal short before unmount, the next mount could fail.
The b-tree is an authoritative information an can be used to override
@ -470,7 +470,7 @@ features see [[Status]] page.
6.0 - send protocol v2
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 transfered as-is without the need
extents can be optionally emitted and transferred as-is without the need
to recompress (or reencrypt) on the receiving side.
6.0 - sysfs exports commit stats
@ -506,7 +506,7 @@ features see [[Status]] page.
An incompatible change that has to be enabled at mkfs time. Add a new
b-tree item that stores information about block groups in a compact way
that significantly improves mount time that's usually long due to
fragmentation and scatterd b-tree items tracking the individual block
fragmentation and scattered b-tree items tracking the individual block
groups. Requires and also enables the free-space-tree and no-holes
features.
@ -518,7 +518,7 @@ features see [[Status]] page.
The overall status of qgroups are exported in
/sys/sys/fs/btrfs/FSID/qgroups/ .
6.1 - check that subperblock is unchnaged at thaw time
6.1 - check that subperblock 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.

13
Documentation/Glossary.rst
View File

@ -83,7 +83,7 @@ copy-on-write
way. In COW filesystems, files tend to fragment as they are modified.
Copy-on-write is also used in the implementation of *snapshots* and
*reflink copies*. A copy-on-write filesystem is, in theory,
'always' consistent, provided the underlying hardware supports
*always* consistent, provided the underlying hardware supports
*barriers*.
COW
@ -142,8 +142,8 @@ fallocate
Command line tool in util-linux, and a syscall, that reserves space in
the filesystem for a file, without actually writing any file data to
the filesystem. First data write will turn the preallocated extents
into regular ones. See <code>man 1 fallocate</code> and <code>man 2
fallocate</code> for more details.
into regular ones. See *fallocate(1)* and *fallocate(2)* manual pages
for more details.
filefrag
A tool to show the number of extents in a file, and hence the amount of
@ -160,7 +160,7 @@ free space cache
fsync
On Unix and Unix-like operating systems (of which Linux is the latter),
the ``lfsync()`` system call causes all buffered file
the ``fsync()`` system call causes all buffered file
descriptor related data changes to be flushed to the underlying block
device. When a file is modified on a modern operating system the
changes are generally not written to the disk immediately but rather
@ -292,9 +292,8 @@ subvolume
a reference on the root of another subvolume. Each btrfs filesystem has
at least one subvolume, the *top-level subvolume*, which contains
everything else in the filesystem. Additional subvolumes can be created
and deleted with the *<code>btrfs</code>* tool. All subvolumes share
the same pool of free space in the filesystem. See also *default
subvolume*.
and deleted with the *btrfs<* tool. All subvolumes share the same pool
of free space in the filesystem. See also *default subvolume*.
superblock
The *block* on the disk, at a fixed known location and of fixed size,

8
Documentation/Source-repositories.rst
View File

@ -72,10 +72,10 @@ patches to the mailing list instead. You can link to a branch in any git
repository if the mails do not make it to the mailing list or for convenience.
The development model of btrfs-progs shares a lot with the kernel model. The
github way is different in some ways. We, the upstream community, expect that
the patches meet some criteria (often lacking in github contributions):
github.com way is different in some ways. We, the upstream community, expect that
the patches meet some criteria (often lacking in github.com contributions):
* proper **subject line**: eg. prefix with *btrfs-progs: subpart, ...* ,
* proper **subject line**: e.g. prefix with *btrfs-progs: subpart, ...* ,
descriptive yet not too long
* proper **changelog**: the changelogs are often missing or lacking
explanation *why* the change was made, or *how* is something broken,
@ -84,7 +84,7 @@ the patches meet some criteria (often lacking in github contributions):
* the **Signed-off-by** line: this document who authored the change, you can
read more about the *The Developer's Certificate of Origin*
`here (chapter 11) <https://www.kernel.org/doc/Documentation/SubmittingPatches>`_]
* **one logical change** per patch: eg. not mixing bugfixes, cleanups,
* **one logical change** per patch: e.g. not mixing bug fixes, cleanups,
features etc., sometimes it's not clear and will be usually pointed out
during reviews

2
Documentation/btrfs-check.rst
View File

@ -22,7 +22,7 @@ by the option *--readonly*.
.. warning::
Do not use *--repair* unless you are advised to do so by a developer
or an experienced user, and then only after having accepted that no *fsck*
successfully repair all types of filesystem corruption. Eg. some other software
successfully repair all types of filesystem corruption. E.g. some other software
or hardware bugs can fatally damage a volume.
The structural integrity check verifies if internal filesystem objects or

10
Documentation/btrfs-man5.rst
View File

@ -19,7 +19,7 @@ tools. Currently covers:
#. control device
#. filesystems with multiple block group profiles
#. seeding device
#. raid56 status and recommended practices
#. RAID56 status and recommended practices
#. storage model, hardware considerations
@ -129,10 +129,10 @@ raid1c34
extended RAID1 mode with copies on 3 or 4 devices respectively
raid56
RAID56
(since: 3.9)
the filesystem contains or contained a raid56 profile of block groups
the filesystem contains or contained a RAID56 profile of block groups
rmdir_subvol
(since: 4.18)
@ -332,7 +332,7 @@ group profiles *RAID1*.
Having just one profile is desired as this also clearly defines the profile of
newly allocated block groups, otherwise this depends on internal allocation
policy. When there are multiple profiles present, the order of selection is
RAID6, RAID5, RAID10, RAID1, RAID0 as long as the device number constraints are
RAID56, RAID10, RAID1, RAID0 as long as the device number constraints are
satisfied.
Commands that print the warning were chosen so they're brought to user
@ -385,7 +385,7 @@ Missing/incomplete support
When RAID56 is on the same filesystem with different raid profiles, the space
reporting is inaccurate, e.g. **df**, **btrfs filesystem df** or **btrfs filesystem
usage**. When there's only a one profile per block group type (e.g. raid5 for data)
usage**. When there's only a one profile per block group type (e.g. RAID5 for data)
the reporting is accurate.
When scrub is started on a RAID56 filesystem, it's started on all devices that

2
Documentation/btrfs-receive.rst
View File

@ -53,7 +53,7 @@ A subvolume is made read-only after the receiving process finishes successfully
-m <ROOTMOUNT>
the root mount point of the destination filesystem
By default the mountpoint is searched in */proc/self/mounts*.
By default the mount point is searched in */proc/self/mounts*.
If */proc* is not accessible, e.g. in a chroot environment, use this option to
tell us where this filesystem is mounted.

6
Documentation/btrfs-rescue.rst
View File

@ -51,12 +51,12 @@ fix-device-size <device>
WARNING: CPU: 3 PID: 439 at fs/btrfs/ctree.h:1559 btrfs_update_device+0x1c5/0x1d0 [btrfs]
clear-uuid-tree <device>
Clear uuid tree, so that kernel can re-generate it at next read-write
Clear UUID tree, so that kernel can re-generate it at next read-write
mount.
Since kernel v4.16 there are more sanity check performed, and sometimes
non-critical trees like uuid tree can cause problems and reject the mount.
In such case, clearing uuid tree may make the filesystem to be mountable again
non-critical trees like UUID tree can cause problems and reject the mount.
In such case, clearing UUID tree may make the filesystem to be mountable again
without much risk as it's built from other trees.
super-recover [options] <device>

2
Documentation/btrfstune.rst
View File

@ -12,7 +12,7 @@ DESCRIPTION
**btrfstune** can be used to enable, disable, or set various filesystem
parameters. The filesystem must be unmounted.
The common usecase is to enable features that were not enabled at mkfs time.
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

2
Documentation/ch-checksumming.rst
View File

@ -1,5 +1,5 @@
Data and metadata are checksummed by default, the checksum is calculated before
write and verifed after reading the blocks from devices. The whole metadata
write and verified after reading the blocks from devices. The whole metadata
block has a checksum stored inline in the b-tree node header, each data block
has a detached checksum stored in the checksum tree.

4
Documentation/ch-compression.rst
View File

@ -20,11 +20,11 @@ ZLIB
* levels: 1 to 9, mapped directly, default level is 3
* good backward compatibility
LZO
* faster compression and decompression than zlib, worse compression ratio, designed to be fast
* faster compression and decompression than ZLIB, worse compression ratio, designed to be fast
* no levels
* good backward compatibility
ZSTD
* compression comparable to zlib with higher compression/decompression speeds and different ratio
* compression comparable to ZLIB with higher compression/decompression speeds and different ratio
* levels: 1 to 15, mapped directly (higher levels are not available)
* since 4.14, levels since 5.1

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

@ -1,7 +1,7 @@
maximum file name length
255
This limit is imposed by Linux VFS, the strucutres of BTRFS could store
This limit is imposed by Linux VFS, the structures of BTRFS could store
larger file names.
maximum symlink target length

9
Documentation/ch-hardware-considerations.rst
View File

@ -73,14 +73,14 @@ media itself.
* *Problem*: while the data are written atomically, the contents get changed
* *Detection*: checksum mismatch on read
* 'Repair*: use another copy or rebuild from multiple blocks using some
* *Repair*: use another copy or rebuild from multiple blocks using some
encoding scheme
**Data get silently written to another offset (3)**
This would be another serious problem as the filesystem has no information
when it happens. For that reason the measures have to be done ahead of time.
This problem is also commonly called 'ghost write'.
This problem is also commonly called *ghost write*.
The metadata blocks have the checksum embedded in the blocks, so a correct
atomic write would not corrupt the checksum. It's likely that after reading
@ -88,7 +88,6 @@ such block the data inside would not be consistent with the rest. To rule that
out there's embedded block number in the metadata block. It's the logical
block number because this is what the logical structure expects and verifies.
The following is based on information publicly available, user feedback,
community discussions or bug report analyses. It's not complete and further
research is encouraged when in doubt.
@ -115,7 +114,7 @@ type of memory is not available in all cases. A memory test should be performed
in case there's a visible bit flip pattern, though this may not detect a faulty
memory module because the actual load of the system could be the factor making
the problems appear. In recent years attacks on how the memory modules operate
have been demonstrated ('rowhammer') achieving specific bits to be flipped.
have been demonstrated (*rowhammer*) achieving specific bits to be flipped.
While these were targeted, this shows that a series of reads or writes can
affect unrelated parts of memory.
@ -216,7 +215,7 @@ so there is some value in reducing them. Depending on the device class (high
end/low end) the features like DUP block group profiles may affect the
reliability in both ways:
* *high end* are typically more reliable and using 'single' for data and
* *high end* are typically more reliable and using *single* for data and
metadata could be suitable to reduce device wear
* *low end* could lack ability to identify errors so an additional redundancy
at the filesystem level (checksums, *DUP*) could help

6
Documentation/ch-mount-options.rst
View File

@ -18,7 +18,7 @@ have been applied.
acl, noacl
(default: on)
Enable/disable support for Posix Access Control Lists (ACLs). See the
Enable/disable support for POSIX Access Control Lists (ACLs). See the
``acl(5)`` manual page for more information about ACLs.
The support for ACL is build-time configurable (BTRFS_FS_POSIX_ACL) and
@ -110,7 +110,7 @@ compress, compress=<type[:level]>, compress-force, compress-force=<type[:level]>
Both *zlib* and *zstd* (since version 5.1) expose the compression level as a
tunable knob with higher levels trading speed and memory (*zstd*) for higher
compression ratios. This can be set by appending a colon and the desired level.
Zlib accepts the range [1, 9] and zstd accepts [1, 15]. If no level is set,
ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. If no level is set,
both currently use a default level of 3. The value 0 is an alias for the
default level.
@ -480,7 +480,7 @@ noatime
performance because no new access time information needs to be written. Without
this option, the default is *relatime*, which only reduces the number of
inode atime updates in comparison to the traditional *strictatime*. The worst
case for atime updates under 'relatime' occurs when many files are read whose
case for atime updates under *relatime* occurs when many files are read whose
atime is older than 24 h and which are freshly snapshotted. In that case the
atime is updated and COW happens - for each file - in bulk. See also
https://lwn.net/Articles/499293/ - *Atime and btrfs: a bad combination? (LWN, 2012-05-31)*.

2
Documentation/ch-subvolume-intro.rst
View File

@ -93,7 +93,7 @@ Case study: system root layouts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are two ways how the system root directory and subvolume layout could be
organized. The interesting usecase for root is to allow rollbacks to previous
organized. The interesting use case for root is to allow rollbacks to previous
version, as one atomic step. If the entire filesystem hierarchy starting in "/"
is in one subvolume, taking snapshot will encompass all files. This is easy for
the snapshotting part but has undesirable consequences for rollback. For example,

2
Documentation/ch-swapfile.rst
View File

@ -7,7 +7,7 @@ swap subsystem:
* filesystem - must have only *single* data profile
* swapfile - the containing subvolume cannot be snapshotted
* swapfile - must be preallocated (i.e. no holes)
* swapfile - must be nodatacow (i.e. also nodatasum, no compression)
* swapfile - must be NODATACOW (i.e. also NODATASUM, no compression)
The limitations come namely from the COW-based design and mapping layer of
blocks that allows the advanced features like relocation and multi-device

2
Documentation/ch-volume-management-intro.rst
View File

@ -20,7 +20,7 @@ Type
Profile
A profile describes an allocation policy based on the redundancy/replication
constraints in connection with the number of devices. The profile applies to
data and metadata block groups separately. Eg. *single*, *RAID1*.
data and metadata block groups separately. E.g. *single*, *RAID1*.
RAID level
Where applicable, the level refers to a profile that matches constraints of the

2
Documentation/ch-zoned-intro.rst
View File

@ -33,7 +33,7 @@ Incompatible features
The main constraint of the zoned devices is lack of in-place update of the data.
This is inherently incompatible with some features:
* nodatacow - overwrite in-place, cannot create such files
* NODATACOW - overwrite in-place, cannot create such files
* fallocate - preallocating space for in-place first write
* mixed-bg - unordered writes to data and metadata, fixing that means using
separate data and metadata block groups

2
Documentation/mkfs.btrfs.rst
View File

@ -258,7 +258,7 @@ extref
raid56
(kernel support since 3.9)
extended format for RAID5/6, also enabled if raid5 or raid6 block groups
extended format for RAID5/6, also enabled if RAID5 or RAID6 block groups
are selected
skinny-metadata