[PATCH 6/8] Documentation: btrfs: document waiting for the root filesystem devices

From: Ismael Luceno

Date: Mon Nov 16 2026 - 17:44:02 EST


Document the whole feature, including the part btrfs opens devices by
their /dev name and so cannot run the search at all without devtmpfs
mounted. Say that too, and what happens when it is not, rather than
leaving a boot that stops with nothing in the log.

Signed-off-by: Ismael Luceno <ismael@xxxxxxxxxxx>
Signed-off-by: Ismael Luceno <iluceno@xxxxxxx>
---
Documentation/filesystems/btrfs.rst | 31 +++++++++++++++++++++++++++++
1 file changed, 31 insertions(+)

diff --git a/Documentation/filesystems/btrfs.rst b/Documentation/filesystems/btrfs.rst
index a81db8f54d68..9dcdb87a53c3 100644
--- a/Documentation/filesystems/btrfs.rst
+++ b/Documentation/filesystems/btrfs.rst
@@ -33,6 +33,37 @@ The main Btrfs features include:
* Read/write metadata verification
* Online resize (shrink, grow)

+Multi-device root filesystem without an initrd
+----------------------------------------------
+
+A multi-device btrfs filesystem is normally assembled by the device scanner in
+userspace, which the initrd runs before mounting the root filesystem. Without
+an initrd there is nothing to run that scanner, so the root filesystem is
+mounted from the single device named by ``root=`` and the remaining devices are
+left out.
+
+Given ``rootwait``, btrfs finds the rest of them during the root mount.
+
+ root=/dev/sda1 rootwait
+
+The devices are then given the time ``rootwait=`` specifies, or indefinite for
+``rootwait`` with no value. The search repeats at the interval set by
+CONFIG_BTRFS_ROOT_SCAN_INTERVAL_MS (100 ms by default) until they are
+all found, and is not made for any other mount: a filesystem mounted later has
+been given the devices it needs, or is being mounted degraded on purpose.
+
+When the wait runs out btrfs mounts whatever it has, which for a redundant
+profile usually means the mount fails and the kernel panics; a warning is
+printed before that happens. Without ``rootwait`` there is no wait at all, and
+an incomplete filesystem is mounted as usual.
+
+The search needs the device nodes in ``/dev``, which come from devtmpfs. Where
+that is not mounted the search cannot start, and btrfs says so and gives up
+rather than waiting for something it can never find.
+
+The search is built with ``CONFIG_BTRFS_ROOT_SCAN``, which depends on
+``CONFIG_DEVTMPFS`` and is on by default.
+
For more information please refer to the documentation site or wiki

https://btrfs.readthedocs.io