btrfs-progs: docs: updates

- reformatting
- new documents
- enhancements
- status updates

Signed-off-by: David Sterba <dsterba@suse.com>

Documentation/Contributors.rst

@@ -13,13 +13,7 @@ Sorted by amount of contributions:
 * Oracle
 
 The following contributed in the past (sorted alphabetically):
-
+Fujitsu, Fusion-IO, Intel, Linux Foundation, Red Hat, STRATO AG.
-* Fujitsu
-* Fusion-IO
-* Intel
-* Linux Foundation
-* Red Hat
-* STRATO AG
 
 Statistics for 6.x series
 -------------------------
@@ -74,6 +68,7 @@ Statistics for 5.x series
    "5.18", "30", "109159", "155372", "143", "+3489 -1523"
    "5.19", "21", "109140", "155848", "202", "+4448 -3972"
 
+
 Statistics for 4.x series
 -------------------------
 
@@ -103,6 +98,7 @@ Statistics for 4.x series
    "4.19", "25", "97547", "132655", "193", "+2058 -3070"
    "4.20", "22", "97830", "133283", "128", "+1560 -932"
 
+
 Statistics for 3.x series
 -------------------------
 
@@ -131,6 +127,7 @@ Statistics for 3.x series
    "3.18", "25", "83910", "112906", "149", "+3696 -1631"
    "3.19", "18", "85420", "115031",  "82", "+2802 -677"
 
+
 Statistics for 2.6.x series
 ---------------------------
 

Documentation/Kernel-by-version.rst

@@ -275,6 +275,9 @@ Fixes:
   new value for maximum active threads would not be set to the actual
   work queues (since 6.0)
 
+6.4 (Jun 2022)
+^^^^^^^^^^^^^^
+
 5.x
 ---
 

Documentation/Quick-start.rst

@@ -1,4 +1,15 @@
 Quick start
 ===========
 
-...
+For a really quick start you can simply create and mount the filesystem. Make
+sure that the block device you'd like to use is suitable so you don't overwrite existing data.
+
+.. code-block:: shell
+
+   # mkfs.btrfs /dev/sdx
+   # mount /dev/sdx /mnt/test
+
+The default options should be acceptable for most users and sometimes can be
+changed later. The example above is for a single device filesystem, creating a
+*single* profile for data (no redundant copies of the blocks), and *DUP*
+for metadata (each block is duplicated).

Documentation/ReleaseChecklist

@@ -1,35 +0,0 @@
-Release checklist
-=================
-
-Last code touches:
-
-* make the code ready, collect patches queued for the release
-* look to mailinglist for any relevant last-minute fixes
-
-Pre-checks:
-
-* update package in OBS, (multi arch build checks)
-* submit sources to coverity
-* run all internal functional tests
-  * defaults
-  * D=asan
-  * D=ubsan
-* run all build tests
-* run with fstests
-
-Pre-release:
-
-* write CHANGES entry
-
-Release:
-
-* tag release, sign
-* make tar
-* build check of unpacked tar
-* upload tar to kernel.org
-* refresh git branches, push tags
-
-Post-release:
-
-* write and send announcement mail to mailinglist
-* update title on IRC

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.3**
+**The table is based on the latest released linux kernel: 6.4**
 
 The columns for each feature reflect the status of the implementation
 in following ways:
@@ -32,7 +32,9 @@ in following ways:
 
 .. role:: statusok
 .. role:: statusmok
-.. role:: statusunst
+.. role:: statusunstable
+.. role:: statusunsupp
+.. role:: statusincompat
 
 .. list-table::
    :header-rows: 1
@@ -126,7 +128,7 @@ in following ways:
      - mostly OK
      - reading from mirrors in parallel can be optimized further (see below)
    * - :ref:`RAID56<mkfs-section-profiles>`
-     - :statusunst:`unstable`
+     - :statusunstable:`unstable`
      - n/a
      - (see below)
    * - Mixed block groups
@@ -220,11 +222,12 @@ in following ways:
    * - :doc:`Subpage block size<Subpage>`
      - :statusmok:`mostly OK`
      - mostly OK
-     -
+     - Also see table below for more detailed compatibility.
    * - :doc:`Zoned mode<Zoned-mode>`
      - :statusmok:`mostly OK`
      - mostly OK
-     - there are known bugs, use only for testing
+     - Not yet feature complete but moderately stable, also see table below
+       for more detailed compatibility.
 
 Please open an issue if:
 
@@ -233,6 +236,8 @@ Please open an issue if:
    worth mentioning separately
 -  you know of a bug that lowers the feature status
 
