From f333fb810d0ef5033db217d2bf12c06646558c70 Mon Sep 17 00:00:00 2001
From: Hugo Buddelmeijer <hugo@buddelmeijer.nl>
Date: Tue, 17 Feb 2026 20:04:06 +0100
Subject: [PATCH] doc: Improve raid-device-mapping documentation.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* doc/guix.texi (Mapped Devices): Move examples into the mapping defvars.
Add how to load kernel modules for raid.  Add RAID cindex.

Change-Id: If2d3f3c48940d2428b36bdd85d31c8288db35f3b
Signed-off-by: Ludovic Courtès <ludo@gnu.org>
Modified-by: Ludovic Courtès <ludo@gnu.org>
Merges: #6512
---
 doc/guix.texi | 58 ++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 39 insertions(+), 19 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index d52be59a1a..0a6020220c 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -18968,7 +18968,7 @@ RAID devices are obtained by @dfn{assembling} several other devices, such
 as hard disks or partitions, into a new one that behaves as one partition.
 
 Mapped devices are declared using the @code{mapped-device} form,
-defined as follows; for examples, see below.
+defined as follows.
 
 @deftp {Data Type} mapped-device
 Objects of this type represent device mappings that will be made when
@@ -19064,23 +19064,6 @@ options, along with @option{--allow-discards}:
 @end lisp
 
 @end table
-@end defvar
-
-@defvar raid-device-mapping
-This defines a RAID device, which is assembled using the @code{mdadm}
-command from the package with the same name.  It requires a Linux kernel
-module for the appropriate RAID level to be loaded, such as @code{raid456}
-for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10.
-@end defvar
-
-@cindex LVM, logical volume manager
-@defvar lvm-device-mapping
-This defines one or more logical volumes for the Linux
-@uref{https://www.sourceware.org/lvm2/, Logical Volume Manager (LVM)}.
-The volume group is activated by the @command{vgchange} command from the
-@code{lvm2} package.
-@end defvar
-
 @cindex disk encryption
 @cindex LUKS
 The following example specifies a mapping from @file{/dev/sda3} to
@@ -19123,6 +19106,23 @@ swap file is encrypted because the entire device is encrypted.
 @xref{Swap Space}, or @xref{Preparing for Installation,,Disk
 Partitioning}, for an example.
 
+
+@end defvar
+
+@defvar raid-device-mapping
+@cindex RAID
+This defines a RAID device, which is assembled using the @code{mdadm}
+command from the package with the same name.  It requires a Linux kernel
+module for the appropriate RAID level to be loaded, such as @code{raid1} for
+RAID-1 (mirroring), @code{raid456} for RAID-4, RAID-5 or RAID-6, or
+@code{raid10} for RAID-10 (@pxref{Initial RAM Disk}).
+
+For example, RAID-1 (mirroring) support can be added with:
+
+@lisp
+(initrd-modules (cons* "raid1" %base-initrd-modules))
+@end lisp
+
 A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
 may be declared as follows:
 
@@ -19137,7 +19137,22 @@ The @file{/dev/md0} device can then be used as the @code{device} of a
 @code{file-system} declaration (@pxref{File Systems}).
 Note that the RAID level need not be given; it is chosen during the
 initial creation and formatting of the RAID device and is determined
-automatically later.
+automatically later, assuming the correct Linux modules have been loaded.
+
+Not having the right kernel modules loaded might result in an error message
+like this at boot:
+
+@example
+mdadm: failed to RUN_ARRAY /dev/md0: Invalid argument
+@end example
+@end defvar
+
+@cindex LVM, logical volume manager
+@defvar lvm-device-mapping
+This defines one or more logical volumes for the Linux
+@uref{https://www.sourceware.org/lvm2/, Logical Volume Manager (LVM)}.
+The volume group is activated by the @command{vgchange} command from the
+@code{lvm2} package.
 
 LVM logical volumes ``alpha'' and ``beta'' from volume group ``vg0'' can
 be declared as follows:
@@ -19152,6 +19167,7 @@ be declared as follows:
 Devices @file{/dev/mapper/vg0-alpha} and @file{/dev/mapper/vg0-beta} can
 then be used as the @code{device} of a @code{file-system} declaration
 (@pxref{File Systems}).
+@end defvar
 
 @node Swap Space
 @section Swap Space
@@ -47267,6 +47283,10 @@ file system, you would write:
   (initrd-modules (cons "megaraid_sas" %base-initrd-modules)))
 @end lisp
 
+Other useful kernel modules include those necessary for a
+@code{raid-device-mapping}, e.g. @code{raid1}, @code{raid456} and
+@code{raid10} (@pxref{Mapped Devices}).
+
 @defvar %base-initrd-modules
 This is the list of kernel modules included in the initrd by default.
 @end defvar