[PATCH] doc: Move the generic memory-documentation to doc/

[Heinrich Schuchardt]

On 9/19/24 17:14, Simon Glass wrote:
> Move this section of the README into doc/ with some minor updates to
> mention SPL and user lower-case hex.
>
> Signed-off-by: Simon Glass <sjg at chromium.org>
> ---
>
>   README                 | 45 ------------------------------------------
>   doc/develop/index.rst  |  1 +
>   doc/develop/memory.rst | 45 ++++++++++++++++++++++++++++++++++++++++++
>   3 files changed, 46 insertions(+), 45 deletions(-)
>   create mode 100644 doc/develop/memory.rst
>
> diff --git a/README b/README
> index 4be1e8c22a0..d73042406b6 100644
> --- a/README
> +++ b/README
> @@ -2516,51 +2516,6 @@ On RISC-V, the following registers are used:
>
>       ==> U-Boot will use gp to hold a pointer to the global data
>
> -Memory Management:
> -------------------
> -
> -U-Boot runs in system state and uses physical addresses, i.e. the
> -MMU is not used either for address mapping nor for memory protection.
> -
> -The available memory is mapped to fixed addresses using the memory
> -controller. In this process, a contiguous block is formed for each
> -memory type (Flash, SDRAM, SRAM), even when it consists of several
> -physical memory banks.
> -
> -U-Boot is installed in the first 128 kB of the first Flash bank (on
> -TQM8xxL modules this is the range 0x40000000 ... 0x4001FFFF). After
> -booting and sizing and initializing DRAM, the code relocates itself
> -to the upper end of DRAM. Immediately below the U-Boot code some
> -memory is reserved for use by malloc() [see CONFIG_SYS_MALLOC_LEN
> -configuration setting]. Below that, a structure with global Board
> -Info data is placed, followed by the stack (growing downward).
> -
> -Additionally, some exception handler code is copied to the low 8 kB
> -of DRAM (0x00000000 ... 0x00001FFF).
> -
> -So a typical memory configuration with 16 MB of DRAM could look like
> -this:
> -
> -	0x0000 0000	Exception Vector code
> -	      :
> -	0x0000 1FFF
> -	0x0000 2000	Free for Application Use
> -	      :
> -	      :
> -
> -	      :
> -	      :
> -	0x00FB FF20	Monitor Stack (Growing downward)
> -	0x00FB FFAC	Board Info Data and permanent copy of global data
> -	0x00FC 0000	Malloc Arena
> -	      :
> -	0x00FD FFFF
> -	0x00FE 0000	RAM Copy of Monitor Code
> -	...		eventually: LCD or video framebuffer
> -	...		eventually: pRAM (Protected RAM - unchanged by reset)
> -	0x00FF FFFF	[End of RAM]
> -
> -
>   System Initialization:
>   ----------------------
>
> diff --git a/doc/develop/index.rst b/doc/develop/index.rst
> index 0d0e60ab56c..cbea38d4323 100644
> --- a/doc/develop/index.rst
> +++ b/doc/develop/index.rst
> @@ -13,6 +13,7 @@ General
>      codingstyle
>      designprinciples
>      docstyle
> +   memory
>      patman
>      process
>      release_cycle
> diff --git a/doc/develop/memory.rst b/doc/develop/memory.rst
> new file mode 100644
> index 00000000000..fa1ae5e97ed
> --- /dev/null
> +++ b/doc/develop/memory.rst
> @@ -0,0 +1,45 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +Memory Management
> +-----------------
> +
> +U-Boot runs in system state and uses physical addresses, i.e. the
> +MMU is not used either for address mapping nor for memory protection.

Hello Simon,

Thanks for getting the description moved.

The text that you are copying dates back to 2004 when U-Boot was
focusing on the Power architecture. It needs some rework.

On RISC-V there is a physical memory protection (PMP) which is typically
set up to guard against overwriting OpenSBI sitting at the lower end of RAM.

There is some ongoing work to implement NX protection via the MMU for ARM.

> +
> +The available memory is mapped to fixed addresses using the
> +memory-controller. In this process, a contiguous block is formed for each
> +memory type (Flash, SDRAM, SRAM), even when it consists of several
> +physical-memory banks.

Can we simply say DRAM instead of SDRAM. We always refer to DRAM below.
Whether the RAM frequency is synchronous or not is irrelevant here.

> +
> +U-Boot is installed in XIP flash memory, or may be loaded into a lower region of
> +RAM by a secondary program loader (SPL). After

This does not describe U-Boot SPL as being a part of U-Boot.

> +booting and sizing and initialising DRAM, the code relocates itself

Initialization of DRAM can be done in code running before U-Boot.

> +to the upper end of DRAM. Immediately below the U-Boot code some
 > +memory is reserved for use by malloc() [see CONFIG_SYS_MALLOC_LEN>
+configuration setting]. Below that, a structure with global Board-Info
> +data is placed, followed by the stack (growing downward).
> +
> +Additionally, some exception handler code may be copied to the low 8 kB
> +of DRAM (0x00000000 ... 0x00001fff).

The exception handler code for RISC-V and ARMv8 is typically not located
at 0x0.

On RISC-V stvec, the Supervisor Trap Vector Base Address Register,
defines where the exception vectors are located in S-Mode.

On ARMv8 VBAR_EL2, the Vector Base Address Register (EL2), sets the
location of the EL2 vector base.

> +
> +So a typical memory configuration with 16 MB of DRAM could look like

%s/MB/MiB/

> +this::
> +
> +	0x0000 0000	Exception Vector code

On RISC-V the lowest memory addresses in RAM are typically used by
OpenSBI. On ARM you may have TF-A sitting there.

> +	      :
> +	0x0000 1fff
> +	0x0000 2000	Free for Application Use
> +	      :
> +	      :
> +
> +	      :
> +	      :
> +	0x00fb ff20	Monitor Stack (Growing downward)
> +	0x00fb ffac	Board Info Data and permanent copy of global data
> +	0x00fc 0000	Malloc Arena
> +	      :
> +	0x00fd ffff
> +	0x00fe 0000	RAM Copy of Monitor Code
> +	...		eventually: LCD or video framebuffer
> +	...		eventually: pRAM (Protected RAM - unchanged by reset)
> +	0x00ff ffff	[End of RAM]

A description of the LMB and EFI should be added in a future patch.

Best regards

Heinrich