+.. _status-subpage-block-size:
+
 Subpage block size
 ------------------
 
@@ -247,19 +252,27 @@ with subpage or require another feature to work:
      - Status
      - Notes
    * - Inline files
-     - unsupported
+     - :statusunsupp:`unsupported`
-     - The max_inline mount option value is ignored
+     - The max_inline mount option value is ignored, as if mounted with max_inline=0
    * - Free space cache v1
-     - unsupported
+     - :statusunsupp:`unsupported`
-     - Free space tree is mandatory
+     - Free space tree is mandatory, v1 has some assumptions about page size
    * - Compression
-     - partial support
+     - :statusok:`partial support`
      - Only page-aligned ranges can be compressed
+   * - Sectorsize
+     - :statusok:`supported`
+     - The list of supported sector sizes on a given version can be found
+       in file :file:`/sys/fs/btrfs/features/supported_sectorsizes`
 
 
 Zoned mode
 ----------
 
+Features that completely incompatible with zoned mode are listed below.
+Compatible features may not be listed and are assumed to work as they
+are unaffected by the zoned device constraints.
+
 .. list-table::
    :header-rows: 1
 
@@ -267,35 +280,56 @@ Zoned mode
      - Status
      - Notes
    * - Boot
-     - incompatible
+     - :statusincompat:`incompatible`
      - The blocks where partition table is stored is used for super block
    * - Mixed block groups
-     - incompatible
+     - :statusincompat:`incompatible`
      - Interleaving data and metadata would lead to out of order write
    * - NODATACOW
-     - incompatible
+     - :statusincompat:`incompatible`
      - In-place overwrite
    * - fallocate
-     - incompatible
+     - :statusincompat:`incompatible`
      - Preallocation of blocks would require an out of order write
    * - Free space cache v1
-     - incompatible
+     - :statusincompat:`incompatible`
      - Cache data are updated in a NODATACOW-way
+   * - Swapfile
+     - :statusincompat:`incompatible`
+     - Swap blocks are written out of order
+   * - Offline UUID change
+     - :statusincompat:`incompatible`
+     - Metadata blocks are updated in-place
    * - Free space tree
-     - supported
+     - :statusok:`supported`
      -
-   * - fstrim
-     - not implemented
-     - This would require free space v1
    * - single profile
-     - supported
+     - :statusok:`supported`
      - Both data and metadata
    * - DUP profile
-     - partial support
+     - :statusok:`partial support`
      - Only for metadata
+   * - Filesystem resize
+     - :statusok:`supported`
+     -
+   * - Balance
+     - :statusok:`supported`
+     -
+   * - Metadata UUID change
+     - :statusok:`supported`
+     -
    * - RAID (all)
      - not implemented
      - This requires raid-stripe-tree feature which is still work in progress
+   * - discard
+     - not implemented
+     - May not be required at all due to automatic zone reclaim
+   * - fsverity
+     - TBD
+     -
+   * - seeding
+     - TBD
+     -
 
 
 Details that do not fit the table

Documentation/Subpage.rst

@@ -9,40 +9,18 @@ to the exactly same size of the block and page. On x86_64 this is typically
 pages, like 64KiB on 64bit ARM or PowerPC. This means filesystems created
 with 64KiB sector size cannot be mounted on a system with 4KiB page size.
 
-While with subpage support, systems with 64KiB page size can create (still needs
+While with subpage support systems with 64KiB page size can create
-"-s 4k" option for :command:`mkfs.btrfs`) and mount filesystems with 4KiB sectorsize.
+and mount filesystems with 4KiB sectorsize.  This still needs to use option "-s
+4k" option for :command:`mkfs.btrfs`.
 
 Requirements, limitations
 -------------------------
 
 The initial subpage support has been added in v5.15, although it's still
 considered as experimental, most features are already working without problems.
+On a 64KiB page system filesystem with 4KiB sectorsize can be mounted and used
+as usual as long as the initial mount succeeds. There are cases a mount will be
+rejected when verifying compatible features.
 
-End users can mount filesystems with 4KiB sectorsize and do their usual
+Please refer to status page of :ref:`status-subpage-block-size` for
-workload, while should not notice any obvious change, as long as the initial
+compatibility.
-mount succeeded (there are cases a mount will be rejected though).
-
-The following features has some limitations for subpage:
-
-- Supported page sizes: 4KiB, 8KiB, 16KiB, 32KiB, 64KiB
-
-- Supported filesystem sector sizes on a given host are exported in
-  :file:`/sys/fs/btrfs/features/supported_sectorsizes`
-
-- No inline extents
-
-  This is an artificial limitation, to prevent mixed inline and regular extents.
-
-  Thus max_inline mount option will be silently ignored for subpage mounts,
-  and it always acts as "max_inline=0".
-
-- Compression writes are limited to page aligned ranges
-
-  Compression write for subpage has been introduced in v5.16, with the
-  limitation that only page aligned range can be compressed.  This limitation
-  is due to how btrfs handles delayed allocation.
-
-- No support for v1 space cache
-
-  The old v1 cache has quite some hard coded page size usage, and considering
-  it already deprecated, we force v2 cache for subpage.

