[PATCH v10 7/9] doc: Improve environment documentation further

[Heinrich Schuchardt]

On 10/22/21 05:08, Simon Glass wrote:
> Make various other updates suggested during review of the rST conversion.
>
> Signed-off-by: Simon Glass <sjg at chromium.org>
> Suggested-by: Heinrich Schuchardt <xypron.glpk at gmx.de>
> ---
>
> Changes in v10:
> - Add updates as suggested by Heinrich
>
>   doc/develop/environment.rst |  51 ++++++++++++++++
>   doc/develop/index.rst       |   1 +
>   doc/usage/environment.rst   | 115 ++++++++++++++----------------------
>   3 files changed, 95 insertions(+), 72 deletions(-)
>   create mode 100644 doc/develop/environment.rst
>
> diff --git a/doc/develop/environment.rst b/doc/develop/environment.rst
> new file mode 100644
> index 00000000000..0b86fafbff7
> --- /dev/null
> +++ b/doc/develop/environment.rst
> @@ -0,0 +1,51 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +Environment implementation
> +==========================
> +
> +See :doc:`../usage/environment` for usage information.
> +
> +Callback functions for environment variables
> +--------------------------------------------
> +
> +For some environment variables, the behavior of u-boot needs to change
> +when their values are changed.  This functionality allows functions to
> +be associated with arbitrary variables.  On creation, overwrite, or
> +deletion, the callback will provide the opportunity for some side
> +effect to happen or for the change to be rejected.
> +
> +The callbacks are named and associated with a function using the
> +U_BOOT_ENV_CALLBACK macro in your board or driver code.
> +
> +These callbacks are associated with variables in one of two ways.  The
> +static list can be added to by defining CONFIG_ENV_CALLBACK_LIST_STATIC
> +in the board configuration to a string that defines a list of
> +associations.  The list must be in the following format::
> +
> +    entry = variable_name[:callback_name]
> +    list = entry[,list]
> +
> +If the callback name is not specified, then the callback is deleted.
> +Spaces are also allowed anywhere in the list.
> +
> +Callbacks can also be associated by defining the ".callbacks" variable
> +with the same list format above.  Any association in ".callbacks" will
> +override any association in the static list. You can define
> +CONFIG_ENV_CALLBACK_LIST_DEFAULT to a list (string) to define the
> +".callbacks" environment variable in the default or embedded environment.
> +
> +If CONFIG_REGEX is defined, the variable_name above is evaluated as a
> +regular expression. This allows multiple variables to be connected to
> +the same callback without explicitly listing them all out.
> +
> +The signature of the callback functions is::
> +
> +    int callback(const char *name, const char *value, enum env_op op, int flags)
> +
> +* name - changed environment variable
> +* value - new value of the environment variable
> +* op - operation (create, overwrite, or delete)
> +* flags - attributes of the environment variable change, see flags H_* in
> +  include/search.h
> +
> +The return value is 0 if the variable change is accepted and 1 otherwise.
> diff --git a/doc/develop/index.rst b/doc/develop/index.rst
> index 5e064a4dac1..9eee8190453 100644
> --- a/doc/develop/index.rst
> +++ b/doc/develop/index.rst
> @@ -15,6 +15,7 @@ Implementation
>      config_binding
>      devicetree/index
>      driver-model/index
> +   environment
>      global_data
>      logging
>      makefiles
> diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst
> index af193739a5a..8ddc672d467 100644
> --- a/doc/usage/environment.rst
> +++ b/doc/usage/environment.rst
> @@ -3,11 +3,11 @@
>   Environment Variables
>   =====================
>
> -U-Boot supports user configuration using Environment Variables which
> +U-Boot supports user configuration using environment variables which
>   can be made persistent by saving to persistent storage, for example flash
>   memory.
>
> -Environment Variables are set using "env set" (alias "setenv"), printed using
> +Environment variables are set using "env set" (alias "setenv"), printed using
>   "env print" (alias "printenv"), and saved to persistent storage using
>   "env save" (alias "saveenv"). Using "env set"
>   without a value can be used to delete a variable from the
> @@ -98,27 +98,37 @@ environment but work is underway to address this.
>   List of environment variables
>   -----------------------------
>
> -Some configuration options can be set using Environment Variables. In many cases
> -the value in the default environment comes from a CONFIG option - see
> +Some device configuration options can be set using environment variables. In
> +many cases the value in the default environment comes from a CONFIG option - see
>   `include/env_default.h`) for this.
>
>   This is most-likely not complete:
>
>   baudrate
> -    Current baud rate used by the serial console. The built-in value is set by
> -    CONFIG_BAUDRATE (see `drivers/serial/Kconfig`)
> +    Used to set the baudrate of the UART - it defaults to CONFIG_BAUDRATE (which
> +    defaults to 115200).
>
>   bootdelay
> -    Current autoboot delay. The built-in value is set by CONFIG_BOOTDELAY (see
> -    `common/Kconfig`)
> +    Delay before automatically running bootcmd. During this time the user
> +    can choose to enter the shell (or the boot menu if
> +    CONFIG_AUTOBOOT_MENU_SHOW=y):
> +
> +    - 0 to autoboot with no delay, but you can stop it by key input.
> +    - -1 to disable autoboot.
> +    - -2 to autoboot with no delay and not check for abort
> +
> +    The default value is defined by CONFIG_BOOTDELAY.
> +    The value of 'bootdelay' is overridden by the /config/bootdelay value in
> +    the device-tree if CONFIG_OF_CONTROL=y.
> +    Does it really make sense that the devicetree overrides the user setting?

