[PATCH v9 2/7] doc: Move environment documentation to rST
Heinrich Schuchardt
xypron.glpk at gmx.de
Wed Oct 20 08:38:10 CEST 2021
On 10/20/21 00:44, Simon Glass wrote:
> Move this from the README to rST format.
>
> Drop i2cfast since it is obviously obsolete and breaks the formatting.
> Other changes and improvements are in a following patch.
>
> Signed-off-by: Simon Glass <sjg at chromium.org>
> Acked-by: Marek Behún <marek.behun at nic.cz>
This patch leads to a build error for 'make htmldocs':
doc/usage/environment.rst:document isn't included in any toctree
Please add the file to doc/usage/index.rst.
> ---
>
> (no changes since v6)
>
> Changes in v6:
> - Move all updates to a separate patch
>
> Changes in v5:
> - Minor updates as suggested by Wolfgang
>
> Changes in v4:
> - Add new patch to move environment documentation to rST
>
> README | 328 --------------------------------
> doc/usage/environment.rst | 381 ++++++++++++++++++++++++++++++++++++++
> 2 files changed, 381 insertions(+), 328 deletions(-)
> create mode 100644 doc/usage/environment.rst
>
> diff --git a/README b/README
> index 840b192aae5..f20bc38a41c 100644
> --- a/README
> +++ b/README
> @@ -2999,334 +2999,6 @@ TODO.
> For now: just type "help <command>".
>
>
> -Environment Variables:
> -======================
> -
> -U-Boot supports user configuration using Environment Variables which
> -can be made persistent by saving to Flash memory.
> -
> -Environment Variables are set using "setenv", printed using
> -"printenv", and saved to Flash using "saveenv". Using "setenv"
> -without a value can be used to delete a variable from the
> -environment. As long as you don't save the environment you are
> -working with an in-memory copy. In case the Flash area containing the
> -environment is erased by accident, a default environment is provided.
> -
> -Some configuration options can be set using Environment Variables.
> -
> -List of environment variables (most likely not complete):
> -
> - baudrate - see CONFIG_BAUDRATE
> -
> - bootdelay - see CONFIG_BOOTDELAY
> -
> - bootcmd - see CONFIG_BOOTCOMMAND
> -
> - bootargs - Boot arguments when booting an RTOS image
> -
> - bootfile - Name of the image to load with TFTP
> -
> - bootm_low - Memory range available for image processing in the bootm
> - command can be restricted. This variable is given as
> - a hexadecimal number and defines lowest address allowed
> - for use by the bootm command. See also "bootm_size"
> - environment variable. Address defined by "bootm_low" is
> - also the base of the initial memory mapping for the Linux
> - kernel -- see the description of CONFIG_SYS_BOOTMAPSZ and
> - bootm_mapsize.
> -
> - bootm_mapsize - Size of the initial memory mapping for the Linux kernel.
> - This variable is given as a hexadecimal number and it
> - defines the size of the memory region starting at base
> - address bootm_low that is accessible by the Linux kernel
> - during early boot. If unset, CONFIG_SYS_BOOTMAPSZ is used
> - as the default value if it is defined, and bootm_size is
> - used otherwise.
> -
> - bootm_size - Memory range available for image processing in the bootm
> - command can be restricted. This variable is given as
> - a hexadecimal number and defines the size of the region
> - allowed for use by the bootm command. See also "bootm_low"
> - environment variable.
> -
> - bootstopkeysha256, bootdelaykey, bootstopkey - See README.autoboot
> -
> - updatefile - Location of the software update file on a TFTP server, used
> - by the automatic software update feature. Please refer to
> - documentation in doc/README.update for more details.
> -
> - autoload - if set to "no" (any string beginning with 'n'),
> - "bootp" will just load perform a lookup of the
> - configuration from the BOOTP server, but not try to
> - load any image using TFTP
> -
> - autostart - if set to "yes", an image loaded using the "bootp",
> - "rarpboot", "tftpboot" or "diskboot" commands will
> - be automatically started (by internally calling
> - "bootm")
> -
> - If set to "no", a standalone image passed to the
> - "bootm" command will be copied to the load address
> - (and eventually uncompressed), but NOT be started.
> - This can be used to load and uncompress arbitrary
> - data.
> -
> - fdt_high - if set this restricts the maximum address that the
> - flattened device tree will be copied into upon boot.
> - For example, if you have a system with 1 GB memory
> - at physical address 0x10000000, while Linux kernel
> - only recognizes the first 704 MB as low memory, you
> - may need to set fdt_high as 0x3C000000 to have the
> - device tree blob be copied to the maximum address
> - 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
> - 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
> - add the information it needs into it, and the memory
> - must be accessible by the kernel.
> -
> - fdtcontroladdr- if set this is the address of the control flattened
> - device tree used by U-Boot when CONFIG_OF_CONTROL is
> - defined.
> -
> - i2cfast - (PPC405GP|PPC405EP only)
> - if set to 'y' configures Linux I2C driver for fast
> - mode (400kHZ). This environment variable is used in
> - initialization code. So, for changes to be effective
> - it must be saved and board must be reset.
> -
> - initrd_high - restrict positioning of initrd images:
> - If this variable is not set, initrd images will be
> - copied to the highest possible address in RAM; this
> - is usually what you want since it allows for
> - maximum initrd size. If for some reason you want to
> - make sure that the initrd image is loaded below the
> - CONFIG_SYS_BOOTMAPSZ limit, you can set this environment
> - variable to a value of "no" or "off" or "0".
> - Alternatively, you can set it to a maximum upper
> - address to use (U-Boot will still check that it
> - does not overwrite the U-Boot stack and data).
> -
> - For instance, when you have a system with 16 MB
> - RAM, and want to reserve 4 MB from use by Linux,
> - you can do this by adding "mem=12M" to the value of
> - the "bootargs" variable. However, now you must make
> - sure that the initrd image is placed in the first
> - 12 MB as well - this can be done with
> -
> - setenv initrd_high 00c00000
> -
> - If you set initrd_high to 0xFFFFFFFF, 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
> - ramdisk at all. This may be useful to reduce the
> - boot time on your system, but requires that this
> - feature is supported by your Linux kernel.
> -
> - ipaddr - IP address; needed for tftpboot command
> -
> - loadaddr - Default load address for commands like "bootp",
> - "rarpboot", "tftpboot", "loadb" or "diskboot"
> -
> - loads_echo - see CONFIG_LOADS_ECHO
> -
> - serverip - TFTP server IP address; needed for tftpboot command
> -
> - bootretry - see CONFIG_BOOT_RETRY_TIME
> -
> - bootdelaykey - see CONFIG_AUTOBOOT_DELAY_STR
> -
> - bootstopkey - see CONFIG_AUTOBOOT_STOP_STR
> -
> - ethprime - controls which interface is used first.
> -
> - ethact - controls which interface is currently active.
> - For example you can do the following
> -
> - => setenv ethact FEC
> - => ping 192.168.0.1 # traffic sent on FEC
> - => setenv ethact SCC
> - => ping 10.0.0.1 # traffic sent on SCC
> -
> - ethrotate - When set to "no" U-Boot does not go through all
> - available network interfaces.
> - It just stays at the currently selected interface.
> -
> - netretry - When set to "no" each network operation will
> - either succeed or fail without retrying.
> - When set to "once" the network operation will
> - fail when all the available network interfaces
> - are tried once without success.
> - 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
> - 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.
> -
> - tftpsrcp - If this is set, the value is used for TFTP's
> - UDP source port.
> -
> - tftpdstp - If this is set, the value is used for TFTP's UDP
> - destination port instead of the Well Know Port 69.
> -
> - tftpblocksize - Block size to use for TFTP transfers; if not set,
> - we use the TFTP server's default block size
> -
> - tftptimeout - Retransmission timeout for TFTP packets (in milli-
> - seconds, minimum value is 1000 = 1 second). Defines
> - when a packet is considered to be lost so it has to
> - be retransmitted. The default is 5000 = 5 seconds.
> - Lowering this value may make downloads succeed
> - faster in networks with high packet loss rates or
> - with unreliable TFTP servers.
> -
> - tftptimeoutcountmax - maximum count of TFTP timeouts (no
> - unit, minimum value = 0). Defines how many timeouts
> - can happen during a single file transfer before that
> - transfer is aborted. The default is 10, and 0 means
> - 'no timeouts allowed'. Increasing this value may help
> - downloads succeed with high packet loss rates, or with
> - unreliable TFTP servers or client hardware.
> -
> - tftpwindowsize - if this is set, the value is used for TFTP's
> - window size as described by RFC 7440.
> - This means the count of blocks we can receive before
> - sending ack to server.
> -
> - vlan - When set to a value < 4095 the traffic over
> - Ethernet is encapsulated/received over 802.1q
> - VLAN tagged frames.
> -
> - bootpretryperiod - Period during which BOOTP/DHCP sends retries.
> - Unsigned value, in milliseconds. If not set, the period will
> - be either the default (28000), or a value based on
> - CONFIG_NET_RETRY_COUNT, if defined. This value has
> - precedence over the valu based on CONFIG_NET_RETRY_COUNT.
> -
> - memmatches - Number of matches found by the last 'ms' command, in hex
> -
> - memaddr - Address of the last match found by the 'ms' command, in hex,
> - or 0 if none
> -
> - mempos - Index position of the last match found by the 'ms' command,
> - in units of the size (.b, .w, .l) of the search
> -
> - zbootbase - (x86 only) Base address of the bzImage 'setup' block
> -
> - zbootaddr - (x86 only) Address of the loaded bzImage, typically
> - BZIMAGE_LOAD_ADDR which is 0x100000
> -
> -The following image location variables contain the location of images
> -used in booting. The "Image" column gives the role of the image and is
> -not an environment variable name. The other columns are environment
> -variable names. "File Name" gives the name of the file on a TFTP
> -server, "RAM Address" gives the location in RAM the image will be
> -loaded to, and "Flash Location" gives the image's address in NOR
> -flash or offset in NAND flash.
> -
> -*Note* - these variables don't have to be defined for all boards, some
> -boards currently use other variables for these purposes, and some
> -boards use these variables for other purposes.
> -
> -Image File Name RAM Address Flash Location
> ------ --------- ----------- --------------
> -u-boot u-boot u-boot_addr_r u-boot_addr
> -Linux kernel bootfile kernel_addr_r kernel_addr
> -device tree blob fdtfile fdt_addr_r fdt_addr
> -ramdisk ramdiskfile ramdisk_addr_r ramdisk_addr
> -
> -The following environment variables may be used and automatically
> -updated by the network boot commands ("bootp" and "rarpboot"),
> -depending the information provided by your boot server:
> -
> - bootfile - see above
> - dnsip - IP address of your Domain Name Server
> - dnsip2 - IP address of your secondary Domain Name Server
> - gatewayip - IP address of the Gateway (Router) to use
> - hostname - Target hostname
> - ipaddr - see above
> - netmask - Subnet Mask
> - rootpath - Pathname of the root filesystem on the NFS server
> - serverip - see above
> -
> -
> -There are two special Environment Variables:
> -
> - serial# - contains hardware identification information such
> - as type string and/or serial number
> - ethaddr - Ethernet address
> -
> -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.
> -
> -
> -Further special Environment Variables:
> -
> - ver - Contains the U-Boot version string as printed
> - with the "version" command. This variable is
> - 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.
> -
> -
> Note for Redundant Ethernet Interfaces:
> =======================================
>
> diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst
> new file mode 100644
> index 00000000000..7a733b44556
> --- /dev/null
> +++ b/doc/usage/environment.rst
> @@ -0,0 +1,381 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +Environment Variables
> +=====================
> +
> +U-Boot supports user configuration using Environment Variables which
environment variables
> +can be made persistent by saving to Flash memory.
This is wrong we support having the environment in many different places.
> +
> +Environment Variables are set using "setenv", printed using
variables
> +"printenv", and saved to Flash using "saveenv". Using "setenv"
%s/to Flash//
> +without a value can be used to delete a variable from the
> +environment. As long as you don't save the environment you are
> +working with an in-memory copy. In case the Flash area containing the
> +environment is erased by accident, a default environment is provided.
> +
In a later series we should create separate man-pages for these commands
as well as for the 'env' command.
> +Some configuration options can be set using Environment Variables.
device configuration options
environment variables
> +
> +List of environment variables (most likely not complete):
> +
> +baudrate
> + see CONFIG_BAUDRATE
Uncommented references to Kconfig variables are not helpful if the
Kconfig variables themselves are not described in the HTML documentation.
How about:
This environment variable is used to set the baudrate of the UART. It
defaults to CONFIG_BAUDRATE (which defaults to 115200).
> +
> +bootdelay
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 overriden 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?
> + see CONFIG_BOOTDELAY
> +
> +bootcmd
> + see CONFIG_BOOTCOMMAND
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
I would not refer to Linux as an RTOS. How about:
Command line arguments passed when booting a binary image.
> +
> +bootfile
> + Name of the image to load with TFTP
%s/image/file/
The tftp command can be used to load any file not only images.
> +
> +bootm_low
> + Memory range available for image processing in the bootm
> + command can be restricted. This variable is given as
> + a hexadecimal number and defines lowest address allowed
> + for use by the bootm command. See also "bootm_size"
> + environment variable. Address defined by "bootm_low" is
> + also the base of the initial memory mapping for the Linux
> + kernel -- see the description of CONFIG_SYS_BOOTMAPSZ and
> + bootm_mapsize.
> +
> +bootm_mapsize
> + Size of the initial memory mapping for the Linux kernel.
> + This variable is given as a hexadecimal number and it
> + defines the size of the memory region starting at base
> + address bootm_low that is accessible by the Linux kernel
> + during early boot. If unset, CONFIG_SYS_BOOTMAPSZ is used
> + as the default value if it is defined, and bootm_size is
> + used otherwise.
> +
> +bootm_size
> + Memory range available for image processing in the bootm
> + command can be restricted. This variable is given as
> + a hexadecimal number and defines the size of the region
> + allowed for use by the bootm command. See also "bootm_low"
> + environment variable.
> +
> +bootstopkeysha256, bootdelaykey, bootstopkey
> + See README.autoboot
This document should also be moved to make it linkable.
> +
> +updatefile
> + Location of the software update file on a TFTP server, used
> + by the automatic software update feature. Please refer to
> + documentation in doc/README.update for more details.
> +
> +autoload
> + if set to "no" (any string beginning with 'n'),
> + "bootp" will just load perform a lookup of the
The dhcp command is also affected.
> + configuration from the BOOTP server, but not try to
> + load any image using TFTP
> +
> +autostart
> + if set to "yes", an image loaded using the "bootp",
> + "rarpboot", "tftpboot" or "diskboot" commands will
> + be automatically started (by internally calling
> + "bootm")
How about the dhcp command?
> +
> + If set to "no", a standalone image passed to the
> + "bootm" command will be copied to the load address
> + (and eventually uncompressed), but NOT be started.
> + This can be used to load and uncompress arbitrary
> + data.
> +
> +fdt_high
> + if set this restricts the maximum address that the
> + flattened device tree will be copied into upon boot.
> + For example, if you have a system with 1 GB memory
> + at physical address 0x10000000, while Linux kernel
> + only recognizes the first 704 MB as low memory, you
> + may need to set fdt_high as 0x3C000000 to have the
> + device tree blob be copied to the maximum address
> + 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
0xffffffff on 32 bit
0xffffffffffffffff on 64 bit
> + 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
> + add the information it needs into it, and the memory
> + must be accessible by the kernel.
> +
> +fdtcontroladdr
> + if set this is the address of the control flattened
> + device tree used by U-Boot when CONFIG_OF_CONTROL is
> + defined.
> +
> +initrd_high
> + restrict positioning of initrd images:
> + If this variable is not set, initrd images will be
> + copied to the highest possible address in RAM; this
> + is usually what you want since it allows for
> + maximum initrd size. If for some reason you want to
> + make sure that the initrd image is loaded below the
> + CONFIG_SYS_BOOTMAPSZ limit, you can set this environment
> + variable to a value of "no" or "off" or "0".
> + Alternatively, you can set it to a maximum upper
> + address to use (U-Boot will still check that it
> + does not overwrite the U-Boot stack and data).
> +
> + For instance, when you have a system with 16 MB
> + RAM, and want to reserve 4 MB from use by Linux,
> + you can do this by adding "mem=12M" to the value of
> + the "bootargs" variable. However, now you must make
> + sure that the initrd image is placed in the first
> + 12 MB as well - this can be done with::
> +
> + setenv initrd_high 00c00000
> +
> + If you set initrd_high to 0xFFFFFFFF, this is an
0xffffffff on 32 bit
0xffffffffffffffff on 64 bit
> + 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
> + ramdisk at all. This may be useful to reduce the
> + boot time on your system, but requires that this
> + feature is supported by your Linux kernel.
> +
> +ipaddr
> + IP address; needed for tftpboot command
This address is also used by the tftp command.
> +
> +loadaddr
> + Default load address for commands like "bootp",
> + "rarpboot", "tftpboot", "loadb" or "diskboot"
> +
> +loads_echo
> + see CONFIG_LOADS_ECHO
> +
> +serverip
> + TFTP server IP address; needed for tftpboot command
and tftp command
> +
> +bootretry
> + see CONFIG_BOOT_RETRY_TIME
> +
> +bootdelaykey
> + see CONFIG_AUTOBOOT_DELAY_STR
> +
> +bootstopkey
> + see CONFIG_AUTOBOOT_STOP_STR
> +
> +ethprime
> + controls which interface is used first.
> +
> +ethact
> + controls which interface is currently active.
%s/interface/network interface/
> + For example you can do the following::
> +
> + => setenv ethact FEC
> + => ping 192.168.0.1 # traffic sent on FEC
> + => setenv ethact SCC
> + => ping 10.0.0.1 # traffic sent on SCC
> +
> +ethrotate
> + When set to "no" U-Boot does not go through all
set to "no" or not set?
> + available network interfaces.
> + It just stays at the currently selected interface.
> +
> +netretry
> + When set to "no" each network operation will
> + either succeed or fail without retrying.
> + When set to "once" the network operation will
> + fail when all the available network interfaces
> + are tried once without success.
> + Useful on scripts which control the retry operation
> + themselves.
> +
> +npe_ucode
> + set load address for the NPE microcode
This variable is not used. Please, remove it.
> +
> +silent_linux
> + If set then Linux will be told to boot silently, by
> + changing the console to be empty. If "yes" it will be
by adding 'console=' to the Linux command line.
> + 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.
> +
> +tftpsrcp
> + If this is set, the value is used for TFTP's
> + UDP source port.
> +
> +tftpdstp
> + If this is set, the value is used for TFTP's UDP
> + destination port instead of the Well Know Port 69.
%s/Well Known Port/default port/
> +
> +tftpblocksize
> + Block size to use for TFTP transfers; if not set,
> + we use the TFTP server's default block size
> +
> +tftptimeout
> + Retransmission timeout for TFTP packets (in milli-
> + seconds, minimum value is 1000 = 1 second). Defines
> + when a packet is considered to be lost so it has to
> + be retransmitted. The default is 5000 = 5 seconds.
> + Lowering this value may make downloads succeed
> + faster in networks with high packet loss rates or
> + with unreliable TFTP servers.
> +
> +tftptimeoutcountmax
> + maximum count of TFTP timeouts (no
> + unit, minimum value = 0). Defines how many timeouts
> + can happen during a single file transfer before that
> + transfer is aborted. The default is 10, and 0 means
> + 'no timeouts allowed'. Increasing this value may help
> + downloads succeed with high packet loss rates, or with
> + unreliable TFTP servers or client hardware.
> +
> +tftpwindowsize
> + if this is set, the value is used for TFTP's
> + window size as described by RFC 7440.
> + This means the count of blocks we can receive before
> + sending ack to server.
> +
> +vlan
> + When set to a value < 4095 the traffic over
> + Ethernet is encapsulated/received over 802.1q
> + VLAN tagged frames.
> +
> +bootpretryperiod
> + Period during which BOOTP/DHCP sends retries.
> + Unsigned value, in milliseconds. If not set, the period will
> + be either the default (28000), or a value based on
> + CONFIG_NET_RETRY_COUNT, if defined. This value has
> + precedence over the valu based on CONFIG_NET_RETRY_COUNT.
> +
> +memmatches
> + Number of matches found by the last 'ms' command, in hex
> +
> +memaddr
> + Address of the last match found by the 'ms' command, in hex,
> + or 0 if none
> +
> +mempos
> + Index position of the last match found by the 'ms' command,
> + in units of the size (.b, .w, .l) of the search
> +
> +zbootbase
> + (x86 only) Base address of the bzImage 'setup' block
> +
> +zbootaddr
> + (x86 only) Address of the loaded bzImage, typically
> + BZIMAGE_LOAD_ADDR which is 0x100000
> +
> +
> +Image locations
> +---------------
> +
> +The following image location variables contain the location of images
> +used in booting. The "Image" column gives the role of the image and is
> +not an environment variable name. The other columns are environment
> +variable names. "File Name" gives the name of the file on a TFTP
> +server, "RAM Address" gives the location in RAM the image will be
> +loaded to, and "Flash Location" gives the image's address in NOR
> +flash or offset in NAND flash.
> +
> +*Note* - these variables don't have to be defined for all boards, some
> +boards currently use other variables for these purposes, and some
> +boards use these variables for other purposes.
> +
> +================= ============== ================ ==============
> +Image File Name RAM Address Flash Location
> +================= ============== ================ ==============
> +u-boot u-boot u-boot_addr_r u-boot_addr
> +Linux kernel bootfile kernel_addr_r kernel_addr
> +device tree blob fdtfile fdt_addr_r fdt_addr
> +ramdisk ramdiskfile ramdisk_addr_r ramdisk_addr
> +================= ============== ================ ==============
> +
> +
> +Automatically updated variables
> +-------------------------------
> +
> +The following environment variables may be used and automatically
> +updated by the network boot commands ("bootp" and "rarpboot"),
> +depending the information provided by your boot server:
> +
> +========= ===================================================
> +Variable Notes
> +========= ===================================================
> +bootfile see above
> +dnsip IP address of your Domain Name Server
> +dnsip2 IP address of your secondary Domain Name Server
> +gatewayip IP address of the Gateway (Router) to use
> +hostname Target hostname
> +ipaddr See above
> +netmask Subnet Mask
> +rootpath Pathname of the root filesystem on the NFS server
> +serverip see above
> +========= ===================================================
> +
> +
> +Special environment variables
> +-----------------------------
> +
> +There are two special Environment Variables:
> +
> +serial#
> + contains hardware identification information such as type string and/or
> + serial number
> +ethaddr
> + Ethernet address
If CONFIG_REGEX=y, also eth*addr (where * is an integer).
> +
> +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.
%s/once./if CONFIG_ENV_OVERWRITE is not set in the board configuration./g
> +
> +Also:
> +
> +ver
> + Contains the U-Boot version string as printed
> + with the "version" command. This variable is
> + 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 :-).
Please, avoid pejorative language:
%s/Windoze :/Windows/
> +
> +
> +Callback functions for environment variables
> +--------------------------------------------
This section does not fit into doc/usage. Please, move it to doc/develop.
Best regards
Heinrich
> +
> +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::
> +
e> + 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.
>
More information about the U-Boot
mailing list