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

[Simon Glass]

Hi Alex,

On Thu, 19 Sept 2024 at 17:28, Alexander Dahl <ada at thorsis.com> wrote:
>
> 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?

I did try to do that, but perhaps did a line wrong?

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

Yes, a strange choice of words perhaps, but fair enough.

>
> `make htmldocs` runs fine, page looks okay, thus:
>
> Acked-by: Alexander Dahl <ada at thorsis.com>

Thanks.

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

Regards,
Simon