This sentence was not meant for inclusion. It was just as comment on the
code. Adding this to a man-page is irritating users. You could at it as
a TODO in the code.

>
>   bootcmd
> -    Defines a command string that is automatically executed when no character
> -    is read on the console interface within a cetain boot delay after reset.
> -    The built-in value is set by CONFIG_BOOTCOMMAND (see `common/Kconfig`)
> +    The command that is run if the user does not enter the shell during the
> +    boot delay.
>
>   bootargs
> -    Boot arguments when booting an RTOS image
> +    Command line arguments passed when booting an operating system or binary
> +    image
>
>   bootfile
>       Name of the image to load with TFTP
> @@ -159,12 +169,12 @@ updatefile
>
>   autoload
>       if set to "no" (any string beginning with 'n'),
> -    "bootp" will just load perform a lookup of the
> +    "bootp" and "dhcp" will just load perform a lookup of the
>       configuration from the BOOTP server, but not try to
>       load any image using TFTP or DHCP.

%s/using TFTP or DHCP//

DHCP is not a protocol to load images. A DHCP server may indicate a TFPT
server.

>
>   autostart
> -    if set to "yes", an image loaded using the "bootp",
> +    if set to "yes", an image loaded using the "bootp", "dhcp",
>       "rarpboot", "tftpboot" or "diskboot" commands will
>       be automatically started (by internally calling
>       "bootm")
> @@ -186,7 +196,8 @@ fdt_high
>       of the 704 MB low memory, so that Linux kernel can
>       access it during the boot procedure.
>
> -    If this is set to the special value 0xFFFFFFFF then
> +    If this is set to the special value 0xffffffff (32-bit machines) or
> +    0xffffffffffffffff (64-bit machines) then
>       the fdt will not be copied at all on boot.  For this
>       to work it must reside in writable memory, have
>       sufficient padding on the end of it for u-boot to
> @@ -220,7 +231,8 @@ initrd_high
>
>           setenv initrd_high 00c00000
>
> -    If you set initrd_high to 0xFFFFFFFF, this is an
> +    If you set initrd_high to 0xffffffff (32-bit machines) or
> +    0xffffffffffffffff (64-bit machines), this is an
>       indication to U-Boot that all addresses are legal
>       for the Linux kernel, including addresses in flash
>       memory. In this case U-Boot will NOT COPY the
> @@ -251,7 +263,7 @@ bootstopkey
>       see CONFIG_AUTOBOOT_STOP_STR
>
>   ethprime
> -    controls which interface is used first.
> +    controls which network interface is used first.
>
>   ethact
>       controls which interface is currently active.
> @@ -265,7 +277,9 @@ ethact
>   ethrotate
>       When set to "no" U-Boot does not go through all
>       available network interfaces.
> -    It just stays at the currently selected interface.
> +    It just stays at the currently selected interface. When unset or set to
> +    anything other than "no", U-Boot does go through all
> +    available network interfaces.
>
>   netretry
>       When set to "no" each network operation will
> @@ -276,12 +290,9 @@ netretry
>       Useful on scripts which control the retry operation
>       themselves.
>
> -npe_ucode
> -    set load address for the NPE microcode
> -
>   silent_linux
>       If set then Linux will be told to boot silently, by
> -    changing the console to be empty. If "yes" it will be
> +    adding 'console=' to its command line. If "yes" it will be
>       made silent. If "no" it will not be made silent. If
>       unset, then it will be made silent if the U-Boot console
>       is silent.
> @@ -292,7 +303,7 @@ tftpsrcp
>
>   tftpdstp
>       If this is set, the value is used for TFTP's UDP
> -    destination port instead of the Well Know Port 69.
> +    destination port instead of the default port 69.
>
>   tftpblocksize
>       Block size to use for TFTP transfers; if not set,
> @@ -415,11 +426,12 @@ serial#
>       contains hardware identification information such as type string and/or
>       serial number
>   ethaddr
> -    Ethernet address
> +    Ethernet address. If CONFIG_REGEX=y, also eth*addr (where * is an integer).

