btrfs-progs: docs: documentation updates and fixes

Signed-off-by: David Sterba <[email protected]>

Author: kdave

Diff for: Documentation/DocConventions.rst

@@ -24,14 +24,16 @@ Quotes, reference, element formatting:
 
 -  exact syntax: monotype ````usage=0````
 -  reference to arguments: italics ``*italics*``
--  command reference: bold text by directive ``:command:`btrfs filesystem show```
+-  command reference:
 
+   -  any system command, example, bold text by directive ``:command:`btrfs filesystem show```
+   -  subcommands with their own manual page ``:doc:`btrfs-filesystem```
    -  subcommand names should be spelled in full, i.e. *filesystem* instead of *fi*
 
 -  file, directory or path references: by directive ``:file:`/path```
 
 -  section references without a label: italics ``*EXAMPLES*``
--  section references with a target label: reference by directive ``:ref:<visible text`target-label`>``
+-  section references with a target label: reference by directive ``:ref:`visible text <target-label>```
 
 -  argument name in option description: caps in angle brackets ``<NAME>``
 
@@ -53,18 +55,32 @@ Referencing:
 
 -  NOTE: we have either full doc reference by ``:doc:`docname``` or
    inter-document reference to an **unambiguous** label
-   ``:ref:`target-label```, i.e. we can't reference a label that may appear in
+   ``:ref:`target-label```, i.e. this can't reference a label that may appear in
    more files due to including, this will lead to the document itself that may
-   not be the full page (may be solvable by own directive, TBD)
+   not be the full page
 
--  generic links can use the free form link syntax with description ```Link text <https://example.com>`_``
+-  **ambiguous** or duplicate labels (that exist in a file that is included from other documents)
+   need to be
+
+   -  defined as ``.. duplabel:: labelname``
+   -  referenced as ``:docref:`visible text <document:label>```
+
+-  generic links can use the free form link syntax with description ```Link text <https://example.com>`__``
+   (note the double underscore, this is *anonymous* link and does not create a reference)
    or plain link that will auto-render to a clikable link https://example.com
 
 -  in manual pages: always use full link as it's meant to be read in terminal
    output and must allow copy&paste
 
+-  own manual page references:
+
+   - ``:doc:`btrfs-filesystem```, i.e. it's the document name, it will render the section automatically
+   - other manual pages ``:manref:page(1)``, the exact name and section number
+
 -  add more clickable references rather than less
 
+-  custom rules and directives are implemented in :file:`Documentation/conf.py`
+
 Conventions:
 
 -  version should be formatted like ``6.1`` or ``v6.1`` and clear what

Diff for: Documentation/Introduction.rst

@@ -8,11 +8,14 @@ and easy administration. Its main features and benefits are:
 *  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
 *  Self-healing - checksums for data and metadata, automatic detection of silent data corruptions
+*  Data compression
+*  Reflinks, fast and efficient file copies
 
-Feature overview:
+Feature overview
+----------------
 
 *  Extent based file storage
-*  2\ :sup:`64` byte == 16 EiB :ref:`maximum file size<administration-limits>` (practical limit is 8 EiB due to Linux VFS)
+*  2\ :sup:`64` byte (16 EiB) :ref:`maximum file size<administration-limits>` (practical limit is 8 EiB due to Linux VFS)
 *  :doc:`Space-efficient packing of small files<Inline-files>`
 *  Space-efficient indexed directories
 *  :ref:`Dynamic inode allocation<administration-flexibility>`
@@ -21,10 +24,10 @@ Feature overview:
 *  :doc:`Compression (ZLIB, LZO, ZSTD), heuristics<Compression>`
 *  :doc:`Integrated multiple device support<Volume-management>`:
 
