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

[Alexander Dahl]

Hello Simon,

Am Thu, Sep 19, 2024 at 05:14:22PM +0200 schrieb Simon Glass:
> Move this section of the README into doc/ with some minor updates to
> mention SPL and user lower-case hex.

Maybe try not to rewrap unchanged paragraphs,
so `git show --color-moved` can detect those as just moved?

> 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.
> +
> +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 XIP flash memory, or may be loaded into a lower region of
> +RAM by a secondary program loader (SPL). After
> +booting and sizing and initialising 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 may be 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

Arena?

`make htmldocs` runs fine, page looks okay, thus:

Acked-by: Alexander Dahl <ada at thorsis.com>

Greets
Alex

> +	      :
> +	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]
> -- 
> 2.43.0
>