Re: 119 grub commands not documented in grub.texi

[Hans Ulrich Niedermann]

On Wed, 22 Apr 2020 12:10:31 +0200
Daniel Kiper <address@hidden> wrote:

> On Sat, Apr 18, 2020 at 12:53:12PM +0200, Hans Ulrich Niedermann
> wrote:
> > I have noticed that there are two commands documented in grub.texi
> > which appear not to occur anywhere within the grub source code:
> > 'pxe_unload' and 'uppermem'.
> >
> >     @node pxe_unload
> >     @subsection pxe_unload
> >
> >     @deffn Command pxe_unload
> >     Unload the PXE environment (@pxref{Network}).
> >
> >     This command is only available on PC BIOS systems.
> >     @end deffn
> >
> > However, judging from the source code ("git grep pxe_unload"),
> > pxe_unload is not available at all, so the documentation is wrong
> > when it claims that the command were available on PC BIOS systems.
> >
> > Should 'pxe_unload' be removed from grub.texi, or does it need a
> > notice that there are plans to implement it?  
> 
> If it is not implemented please drop it.

I could not find any traces in the current source tree: The string
pxe_unload only appears in ChangeLog-2015 and docs/grub.texi:

$ git grep pxe_unload
ChangeLog-2015: * include/grub/i386/pc/pxe.h (grub_pxe_unload): Removed.
ChangeLog-2015: (pxe_unload): New section.
ChangeLog-2015: (grub_cmd_pxe_unload): New function.
docs/grub.texi:* pxe_unload::                  Unload the PXE environment
docs/grub.texi:@node pxe_unload
docs/grub.texi:@subsection pxe_unload
docs/grub.texi:@deffn Command pxe_unload
$

Looks like 671a78acb0648d3d73c95ab0f021f907499aacc0 from 2011-07-05
removed the code. The removal of the 'pxe_unload' documentation will be
in my patch set.

> > Regarding 'uppermem', there is only
> >
> >     @node uppermem
> >     @subsection uppermem
> >
> >     This command is not yet implemented for GRUB 2, although it is
> > planned.
> >
> > This may be a valid state for the "uppermem" command.  
> 
> Probably it is a remnant from ancient times. Please drop it too.

I have found the (non-existing) 'uppermem' command mentioned in the
'GNU/Linux' node (info grub -n 'GNU/Linux') as well:

| @strong{Caution:} If you use an initrd and specify the @samp{mem=}
| option to the kernel to let it use less than actual memory size, you
| will also have to specify the same memory size to GRUB. To let GRUB
| know the size, run the command @command{uppermem} @emph{before}
| loading the kernel. @xref{uppermem}, for more information.

Maybe someone with some familiarity with the code which implements the
"linux" and "initrd" commands and how Linux kernels and Linux
initrds are loaded could shed some light on the current status of
the 'mem=' Linux kernel parameter and the non-existing 'uppermem' grub
command.

Might this be the reason why 'uppermem' has been planned for Grub2 in
the past?

> > If you want me to, I can submit a patch for the check-commands.py  
> 
> I cannot find check-commands.py, anyway...
> 
> > script to autogenerate a list of undocumented commands which should
> > be documented which can then be auto-included in grub.texi and
> > appear in the generated 'grub.info'. This would give a reader of
> > the grub manual at least the knowledge that those command actually
> > exist, and could be coupled with a call for help documenting those
> > commands right inside grub.texi itself.  
> 
> That would be perfect. Especially if it appears in 2.06 release.

That patch is on its way.

Uli