Re: [PATCH v4 2/5] doc: Move environment documentation to rST

[Wolfgang Denk <wd@denx.de>]

Dear Simon,

In message <20210919185950.3813952-3-sjg@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 00000000000..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-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
> +================= ============== ================ ==============

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
> +netmask    Subnet 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: wd@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