Merge patch series "Change DRAM message and add RAM doc"

Neha Malcom Francis <n-francis@ti.com> says:

This short series is an ongoing effort to make RAM utilization clearer for
easier debugging and understanding of code. Intention is for users to quickly
be able to identify the CONFIGs needed to modify for their RAM usecase.

Link: https://lore.kernel.org/r/20250319140327.301266-1-n-francis@ti.com

.gitattributes

@@ -6,3 +6,4 @@
 *.ttf binary
 *.gz binary
 *.png binary
+*.svg binary

common/board_f.c

@@ -254,7 +254,7 @@ static int show_dram_config(void)
 
 	print_size(gd->ram_size, "");
 	if (!sizes_near(gd->ram_size, size)) {
-		printf(" (effective ");
+		printf(" (total ");
 		print_size(size, ")");
 	}
 	board_add_ram_info(0);

doc/develop/memory.rst

@@ -1,7 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0-or-later
 
 Memory Management
------------------
+=================
 
 .. note::
 
@@ -47,3 +47,159 @@ this::
 	...		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