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

[Heinrich Schuchardt]

On 6/30/22 12:06, Simon Glass wrote:
> 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>

Below you want a change?

>
>>
>> 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

What makes you think that BSD or Haiku have the same constraints as Linux?

>> +specific to another architecture, are good rules to follow for other
>> +architectures as well.

No. RISC-V does not have the same requirements as ARM. E.g. the initrd
can be located anywhere in memory.

>> +
>> +Example Image locations
>> +^^^^^^^^^^^^^^^^^^^^^^^

You seem not to refer to a file 'Image'.

%s/Image/image/

>> +
>> +If we take the Texas Instruments OMAP2PLUS family of ARMv7 processors as an
>> +example for the above listed variables, we would do::

%s/we would do/we chose/ ?

>> +
>> +    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' ?

Please, mention that MAX_UNCOMP_KERNEL_SIZE = 32 MiB is ARMv7 specific.

>
>
>> +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

%s/allow for us/allow/

>> +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

Please, mention that decompressor code otherwise will have to relocate
the compressed kernel.

>> +say that the device tree will be placed at 128MiB offset from the start of

Please, mention that initrd must be

* within 512 MiB (0x20000000) of the memory start on arm
   (which restricts initrd_high)
* in a a 1 GB aligned region of size '1UL << (VA_BITS_MIN - 1)' that
   includes the kernel on arm64

On RISC-V such a limitation does not exist.

>> +memory.  This is suggested by the kernel documment as it is exceedingly

%s/documment/document

>> +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

If the load address ranges occupy the first 256 MiB, where will be the
space for relocation on a 256 MiB board? Without mentioning initrd_high
this paragraph is incomplete.

>> +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.

A section per architecture clearly naming the architecture specific
restrictions of Linux would be much more helpful.

Best regards

Heinrich

>>
>>   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
>>