From 456bdb70def1fe371f964e82158a53f6baf1d3a4 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sun, 29 Sep 2024 19:49:36 -0600 Subject: xpl: Rename spl_phase() to xpl_phase() Rename this function to indicate that it refers to any xPL phase. Signed-off-by: Simon Glass --- doc/develop/spl.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'doc/develop') diff --git a/doc/develop/spl.rst b/doc/develop/spl.rst index 4bb48e6b7b3..a92110e4fa9 100644 --- a/doc/develop/spl.rst +++ b/doc/develop/spl.rst @@ -34,6 +34,8 @@ For example:: foo(); #endif + if (xpl_phase() == PHASE_TPL) + bar(); The building of SPL images can be enabled by CONFIG_SPL option in Kconfig. @@ -117,7 +119,7 @@ Further usages of U-Boot SPL comprise: Checking the boot phase ----------------------- -Use `spl_phase()` to find the current U-Boot phase, e.g. `PHASE_SPL`. You can +Use `xpl_phase()` to find the current U-Boot phase, e.g. `PHASE_SPL`. You can also find the previous and next phase and get the phase name. -- cgit v1.2.3 From a64e7d73d62f139a3805483a36194c71a7f8b845 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sun, 29 Sep 2024 19:49:41 -0600 Subject: log: global: Rename warn_non_spl() This should now refer to xPL rather than SPL, so update it throughout the tree. Signed-off-by: Simon Glass --- doc/develop/logging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/develop') diff --git a/doc/develop/logging.rst b/doc/develop/logging.rst index 704a6bf1d84..d7a40c94bf0 100644 --- a/doc/develop/logging.rst +++ b/doc/develop/logging.rst @@ -292,7 +292,7 @@ Convert debug() statements in the code to log() statements Convert error() statements in the code to log() statements -Figure out what to do with BUG(), BUG_ON() and warn_non_spl() +Figure out what to do with BUG(), BUG_ON() and warn_non_xpl() Add a way to browse log records -- cgit v1.2.3 From e16bfd9e586a4114920e463f7af4fb87be6d3bc3 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sun, 29 Sep 2024 19:49:42 -0600 Subject: doc: Update SPL docs for the xPL changes 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 --- doc/develop/spl.rst | 79 +++++++++++++++++++++++++++-------------------------- 1 file changed, 41 insertions(+), 38 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/spl.rst b/doc/develop/spl.rst index a92110e4fa9..aa6d28fa333 100644 --- a/doc/develop/spl.rst +++ b/doc/develop/spl.rst @@ -1,11 +1,12 @@ -Generic SPL framework +Generic xPL framework ===================== Overview -------- -To unify all existing implementations for a secondary program loader (SPL) -and to allow simply adding of new implementations this generic SPL framework +To unify all existing implementations for secondary/tertiary program loaders +(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 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 ------------ -The object files for SPL are built separately and placed in the "spl" directory. -The final binaries which are generated are u-boot-spl, u-boot-spl.bin and -u-boot-spl.map. +The object files for xPL are built separately and placed in a subdirectory +("spl", "tpl" or "vpl"). +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. -Source files can therefore be compiled for SPL with different settings. +A config option named CONFIG_XPL_BUILD is enabled by Kconfig for xPL builds. +Source files can therefore be compiled for xPL with different settings. For example:: - ifeq ($(CONFIG_SPL_BUILD),y) + ifeq ($(CONFIG_XPL_BUILD),y) obj-y += board_spl.o else obj-y += board.o endif - obj-$(CONFIG_SPL_BUILD) += foo.o + obj-$(CONFIG_XPL_BUILD) += foo.o - #ifdef CONFIG_SPL_BUILD + if (IS_ENABLED(CONFIG_XPL_BUILD)) foo(); - #endif if (xpl_phase() == PHASE_TPL) 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 -configured by defining CONFIG_SPL_TEXT_BASE. The linker script has to be -defined with CONFIG_SPL_LDSCRIPT. +Because xPL images normally have a different text base, one has to be +configured by defining CONFIG_xPL_TEXT_BASE. The linker script has to be +defined with CONFIG_xPL_LDSCRIPT. -To support generic U-Boot libraries and drivers in the SPL binary one can -optionally define CONFIG_SPL_XXX_SUPPORT. Currently following options +To support generic U-Boot libraries and drivers in the xPL binary one can +optionally define CONFIG_xPL_XXX_SUPPORT. Currently following options are supported: 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_BLOBLIST (common/bloblist.o) -Adding SPL-specific code +Adding xPL-specific code ------------------------ 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. -While many boards use SPL, less use TPL. +While many boards use SPL, fewer use TPL. TPL 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. -Reserving memory in SPL +Reserving memory in xPL ----------------------- -If memory needs to be reserved in RAM during SPL stage with the requirement that -the SPL reserved memory remains preserved across further boot stages too +If memory needs to be reserved in RAM during an xPL phase with the requirement +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 -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. -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 -end of RAM for which helper function spl_reserve_video_from_ram_top is provided -which makes sure that video memory is placed at top of reservation area with +end of RAM for which the helper function spl_reserve_video_from_ram_top() is +provided +which makes sure that video memory is placed at the top of reservation area with further reservations below it. -The corresponding information of reservation for those regions can be passed to -further boot stages using a bloblist. For e.g. the information for -framebuffer area reserved by SPL can be passed onto U-boot using -BLOBLISTT_U_BOOT_VIDEO. - -The further boot stages need to parse each of the bloblist passed from SPL stage -starting from video bloblist and skip this whole SPL reserved memory area from -end of RAM as per the bloblists received, before carrying out further -reservations or updating the relocation address. For e.g, U-boot proper uses -function "setup_relocaddr_from_bloblist" to parse the bloblists passed from -previous stage and skip the memory reserved from previous stage accordingly. +The reservation information for these regions can be passed to the +further boot phases using a bloblist. For e.g. the information for the +framebuffer area reserved by xPL can be passed onto U-Boot using +BLOBLISTT_U_BOOT_VIDEO + +The further boot phases need to parse each of the blobs passed from xPL phase +starting from video bloblist and skip this whole xPL reserved-memory area from +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 +function setup_relocaddr_from_bloblist() to parse the bloblist passed from +previous phase and skip the memory reserved from previous phase accordingly. -- cgit v1.2.3 From 64746bfdff20017c3d0f87475f8938538ddd855d Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sun, 29 Sep 2024 19:49:44 -0600 Subject: doc: Move init-related things out of README Move this section to rst, changing it just enough so that it builds. Signed-off-by: Simon Glass --- doc/develop/index.rst | 1 + doc/develop/init.rst | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 93 insertions(+) create mode 100644 doc/develop/init.rst (limited to 'doc/develop') diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 0d0e60ab56c..da9643dca14 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -38,6 +38,7 @@ Implementation distro driver-model/index environment + init expo cedit event diff --git a/doc/develop/init.rst b/doc/develop/init.rst new file mode 100644 index 00000000000..2955d9bdbc3 --- /dev/null +++ b/doc/develop/init.rst @@ -0,0 +1,92 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Board Initialisation Flow +------------------------- + +This is the intended start-up flow for boards. This should apply for both +SPL and U-Boot proper (i.e. they both follow the same rules). + +Note: "SPL" stands for "Secondary Program Loader," which is explained in +more detail later in this file. + +At present, SPL mostly uses a separate code path, but the function names +and roles of each function are the same. Some boards or architectures +may not conform to this. At least most ARM boards which use +CONFIG_SPL_FRAMEWORK conform to this. + +Execution typically starts with an architecture-specific (and possibly +CPU-specific) start.S file, such as: + +- arch/arm/cpu/armv7/start.S +- arch/powerpc/cpu/mpc83xx/start.S +- arch/mips/cpu/start.S + +and so on. From there, three functions are called; the purpose and +limitations of each of these functions are described below. + +lowlevel_init() +~~~~~~~~~~~~~~~ + +- purpose: essential init to permit execution to reach board_init_f() +- no global_data or BSS +- there is no stack (ARMv7 may have one but it will soon be removed) +- must not set up SDRAM or use console +- must only do the bare minimum to allow execution to continue to + board_init_f() +- this is almost never needed +- return normally from this function + +board_init_f() +~~~~~~~~~~~~~~ + +- purpose: set up the machine ready for running board_init_r(): + i.e. SDRAM and serial UART +- global_data is available +- stack is in SRAM +- BSS is not available, so you cannot use global/static variables, + only stack variables and global_data + +Non-xPL-specific notes: + + - dram_init() is called to set up DRAM. If already done in SPL this + can do nothing + +xPL-specific notes: + + - you can override the entire board_init_f() function with your own + version as needed. + - preloader_console_init() can be called here in extremis + - should set up SDRAM, and anything needed to make the UART work + - there is no need to clear BSS, it will be done by crt0.S + - for specific scenarios on certain architectures an early BSS *can* + be made available (via CONFIG_SPL_EARLY_BSS by moving the clearing + of BSS prior to entering board_init_f()) but doing so is discouraged. + Instead it is strongly recommended to architect any code changes + or additions such to not depend on the availability of BSS during + board_init_f() as indicated in other sections of this README to + maintain compatibility and consistency across the entire code base. + - must return normally from this function (don't call board_init_r() + directly) + +Here the BSS is cleared. For SPL, if CONFIG_SPL_STACK_R is defined, then at +this point the stack and global_data are relocated to below +CONFIG_SPL_STACK_R_ADDR. For non-SPL, U-Boot is relocated to run at the top of +memory. + +board_init_r() +~~~~~~~~~~~~~~ + + - purpose: main execution, common code + - global_data is available + - SDRAM is available + - BSS is available, all static/global variables can be used + - execution eventually continues to main_loop() + +Non-SPL-specific notes: + + - U-Boot is relocated to the top of memory and is now running from + there. + +SPL-specific notes: + + - stack is optionally in SDRAM, if CONFIG_SPL_STACK_R is defined -- cgit v1.2.3 From ac644df9a4d5d39b3214d230a14e5ef5c8cfcdf4 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sun, 29 Sep 2024 19:49:45 -0600 Subject: doc: Update init docs for the xPL changes Update the documentation here to cover the meaning of xPL Signed-off-by: Simon Glass --- doc/develop/init.rst | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/init.rst b/doc/develop/init.rst index 2955d9bdbc3..ce985781bb4 100644 --- a/doc/develop/init.rst +++ b/doc/develop/init.rst @@ -4,15 +4,16 @@ Board Initialisation Flow ------------------------- This is the intended start-up flow for boards. This should apply for both -SPL and U-Boot proper (i.e. they both follow the same rules). +xPL and U-Boot proper (i.e. they both follow the same rules). -Note: "SPL" stands for "Secondary Program Loader," which is explained in -more detail later in this file. +Note: "xPL" stands for "any Program Loader", including SPL (Secondary +Program Loader), TPL (Tertiary Program Loader) and VPL (Verifying Program +Loader). The boot sequence is TPL->VPL->SPL->U-Boot proper -At present, SPL mostly uses a separate code path, but the function names +At present, xPL mostly uses a separate code path, but the function names and roles of each function are the same. Some boards or architectures may not conform to this. At least most ARM boards which use -CONFIG_SPL_FRAMEWORK conform to this. +CONFIG_xPL_FRAMEWORK conform to this. Execution typically starts with an architecture-specific (and possibly CPU-specific) start.S file, such as: @@ -48,7 +49,7 @@ board_init_f() Non-xPL-specific notes: - - dram_init() is called to set up DRAM. If already done in SPL this + - dram_init() is called to set up DRAM. If already done in xPL this can do nothing xPL-specific notes: @@ -68,9 +69,9 @@ xPL-specific notes: - must return normally from this function (don't call board_init_r() directly) -Here the BSS is cleared. For SPL, if CONFIG_SPL_STACK_R is defined, then at +Here the BSS is cleared. For xPL, if CONFIG_xPL_STACK_R is defined, then at this point the stack and global_data are relocated to below -CONFIG_SPL_STACK_R_ADDR. For non-SPL, U-Boot is relocated to run at the top of +CONFIG_xPL_STACK_R_ADDR. For non-xPL, U-Boot is relocated to run at the top of memory. board_init_r() @@ -82,11 +83,11 @@ board_init_r() - BSS is available, all static/global variables can be used - execution eventually continues to main_loop() -Non-SPL-specific notes: +Non-xPL-specific notes: - U-Boot is relocated to the top of memory and is now running from there. -SPL-specific notes: +xPL-specific notes: - - stack is optionally in SDRAM, if CONFIG_SPL_STACK_R is defined + - stack is optionally in SDRAM, if CONFIG_xPL_STACK_R is defined -- cgit v1.2.3 From 1d6132e2a2b1217567b88ddd6d11662afd4001df Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sun, 29 Sep 2024 19:49:50 -0600 Subject: global: Use CONFIG_XPL_BUILD instead of CONFIG_SPL_BUILD Complete this rename for all directories outside arch/ board/ drivers/ and include/ Use the new symbol to refer to any 'SPL' build, including TPL and VPL Signed-off-by: Simon Glass --- doc/develop/distro.rst | 4 ++-- doc/develop/qconfig.rst | 2 +- doc/develop/tests_sandbox.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/distro.rst b/doc/develop/distro.rst index 9e715b23ebb..637bc27fc2d 100644 --- a/doc/develop/distro.rst +++ b/doc/develop/distro.rst @@ -189,7 +189,7 @@ TO BE UPDATED: In your board configuration file, include the following:: - #ifndef CONFIG_SPL_BUILD + #ifndef CONFIG_XPL_BUILD #include #endif @@ -316,7 +316,7 @@ that it supports the correct set of possible boot device types. To provide this configuration, simply define macro BOOT_TARGET_DEVICES prior to including . For example:: - #ifndef CONFIG_SPL_BUILD + #ifndef CONFIG_XPL_BUILD #define BOOT_TARGET_DEVICES(func) \ func(MMC, mmc, 1) \ func(MMC, mmc, 0) \ diff --git a/doc/develop/qconfig.rst b/doc/develop/qconfig.rst index 123779eab17..a18f32470ca 100644 --- a/doc/develop/qconfig.rst +++ b/doc/develop/qconfig.rst @@ -226,7 +226,7 @@ Available options Look for moved config options in spl/include/autoconf.mk instead of include/autoconf.mk. This is useful for moving options for SPL build because SPL related options (mostly prefixed with CONFIG_SPL\_) are - sometimes blocked by CONFIG_SPL_BUILD ifdef conditionals. + sometimes blocked by CONFIG_XPL_BUILD ifdef conditionals. -j, --jobs Specify the number of threads to run simultaneously. If not specified, diff --git a/doc/develop/tests_sandbox.rst b/doc/develop/tests_sandbox.rst index 72923070150..0630180bc55 100644 --- a/doc/develop/tests_sandbox.rst +++ b/doc/develop/tests_sandbox.rst @@ -278,7 +278,7 @@ Whatever sandbox build is used, which tests are present is determined by which source files are built. For sandbox_spl, the of_platdata tests are built because of the build rule in test/dm/Makefile:: - ifeq ($(CONFIG_SPL_BUILD),y) + ifeq ($(CONFIG_XPL_BUILD),y) obj-$(CONFIG_SPL_OF_PLATDATA) += of_platdata.o else ...other tests for non-spl -- cgit v1.2.3 From c46760d5967d12b6f7d37402878d1607a98b2b84 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sun, 29 Sep 2024 19:49:53 -0600 Subject: global: Rename SPL_ to XPL_ Use XPL_ as the symbol to indicate an SPL build. This means that SPL_ is no-longer set. Signed-off-by: Simon Glass --- doc/develop/tests_writing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/tests_writing.rst b/doc/develop/tests_writing.rst index a328ebfef33..54efb7e1b04 100644 --- a/doc/develop/tests_writing.rst +++ b/doc/develop/tests_writing.rst @@ -321,15 +321,15 @@ to control that. Finally, add the test to the build by adding to the Makefile in the same directory:: - obj-$(CONFIG_$(SPL_)CMDLINE) += wibble.o + obj-$(CONFIG_$(XPL_)CMDLINE) += wibble.o Note that CMDLINE is never enabled in SPL, so this test will only be present in U-Boot proper. See below for how to do SPL tests. As before, you can add an extra Kconfig check if needed:: - ifneq ($(CONFIG_$(SPL_)WIBBLE),) - obj-$(CONFIG_$(SPL_)CMDLINE) += wibble.o + ifneq ($(CONFIG_$(XPL_)WIBBLE),) + obj-$(CONFIG_$(XPL_)CMDLINE) += wibble.o endif -- cgit v1.2.3