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

[Fiona Klute]

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

Best regards,
Fiona

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