Documentation/Trim.rst

@@ -38,4 +38,6 @@ relocate the data, however this leads to unexpected performance drop. Running
 trim periodically could prevent that too.
 
 When a filesystem is created by :doc:`mkfs.btrfs` and is capable
-of trim, then it's by default performed on all devices.
+of trim, then it's by default performed on all devices. Since kernel 6.2 the
+*discard=async* mount option is automatically enabled on devices that support
+that.

Documentation/_static/style.css

@@ -16,6 +16,14 @@
 	color: darkorange;
 }
 
-.statusunst {
+.statusunstable {
 	color: red;
 }
+
+.statusunsupp {
+	color: darkorange;
+}
+
+.statusincompat {
+	color: goldenrod;
+};

Documentation/btrfs-ioctl.rst

@@ -34,6 +34,11 @@ DATA STRUCTURES AND DEFINITIONS
 
 .. code-block:: c
 
+        #define BTRFS_SUBVOL_RDONLY                  (1ULL << 1)
+        #define BTRFS_SUBVOL_QGROUP_INHERIT          (1ULL << 2)
+        #define BTRFS_DEVICE_SPEC_BY_ID              (1ULL << 3)
+        #define BTRFS_SUBVOL_SPEC_BY_ID              (1ULL << 4)
+
         struct btrfs_ioctl_vol_args_v2 {
                 __s64 fd;
                 __u64 transid;
@@ -111,6 +116,40 @@ DATA STRUCTURES AND DEFINITIONS
                 __u64 reserved[8];
         };
 
+.. _struct_btrfs_qgroup_inherit:
+
+.. code-block:: c
+
+        #define BTRFS_QGROUP_INHERIT_SET_LIMITS         (1ULL << 0)
+
+        struct btrfs_qgroup_inherit {
+                __u64 flags;
+                __u64 num_qgroups;
+                __u64 num_ref_copies;
+                __u64 num_excl_copies;
+                struct btrfs_qgroup_limit lim;
+                __u64 qgroups[];
+        };
+
+.. _struct_btrfs_qgroup_limit:
+
+.. code-block:: c
+
+	#define BTRFS_QGROUP_LIMIT_MAX_RFER             (1ULL << 0)
+	#define BTRFS_QGROUP_LIMIT_MAX_EXCL             (1ULL << 1)
+	#define BTRFS_QGROUP_LIMIT_RSV_RFER             (1ULL << 2)
+	#define BTRFS_QGROUP_LIMIT_RSV_EXCL             (1ULL << 3)
+	#define BTRFS_QGROUP_LIMIT_RFER_CMPR            (1ULL << 4)
+	#define BTRFS_QGROUP_LIMIT_EXCL_CMPR            (1ULL << 5)
+
+	struct btrfs_qgroup_limit {
+		__u64 flags;
+		__u64 max_rfer;
+		__u64 max_excl;
+		__u64 rsv_rfer;
+		__u64 rsv_excl;
+	};
+
 .. list-table::
    :header-rows: 1
 
@@ -150,7 +189,7 @@ The 'BTRFS_IOC_NUMBER' is says which operation should be done on the given
 arguments. Some ioctls take a specific data structure, some of them share a
 common one, no argument structure ioctls exist too.
 
-The library 'libbtrfsutil' wraps a few ioctls for convenience. Using raw ioctls
+The library *libbtrfsutil* wraps a few ioctls for convenience. Using raw ioctls
 is not discouraged but may be cumbersome though it does not need additional
 library dependency. Backward compatibility is guaranteed and incompatible
 changes usually lead to a new version of the ioctl. Enhancements of existing
@@ -174,8 +213,8 @@ LIST OF IOCTLS
      - (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
      -
      -
@@ -185,9 +224,9 @@ LIST OF IOCTLS
    * - BTRFS_IOC_SCAN_DEV
      -
      -
-   * - BTRFS_IOC_SYNC
+   * - :ref:`BTRFS_IOC_SYNC<BTRFS_IOC_SYNC>`
-     -
+     - Sync the filesystem, possibly process queued up work
-     -
+     - NULL
    * - BTRFS_IOC_CLONE
      -
      -
@@ -375,6 +414,50 @@ BTRFS_IOC_SUBVOL_CREATE
        size is limited by Linux VFS to 255 characters and must not contain a slash
        ('/')
 
+BTRFS_IOC_SNAP_CREATE
+~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+   obsoleted by :ref:`BTRFS_IOC_SNAP_CREATE_V2<BTRFS_IOC_SNAP_CREATE_V2>`
+
+*(since: 3.0, obsoleted: 4.0)* Create a snapshot of 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
+     - 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
+       size is limited by Linux VFS to 255 characters and must not contain a slash
+       ('/')
+
+.. _BTRFS_IOC_SYNC:
+
+BTRFS_IOC_SYNC
+~~~~~~~~~~~~~~
+
+Sync the filesystem data as would ``sync()`` syscall do, additionally
+wake up the internal transaction thread that may trigger actions like
+subvolume cleaning or queued defragmentation.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Field
+     - Description
+   * - ioctl fd
+     - file descriptor of any file or directory in the filesystem
+   * - ioctl args
+     - NULL
+
 .. _BTRFS_IOC_SNAP_CREATE_V2:
 
 BTRFS_IOC_SNAP_CREATE_V2
@@ -392,7 +475,8 @@ Create a snapshot of a subvolume.
    * - ioctl args
      - :ref:`struct btrfs_ioctl_vol_args_v2<struct_btrfs_ioctl_vol_args_v2>`
    * - args.fd
-     - file descriptor of any directory inside the subvolume to snapshot
+     - file descriptor of any directory inside the subvolume to snapshot,
+       must be on the filesystem
    * - args.transid
      - ignored
    * - args.flags
@@ -406,7 +490,7 @@ Create a snapshot of a subvolume.
 BTRFS_IOC_SUBVOL_CREATE_V2
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-*(since: 3.6)* Create a subvolume, qgroup inheritance can be specified.
+*(since: 3.6)* Create a subvolume, qgroup inheritance and limits can be specified.
 
 .. list-table::
    :header-rows: 1
@@ -422,17 +506,19 @@ BTRFS_IOC_SUBVOL_CREATE_V2
    * - args.transid
      - ignored
    * - args.flags
-     - ignored
+     - flags to set on the subvolume, ``BTRFS_SUBVOL_RDONLY`` for readonly,
+       ``BTRFS_SUBVOL_QGROUP_INHERIT`` if the qgroup related fileds should be
+       processed
    * - args.size
-     - ...
+     - number of entries in ``args.qgroup_inherit``
    * - args.qgroup_inherit
-     - ...
+     - inherit the given qgroups
+       (: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
        size is limited by Linux VFS to 255 characters and must not contain a
        slash ('/')
-   * - devid
-     - ...
 
 .. _BTRFS_IOC_SUBVOL_GETFLAGS:
 

Documentation/dev/ReleaseChecklist.rst

@@ -0,0 +1,49 @@
+Release checklist
+=================
+
+Last code touches:
+
+*  make the code ready, collect patches queued for the release
+*  look to mailinglist for any relevant last-minute fixes
+*  skim patches for typos, inconsistent subjects
+
+Pre-checks:
+
+*  update package in OBS, (multi arch build checks)
+*  run all functional tests locally with
+
+   *  defaults
+   *  D=asan
+   *  D=ubsan
+*  run all build tests (``tests/build-tests.sh``)
+*  run with fstests
+*  check Github actions for status (https://github.com/kdave/btrfs-progs/actions)
+
+   *  branch *devel*
+   *  branch *release-test* -- extensive pre-release build checks
+   *  branch *coverage-test* -- code coverage, for information purposes only
+
+Pre-release:
+
+*  write CHANGES entry (will be visible on RTD right away)
+
+Release:
+
+*  tag release, sign
+*  build check of unpacked tar
+*  generate documentation
+*  make tar
+*  upload tar to kernel.org
+*  refresh git branches, push tags
+
+Post-release:
+
+*  write and send announcement mail to the mailinglist
+*  update title on IRC
+*  github updates
+
+   *  create a new release from the latest tag
+   *  copy text from CHANGES as contents, formatting is the same
+   *  wait for static binaries github action to finish
+   *  run ``ci/actions/update-artifacts`` to copy the built static binaries to the
+      release (requires github command line tool ``gh``)

Documentation/index.rst

@@ -61,6 +61,7 @@ Welcome to BTRFS documentation!
    dev/dev-send-stream
    dev/dev-json
    dev/dev-internal-apis
+   dev/ReleaseChecklist
    btrfs-ioctl
 
 .. toctree::