mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: Ismael Luceno <ismael@iodev.co.uk>
To: linux-kernel@vger.kernel.org
Cc: Ismael Luceno <ismael@iodev.co.uk>,
	Ismael Luceno <iluceno@suse.de>, David Sterba <dsterba@suse.com>,
	Chris Mason <mason@kernel.org>, Jonathan Corbet <corbet@lwn.net>,
	Shuah Khan <skhan@linuxfoundation.org>,
	Randy Dunlap <rdunlap@infradead.org>,
	linux-btrfs@vger.kernel.org (open list:BTRFS FILE SYSTEM),
	linux-doc@vger.kernel.org (open list:DOCUMENTATION)
Subject: [PATCH 6/8] Documentation: btrfs: document waiting for the root filesystem devices
Date: Mon, 16 Nov 2026 23:43:22 +0100	[thread overview]
Message-ID: <20261116224316.11237-16-ismael@iodev.co.uk> (raw)
In-Reply-To: <20261116224316.11237-10-ismael@iodev.co.uk>

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@iodev.co.uk>
Signed-off-by: Ismael Luceno <iluceno@suse.de>
---
 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

  parent reply	other threads:[~2026-11-16 22:43 UTC|newest]

Thread overview: 10+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-16 22:43 [PATCH 0/8] btrfs: assemble a multi-device root filesystem without an initrd Ismael Luceno
2026-11-16 22:43 ` [PATCH 1/8] btrfs: add config options for the root device scan Ismael Luceno
2026-11-16 22:43 ` [PATCH 2/8] init: mount devtmpfs before the root filesystem Ismael Luceno
2026-11-16 22:43 ` [PATCH 3/8] init: let filesystems ask whether they are mounting the root device Ismael Luceno
2026-11-16 22:43 ` [PATCH 4/8] btrfs: add a helper to scan all block devices Ismael Luceno
2026-11-16 22:43 ` [PATCH 5/8] btrfs: wait for the root filesystem to have all its devices Ismael Luceno
2026-11-16 22:43 ` Ismael Luceno [this message]
2026-11-16 22:43 ` [PATCH 7/8] init: let a filesystem resolve a root device by UUID or label Ismael Luceno
2026-11-16 22:43 ` [PATCH 8/8] btrfs: resolve root=UUID= and root=LABEL= Ismael Luceno
2026-11-16 23:41 ` [PATCH 0/8] btrfs: assemble a multi-device root filesystem without an initrd Qu Wenruo

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20261116224316.11237-16-ismael@iodev.co.uk \
    --to=ismael@iodev.co.uk \
    --cc=corbet@lwn.net \
    --cc=dsterba@suse.com \
    --cc=iluceno@suse.de \
    --cc=linux-btrfs@vger.kernel.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mason@kernel.org \
    --cc=rdunlap@infradead.org \
    --cc=skhan@linuxfoundation.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®