Message ID | 20211019224422.1447059-3-sjg@chromium.org |
---|---|
State | Superseded |
Delegated to: | Tom Rini |
Headers | show |
Series | env: Allow environment in text files | expand |
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@chromium.org> > Acked-by: Marek Behún <marek.behun@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. >
Hi Heinrich, On Wed, 20 Oct 2021 at 00:38, Heinrich Schuchardt <xypron.glpk@gmx.de> wrote: > > 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@chromium.org> > > Acked-by: Marek Behún <marek.behun@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 > > Thanks for your comments on this. I'll add another patch with these. Regards, Simon
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 +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. + +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 + + +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 + +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. + +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 :-). + + +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.