colin/u-boot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: Update SPL docs for the xPL changes

Browse Source 
Update the various references to SPL in this document. Make sure to
refer to 'phases' instead of 'stages', which is not a U-Boot term.

Fix a few U-boot typos and try to improve grammar a little while we are
here.

Signed-off-by: Simon Glass <sjg@chromium.org>
This commit is contained in:
Simon Glass
2024-09-29 19:49:42 -06:00
committed by Tom Rini
parent a64e7d73d6
commit e16bfd9e58
1 changed files with 40 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
doc/develop/spl.rst
View File

@@ -1,11 +1,12 @@
Generic SPL framework Generic xPL framework
===================== =====================
Overview Overview
-------- --------
To unify all existing implementations for a secondary program loader (SPL) To unify all existing implementations for secondary/tertiary program loaders
and to allow simply adding of new implementations this generic SPL framework (generically called xPL)
and to allow simply adding of new implementations this generic xPL framework
has been created. With this framework almost all source files for a board has been created. With this framework almost all source files for a board
can be reused. No code duplication or symlinking is necessary anymore. can be reused. No code duplication or symlinking is necessary anymore.
@@ -13,38 +14,39 @@ can be reused. No code duplication or symlinking is necessary anymore.
How it works How it works
------------ ------------
The object files for SPL are built separately and placed in the "spl" directory. The object files for xPL are built separately and placed in a subdirectory
The final binaries which are generated are u-boot-spl, u-boot-spl.bin and ("spl", "tpl" or "vpl").
u-boot-spl.map. The final binaries which are generated for SPL are u-boot-spl, u-boot-spl.bin
and u-boot-spl.map
A config option named CONFIG_SPL_BUILD is enabled by Kconfig for SPL. A config option named CONFIG_XPL_BUILD is enabled by Kconfig for xPL builds.
Source files can therefore be compiled for SPL with different settings. Source files can therefore be compiled for xPL with different settings.
For example:: For example::
ifeq ($(CONFIG_SPL_BUILD),y) ifeq ($(CONFIG_XPL_BUILD),y)
obj-y += board_spl.o obj-y += board_spl.o
else else
obj-y += board.o obj-y += board.o
endif endif
obj-$(CONFIG_SPL_BUILD) += foo.o obj-$(CONFIG_XPL_BUILD) += foo.o
#ifdef CONFIG_SPL_BUILD if (IS_ENABLED(CONFIG_XPL_BUILD))
foo(); foo();
#endif
if (xpl_phase() == PHASE_TPL) if (xpl_phase() == PHASE_TPL)
bar(); bar();
The building of SPL images can be enabled by CONFIG_SPL option in Kconfig. The building of xPL images can be enabled by CONFIG_SPL (etc.) options in
Kconfig.
Because SPL images normally have a different text base, one has to be Because xPL images normally have a different text base, one has to be
configured by defining CONFIG_SPL_TEXT_BASE. The linker script has to be configured by defining CONFIG_xPL_TEXT_BASE. The linker script has to be
defined with CONFIG_SPL_LDSCRIPT. defined with CONFIG_xPL_LDSCRIPT.
To support generic U-Boot libraries and drivers in the SPL binary one can To support generic U-Boot libraries and drivers in the xPL binary one can
optionally define CONFIG_SPL_XXX_SUPPORT. Currently following options optionally define CONFIG_xPL_XXX_SUPPORT. Currently following options
are supported: are supported:
CONFIG_SPL_LIBCOMMON_SUPPORT (common/libcommon.o) CONFIG_SPL_LIBCOMMON_SUPPORT (common/libcommon.o)
@@ -77,7 +79,7 @@ CONFIG_SPL_DM_GPIO (drivers/gpio/gpio-uclass.o)
CONFIG_SPL_BMP (drivers/video/bmp.o) CONFIG_SPL_BMP (drivers/video/bmp.o)
CONFIG_SPL_BLOBLIST (common/bloblist.o) CONFIG_SPL_BLOBLIST (common/bloblist.o)
Adding SPL-specific code Adding xPL-specific code
------------------------ ------------------------
To check whether a feature is enabled, use CONFIG_IS_ENABLED():: To check whether a feature is enabled, use CONFIG_IS_ENABLED()::
@@ -92,7 +94,7 @@ U-Boot Boot Phases
------------------ ------------------
U-Boot goes through the following boot phases where TPL, VPL, SPL are optional. U-Boot goes through the following boot phases where TPL, VPL, SPL are optional.
While many boards use SPL, less use TPL. While many boards use SPL, fewer use TPL.
TPL TPL
Very early init, as tiny as possible. This loads SPL (or VPL if enabled). Very early init, as tiny as possible. This loads SPL (or VPL if enabled).
@@ -179,29 +181,30 @@ files instead introduces another set of headaches. These warnings are
not usually important to understanding the flow, however. not usually important to understanding the flow, however.
Reserving memory in SPL Reserving memory in xPL
----------------------- -----------------------
If memory needs to be reserved in RAM during SPL stage with the requirement that If memory needs to be reserved in RAM during an xPL phase with the requirement
the SPL reserved memory remains preserved across further boot stages too that the xPL reserved memory remains preserved across further boot phases too
then it needs to be reserved mandatorily starting from end of RAM. This is to then it needs to be reserved mandatorily starting from end of RAM. This is to
ensure that further stages can simply skip this region before carrying out ensure that further phases can simply skip this region before carrying out
further reservations or updating the relocation address. further reservations or updating the relocation address.
Also out of these regions which are to be preserved across further stages of Also out of these regions which are to be preserved across further phases of
boot, video framebuffer memory region must be reserved first starting from boot, video framebuffer memory region must be reserved first starting from
end of RAM for which helper function spl_reserve_video_from_ram_top is provided end of RAM for which the helper function spl_reserve_video_from_ram_top() is
which makes sure that video memory is placed at top of reservation area with provided
which makes sure that video memory is placed at the top of reservation area with
further reservations below it. further reservations below it.
The corresponding information of reservation for those regions can be passed to The reservation information for these regions can be passed to the
further boot stages using a bloblist. For e.g. the information for further boot phases using a bloblist. For e.g. the information for the
framebuffer area reserved by SPL can be passed onto U-boot using framebuffer area reserved by xPL can be passed onto U-Boot using
BLOBLISTT_U_BOOT_VIDEO. BLOBLISTT_U_BOOT_VIDEO
The further boot stages need to parse each of the bloblist passed from SPL stage The further boot phases need to parse each of the blobs passed from xPL phase
starting from video bloblist and skip this whole SPL reserved memory area from starting from video bloblist and skip this whole xPL reserved-memory area from
end of RAM as per the bloblists received, before carrying out further end of RAM as per the blobs received, before carrying out further
reservations or updating the relocation address. For e.g, U-boot proper uses reservations or updating the relocation address. For e.g, U-Boot proper uses
function "setup_relocaddr_from_bloblist" to parse the bloblists passed from function setup_relocaddr_from_bloblist() to parse the bloblist passed from
previous stage and skip the memory reserved from previous stage accordingly. previous phase and skip the memory reserved from previous phase accordingly.