doc: Add "Initial RAM Disk" section.

* doc/guix.texi (Initial RAM Disk): New node.
* gnu/system/linux-initrd.scm (expression->initrd): Adjust docstring.

2 files changed, 78 insertions, 5 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 8da9ad639c..9f08bc1a7e 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2847,6 +2847,7 @@ instance to support new system services.
 * File Systems::                Configuring file system mounts.
 * User Accounts::               Specifying user accounts.
 * Services::                    Specifying system services.
+* Initial RAM Disk::            Linux-Libre bootstrapping.
 * Invoking guix system::        Instantiating a system configuration.
 * Defining Services::           Adding new service definitions.
 @end menu
@@ -3259,6 +3260,76 @@ password.  When @var{auto-login?} is true, log in automatically as
 @end deffn
 
 
+@node Initial RAM Disk
+@subsection Initial RAM Disk
+
+@cindex initial RAM disk (initrd)
+@cindex initrd (initial RAM disk)
+For bootstrapping purposes, the Linux-Libre kernel is passed an
+@dfn{initial RAM disk}, or @dfn{initrd}.  An initrd contains a temporary
+root file system, as well as an initialization script.  The latter is
+responsible for mounting the real root file system, and for loading any
+kernel modules that may be needed to achieve that.
+
+The @code{initrd} field of an @code{operating-system} declaration allows
+you to specify which initrd you would like to use.  The @code{(gnu
+system linux-initrd)} module provides two ways to build an initrd: the
+high-level @code{base-initrd} procedure, and the low-level
+@code{expression->initrd} procedure.
+
+The @code{base-initrd} procedure is intended to cover most common uses.
+For example, if you want to add a bunch of kernel modules to be loaded
+at boot time, you can define the @code{initrd} field of the operating
+system declaration like this:
+
+@example
+(initrd (cut base-init <>
+             #:extra-modules '("my.ko" "modules.ko")))
+@end example
+
+It also handles common use cases that involves using the system as a
+QEMU guest, or as a ``live'' system whose root file system is volatile.
+
+@deffn {Monadic Procedure} base-initrd @var{file-systems} @
+       [#:qemu-networking? #f] [#:virtio? #f] [#:volatile-root? #f] @
+       [#:extra-modules '()]
+Return a monadic derivation that builds a generic initrd.  @var{file-systems} is
+a list of file-systems to be mounted by the initrd, possibly in addition to
+the root file system specified on the kernel command line via @code{--root}.
+
+When @var{qemu-networking?} is true, set up networking with the standard QEMU
+parameters.  When @var{virtio?} is true, load additional modules so the initrd can
+be used as a QEMU guest with para-virtualized I/O drivers.
+
+When @var{volatile-root?} is true, the root file system is writable but any changes
+to it are lost.
+
+The initrd is automatically populated with all the kernel modules necessary
+for @var{file-systems} and for the given options.  However, additional kernel
+modules can be listed in @var{extra-modules}.  They will be added to the initrd, and
+loaded at boot time in the order in which they appear.
+@end deffn
+
+Needless to say, the initrds we produce and use embed a
+statically-linked Guile, and the initialization program is a Guile
+program.  That gives a lot of flexibility.  The
+@code{expression->initrd} procedure builds such an initrd, given the
+program to run in that initrd.
+
+@deffn {Monadic Procedure} expression->initrd @var{exp} @
+       [#:guile %guile-static-stripped] [#:name "guile-initrd"] @
+       [#:modules '()] [#:to-copy '()] [#:linux #f] @
+       [#:linux-modules '()]
+Return a derivation that builds a Linux initrd (a gzipped cpio archive)
+containing @var{guile} and that evaluates @var{exp}, a G-expression,
+upon booting.
+
+@var{linux-modules} is a list of @file{.ko} file names to be copied from
+@var{linux} into the initrd.  @var{to-copy} is a list of additional
+derivations or packages to copy to the initrd.  @var{modules} is a list
+of Guile module names to be embedded in the initrd.
+@end deffn
+
 @node Invoking guix system
 @subsection Invoking @code{guix system}
 
diff --git a/gnu/system/linux-initrd.scm b/gnu/system/linux-initrd.scm
index afbfc692d3..9e39f2d663 100644
--- a/gnu/system/linux-initrd.scm
+++ b/gnu/system/linux-initrd.scm
@@ -57,11 +57,13 @@
                              (to-copy '())
                              (linux #f)
                              (linux-modules '()))
-  "Return a package that contains a Linux initrd (a gzipped cpio archive)
-containing GUILE and that evaluates EXP upon booting.  LINUX-MODULES is a list
-of `.ko' file names to be copied from LINUX into the initrd.  TO-COPY is a
-list of additional derivations or packages to copy to the initrd.  MODULES is
-a list of Guile module names to be embedded in the initrd."
+  "Return a derivation that builds a Linux initrd (a gzipped cpio archive)
+containing GUILE and that evaluates EXP, a G-expression, upon booting.
+
+LINUX-MODULES is a list of '.ko' file names to be copied from LINUX into the
+initrd.  TO-COPY is a list of additional derivations or packages to copy to
+the initrd.  MODULES is a list of Guile module names to be embedded in the
+initrd."
 
   ;; General Linux overview in `Documentation/early-userspace/README' and
   ;; `Documentation/filesystems/ramfs-rootfs-initramfs.txt'.