Re: [PATCH v2 7/9] Documentation: kgdboc: Document new earlycon_kgdboc parameter

[Daniel Thompson]

On Tue, Apr 21, 2020 at 02:14:45PM -0700, Douglas Anderson wrote:
> The recent patch ("kgdboc: Add earlycon_kgdboc to support early kgdb
> using boot consoles") adds a new kernel command line parameter.
> Document it.
> 
> Note that the patch adding the feature does some comparing/contrasting
> of "earlycon_kgdboc" vs. the existing "ekgdboc".  See that patch for
> more details, but briefly "ekgdboc" can be used _instead_ of "kgdboc"
> and just makes "kgdboc" do its normal initialization early (only works
> if your tty driver is already ready).  The new "earlycon_kgdboc" works
> in combination with "kgdboc" and is backed by boot consoles.
> 
> Signed-off-by: Douglas Anderson <dianders@xxxxxxxxxxxx>
> ---
> 
> Changes in v2: None
> 
>  .../admin-guide/kernel-parameters.txt         | 20 +++++++++++++++++++
>  Documentation/dev-tools/kgdb.rst              | 14 +++++++++++++
>  2 files changed, 34 insertions(+)
> 
> diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
> index f2a93c8679e8..588625ec2993 100644
> --- a/Documentation/admin-guide/kernel-parameters.txt
> +++ b/Documentation/admin-guide/kernel-parameters.txt
> @@ -1132,6 +1132,22 @@
>  			address must be provided, and the serial port must
>  			already be setup and configured.
>  
> +	earlycon_kgdboc=	[KGDB,HW]
> +			If the boot console provides the ability to read
> +			characters and can work in polling mode, you can use
> +			this parameter to tell kgdb to use it as a backend
> +			until the normal console is registered. Intended to
> +			be used together with the kgdboc parameter which
> +			specifies the normal console to transition to.
> +
> +			The the name of the early console should be specified
> +			as the value of this parameter. Note that the name of
> +			the early console might be different than the tty
> +			name passed to kgdboc. If only one boot console with
> +			a read() function is enabled it's OK to leave the
> +			value blank and the first boot console that implements
> +			read() will be picked.

There's no need for the "If only one boot console with a read()
funcuiton is enabled" here,

Seeing this in alphabetic order in this patch it also crosses my mind
that kgdboc_earlycon might be a better name so that is sorts closer
to the other kgdb options. This is a kgdboc feature that uses earlycon
not an earlycon feature that uses kgdboc.


> +
>  	earlyprintk=	[X86,SH,ARM,M68k,S390]
>  			earlyprintk=vga
>  			earlyprintk=sclp
> @@ -1190,6 +1206,10 @@
>  			This is designed to be used in conjunction with
>  			the boot argument: earlyprintk=vga
>  
> +			This parameter works in place of the kgdboc parameter
> +			but can only be used if the backing tty is available
> +			very early in the boot process.
> +

I wonder if pragmatic advice is more useful:

  For early debugging via a serial port see earlycon_kgdboc instead.

>  	edd=		[EDD]
>  			Format: {"off" | "on" | "skip[mbr]"}
>  
> diff --git a/Documentation/dev-tools/kgdb.rst b/Documentation/dev-tools/kgdb.rst
> index d38be58f872a..c0b321403d9a 100644
> --- a/Documentation/dev-tools/kgdb.rst
> +++ b/Documentation/dev-tools/kgdb.rst
> @@ -274,6 +274,20 @@ don't like this are to hack gdb to send the :kbd:`SysRq-G` for you as well as
>  on the initial connect, or to use a debugger proxy that allows an
>  unmodified gdb to do the debugging.
>  
> +Kernel parameter: ``earlycon_kgdboc``
> +-------------------------------------
> +
> +If you specify the kernel parameter ``earlycon_kgdboc`` and your serial
> +driver registers a boot console that supports polling (doesn't need
> +interrupts and implements a nonblocking read() function) kgdb will attempt
> +to work using the boot console until it can transition to the regular
> +tty driver specified by the ``kgdboc`` parameter.
> +
> +Normally there is only one boot console (especially that implements the
> +read() function) so just adding ``earlycon_kgdboc`` on its own is
> +sufficient to make this work.  If you have more than one boot console you
> +can add the boot console's name to differentiate.
> +

I think we need an example here. The example in the patch header for
the previous patch was useful (at least for me).


Daniel.