1Generic SPL framework
2=====================
3
4Overview
5--------
6
7To unify all existing implementations for a secondary program loader (SPL)
8and to allow simply adding of new implementations this generic SPL framework
9has been created. With this framework almost all source files for a board
10can be reused. No code duplication or symlinking is necessary anymore.
11
12
13How it works
14------------
15
16The object files for SPL are built separately and placed in the "spl" directory.
17The final binaries which are generated are u-boot-spl, u-boot-spl.bin and
18u-boot-spl.map.
19
20A config option named CONFIG_SPL_BUILD is enabled by Kconfig for SPL.
21Source files can therefore be compiled for SPL with different settings.
22
23For example::
24
25   ifeq ($(CONFIG_SPL_BUILD),y)
26   obj-y += board_spl.o
27   else
28   obj-y += board.o
29   endif
30
31   obj-$(CONFIG_SPL_BUILD) += foo.o
32
33   #ifdef CONFIG_SPL_BUILD
34           foo();
35   #endif
36
37
38The building of SPL images can be enabled by CONFIG_SPL option in Kconfig.
39
40Because SPL images normally have a different text base, one has to be
41configured by defining CONFIG_SPL_TEXT_BASE. The linker script has to be
42defined with CONFIG_SPL_LDSCRIPT.
43
44To support generic U-Boot libraries and drivers in the SPL binary one can
45optionally define CONFIG_SPL_XXX_SUPPORT. Currently following options
46are supported:
47
48CONFIG_SPL_LIBCOMMON_SUPPORT (common/libcommon.o)
49CONFIG_SPL_LIBDISK_SUPPORT (disk/libdisk.o)
50CONFIG_SPL_I2C (drivers/i2c/libi2c.o)
51CONFIG_SPL_GPIO (drivers/gpio/libgpio.o)
52CONFIG_SPL_MMC (drivers/mmc/libmmc.o)
53CONFIG_SPL_SERIAL (drivers/serial/libserial.o)
54CONFIG_SPL_SPI_FLASH_SUPPORT (drivers/mtd/spi/libspi_flash.o)
55CONFIG_SPL_SPI (drivers/spi/libspi.o)
56CONFIG_SPL_FS_FAT (fs/fat/libfat.o)
57CONFIG_SPL_FS_EXT4
58CONFIG_SPL_LIBGENERIC_SUPPORT (lib/libgeneric.o)
59CONFIG_SPL_POWER (drivers/power/libpower.o)
60CONFIG_SPL_NAND_SUPPORT (drivers/mtd/nand/raw/libnand.o)
61CONFIG_SPL_DRIVERS_MISC (drivers/misc)
62CONFIG_SPL_DMA (drivers/dma/libdma.o)
63CONFIG_SPL_POST_MEM_SUPPORT (post/drivers/memory.o)
64CONFIG_SPL_NAND_LOAD (drivers/mtd/nand/raw/nand_spl_load.o)
65CONFIG_SPL_SPI_LOAD (drivers/mtd/spi/spi_spl_load.o)
66CONFIG_SPL_RAM_DEVICE (common/spl/spl.c)
67CONFIG_SPL_WATCHDOG (drivers/watchdog/libwatchdog.o)
68
69Adding SPL-specific code
70------------------------
71
72To check whether a feature is enabled, use CONFIG_IS_ENABLED()::
73
74  if (CONFIG_IS_ENABLED(CLK))
75      ...
76
77This checks CONFIG_CLK for the main build, CONFIG_SPL_CLK for the SPL build,
78CONFIG_TPL_CLK for the TPL build, etc.
79
80U-Boot Phases
81-------------
82
83U-Boot boots through the following phases:
84
85TPL
86   Very early init, as tiny as possible. This loads SPL (or VPL if enabled).
87
88VPL
89   Optional verification step, which can select one of several SPL binaries,
90   if A/B verified boot is enabled. Implementation of the VPL logic is
91   work-in-progress. For now it just boots into SPL.
92
93SPL
94   Secondary program loader. Sets up SDRAM and loads U-Boot proper. It may also
95   load other firmware components.
96
97U-Boot
98   U-Boot proper, containing the command line and boot logic.
99
100
101Checking the boot phase
102-----------------------
103
104Use `spl_phase()` to find the current U-Boot phase, e.g. `PHASE_SPL`. You can
105also find the previous and next phase and get the phase name.
106
107
108Device tree
109-----------
110The U-Boot device tree is filtered by the fdtgrep tools during the build
111process to generate a much smaller device tree used in SPL (spl/u-boot-spl.dtb)
112with:
113
114- the mandatory nodes (/alias, /chosen, /config)
115- the nodes with one pre-relocation property:
116  'bootph-all' or 'bootph-pre-ram'
117
118fdtgrep is also used to remove:
119
120- the properties defined in CONFIG_OF_SPL_REMOVE_PROPS
121- all the pre-relocation properties
122  ('bootph-all', 'bootph-pre-ram' (SPL), 'bootph-pre-sram' (TPL) and
123  'bootph-verify' (TPL))
124
125All the nodes remaining in the SPL devicetree are bound
126(see doc/driver-model/design.rst).
127
128NOTE: U-Boot migrated to a new schema for the u-boot,dm-* tags in 2023. Please
129update to use the new bootph-* tags as described in the
130doc/device-tree-bindings/bootph.yaml binding file.
131
132Debugging
133---------
134
135When building SPL with DEBUG set you may also need to set CONFIG_PANIC_HANG
136as in most cases do_reset is not defined within SPL.
137
138
139Estimating stack usage
140----------------------
141
142With gcc 4.6 (and later) and the use of GNU cflow it is possible to estimate
143stack usage at various points in run sequence of SPL.  The -fstack-usage option
144to gcc will produce '.su' files (such as arch/arm/cpu/armv7/syslib.su) that
145will give stack usage information and cflow can construct program flow.
146
147Must have gcc 4.6 or later, which supports -fstack-usage:
148
149#. Build normally
150#. Perform the following shell command to generate a list of C files used in
151   SPL:
152#. `find spl -name '*.su' | sed -e 's:^spl/::' -e 's:[.]su$:.c:' > used-spl.list`
153#. Execute cflow:
154   `$ cflow --main=board_init_r $(cat used-spl.list) 2>&1 | $PAGER`
155
156cflow will spit out a number of warnings as it does not parse
157the config files and picks functions based on #ifdef.  Parsing the '.i'
158files instead introduces another set of headaches.  These warnings are
159not usually important to understanding the flow, however.
160