diff options
Diffstat (limited to 'doc/develop')
| -rw-r--r-- | doc/develop/index.rst | 1 | ||||
| -rw-r--r-- | doc/develop/kconfig.rst | 157 | ||||
| -rw-r--r-- | doc/develop/release_cycle.rst | 2 | ||||
| -rw-r--r-- | doc/develop/uefi/uefi.rst | 45 |
4 files changed, 202 insertions, 3 deletions
diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 30f7fdb8847..d9f2a838207 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -13,6 +13,7 @@ General codingstyle designprinciples docstyle + kconfig memory patman process diff --git a/doc/develop/kconfig.rst b/doc/develop/kconfig.rst new file mode 100644 index 00000000000..227074dc497 --- /dev/null +++ b/doc/develop/kconfig.rst @@ -0,0 +1,157 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kconfig in U-Boot +================= + +This document describes the configuration infrastructure of U-Boot. + +The conventional configuration was replaced by Kconfig at v2014.10-rc1 release. + +Language Specification +---------------------- + +The Kconfig configuration language originates in Linux kernel. +See the Linux document +`Kconfig Language <https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html>`_ +for a description of Kconfig. + +Difference from Linux's Kconfig +------------------------------- + +Here are some worth-mentioning configuration targets. + +silentoldconfig + This target updates .config, include/generated/autoconf.h and + include/configs/* as in Linux. In U-Boot, it also does the following + for the compatibility with the old configuration system: + + * create a symbolic link "arch/${ARCH}/include/asm/arch" pointing to + the SoC/CPU specific header directory + * create include/config.h + * create include/autoconf.mk + * create spl/include/autoconf.mk (SPL and TPL only) + * create tpl/include/autoconf.mk (TPL only) + + If we could completely switch to Kconfig in a long run + (i.e. remove all the include/configs/\*.h), those additional processings + above would be removed. + +defconfig + In U-Boot, "make defconfig" is a shorthand of "make sandbox_defconfig" + +<board>_defconfig + Now it works as in Linux. + The prefixes such as "+S:" in \*_defconfig are deprecated. + You can simply remove the prefixes. Do not add them for new boards. + +<board>_config + This does not exist in Linux's Kconfig. + "make <board>_config" works the same as "make <board>_defconfig". + Prior to Kconfig, in U-Boot, "make <board>_config" was used for the + configuration. It is still supported for backward compatibility, so + we do not need to update the distro recipes. + +The other configuration targets work as in Linux Kernel. + +Migration steps to Kconfig +-------------------------- + +Prior to Kconfig, the C preprocessor based board configuration had been used +in U-Boot. + +Although Kconfig was introduced and some configs have been moved to Kconfig, +many of configs are still defined in C header files. It will take a very +long term to move all of them to Kconfig. In the interim, the two different +configuration infrastructures should coexist. +The configuration files are generated by both Kconfig and the old preprocessor +based configuration as follows: + +Configuration files for use in C sources + - include/generated/autoconf.h (generated by Kconfig for Normal) + - include/configs/<board>.h (exists for all boards) + +Configuration file for use in makefiles + - include/config/auto.conf (generated by Kconfig) + - include/autoconf.mk (generated by the old config for Normal) + - spl/include/autoconfig.mk (generated by the old config for SPL) + - tpl/include/autoconfig.mk (generated by the old config for TPL) + +When adding a new CONFIG macro, it is highly recommended to add it to Kconfig +rather than to a header file. + +Conversion from boards.cfg to Kconfig +------------------------------------- + +Prior to Kconfig, boards.cfg was a primary database that contained Arch, CPU, +SoC, etc. of all the supported boards. It was deleted when switching to +Kconfig. Each field of boards.cfg was converted as follows: + +=========== ==================================================== +From To +=========== ==================================================== +Arch CONFIG_SYS_ARCH defined by Kconfig +Board CONFIG_SYS_BOARD defined by Kconfig +CPU CONFIG_SYS_CPU defined by Kconfig +Maintainers "M:" entry of MAINTAINERS +SoC CONFIG_SYS_SOC defined by Kconfig +Status "S:" entry of MAINTAINERS +Target File name of defconfig (configs/<target>\_defconfig) +Vendor CONFIG_SYS_VENDOR defined by Kconfig +=========== ==================================================== + +Tips to add/remove boards +------------------------- + +When adding a new board, the following steps are generally needed: + +1. Add a header file include/configs/<target>.h + +2. Make sure to define necessary CONFIG_SYS_* in Kconfig: + + * Define CONFIG_SYS_CPU="cpu" to compile arch/<arch>/cpu/<cpu> + * Define CONFIG_SYS_SOC="soc" to compile arch/<arch>/cpu/<cpu>/<soc> + * Define CONFIG_SYS_VENDOR="vendor" to compile board/<vendor>/common/\* + and board/<vendor>/<board>/\* + * Define CONFIG_SYS_BOARD="board" to compile board/<board>/\* + (or board/<vendor>/<board>/* if CONFIG_SYS_VENDOR is defined) + Define CONFIG_SYS_CONFIG_NAME="target" to include + include/configs/<target>.h + +3. Add a new entry to the board select menu in Kconfig. + The board select menu is located in arch/<arch>/Kconfig or + arch/<arch>/\*/Kconfig. + +4. Add a MAINTAINERS file + It is generally placed at board/<board>/MAINTAINERS or + board/<vendor>/<board>/MAINTAINERS + +5. Add configs/<target>_defconfig + +When removing an obsolete board, the following steps are generally needed: + +1. Remove configs/<target>_defconfig + +2. Remove include/configs/<target>.h if it is not used by any other boards + +3. Remove board/<vendor>/<board>/\* or board/<board>/\* if it is not used + by any other boards + +4. Update MAINTAINERS if necessary + +5. Remove the unused entry from the board select menu in Kconfig + +6. Add an entry to doc/README.scrapyard + +TODO +---- + +* In the pre-Kconfig, a single board had multiple entries in the boards.cfg + file with differences in the option fields. The corresponding defconfig + files were auto-generated when switching to Kconfig. Now we have too many + defconfig files compared with the number of the supported boards. It is + recommended to have only one defconfig per board and allow users to select + the config options. + +* Move the config macros in header files to Kconfig. When we move at least + macros used in makefiles, we can drop include/autoconfig.mk, which makes + the build scripts much simpler. diff --git a/doc/develop/release_cycle.rst b/doc/develop/release_cycle.rst index 1548d2634ff..c742c2f8e20 100644 --- a/doc/develop/release_cycle.rst +++ b/doc/develop/release_cycle.rst @@ -71,7 +71,7 @@ For the next scheduled release, release candidates were made on:: * U-Boot v2025.01-rc2 was released on Mon 11 November 2024. -.. * U-Boot v2025.01-rc3 was released on Mon 25 November 2024. +* U-Boot v2025.01-rc3 was released on Mon 25 November 2024. .. * U-Boot v2025.01-rc4 was released on Mon 09 December 2024. diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index 0760ca91d4f..48d6110b2ad 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -681,8 +681,8 @@ UEFI variables. Booting according to these variables is possible via:: As of U-Boot v2020.10 UEFI variables cannot be set at runtime. The U-Boot command 'efidebug' can be used to set the variables. -UEFI HTTP Boot -~~~~~~~~~~~~~~ +UEFI HTTP Boot using the legacy TCP stack +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ HTTP Boot provides the capability for system deployment and configuration over the network. HTTP Boot can be activated by specifying:: @@ -715,6 +715,47 @@ We need to preset the "httpserverip" environment variable to proceed the wget:: setenv httpserverip 192.168.1.1 +UEFI HTTP(s) Boot using lwIP +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Similar to the above U-Boot can do EFI HTTP boot using lwIP. If we combine this +with Mbed TLS we can also download from https:// + +HTTP(s) Boot can be activated by specifying:: + + CONFIG_EFI_HTTP_BOOT + CONFIG_NET_LWIP + CONFIG_WGET_HTTPS + +For QEMU targets there's a Kconfig that supports this by default:: + + make qemu_arm64_lwip_defconfig + +The commands and functionality are similar to the legacy stack, with the notable +exception of not having to define an "httpserverip" if you are trying to resolve +an IP. However, lwIP code doesn't yet support redirects:: + + => efidebug boot add -u 1 netinst https://cdimage.debian.org/cdimage/weekly-builds/arm64/iso-cd/debian-testing-arm64-netinst.iso + => dhcp + DHCP client bound to address 10.0.2.15 (3 ms) + => efidebug boot order 1 + => bootefi bootmgr + + HTTP server error 302 + Loading Boot0001 'netinst' failed + EFI boot manager: Cannot load any image + +If the url you specified isn't a redirect:: + + => efidebug boot add -u 1 netinst https://download.rockylinux.org/pub/rocky/9/isos/aarch64/Rocky-9.4-aarch64-minimal.iso + => dhcp + => bootefi bootmgr + ####################################### + +If the downloaded file extension is .iso or .img file, efibootmgr tries to +mount the image and boot with the default file(e.g. EFI/BOOT/BOOTAA64.EFI). +If the downloaded file is PE-COFF image, load the downloaded file and +start it. + Executing the built in hello world application ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |