doc/develop/spl.rst

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