Hi Bin,
On Sat, 28 Aug 2021 at 07:15, Bin Meng bmeng.cn@gmail.com wrote:
Hi Simon,
On Sat, Aug 28, 2021 at 11:23 AM Simon Glass sjg@chromium.org wrote:
At present some of the ideas and techniques behind devicetree in U-Boot are assumed, implied or unsaid. Add some documentation to cover how devicetree is build, how it can be modified and the rules about using the various CONFIG_OF_... options.
Signed-off-by: Simon Glass sjg@chromium.org
doc/develop/index.rst | 1 + doc/develop/package/devicetree.rst | 315 +++++++++++++++++++++++++++++ doc/develop/package/index.rst | 1 + 3 files changed, 317 insertions(+) create mode 100644 doc/develop/package/devicetree.rst
diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 83c929babda..d5ad8f9fe53 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -36,6 +36,7 @@ Packaging :maxdepth: 1
package/index
- package/devicetree
Testing
diff --git a/doc/develop/package/devicetree.rst b/doc/develop/package/devicetree.rst new file mode 100644 index 00000000000..fccbb182f3e --- /dev/null +++ b/doc/develop/package/devicetree.rst @@ -0,0 +1,315 @@ +.. SPDX-License-Identifier: GPL-2.0+
+Updating the devicetree +=======================
+U-Boot uses devicetree for runtime configuration and storing required blobs or +any other information it needs to operate. It is possible to update the +devicetree separately from actually building U-Boot. This provides a good degree +of control and flexibility for firmware that uses U-Boot in conjunction with +other project.
+There are many reasons why it is useful to modify the devicetree after building +it:
+- Configuration can be changed, e.g. which UART to use +- A serial number can be added +- Public keys can be added to allow image verification +- Console output can be changed (e.g. to select serial or vidconsole)
+This section describes how to work with devicetree to accomplish your goals.
+See also :doc:`../devicetree/control` for a basic summary of the available +features.
+Devicetree source +-----------------
+Every board in U-Boot must include a devicetree sufficient to build and boot +that board on suitable hardware (or emulation). This is specified using the +`CONFIG DEFAULT_DEVICE_TREE` option.
+Current situation (August 2021) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+As an aside, at present U-Boot allows `CONFIG_DEFAULT_DEVICE_TREE` to be empty, +e.g. if `CONFIG_OF_BOARD` or `CONFIG_OF_PRIOR_STAGE` are used. This has +unfortunately created an enormous amount of confusion and some wasted effort. +This was not intended and this bug will be fixed soon. Specifically:
+- `CONFIG_OF_BOARD` was added in rpi_patch_ for Raspberry Pi, which does have
- an in-tree devicetree, but this feature has since been used for boards that
- don't
+- `CONFIG_OF_PRIOR_STAGE` was added in bcm_patch_ as part of a larger Broadcom
- change with a tag indicating it only affected one board, so the change in
- behaviour was not noticed at the time. It has since been used by RISC-V qemu
- boards.
+Once this bug is fixed, CONFIG_OF_BOARD and CONFIG_OF_PRIOR_STAGE will override +(at runtime) the devicetree suppled with U-Boot, but will otherwise use +CONFIG_OF_SEPARATE for the in-tree build. So these two will become options, +moving out of the 'choice' in `dts/Kconfig`
+Offending boards are:
+- bcm7260 +- bcm7445 +- qemu_arm64 +- qemu_arm +- qemu-ppce500 +- qemu-riscv32 +- qemu-riscv32_smode +- qemu-riscv64 +- qemu-riscv64_smode
+All of these need to have a devicetree added in-tree. This is targeted to be +fixed in the 2022.01 release.
Do you have some idea of how to support the QEMU case, if not using CONFIG_OF_PRIOR_STAGE?
To be clear, I am not planning to remove this option. It will still work.
But I do want to have an in-tree devicetree for all boards, and someone will need to update qemu to support adding U-Boot nodes/properties. It always has an array of options controlling what it presents to BIOS/UEFI, for example, so this should not be too controversial.
Regards, Simon