[PATCH 3/3] doc: environment: Further expand on Image locations and provide example

[Simon Glass]

On Mon, 20 Jun 2022 at 08:32, Tom Rini <trini at konsulko.com> wrote:
>
> Start by elaborating on what some of our constraints tend to be with
> image location values, and document where these external constraints
> come from.  Provide a new subsection, an example based on the TI ARMv7
> OMAP2PLUS families of chips, that gives sample values and explains why
> we use these particular values.  This is based on what is in
> include/configs/ti_armv7_common.h as of fb3ad9bd923d ("TI: Add, use a
> DEFAULT_LINUX_BOOT_ENV environment string") as this contains just the
> values referenced in this document now and not some of the further
> additions that are less generic.
>
> Signed-off-by: Tom Rini <trini at konsulko.com>
> ---
>  doc/usage/environment.rst | 39 +++++++++++++++++++++++++++++++++++++++
>  1 file changed, 39 insertions(+)

Reviewed-by: Simon Glass <sjg at chromium.org>

>
> diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst
> index a9a4702632d2..f70ccd6a58ee 100644
> --- a/doc/usage/environment.rst
> +++ b/doc/usage/environment.rst
> @@ -404,6 +404,42 @@ device tree blob  fdtfile        fdt_addr_r       fdt_addr
>  ramdisk           ramdiskfile    ramdisk_addr_r   ramdisk_addr
>  ================= ============== ================ ==============
>
> +When setting the RAM addresses for `kernel_addr_r`, `fdt_addr_r` and
> +`ramdisk_addr_r` there are several constraints to keep in mind. When booting
> +Linux, the `Booting ARM Linux`_ and `Booting AArch64 Linux`_ documents lay out
> +the requirements for booting all ARM platforms, including both alignment and
> +where within memory various things must be.  These guidelines tend to also be
> +correct for other OSes and unless specifically contradicted by documentation
> +specific to another architecture, are good rules to follow for other
> +architectures as well.
> +
> +Example Image locations
> +^^^^^^^^^^^^^^^^^^^^^^^
> +
> +If we take the Texas Instruments OMAP2PLUS family of ARMv7 processors as an
> +example for the above listed variables, we would do::
> +
> +    loadaddr=0x82000000
> +    kernel_addr_r=${loadaddr}
> +    fdt_addr_r=0x88000000
> +    ramdisk_addr_r=0x88080000
> +    bootm_size=0x10000000
> +
> +To explain this, we start by noting that DRAM starts at 0x80000000.  A 32MiB

Should it say 'We use a 32MiB' ?


> +buffer from the start of memory as our default load address, and so where the
> +kernel would also be loaded to.  This will hopefully allow for us to have the
> +whole of the compressed kernel image exist in memory above where the whole of
> +the decompressed kernel image will be, and allow for a quicker boot.  Next, we
> +say that the device tree will be placed at 128MiB offset from the start of
> +memory.  This is suggested by the kernel documment as it is exceedingly
> +unlikely to be overwritten by the kernel itself given other architectural
> +constraints.  We then allow for the device tree to be up to 512KiB in size
> +before placing the ramdisk in memory.  We then say that everything should be
> +within the first 256MiB of memory so that U-Boot can relocate things as needed
> +to ensure proper alignment.  We pick 256MiB as our value here because we know
> +there are very few platforms on in this family with less memory.  It could be
> +as high as 768MiB and still ensure that everything would be visible to the
> +kernel, but again we go with what we assume is the safest assumption.
>
>  Automatically updated variables
>  -------------------------------
> @@ -472,3 +508,6 @@ Implementation
>  --------------
>
>  See :doc:`../develop/environment` for internal development details.
> +
> +.. _`Booting ARM Linux`: https://www.kernel.org/doc/html/latest/arm/booting.html
> +.. _`Booting AArch64 Linux`: https://www.kernel.org/doc/html/latest/arm64/booting.html
> --
> 2.25.1
>