btrfs-progs: docs: updates

- reformatting - new documents - enhancements - status updates Signed-off-by: David Sterba <[email protected]>
kdave · Aug 28, 2023 · 8001e37 · 8001e37
1 parent a81a3d7
commit 8001e37
Show file tree

Hide file tree

Showing 11 changed files with 331 additions and 197 deletions.
diff --git a/Documentation/Contributors.rst b/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
 -------------------------
@@ -37,13 +31,13 @@ Statistics for 6.x series
 
 Legend:
 
-- *Files:* fs/btrfs/\*.[ch], fs/btrfs/tests/\*.[ch], include/uapi/linux/btrfs.h, include/uapi/linux/btrfs_tree.h, include/linux/btrfs.h, include/trace/events/btrfs.h
-- *Version:* mainline version
-- *Contributors:* number of people that sent patches that modified ''Files'', direct btrfs development or originating from other tree-wide changes
-- *SLOC:* lines of code, http://dwheeler.com/sloccount/ (generated by version 2.26)
-- *Raw lines:* counted by ''wc -l'' over ''Files''
-- *Patches:* number of patches from ''Contributors'', merge commits excluded
-- *Diffstat:* lines added and deleted in ''Files''
+-  *Files:* fs/btrfs/\*.[ch], fs/btrfs/tests/\*.[ch], include/uapi/linux/btrfs.h, include/uapi/linux/btrfs_tree.h, include/linux/btrfs.h, include/trace/events/btrfs.h
+-  *Version:* mainline version
+-  *Contributors:* number of people that sent patches that modified ''Files'', direct btrfs development or originating from other tree-wide changes
+-  *SLOC:* lines of code, http://dwheeler.com/sloccount/ (generated by version 2.26)
+-  *Raw lines:* counted by ''wc -l'' over ''Files''
+-  *Patches:* number of patches from ''Contributors'', merge commits excluded
+-  *Diffstat:* lines added and deleted in ''Files''
 
 
 Statistics for 5.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
 ---------------------------
 

diff --git a/Documentation/Kernel-by-version.rst b/Documentation/Kernel-by-version.rst
@@ -45,13 +45,13 @@ Summary of kernel changes for each version.
 
 Performance improvements:
 
-- reduced amount of reserved metadata for delayed items
+-  reduced amount of reserved metadata for delayed items
 
-  - when inserted items can be batched into one leaf
-  - when deleting batched directory index items
-  - when deleting delayed items used for deletion
-  - overall improved count of files/sec, decreased subvolume lock
-    contention
+   -  when inserted items can be batched into one leaf
+   -  when deleting batched directory index items
+   -  when deleting delayed items used for deletion
+   -  overall improved count of files/sec, decreased subvolume lock
+      contention
 
 - metadata item access bounds checker micro-optimized, with a few
   percent of improved runtime for metadata-heavy operations
@@ -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
 ---
 

diff --git a/Documentation/Quick-start.rst b/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).
diff --git a/Documentation/ReleaseChecklist b/Documentation/ReleaseChecklist
diff --git a/Documentation/Status.rst b/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,55 +252,84 @@ with subpage or require another feature to work:
      - Status
      - Notes
    * - Inline files
-     - unsupported
-     - The max_inline mount option value is ignored
+     - :statusunsupp:`unsupported`
+     - The max_inline mount option value is ignored, as if mounted with max_inline=0
    * - Free space cache v1
-     - unsupported
-     - Free space tree is mandatory
+     - :statusunsupp:`unsupported`
+     - 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
 
    * - Feature
      - 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

diff --git a/Documentation/Subpage.rst b/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
-"-s 4k" option for :command:`mkfs.btrfs`) and mount filesystems with 4KiB sectorsize.
+While with subpage support systems with 64KiB page size can create
+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
-workload, while should not notice any obvious change, as long as the initial
-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.
+Please refer to status page of :ref:`status-subpage-block-size` for
+compatibility.
diff --git a/Documentation/Trim.rst b/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.
diff --git a/Documentation/_static/style.css b/Documentation/_static/style.css
@@ -16,6 +16,14 @@
 	color: darkorange;
 }
 
-.statusunst {
+.statusunstable {
 	color: red;
 }
+
+.statusunsupp {
+	color: darkorange;
+}
+
+.statusincompat {
+	color: goldenrod;
+};