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

[Simon Glass]

Hi Heinrich,

On Sun, 22 Sept 2024 at 11:02, Heinrich Schuchardt <xypron.glpk at gmx.de> wrote:
>
> 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.

I don't believe we need to get into the weeds on this description. It
is just setting some guiding principles. Yes, every architecture is
different, but people can see the general idea.

Perhaps we should add details about each architecture at the end, i.e.
provide a link to an arch-specific page which provides more
information?

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

With my two series we can clean up EFI so that it works within the above.

Regards,
Simon