grub-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: 119 grub commands not documented in grub.texi


From: Daniel Kiper
Subject: Re: 119 grub commands not documented in grub.texi
Date: Thu, 23 Apr 2020 12:30:53 +0200
User-agent: NeoMutt/20170113 (1.7.2)

On Wed, Apr 22, 2020 at 09:29:13PM +0200, Hans Ulrich Niedermann wrote:
> 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?

It looks that it was planned. However, if nobody wrote it up until now
then nobody wants to use it. So, I think that we can safely drop it from
the documentation to not confuse the user.

> > > 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.

I saw it. However, I have to ask somebody more familiar with python than
I to make its review.

Daniel



reply via email to

[Prev in Thread] Current Thread [Next in Thread]