doc/develop/memory.rst - filogic/uboot - Gitiles

 .. SPDX-License-Identifier: GPL-2.0-or-later

 Memory Management
 =================

 .. note::

   This information is outdated and needs to be updated.

 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
 	      :
 	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 RAM Utilization in U-Boot in ARM
 ---------------------------------------

 Let us break down the relevant parts of the execution sequence where system RAM
 comes into play. Please note that these are individual pieces of the entire
 boot sequence. It is not exhaustive, rather it aims to show only the pieces
 where the system RAM is modified. See arch/arm/lib/crt0* to understand the
 complete execution sequence.

 Also note that the below sequence is not a hard and fast rule on how DRAM usage
 would be and an architecture and board specific analysis is required for the
 exact flow.

 SPL Flow
 ........

    #. Pre-DRAM

       Prior to setting up of the DRAM, the stack, malloc is defined as below
       possibly sitting on a smaller readily available memory (SRAM etc.):

       .. image:: pics/spl_before_reloc.svg
          :alt: contents of ready RAM before relocation in SPL

       Please see CONFIG_SPL_EARLY_BSS if BSS initialization is needed prior
       to entering board_init_f().


    #. DRAM Initialization

       This is typically triggered by board_init_f prior to relocating the stack
       and the GD (optionally) to the system RAM. DRAM drivers reside in
       drivers/ram/. Their probe/configuration can be done either via placing the
       logic in dram_init() or wherever deemed applicable within board_init_f.

       Post board_init_f, spl_relocate_stack_gd() is called to relocate the stack
       and the GD to the newly initialized DRAM. If CONFIG_SPL_SYS_MALLOC_SIMPLE
       is set it is also possible to use some amount of this DRAM stack as memory
       pool for malloc_simple.

       Both of which are an optional move at this point in the sequence. This is
       still an intermediate environment.

    #. Final Environment Set Up

       The final environment is setup and the system RAM now looks like this:

       .. image:: pics/spl_after_reloc.svg
          :alt: contents of DRAM after relocation in SPL

       Again stack and gd are an optional move and may still remain in the
       available RAM (SRAM, locked cache etc.)

 U-Boot Proper Flow
 ..................

    TODO: this section is still under progress

    #. DRAM Initialization

       This follows the same as in SPL flow. In board_init_f(), a part of memory
       is reserved at the end of RAM (see reserve_* functions in init_sequence_f)

    #. Code Relocation

       relocate_code() is called which relocates U-Boot code from the current
       location into the relocation destination in system RAM. Typically it is
       relocated to the upper portion of the memory. So DRAM now has:
       * stack
       * gd
       * code

       The code relocation happens to the upper portion of the memory after certain
       portion of memory is reserved. This is memory that is intended to not be
       "touched" by U-Boot.

    #. Final Environment Set Up

       At this stage we are completely running out of the system RAM with:
       * stack
       * gd
       * code
       * bss
       * initialized non-const data
       * initialized const data

       It is better to do a complete analysis to visualize the layers the system
       RAM is composed of at the end of this flow. This is entirely dependent on
       CPU/SoC architecture.

 Getting information about system RAM
 ....................................

    At boot:

    The prints given by announce_dram_init() and show_dram_config() come up in the
    boot banner like so::

       DRAM:  2 GiB (total 32 GiB)

    U-Boot supports addressing upto 39-bit. To avoid trying to access higher
    addresses in systems with > 39-bit addresses, U-Boot caps itself (gd->ram_size)
    to the first bank. This is also inline with philosophy that U-Boot is a
    bootloader and not a full-fledged operating system. The first value represents
    this memory that is available for U-Boot while the "total" value represents the
    total system RAM available on the device.

    Getting the most basic information on how system RAM has been set up is by
    running `bdinfo` at U-Boot prompt::

       => bdinfo
       boot_params = 0x0000000000000000
       DRAM bank   = 0x0000000000000000
       -> start    = 0x0000000080000000
       -> size     = 0x0000000080000000
       DRAM bank   = 0x0000000000000001
       -> start    = 0x0000000880000000
       -> size     = 0x0000000780000000
       flashstart  = 0x0000000000000000
       flashsize   = 0x0000000000000000
       flashoffset = 0x0000000000000000
       baudrate    = 115200 bps
       relocaddr   = 0x00000000ffec1000
       reloc off   = 0x000000007f6c1000
       Build       = 64-bit
       current eth = ethernet@46000000port@1
       ethaddr     = 3c:e0:64:62:4b:4e
       IP addr     = <NULL>
       fdt_blob    = 0x00000000fde7df60
       lmb_dump_all:
        memory.count = 0x1
        memory[0]      [0x80000000-0xffffffff], 0x80000000 bytes flags: none
        reserved.count = 0x2
        reserved[0]    [0x9e800000-0xabffffff], 0x0d800000 bytes flags: no-map
        reserved[1]    [0xfce79f50-0xffffffff], 0x031860b0 bytes flags: no-overwrite
       devicetree  = separate
       serial addr = 0x0000000002880000
        width      = 0x0000000000000000
        shift      = 0x0000000000000002
        offset     = 0x0000000000000000
        clock      = 0x0000000002dc6c00
       arch_number = 0x0000000000000000
       TLB addr    = 0x00000000ffff0000
       irq_sp      = 0x00000000fde7df50
       sp start    = 0x00000000fde7df50
       Early malloc usage: 3288 / 8000


    Here you are able to see the banks of DDR that have been set up in DRAM bank
    -> start and -> size as well as the reserved memories in lmb_dump_all.

 Testing Memory
 --------------

    Please see doc/README.memory-test
	.. SPDX-License-Identifier: GPL-2.0-or-later

	Memory Management
	=================

	.. note::

	This information is outdated and needs to be updated.

	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
	:
	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 RAM Utilization in U-Boot in ARM
	---------------------------------------

	Let us break down the relevant parts of the execution sequence where system RAM
	comes into play. Please note that these are individual pieces of the entire
	boot sequence. It is not exhaustive, rather it aims to show only the pieces
	where the system RAM is modified. See arch/arm/lib/crt0* to understand the
	complete execution sequence.

	Also note that the below sequence is not a hard and fast rule on how DRAM usage
	would be and an architecture and board specific analysis is required for the
	exact flow.

	SPL Flow
	........

	#. Pre-DRAM

	Prior to setting up of the DRAM, the stack, malloc is defined as below
	possibly sitting on a smaller readily available memory (SRAM etc.):

	.. image:: pics/spl_before_reloc.svg
	:alt: contents of ready RAM before relocation in SPL

	Please see CONFIG_SPL_EARLY_BSS if BSS initialization is needed prior
	to entering board_init_f().


	#. DRAM Initialization

	This is typically triggered by board_init_f prior to relocating the stack
	and the GD (optionally) to the system RAM. DRAM drivers reside in
	drivers/ram/. Their probe/configuration can be done either via placing the
	logic in dram_init() or wherever deemed applicable within board_init_f.

	Post board_init_f, spl_relocate_stack_gd() is called to relocate the stack
	and the GD to the newly initialized DRAM. If CONFIG_SPL_SYS_MALLOC_SIMPLE
	is set it is also possible to use some amount of this DRAM stack as memory
	pool for malloc_simple.

	Both of which are an optional move at this point in the sequence. This is
	still an intermediate environment.

	#. Final Environment Set Up

	The final environment is setup and the system RAM now looks like this:

	.. image:: pics/spl_after_reloc.svg
	:alt: contents of DRAM after relocation in SPL

	Again stack and gd are an optional move and may still remain in the
	available RAM (SRAM, locked cache etc.)

	U-Boot Proper Flow
	..................

	TODO: this section is still under progress

	#. DRAM Initialization

	This follows the same as in SPL flow. In board_init_f(), a part of memory
	is reserved at the end of RAM (see reserve_* functions in init_sequence_f)

	#. Code Relocation

	relocate_code() is called which relocates U-Boot code from the current
	location into the relocation destination in system RAM. Typically it is
	relocated to the upper portion of the memory. So DRAM now has:
	* stack
	* gd
	* code

	The code relocation happens to the upper portion of the memory after certain
	portion of memory is reserved. This is memory that is intended to not be
	"touched" by U-Boot.

	#. Final Environment Set Up

	At this stage we are completely running out of the system RAM with:
	* stack
	* gd
	* code
	* bss
	* initialized non-const data
	* initialized const data

	It is better to do a complete analysis to visualize the layers the system
	RAM is composed of at the end of this flow. This is entirely dependent on
	CPU/SoC architecture.

	Getting information about system RAM
	....................................

	At boot:

	The prints given by announce_dram_init() and show_dram_config() come up in the
	boot banner like so::

	DRAM: 2 GiB (total 32 GiB)

	U-Boot supports addressing upto 39-bit. To avoid trying to access higher
	addresses in systems with > 39-bit addresses, U-Boot caps itself (gd->ram_size)
	to the first bank. This is also inline with philosophy that U-Boot is a
	bootloader and not a full-fledged operating system. The first value represents
	this memory that is available for U-Boot while the "total" value represents the
	total system RAM available on the device.

	Getting the most basic information on how system RAM has been set up is by
	running `bdinfo` at U-Boot prompt::

	=> bdinfo
	boot_params = 0x0000000000000000
	DRAM bank = 0x0000000000000000
	-> start = 0x0000000080000000
	-> size = 0x0000000080000000
	DRAM bank = 0x0000000000000001
	-> start = 0x0000000880000000
	-> size = 0x0000000780000000
	flashstart = 0x0000000000000000
	flashsize = 0x0000000000000000
	flashoffset = 0x0000000000000000
	baudrate = 115200 bps
	relocaddr = 0x00000000ffec1000
	reloc off = 0x000000007f6c1000
	Build = 64-bit
	current eth = ethernet@46000000port@1
	ethaddr = 3c:e0:64:62:4b:4e
	IP addr = <NULL>
	fdt_blob = 0x00000000fde7df60
	lmb_dump_all:
	memory.count = 0x1
	memory[0] [0x80000000-0xffffffff], 0x80000000 bytes flags: none
	reserved.count = 0x2
	reserved[0] [0x9e800000-0xabffffff], 0x0d800000 bytes flags: no-map
	reserved[1] [0xfce79f50-0xffffffff], 0x031860b0 bytes flags: no-overwrite
	devicetree = separate
	serial addr = 0x0000000002880000
	width = 0x0000000000000000
	shift = 0x0000000000000002
	offset = 0x0000000000000000
	clock = 0x0000000002dc6c00
	arch_number = 0x0000000000000000
	TLB addr = 0x00000000ffff0000
	irq_sp = 0x00000000fde7df50
	sp start = 0x00000000fde7df50
	Early malloc usage: 3288 / 8000


	Here you are able to see the banks of DDR that have been set up in DRAM bank
	-> start and -> size as well as the reserved memories in lmb_dump_all.

	Testing Memory
	--------------

	Please see doc/README.memory-test