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

[Tony Dinh]

Hi Fiona,

Added Heinrich to CC list.

On Sat, May 18, 2024 at 4:05 AM Fiona Klute <fiona.klute at gmx.de> wrote:
>
> Hi Tony!
>
> Am 16.05.24 um 21:28 schrieb Tony Dinh:
> > 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.
>
> Maybe it'd make sense to link to a general network setup section for
> alternatives? The problem is I can't find any in the existing docs, the
> closest I see is the "Automatically updated variables" list:
> https://docs.u-boot.org/en/latest/usage/environment.html#automatically-updated-variables
>
> As far as I understand you can also set the environment variables
> mentioned there manually to configure networking, but I'm not sure if
> that applies to all of them.
>
> Is my understanding correct? If yes, I could send a separate patch to
> add that information, and maybe rename the section to "Network
> configuration variables".

Currently, there is no documentation for using static IP in netconsole
that I'm aware of. I think it would be great if you send a separate
patch after this. Basically, the current u-boot network driver model
will automatically bring up the network when we try to use it, e.g.
pinging a server, or dhcp.

So the difference is instead of dhcp in your example, we could also do this:

env set ipaddr 192.168.1.100
env set nc 'if ping ${ncip}; then env set stdout nc; env set stderr
nc; env set stdin nc; fi'

Note that the board ipaddr needed to be set before the ping.

All the best,
Tony

>
> Best regards,
> Fiona
>
> > Reviewed-by: Tony Dinh <mibodhi at gmail.com>
> >
> > All the best,
> > Tony
>