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>

Documentation/Feature-by-version.rst

@@ -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
 ---
 

Documentation/Introduction.rst

@@ -5,43 +5,45 @@ BTRFS is a modern copy on write (COW) filesystem for Linux aimed at
 implementing advanced features while also focusing on fault tolerance, repair
 and easy administration. Its main features and benefits are:
 
-* Snapshots which do not make a full copy of the files
+*  Snapshots which do not make a full copy of the files
-* Built-in volume management, support for software-based RAID 0, RAID 1, RAID 10 and others
+*  Built-in volume management, support for software-based RAID 0, RAID 1, RAID 10 and others
-* Self-healing - checksums for data and metadata, automatic detection of silent data corruptions
+*  Self-healing - checksums for data and metadata, automatic detection of silent data corruptions
 
 Feature overview:
 
-* Extent based file storage
+*  Extent based file storage
-* 2\ :sup:`64` byte == 16 EiB maximum file size (practical limit is 8 EiB due to Linux VFS)
+*  2\ :sup:`64` byte == 16 EiB maximum file size (practical limit is 8 EiB due to Linux VFS)
-* Space-efficient packing of small files
+*  Space-efficient packing of small files
-* Space-efficient indexed directories
+*  Space-efficient indexed directories
-* Dynamic inode allocation
+*  Dynamic inode allocation
-* Writable snapshots, read-only snapshots
+*  Writable snapshots, read-only snapshots
-* Subvolumes (separate internal filesystem roots)
+*  Subvolumes (separate internal filesystem roots)
-* Checksums on data and metadata (crc32c, xxhash, sha256, blake2b)
+*  Checksums on data and metadata (crc32c, xxhash, sha256, blake2b)
-* Compression (ZLIB, LZO, ZSTD), heuristics
+*  Compression (ZLIB, LZO, ZSTD), heuristics
-* Integrated multiple device support
+*  Integrated multiple device support
-   * File Striping
+
-   * File Mirroring
+    *  File Striping
-   * File Striping+Mirroring
+    *  File Mirroring
-   * Single and Dual Parity implementations (experimental, not production-ready)
+    *  File Striping+Mirroring
-* SSD (flash storage) awareness (TRIM/Discard for reporting free blocks for
+    *  Single and Dual Parity implementations (experimental, not production-ready)
-  reuse) and optimizations (e.g. avoiding unnecessary seek optimizations,
+*  SSD (flash storage) awareness (TRIM/Discard for reporting free blocks for
-  sending writes in clusters, even if they are from unrelated files. This
+   reuse) and optimizations (e.g. avoiding unnecessary seek optimizations,
-  results in larger write operations and faster write throughput)
+   sending writes in clusters, even if they are from unrelated files. This
-* Efficient incremental backup
+   results in larger write operations and faster write throughput)
-* Background scrub process for finding and repairing errors of files with redundant copies
+*  Efficient incremental backup
-* Online filesystem defragmentation
+*  Background scrub process for finding and repairing errors of files with redundant copies
-* Offline filesystem check
+*  Online filesystem defragmentation
-* In-place conversion of existing ext2/3/4 and reiserfs file systems
+*  Offline filesystem check
-* Seed devices. Create a (readonly) filesystem that acts as a template to seed
+*  In-place conversion of existing ext2/3/4 and reiserfs file systems
-  other Btrfs filesystems. The original filesystem and devices are included as
+*  Seed devices. Create a (readonly) filesystem that acts as a template to seed
-  a readonly starting point for the new filesystem. Using copy on write, all
+   other Btrfs filesystems. The original filesystem and devices are included as
-  modifications are stored on different devices; the original is unchanged.
+   a readonly starting point for the new filesystem. Using copy on write, all
-* Subvolume-aware quota support
+   modifications are stored on different devices; the original is unchanged.
-* Send/receive of subvolume changes
+*  Subvolume-aware quota support
-   * Efficient incremental filesystem mirroring
+*  Send/receive of subvolume changes
-* Batch, or out-of-band deduplication (happens after writes, not during)
+
-* Swapfile support
+    *  Efficient incremental filesystem mirroring
-* Tree-checker, post-read and pre-write metadata verification
+*  Batch, or out-of-band deduplication (happens after writes, not during)
-* Zoned mode support (SMR/ZBC/ZNS friendly allocation)
+*  Swapfile support
+*  Tree-checker, post-read and pre-write metadata verification
+*  Zoned mode support (SMR/ZBC/ZNS friendly allocation)

Documentation/Status.rst

@@ -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

Documentation/_static/style.css

@@ -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;
 }

Documentation/btrfs-ioctl.rst

@@ -240,10 +240,7 @@ LIST OF IOCTLS
    * - Name
      - Description
      - Data
-   * - BTRFS_IOC_SUBVOL_CREATE
+   * - :ref:`BTRFS_IOC_SNAP_CREATE<BTRFS_IOC_SNAP_CREATE>`
-     - (obsolete) create a subvolume
-     - :ref:`struct btrfs_ioctl_vol_args<struct_btrfs_ioctl_vol_args>`
-   * - 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
+   * - :ref:`BTRFS_IOC_SUBVOL_CREATE<BTRFS_IOC_SUBVOL_CREATE>`
-     -
+     - (obsolete) create a subvolume
-     -
+     - :ref:`struct btrfs_ioctl_vol_args<struct_btrfs_ioctl_vol_args>`
-   * - BTRFS_IOC_SNAP_DESTROY
+   * - :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
+.. _BTRFS_IOC_SNAP_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
 ~~~~~~~~~~~~~~~~~~~~~
@@ -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 ('/')
 

Documentation/mkfs.btrfs.rst

@@ -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)
 

kernel-shared/uapi/btrfs.h

@@ -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)