[PATCH v2 1/2] doc: Detailed example for netconsole setup

[Tony Dinh]

Hi Fiona,

On Thu, May 16, 2024 at 3:43 AM Fiona Klute <fiona.klute at gmx.de> wrote:
>
> This adds details that I would have liked to have readily available,
> in particular how to activate the network interface before enabling
> netconsole, and how to integrate netconsole so you can use the U-Boot
> prompt.
>
> Signed-off-by: Fiona Klute <fiona.klute at gmx.de>
> ---
> Changes in v2:
> * Include stderr redirection
> * Use 4 spaces instead of tabs for code block to avoid overflowing
>   lines
>
>  doc/usage/netconsole.rst | 33 ++++++++++++++++++++++++++++++++-
>  1 file changed, 32 insertions(+), 1 deletion(-)
>
> diff --git a/doc/usage/netconsole.rst b/doc/usage/netconsole.rst
> index 2aa3b9ccc5..647f0c220b 100644
> --- a/doc/usage/netconsole.rst
> +++ b/doc/usage/netconsole.rst
> @@ -18,7 +18,9 @@ broadcast address and port 6666 are used. If it is set to an IP
>  address of 0 (or 0.0.0.0) then no messages are sent to the network.
>  The source / listening port can be configured separately by setting
>  the 'ncinport' environment variable and the destination port can be
> -configured by setting the 'ncoutport' environment variable.
> +configured by setting the 'ncoutport' environment variable. Note that
> +you need to set up the network interface (e.g. using DHCP) before it
> +can be used for network console.
>
>  For example, if your server IP is 192.168.1.1, you could use::
>
> @@ -107,3 +109,32 @@ as follows:
>
>  Note that unlike the U-Boot implementation the Linux netconsole is
>  unidirectional, i. e. you have console output only in Linux.
> +
> +Setup via environment
> +---------------------
> +
> +If persistent environment is enabled in your U-Boot configuration, you
> +can configure the network console using the environment. For example::
> +
> +    => env set autoload no
> +    => env set hostname "u-boot"
> +    => env set bootdelay 5
> +    => env set nc 'dhcp; env set stdout nc; env set stderr nc; env set stdin nc'
> +    => env set ncip 192.168.1.1
> +    => env set preboot "${preboot}; run nc;"
> +    => env save
> +    => reset
> +
> +``autoload no`` tells the ``dhcp`` command to configure the network
> +interface without trying to load an image. ``hostname "u-boot"`` sets
> +the hostname to be sent in DHCP requests, so they are easy to
> +recognize in the DHCP server log. The command in ``nc`` calls ``dhcp``
> +to make sure the network interface is set up before enabling
> +netconsole.
> +
> +Adding ``nc`` to ``preboot`` tells U-Boot to activate netconsole
> +before trying to find any boot options, so you can interact with it if
> +desired.
> +
> +``env save`` stores the settings persistently, and ``reset`` then
> +triggers a fresh start that will use the changed settings.
> --
> 2.43.0
>

Just for information, if the board uses static IP then the example
would be slightly different. I usually use static IP and ping the
netconsole server to make sure it is up. However, I think this DHCP
example is good enough to show how to prepare and activate netconsole.

Reviewed-by: Tony Dinh <mibodhi at gmail.com>

All the best,
Tony