ethaddr
	Ethernet address

         This variable can be set only once. U-Boot refuses to delete or
	overwrite this variable once it has bee set unless
	CONFIG_ENV_OVERWRITE is enabled in the board configuration.
	The same applies to eth*addr (where * is an integer) if
	CONFIG_REGEX=y.

Best regards

Heinrich

>
>   These variables can be set only once (usually during manufacturing of
>   the board). U-Boot refuses to delete or overwrite these variables
> -once they have been set once.
> +once they have been set, unless CONFIG_ENV_OVERWRITE is enabled in the board
> +configuration.
>
>   Also:
>
> @@ -429,53 +441,7 @@ ver
>       readonly (see CONFIG_VERSION_VARIABLE).
>
>   Please note that changes to some configuration parameters may take
> -only effect after the next boot (yes, that's just like Windoze :-).
> -
> -
> -Callback functions for environment variables
> ---------------------------------------------
> -
> -For some environment variables, the behavior of u-boot needs to change
> -when their values are changed.  This functionality allows functions to
> -be associated with arbitrary variables.  On creation, overwrite, or
> -deletion, the callback will provide the opportunity for some side
> -effect to happen or for the change to be rejected.
> -
> -The callbacks are named and associated with a function using the
> -U_BOOT_ENV_CALLBACK macro in your board or driver code.
> -
> -These callbacks are associated with variables in one of two ways.  The
> -static list can be added to by defining CONFIG_ENV_CALLBACK_LIST_STATIC
> -in the board configuration to a string that defines a list of
> -associations.  The list must be in the following format::
> -
> -    entry = variable_name[:callback_name]
> -    list = entry[,list]
> -
> -If the callback name is not specified, then the callback is deleted.
> -Spaces are also allowed anywhere in the list.
> -
> -Callbacks can also be associated by defining the ".callbacks" variable
> -with the same list format above.  Any association in ".callbacks" will
> -override any association in the static list. You can define
> -CONFIG_ENV_CALLBACK_LIST_DEFAULT to a list (string) to define the
> -".callbacks" environment variable in the default or embedded environment.
> -
> -If CONFIG_REGEX is defined, the variable_name above is evaluated as a
> -regular expression. This allows multiple variables to be connected to
> -the same callback without explicitly listing them all out.
> -
> -The signature of the callback functions is::
> -
> -    int callback(const char *name, const char *value, enum env_op op, int flags)
> -
> -* name - changed environment variable
> -* value - new value of the environment variable
> -* op - operation (create, overwrite, or delete)
> -* flags - attributes of the environment variable change, see flags H_* in
> -  include/search.h
> -
> -The return value is 0 if the variable change is accepted and 1 otherwise.
> +only effect after the next boot (yes, that's just like Windows).
>
>
>   External environment file
> @@ -491,3 +457,8 @@ key=value pairs. Blank lines and lines beginning with # are ignored.
>
>   Future work may unify this feature with the text-based environment, perhaps
>   moving the contents of `env_default.h` to a text file.
> +
> +Implementation
> +--------------
> +
> +See :doc:`../develop/environment` for internal development details.
>