[PATCH v4 2/5] doc: Move environment documentation to rST
Move this from the README to rST format. Drop i2cfast since it is obviously obsolete and breaks the formatting. Signed-off-by: Simon Glass --- Changes in v4: - Add new patch to move environment documentation to rST README| 328 doc/usage/environment.rst | 382 ++ doc/usage/index.rst | 1 + 3 files changed, 383 insertions(+), 328 deletions(-) create mode 100644 doc/usage/environment.rst diff --git a/README b/README index a3f81e4aed0..31eaf2f5f81 100644 --- a/README +++ b/README @@ -3180,334 +3180,6 @@ TODO. For now: just type "help ". -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 0x1000, while Linux kernel - only recognizes the first 704 MB as low memory, you - may need to set fdt_high as 0x3C00 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 0x 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 -
Re: [PATCH v4 2/5] doc: Move environment documentation to rST
Dear Simon,
In message <20210919185950.3813952-3-...@chromium.org> you wrote:
> Move this from the README to rST format.
Just a few nitpicks...
> diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst
> new file mode 100644
> index 000..be785a8f717
> --- /dev/null
> +++ b/doc/usage/environment.rst
> @@ -0,0 +1,382 @@
> +.. 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.
...by saving to persistent storage, for example flash memory.
> +Environment Variables are set using "setenv", printed using
> +"printenv", and saved to Flash using "saveenv". Using "setenv"
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" ...
> +Some configuration options can be set using Environment Variables.
This probably needs an explanation what "configuration options'
means here?
> +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-bootu-boot u-boot_addr_ru-boot_addr
> +Linux kernel bootfile kernel_addr_rkernel_addr
> +device tree blob fdtfilefdt_addr_r fdt_addr
> +ramdisk ramdiskfileramdisk_addr_r ramdisk_addr
> += == ==
Maybe it should be pointed out that this is just a commonly used set
of variable names, used in some other variable definitions, but is
in no way hard coded anywhere in U-Boot code.
OK, I see that "bootfile" and ""fdtfile" are now actually used in
some code - but IMO this is a bad idea and should be fixed.
> +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
> +netmaskSubnet Mask
> +rootpath Pathname of the root filesystem on the NFS server
> +serverip see above
> += ===
This list is incomplete; for example, sysboot sets bootfile, too.
For completeness, .flags etc. should be documented, too [but yes,
this is a separate task of course].
Best regards,
Wolfgang Denk
--
DENX Software Engineering GmbH, Managing Director: Wolfgang Denk
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: w...@denx.de
I wrote my name at the top of the page. I wrote down the number of
the question ``1''. After much reflection I put a bracket round it
thus ``(1)''. But thereafter I could not think of anything connected
with it that was either relevant or true.
- Sir Winston Churchill _My Early Life_ ch. 2