-    * File Striping (like RAID0)
-    * File Mirroring (like RAID1 up to 4 copies)
-    * File Striping+Mirroring (like RAID10)
-    * Single and Dual Parity implementations (like RAID5/6, experimental, not production-ready)
+   * File Striping (like RAID0)
+   * File Mirroring (like RAID1 up to 4 copies)
+   * File Striping+Mirroring (like RAID10)
+   * Single and Dual Parity implementations (like RAID5/6, experimental, not production-ready)
 
 *  SSD/NVMe (flash storage) awareness, :doc:`TRIM/Discard<Trim>` for reporting free blocks for
    reuse and optimizations (e.g. avoiding unnecessary seek optimizations,
@@ -45,3 +48,26 @@ Feature overview:
 *  :doc:`Swapfile support<Swapfile>`
 *  :doc:`Tree-checker<Tree-checker>`, post-read and pre-write metadata verification
 *  :doc:`Zoned mode support<Zoned-mode>` (SMR/ZBC/ZNS friendly allocation, emulated on non-zoned devices)
+
+A more detailed list of features and compatibility is on the :doc:`status page <Status>`.
+
+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).
+
+Read more about:
+
+   * creating a filesystem at :doc:`mkfs.btrfs`
+   * mount options at :doc:`Administration`

Diff for: Documentation/Quick-start.rst

@@ -1,6 +1,9 @@
 Experimental features
 =====================
 
+User space tools (btrfs-progs)
+------------------------------
+
 Experimental or unstable features may be enabled by
 
     ./configure --enable-experimental
@@ -38,3 +41,20 @@ 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
 issues if needed.
+
+
+Kernel module
+-------------
+
+The kernel module can be configured to enable experimental features or
+functionality since version 6.13 by
+`CONFIG_BTRFS_EXPERIMENTAL <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/fs/btrfs/Kconfig#n82>`__ .
+The features can get added or removed in each release. At runtime the status
+can be seen in the system log message once the kernel module is loaded:
+
+.. code-block:: none
+
+   Btrfs loaded, experimental=on, debug=on, assert=on, ref-verify=on, zoned=yes, fsverity=yes
+
+
+In some cases (standalone features) it's exported in :file:`/sys/fs/btrfs/FSID/features`.

Diff for: Documentation/dev/Experimental.rst

@@ -1,8 +1,8 @@
 Btrees
 ======
 
-Btrees Introduction
--------------------
+B-trees Introduction
+--------------------
 
 Btrfs uses a single set of btree manipulation code for all metadata in
 the filesystem. For performance or organizational purposes, the trees
@@ -109,3 +109,40 @@ Data Relocation Tree
 
 Log Root Tree
 -------------
+
+
+UUID Tree
+---------
+
+The tree storesc correspondence between UUIDs and subvolumes. Used for
+quick lookup during send.
+
+
+Quota Tree
+----------
+
+The qgroup information about status and qgroup relations are stored in this tree.
+The tree exists only when quotas are enabled.
+
+
+Free Space Tree
+---------------
+
+This tree implements *space_cache=v2*, which is a tree-based tracking of free
+space. Successor of the v1 code which used inodes to store the space information.
+
+
+Block Group Tree
+----------------
+
+Separate tree (and feature) that stores only block group items and allows quick lookup
+during mount. Otherwise the block group items are scattered in the Extent tree
+and cause slow mount due to excessive seeking.
+
+
+Raid Stripe Tree
+----------------
+
+A separate tracking of file extents and block groups that allows more flexible
+location of physical offsets while keeping the logical offsets the same. This
+is used by zoned mode and raid56.

Diff for: Documentation/dev/dev-btrees.rst

@@ -45,16 +45,27 @@ and for concatenation helpers :code:`path_cat_out()` or
 :code:`path_cat_out3()` and check the error values for overflows. There are
 helpers to check file type :code:`path_is_*()`.
 
+Dynamic array of pointers
+-------------------------
+
+Files: :file:`common/array.h`
+
+Extensible array containing pointers to objects, is reallocated when the
+new elements don't fit current capacity. For iteration the array is accessible
+as *array->datai[i]* of type *void\** and needs be cast to user type.
+
 TODO
 ----
 
 Undocumented or incomplete APIs:
 
-* common/array.h
 * common/cpu-utils.h
 * common/device-utils.h
+* common/format-output.h
 * common/messages.h
 * common/open-utils.h
+* common/rbtree-utils.h
 * common/sort-utils.h
 * common/string-table.h
+* common/sysfs-utils.h
 * common/task-utils.h

Diff for: Documentation/dev/dev-internal-apis.rst

@@ -113,5 +113,4 @@ for missing contents.
    :maxdepth: 1
    :caption: TODO
 
-   Quick-start
    trouble-index