[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] docs: Improve initrd documentation
From: |
Oskari Pirhonen |
Subject: |
Re: [PATCH] docs: Improve initrd documentation |
Date: |
Sat, 29 Jul 2023 14:33:10 -0500 |
On Sat, Jul 29, 2023 at 07:28:40 +0200, Paul Menzel wrote:
> Dear Glenn,
>
>
> Thank you for all your work on GRUB.
>
> Am 28.06.23 um 12:12 schrieb Glenn Washburn:
> > Remove reference to "initial ramdisk" and replace with "initrd". This then
> > covers the case of ramdisk and ramfs, which is the usual method with kernels
> > 2.6 and greater. Add sentence with URL to initrd documentation Linux kernel.
> > Also, add a section documenting how to have the initrd command generate a
> > new-style initrd via a specially crafted argument and include an example.
>
> (I’d format this as a list.)
>
> >
> > Update initrd16 to refer to the initrd section and make note that initrd16
> > is only on the pc platform.
> >
> > Signed-off-by: Glenn Washburn <development@efficientek.com>
> > ---
> > docs/grub.texi | 46 ++++++++++++++++++++++++++++++++++++++++------
> > 1 file changed, 40 insertions(+), 6 deletions(-)
> >
> > diff --git a/docs/grub.texi b/docs/grub.texi
> > index b39b72230c6f..bea86669191b 100644
> > --- a/docs/grub.texi
> > +++ b/docs/grub.texi
> > @@ -4076,10 +4076,43 @@ load a defective boot loader, such as SCO UnixWare
> > 7.1.
> > @subsection initrd
> >
> > @deffn Command initrd file [file @dots{}]
> > -Load, in order, all initial ramdisks for a Linux kernel image, and set
> > -the appropriate parameters in the Linux setup area in memory. This may
> > only
> > -be used after the @command{linux} command (@pxref{linux}) has been run.
> > See
> > -also @ref{GNU/Linux}.
> > +Load, in order, all initrds for a Linux kernel image, and set the
> > +appropriate parameters in the Linux setup area in memory. This may only
> > +be used after the @command{linux} command (@pxref{linux}) has been run.
> > +See @ref{GNU/Linux} for more info on booting GNU/Linux. For more
> > +information on initrds see the GNU/Linux kernel
> > +@uref{https://docs.kernel.org/filesystems/ramfs-rootfs-initramfs.html,
> > +documentation} on them.
>
> The “on them” at the end sounds like a leftover. But I am no native speaker.
>
The "on them" is fine IMO because it clarifies what part of the
documentation is being referred to. In info(1), the sentence gets
rendered as:
For more information on initrds see the GNU/Linux kernel
documentation ($URL) on them.
But, according to the texinfo docs, for HTML it gets rendered without
the inline URL.
It's just a matter of personal preference I guess. I have no strong
opinion in either direction.
> > +
> > +A new-style initrd (for kernels greater than 2.6) containing one file
> > +with leading path components can also be generated at run time. This
> > +can be done by prefixing an argument with @code{newc:} followed by the
> > +path of the file in the new initrd, a @code{:}, and then the GRUB file
> > +path to the file data to be be included.
> > +
> > +For example:
> > +@example
> > +initrd newc:/etc/ssh/config:(hd0,2)/home/user/.ssh/config \
> > + newc:/etc/ssh/ssh_host_rsa_key:/etc/ssh/ssh_host_rsa_key \
> > + /boot/initrd.gz \
> > + newc:/init:/home/user/init.fixed
> > +@end example
> > +
> > +This command will generate two new-style initrds on the fly. The first
> > +contains the path @samp{/etc/ssh/config} with the contents of
> > +@samp{(hd0,2)/home/user/.ssh/config} and the path
> > +@samp{/etc/ssh/ssh_host_rsa_key} with the contents of
> > +@samp{/etc/ssh/ssh_host_rsa_key} on the @var{root} device. Parent directory
> > +paths will automatically be generated as needed. This first generated
> > initrd
> > +will then have @samp{/boot/initrd.gz} concatenated after it. Next, another
> > +new-style archive will be generated with the contents of
> > @samp{/home/user/init.fixed}
> > +in the path @samp{/init} and appended to the previous concatenation.
> > Finally,
> > +the result will be sent to the kernel when booted.
> > +
> > +Keep in mind that paths that comes later will take precendence. So in the
>
> 1. come later
> 2. precedence
>
Good catch.
> > +example above, the generated path @samp{/init} will overwrite any
> > @samp{/init}
> > +in @samp{/boot/initrd.gz}. This can be useful when changing the main initrd
> > +is undesirable or difficult.
> > @end deffn
>
> (Today I learned something new. Nice feature.)
>
> >
> >
> > @@ -4090,9 +4123,10 @@ also @ref{GNU/Linux}.
> > Load, in order, all initial ramdisks for a Linux kernel image to be
> > booted in
> > 16-bit mode, and set the appropriate parameters in the Linux setup area in
> > memory. This may only be used after the @command{linux16} command
> > -(@pxref{linux16}) has been run. See also @ref{GNU/Linux}.
> > +(@pxref{linux16}) has been run. See also @ref{GNU/Linux} and the
> > @command{initrd}
> > +(@pxref{initrd}) for more details.
> >
> > -This command is only available on x86 systems.
> > +This command is only available on the pc platform for x86 systems.
> > @end deffn
>
> Reviewed-by: Paul Menzel <pmenzel@molgen.mpg.de>
>
A v2 was posted July 3 [1], could you re-comment on there?
- Oskari
[1]: https://lists.gnu.org/archive/html/grub-devel/2023-07/msg00007.html
>
> Kind regards,
>
> Paul
signature.asc
Description: PGP signature