diff options
Diffstat (limited to 'doc/develop')
| -rw-r--r-- | doc/develop/bootstd.rst | 4 | ||||
| -rw-r--r-- | doc/develop/devicetree/control.rst | 169 | ||||
| -rw-r--r-- | doc/develop/distro.rst | 6 |
3 files changed, 130 insertions, 49 deletions
diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd.rst index 496e24bc7a6..a07a72581e7 100644 --- a/doc/develop/bootstd.rst +++ b/doc/develop/bootstd.rst @@ -531,6 +531,10 @@ Then the iterator is set up to according to the parameters given: `BOOTFLOWIF_SINGLE_MEDIA` is set. In this case, moving to the next bootdev processes just the children of the media device. Hunters are used, in this example just the "mmc" hunter. + - If `label` indicates a particular partition in a particular media device + (e.g. "mmc1:3") then `BOOTFLOWIF_SINGLE_PARTITION` is set. In this case, + only a single partition within a bootdev is processed. Hunters are used, in + this example just the "mmc" hunter. - If `label` indicates a media uclass (e.g. "mmc") then `BOOTFLOWIF_SINGLE_UCLASS` is set. In this case, all bootdevs in that uclass are used. Hunters are used, in this example just the "mmc" hunter diff --git a/doc/develop/devicetree/control.rst b/doc/develop/devicetree/control.rst index 11c92d440f4..4cc1457d4ea 100644 --- a/doc/develop/devicetree/control.rst +++ b/doc/develop/devicetree/control.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0+ .. sectionauthor:: Copyright 2011 The Chromium OS Authors +.. Copyright 2023-2024 Linaro Ltd. Devicetree Control in U-Boot ============================ @@ -22,24 +23,23 @@ for three reasons: hierarchical format - It is fairly efficient to read incrementally -The arch/<arch>/dts directories contains a Makefile for building the devicetree -blob and embedding it in the U-Boot image. This is useful since it allows -U-Boot to configure itself according to what it finds there. If you have -a number of similar boards with different peripherals, you can describe -the features of each board in the devicetree file, and have a single -generic source base. +The U-Boot Makefile infrastructure allows for building the devicetree blob +and embedding it in the U-Boot image. This is useful since it allows U-Boot +to configure itself according to what it finds there. If you have a number +of similar boards with different peripherals, you can describe the features +of each board in the devicetree file, and have a single generic source base. -To enable this feature, add CONFIG_OF_CONTROL to your board config file. +To enable this feature, select `OF_CONTROL` via Kconfig. What is a Flattened Devicetree? ------------------------------- An fdt can be specified in source format as a text file. To read about -the fdt syntax, take a look at the specification (dtspec_). +the fdt syntax, take a look at `the devicetree specification`_. -There is also a mailing list (dtlist_) for the compiler and associated -tools. +There is also a `devicetree compiler mailing list`_ for the compiler and +associated tools. In case you are wondering, OF stands for Open Firmware. This follows the convention used in Linux. @@ -68,8 +68,16 @@ a binary file. U-Boot adds its own `fdtgrep` for creating subsets of the file. Where do I get a devicetree file for my board? ---------------------------------------------- -You may find that the Linux kernel has a suitable file. Look in the -kernel source in arch/<arch>/boot/dts. +The devicetree files and devicetree bindings are maintained as part of the Linux +kernel git repository. Traditionally, U-Boot placed copies of devicetree source +files from the Linux kernel into `arch/<arch>/dts/<name>.dts`. However, this +required each board maintainer to manually keep their devicetree in sync with +the Linux kernel and often led to divergence between these copies. + +U-Boot rather maintains a Git subtree as `dts/upstream/` sub-directory. It is +regularly synced with the Linux kernel and hence no need for manual devicetree +sync. You may find that the `dts/upstream/` already has a suitable devicetree +file for your board. Look in `dts/upstream/src/<arch>/<vendor>`. If not you might find other boards with suitable files that you can modify to your needs. Look in the board directories for files with a @@ -78,40 +86,58 @@ modify to your needs. Look in the board directories for files with a Failing that, you could write one from scratch yourself! -Configuration -------------- +Resyncing with devicetree-rebasing +---------------------------------- + +The `devicetree-rebasing repository`_ maintains a fork cum mirror copy of +devicetree files along with the bindings synced at every Linux kernel major +release or intermediate release candidates. The U-Boot maintainers regularly +sync the `dts/upstream/` subtree from the devicetree-rebasing repo whenever +the next branch opens (refer: :doc:`../release_cycle`) with the latest mainline +Linux kernel release. To sync the `dts/upstream/` subtree, run:: + + ./dts/update-dts-subtree.sh pull <devicetree-rebasing-release-tag> + +If required it is also possible to cherry-pick fixes from the +devicetree-rebasing repository prior to next sync, usage:: -Use:: + ./dts/update-dts-subtree.sh pick <devicetree-rebasing-commit-id> - #define CONFIG_DEFAULT_DEVICE_TREE "<name>" -to set the filename of the devicetree source. Then put your devicetree -file into:: +Configuration +------------- + +SoC/board maintainers are encouraged to migrate to use synced copies from +`dts/upstream/src/<arch>/<vendor>`. To do that add `imply OF_UPSTREAM` for the +SoC being used via Kconfig and set `DEFAULT_DEVICE_TREE=<vendor>/<name>` when +prompted by Kconfig. - arch/<arch>/dts/<name>.dts +However, if `dts/upstream/` hasn't yet received devicetree source file for your +newly added board support then you can add corresponding devicetree source file +as `arch/<arch>/dts/<name>.dts`. To select that add `# CONFIG_OF_UPSTREAM is not +set` and set `DEFAULT_DEVICE_TREE=<name>` when prompted by Kconfig. -This should include your CPU or SOC's devicetree file, placed in -`arch/<arch>/dts`, and then make any adjustments required using a u-boot-dtsi -file for your board. +This should include your CPU or SoC's devicetree file. On top of that any U-Boot +specific tweaks (see: :ref:`dttweaks`) can be made for your board. -If CONFIG_OF_EMBED is defined, then it will be picked up and built into +If `OF_EMBED` is selected by Kconfig, then it will be picked up and built into the U-Boot image (including u-boot.bin). This is suitable for debugging and development only and is not recommended for production devices. -If CONFIG_OF_SEPARATE is defined, then it will be built and placed in +If `OF_SEPARATE` is selected by Kconfig, then it will be built and placed in a u-boot.dtb file alongside u-boot-nodtb.bin with the combined result placed -in u-boot.bin so you can still just flash u-boot.bin onto your board. If you are -using CONFIG_SPL_FRAMEWORK, then u-boot.img will be built to include the device -tree binary. +in u-boot.bin so you can still just flash u-boot.bin onto your board. If Kconfig +option `SPL_FRAMEWORK` is enabled, then u-boot.img will be built to include the +device tree binary. -If CONFIG_OF_BOARD is defined, a board-specific routine will provide the +If `OF_BOARD` is selected by Kconfig, a board-specific routine will provide the devicetree at runtime, for example if an earlier bootloader stage creates it and passes it to U-Boot. -If CONFIG_BLOBLIST is defined, the devicetree may come from a bloblist passed -from a previous stage, if present. +If `BLOBLIST` is selected by Kconfig, the devicetree may come from a bloblist +passed from a previous stage, if present. -If CONFIG_SANDBOX is defined, then it will be read from a file on +If `SANDBOX` is selected by Kconfig, then it will be read from a file on startup. Use the -d flag to U-Boot to specify the file to read, -D for the default and -T for the test devicetree, used to run sandbox unit tests. @@ -145,7 +171,7 @@ Build: After the board configuration is done, fdt supported u-boot can be built in two ways: -# build the default dts which is defined from CONFIG_DEFAULT_DEVICE_TREE:: +# build the default dts which is selected by DEFAULT_DEVICE_TREE Kconfig:: $ make @@ -159,8 +185,9 @@ ways: Adding tweaks for U-Boot ------------------------ -It is strongly recommended that devicetree files in U-Boot are an exact copy of -those in Linux, so that it is easy to sync them up from time to time. +With `dts/upstream` Git subtree, it is ensured that devicetree files in U-Boot +are an exact copy of those in Linux kernel available under +`dts/upstream/src/<arch>/<vendor>`. U-Boot is of course a very different project from Linux, e.g. it operates under much more restrictive memory and code-size constraints. Where Linux may use a @@ -173,8 +200,8 @@ constraints are even more extreme and the devicetree is shrunk to remove unwanted nodes, or even turned into C code to avoid access overhead. U-Boot automatically looks for and includes a file with updates to the standard -devicetree for your board, searching for them in the same directory as the -main file, in this order:: +devicetree for your board, searching for them in `arch/<arch>/dts/` in this +order:: <orig_filename>-u-boot.dtsi <CONFIG_SYS_SOC>-u-boot.dtsi @@ -198,11 +225,53 @@ As mentioned above, the U-Boot build system automatically includes a `*-u-boot.dtsi` file, if found, containing U-Boot specific quirks. However, some data, such as the mentioned public keys, are not appropriate for upstream U-Boot but are better kept and maintained -outside the U-Boot repository. You can use CONFIG_DEVICE_TREE_INCLUDES -to specify a list of .dtsi files that will also be included when +outside the U-Boot repository. You can use `DEVICE_TREE_INCLUDES` Kconfig +option to specify a list of .dtsi files that will also be included when building .dtb files. +Devicetree bindings schema checks +--------------------------------- + +With devicetee-rebasing Git subtree, the devicetree bindings are also regularly +synced with Linux kernel as `dts/upstream/Bindings/` sub-directory. This +allows U-Boot to run devicetree bindings schema checks which will bring +compliance to U-Boot core/drivers regarding usage of devicetree. + +Dependencies +~~~~~~~~~~~~ + +The DT schema project must be installed in order to validate the DT schema +binding documents and validate DTS files using the DT schema. For installation +instructions, refer to the `DT schema project page`_. + +Several executables (dt-doc-validate, dt-mk-schema, dt-validate) will be +installed. Ensure they are in your PATH (~/.local/bin by default). + +You should also install yamllint (used by dtschema when present). On Debian/ +Ubuntu systems:: + + apt install yamllint + +Running checks +~~~~~~~~~~~~~~ + +In order to perform validation of DTB files, use the ``dtbs_check`` target:: + + make dtbs_check + +It is also possible to run checks with a subset of matching schema files by +setting the ``DT_SCHEMA_FILES`` variable to 1 or more specific schema files or +patterns (partial match of a fixed string). Each file or pattern should be +separated by ':'. + +:: + + make dtbs_check DT_SCHEMA_FILES=trivial-devices.yaml:rtc.yaml + make dtbs_check DT_SCHEMA_FILES=/gpio/ + make dtbs_check DT_SCHEMA_FILES=trivial-devices.yaml + + Relocation, SPL and TPL ----------------------- @@ -213,14 +282,14 @@ The full devicetree is available to U-Boot proper, but normally only a subset 'SPL Support' in doc/driver-model/design.rst for more details. -Using several DTBs in the SPL (CONFIG_SPL_MULTI_DTB) ----------------------------------------------------- +Using several DTBs in the SPL (SPL_MULTI_DTB_FIT Kconfig option) +---------------------------------------------------------------- In some rare cases it is desirable to let SPL be able to select one DTB among many. This usually not very useful as the DTB for the SPL is small and usually fits several platforms. However the DTB sometimes include information that do work on several platforms (like IO tuning parameters). -In this case it is possible to use CONFIG_SPL_MULTI_DTB. This option appends to -the SPL a FIT image containing several DTBs listed in SPL_OF_LIST. +In this case it is possible to use SPL_MULTI_DTB_FIT Kconfig option. This option +appends to the SPL a FIT image containing several DTBs listed in SPL_OF_LIST. board_fit_config_name_match() is called to select the right DTB. If board_fit_config_name_match() relies on DM (DM driver to access an EEPROM @@ -247,10 +316,10 @@ architectures. It is important to understand that the fdt only selects options available in the platform / drivers. It cannot add new drivers (yet). So -you must still have the CONFIG option to enable the driver. For example, -you need to define CONFIG_SYS_NS16550 to bring in the NS16550 driver, +you must still have the Kconfig option to enable the driver. For example, +you need to enable SYS_NS16550 Kconfig option to bring in the NS16550 driver, but can use the fdt to specific the UART clock, peripheral address, etc. -In very broad terms, the CONFIG options in general control *what* driver +In very broad terms, the Kconfig options in general control *what* driver files are pulled in, and the fdt controls *how* those files work. History @@ -264,8 +333,10 @@ used it before Linux (e.g. snow). The two projects developed in parallel and there are still some differences in the bindings for certain boards. While there has been discussion of having a separate repository for devicetree files, in practice the Linux kernel Git repository has become the place where -these are stored, with U-Boot taking copies and adding tweaks with u-boot.dtsi -files. +these are stored, with U-Boot taking copies via +`devicetree-rebasing repository`_ and adding tweaks with u-boot.dtsi files. -.. _dtspec: https://www.devicetree.org/specifications/ -.. _dtlist: https://www.spinics.net/lists/devicetree-compiler/ +.. _the devicetree specification: https://www.devicetree.org/specifications/ +.. _devicetree compiler mailing list: https://www.spinics.net/lists/devicetree-compiler/ +.. _devicetree-rebasing repository: https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git +.. _DT schema project page: https://github.com/devicetree-org/dt-schema/tree/main diff --git a/doc/develop/distro.rst b/doc/develop/distro.rst index 8016acad098..9e715b23ebb 100644 --- a/doc/develop/distro.rst +++ b/doc/develop/distro.rst @@ -81,6 +81,12 @@ as specified at `Boot Loader Specification`_: * Does not document the fdtdir option, which automatically selects the DTB to pass to the kernel. +* If no fdt/fdtdir is provided, the U-Boot will pass its own currently used + device tree. + +* If ``-`` is passed as fdt argument and ``CONFIG_SUPPORT_PASSING_ATAGS`` is + enabled, then no device tree will be used (legacy booting / pre-dtb kernel). + See also doc/README.pxe under 'pxe file format'. One example extlinux.conf generated by the Fedora installer is:: |