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: formatting, fixups, updates 

- update Status page
- new features in 6.7
- more ioctls
- CSS fix to wrap long lines in tables

[ci skip]

Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
David Sterba 2023-10-30 23:15:31 +01:00
parent ffebbf6f2a
commit fcd9142b67
7 changed files with 207 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -93,6 +93,16 @@ features see :doc:`Status<Status>` page.
finalizing the directory, the cache also gains significant speedups (up
to 10x).
6.7 - raid-stripe-tree
New tree for logical mapping, allows some RAID modes for zoned mode.
6.7 - simplified quota accounting
A simplified mode of qgroups accounting
6.7 - temporary fsid
Mount of cloned devices is now possible, the filesystem will get a new
randomly generated UUID on mount
5.x
---

2
Documentation/Introduction.rst
View File

@ -21,6 +21,7 @@ Feature overview:
* Checksums on data and metadata (crc32c, xxhash, sha256, blake2b)
* Compression (ZLIB, LZO, ZSTD), heuristics
* Integrated multiple device support
* File Striping
* File Mirroring
* File Striping+Mirroring
@ -40,6 +41,7 @@ Feature overview:
modifications are stored on different devices; the original is unchanged.
* Subvolume-aware quota support
* Send/receive of subvolume changes
* Efficient incremental filesystem mirroring
* Batch, or out-of-band deduplication (happens after writes, not during)
* Swapfile support

31
Documentation/Status.rst
View File

@ -13,7 +13,7 @@ in meeting your performance expectations for your specific workload.
Combination of features can vary in performance, the table does not
cover all possibilities.
**The table is based on the latest released linux kernel: 6.5**
**The table is based on the latest released linux kernel: 6.6**
The columns for each feature reflect the status of the implementation
in following ways:
@ -123,6 +123,10 @@ in following ways:
- :statusok:`OK`
- OK
-
* - Temporary UUID
- 6.7
- 6.7
-
* - :doc:`Seeding<Seeding-device>`
- :statusok:`OK`
- OK
@ -131,6 +135,10 @@ in following ways:
- :statusmok:`mostly OK`
- mostly OK
- qgroups with many snapshots slows down balance
* - :doc:`Quotas, simple qgroups<Qgroups>`
- 6.7
- 6.7
- simplified qgroup accounting, better performance
* - :doc:`Swapfile<Swapfile>`
- :statusok:`OK`
- n/a
@ -226,7 +234,11 @@ converted later).
- :statusok:`OK`
- OK
-
* - :ref:`Block group tree`<mkfs-feature-block-group-tree>`
* - :ref:`Block group tree<mkfs-feature-block-group-tree>`
- :statusok:`OK`
- OK
-
* - :ref:`Raid stripe tree<mkfs-feature-raid-stripe-tree>`
- :statusok:`OK`
- OK
-
@ -321,7 +333,7 @@ are unaffected by the zoned device constraints.
- Notes
* - Boot
- :statusincompat:`incompatible`
- The blocks where partition table is stored is used for super block
- The blocks where partition table is stored are used for super block
* - Mixed block groups
- :statusincompat:`incompatible`
- Interleaving data and metadata would lead to out of order write
@ -343,6 +355,12 @@ are unaffected by the zoned device constraints.
* - Free space tree
- :statusok:`supported`
-
* - Block group tree
- :statusok:`supported`
-
* - Raid stripe tree
- :statusok:`supported`
- Allows to use RAID in zoned mode
* - Filesystem resize
- :statusok:`supported`
-
@ -352,9 +370,12 @@ are unaffected by the zoned device constraints.
* - Metadata UUID change
- :statusok:`supported`
-
* - RAID (all)
* - RAID0, RAID1*
- :statusok:`supported`
- requires `raid-stripe-tree`
* - RAID56
- not implemented
- This requires raid-stripe-tree feature which is still work in progress
- will be supported once raid-stripe-tree support is implemented
* - discard
- not implemented
- May not be required at all due to automatic zone reclaim

8
Documentation/_static/style.css
View File

@ -2,6 +2,14 @@
max-width: 1200px !important;
}
.wy-table-responsive {
white-space: normal !important;
}
.wy-table-responsive table td, .wy-table-responsive table th {
white-space: normal !important;
}
.green {
color: green;
}

153
Documentation/btrfs-ioctl.rst
View File

@ -240,10 +240,7 @@ LIST OF IOCTLS
* - Name
- Description
- Data
* - BTRFS_IOC_SUBVOL_CREATE
- (obsolete) create a subvolume
- :ref:`struct btrfs_ioctl_vol_args<struct_btrfs_ioctl_vol_args>`
* - BTRFS_IOC_SNAP_CREATE
* - :ref:`BTRFS_IOC_SNAP_CREATE<BTRFS_IOC_SNAP_CREATE>`
- (obsolete) create a snapshot of a subvolume
- :ref:`struct btrfs_ioctl_vol_args<struct_btrfs_ioctl_vol_args>`
* - BTRFS_IOC_DEFRAG
@ -252,9 +249,9 @@ LIST OF IOCTLS
* - BTRFS_IOC_RESIZE
-
-
* - BTRFS_IOC_SCAN_DEV
-
-
* - :ref:`BTRFS_IOC_SCAN_DEV<BTRFS_IOC_SCAN_DEV>`
- scan and register a given device path with filesystem module
- :ref:`struct btrfs_ioctl_vol_args<struct_btrfs_ioctl_vol_args>`
* - :ref:`BTRFS_IOC_SYNC<BTRFS_IOC_SYNC>`
- Sync the filesystem, possibly process queued up work
- NULL
@ -273,12 +270,12 @@ LIST OF IOCTLS
* - BTRFS_IOC_CLONE_RANGE
-
-
* - BTRFS_IOC_SUBVOL_CREATE
-
-
* - BTRFS_IOC_SNAP_DESTROY
-
-
* - :ref:`BTRFS_IOC_SUBVOL_CREATE<BTRFS_IOC_SUBVOL_CREATE>`
- (obsolete) create a subvolume
- :ref:`struct btrfs_ioctl_vol_args<struct_btrfs_ioctl_vol_args>`
* - :ref:`BTRFS_IOC_SNAP_DESTROY<BTRFS_IOC_SNAP_DESTROY>`
- (obsolete) delete a subvolume
- :ref:`struct btrfs_ioctl_vol_args<struct_btrfs_ioctl_vol_args>`
* - BTRFS_IOC_DEFRAG_RANGE
-
-
@ -291,9 +288,9 @@ LIST OF IOCTLS
* - BTRFS_IOC_INO_LOOKUP
-
-
* - BTRFS_IOC_DEFAULT_SUBVOL
-
-
* - :ref:`BTRFS_IOC_DEFAULT_SUBVOL<BTRFS_IOC_DEFAULT_SUBVOL>`
- set the default subvolume id
- uint64_t
* - BTRFS_IOC_SPACE_INFO
-
-
@ -421,29 +418,7 @@ LIST OF IOCTLS
DETAILED DESCRIPTION
--------------------
BTRFS_IOC_SUBVOL_CREATE
~~~~~~~~~~~~~~~~~~~~~~~
.. note::
obsoleted by :ref:`BTRFS_IOC_SUBVOL_CREATE_V2<BTRFS_IOC_SUBVOL_CREATE_V2>`
*(since: 3.0, obsoleted: 4.0)* Create a subvolume.
.. list-table::
:header-rows: 1
* - Field
- Description
* - ioctl fd
- file descriptor of the parent directory of the new subvolume
* - ioctl args
- :ref:`struct btrfs_ioctl_vol_args<struct_btrfs_ioctl_vol_args>`
* - args.fd
- ignored
* - args.name
- name of the subvolume, although the buffer can be almost 4k, the file
size is limited by Linux VFS to 255 characters and must not contain a slash
('/')
.. _BTRFS_IOC_SNAP_CREATE:
BTRFS_IOC_SNAP_CREATE
~~~~~~~~~~~~~~~~~~~~~
@ -466,10 +441,34 @@ BTRFS_IOC_SNAP_CREATE
- file descriptor of any directory inside the subvolume to snapshot,
must be on the same filesystem
* - args.name
- name of the subvolume, although the buffer can be almost 4k, the file
- name of the subvolume, although the buffer can be almost 4KiB, the file
size is limited by Linux VFS to 255 characters and must not contain a slash
('/')
.. _BTRFS_IOC_SCAN_DEV:
BTRFS_IOC_SCAN_DEV
~~~~~~~~~~~~~~~~~~
Scan and register a given device in the filesystem module, which can be later
used for automatic device and filesystem association at mount time. This
operates on the control device, not files from a mounted filesystem.
Can be safely called repeatedly with same device path.
.. list-table::
:header-rows: 1
* - Field
- Description
* - ioctl fd
- file descriptor of the control device :file:`/dev/btrfs-control`
* - ioctl args
- :ref:`struct btrfs_ioctl_vol_args<struct_btrfs_ioctl_vol_args>`
* - args.fd
- ignored
* - args.name
- full path of the device
.. _BTRFS_IOC_SYNC:
BTRFS_IOC_SYNC
@ -489,6 +488,76 @@ subvolume cleaning or queued defragmentation.
* - ioctl args
- NULL
.. _BTRFS_IOC_SUBVOL_CREATE:
BTRFS_IOC_SUBVOL_CREATE
~~~~~~~~~~~~~~~~~~~~~~~
.. note::
obsoleted by :ref:`BTRFS_IOC_SUBVOL_CREATE_V2<BTRFS_IOC_SUBVOL_CREATE_V2>`
*(since: 3.0, obsoleted: 4.0)* Create a subvolume.
.. list-table::
:header-rows: 1
* - Field
- Description
* - ioctl fd
- file descriptor of the parent directory of the new subvolume
* - ioctl args
- :ref:`struct btrfs_ioctl_vol_args<struct_btrfs_ioctl_vol_args>`
* - args.fd
- ignored
* - args.name
- name of the subvolume, although the buffer can be almost 4KiB, the file
size is limited by Linux VFS to 255 characters and must not contain a slash
('/')
.. _BTRFS_IOC_SNAP_DESTROY:
BTRFS_IOC_SNAP_DESTROY
~~~~~~~~~~~~~~~~~~~~~~
.. note::
obsoleted by :ref:`BTRFS_IOC_SNAP_DESTROY_V2<BTRFS_IOC_SNAP_DESTROY_V2>`
*(since: 2.6.33, obsoleted: 5.7)* Delete a subvolume.
.. list-table::
:header-rows: 1
* - Field
- Description
* - ioctl fd
- file descriptor of the parent directory of the new subvolume
* - ioctl args
- :ref:`struct btrfs_ioctl_vol_args<struct_btrfs_ioctl_vol_args>`
* - args.fd
- ignored
* - args.name
- name of the subvolume, although the buffer can be almost 4KiB, the file
size is limited by Linux VFS to 255 characters and must not contain a slash
('/')
.. _BTRFS_IOC_DEFAULT_SUBVOL:
BTRFS_IOC_DEFAULT_SUBVOL
~~~~~~~~~~~~~~~~~~~~~~~~
Set the given subvolume id as the default one when mounting the filesystem
without `subvol=path` or `subvolid=id` options.
.. list-table::
:header-rows: 1
* - Field
- Description
* - ioctl fd
- file descriptor of the directory inside which to create the new snapshot
* - ioctl args
- numeric value of subvolume to become default (uint64_t)
.. _BTRFS_IOC_SNAP_CREATE_V2:
BTRFS_IOC_SNAP_CREATE_V2
@ -513,7 +582,7 @@ Create a snapshot of a subvolume.
* - args.flags
- any subset of `BTRFS_SUBVOL_RDONLY` to make the new snapshot read-only,
or `BTRFS_SUBVOL_QGROUP_INHERIT` to apply the `qgroup_inherit` field
* - name
* - args.name
- the name, under the ioctl fd, for the new subvolume
.. _BTRFS_IOC_SUBVOL_CREATE_V2:
@ -547,7 +616,7 @@ BTRFS_IOC_SUBVOL_CREATE_V2
(:ref:`struct btrfs_qgroup_inherit<struct_btrfs_qgroup_inherit>`) and
limits (:ref:`struct btrfs_qgroup_limit<struct_btrfs_qgroup_limit>`)
* - name
- name of the subvolume, although the buffer can be almost 4k, the file
- name of the subvolume, although the buffer can be almost 4KiB, the file
size is limited by Linux VFS to 255 characters and must not contain a
slash ('/')

12
Documentation/mkfs.btrfs.rst
View File

@ -333,6 +333,18 @@ block-group-tree
enabled at *mkfs* time is possible, see :doc:`btrfstune`. Online
conversion is not possible.
.. _mkfs-feature-raid-stripe-tree:
raid-stripe-tree
(kernel support since 6.7)
New tree for logical file extent mapping where the physical mapping
may not match on multiple devices. this is now used in zoned mode to
implement RAID0/RAID1* profiles, but can be used in non-zoned mode as
well. The support for RAID56 is in development and will eventually
fix the problems with the current implementation. This is a backward
incompatible feature and has to be enabled at mkfs time.
squota
(kernel support since 6.7)

2
kernel-shared/uapi/btrfs.h
View File

@ -1171,7 +1171,7 @@ enum btrfs_err_code {
struct btrfs_ioctl_vol_args)
#define BTRFS_IOC_RESIZE _IOW(BTRFS_IOCTL_MAGIC, 3, \
struct btrfs_ioctl_vol_args)
#define BTRFS_IOC_SCAN_DEV _IOW(BTRFS_IOCTL_MAGIC, 4, \
#define BTRFS_IOC_SCAN_DEV _IOW(BTRFS_IOCTL_MAGIC, 5, \
struct btrfs_ioctl_vol_args)
#define BTRFS_IOC_FORGET_DEV _IOW(BTRFS_IOCTL_MAGIC, 5, \
struct btrfs_ioctl_vol_args)