[PATCH v3 25/25] doc: Add devicetree bindings for options
Simon Glass
sjg at chromium.org
Sun Nov 3 01:33:17 CET 2024
Some of U-Boot's options have made it upstream, so bring in the binding
file.
This is taken from dt-schema commit c9b4797
Signed-off-by: Simon Glass <sjg at chromium.org>
---
(no changes since v2)
Changes in v2:
- Enable LED on the 5 affected platforms
- Reorder patches for bisectability
- Add dt-schema bindings for LED
doc/device-tree-bindings/options.yaml | 79 +++++++++++
doc/device-tree-bindings/options/u-boot.yaml | 136 +++++++++++++++++++
2 files changed, 215 insertions(+)
create mode 100644 doc/device-tree-bindings/options.yaml
create mode 100644 doc/device-tree-bindings/options/u-boot.yaml
diff --git a/doc/device-tree-bindings/options.yaml b/doc/device-tree-bindings/options.yaml
new file mode 100644
index 00000000000..d6f5bbb00db
--- /dev/null
+++ b/doc/device-tree-bindings/options.yaml
@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-clause
+# Copyright 2021 Google LLC
+#
+
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/options.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: /options Node
+
+maintainers:
+ - Simon Glass <sjg at chromium.org>
+
+description: |
+ The '/options' node does not represent a real device, but serves as a place
+ for passing data into and between firmware components, such as memory
+ mappings. Data in the '/options' node does not represent the hardware. It is
+ ignored by operating systems.
+
+ Properties in this node should be common to (and used by) at least two
+ firmware projects, such as U-Boot and TF-A. Project-specific subnodes can be
+ used for properties which are specific to a single project.
+
+ This is based on the precedent set by IEEE 1275-1994 IEEE Standard for Boot
+ (Initialization Configuration) Firmware: Core Requirements and Practices
+ at https://www.openfirmware.info/data/docs/of1275.pdf
+
+ Purpose of '/options' node
+ --------------------------
+
+ A common problem with firmware is that many builds are needed to deal with the
+ slight variations between different, related models of the same hardware. For
+ example, one model may have a TPM and another may not. Devicetree provides an
+ excellent solution to this problem, in that the devicetree to actually use on
+ a platform can be injected in the factory based on which model is being
+ manufactured at the time.
+
+ A related problem causing build proliferation is dealing with the differences
+ between development firmware, developer-friendly firmware (e.g. with all
+ security features present but with the ability to access the command line),
+ test firmware (which runs tests used in the factory), final production
+ firmware (before signing), signed firmware (where the signatures have been
+ inserted) and the like. Ideally all or most of these should use the same
+ firmware build, with just some options to determine the features available.
+ For example, being able to control whether the UART console or JTAG are
+ available, on any image, is a great debugging aid.
+
+ When the firmware consists of multiple parts (various U-Boot phases, TF-A,
+ OP-TEE), it is helpful that all operate the same way at runtime, regardless of
+ how they were built. This can be achieved by passing the runtime configuration
+ (e.g. 'enable UART console', 'here are your public keys') along the chain
+ through each firmware stage. It is frustrating to have to replicate a bug on
+ production firmware which does not happen on developer firmware, because they
+ are completely different builds.
+
+ The '/options' node provides useful functionality for this. It allows the
+ different controls to be 'factored out' of the firmware binaries, so they can
+ be controlled separately from the initial source-code build. The node can be
+ easily updated by a build or factory tool and can control various features in
+ the firmware binaries. It is similar in concept to a Kconfig option, except
+ that it can be changed after firmware binaries are built.
+
+ The '/options' node is similar in concept to /chosen (see chosen.yaml) except
+ that it is for passing information *into* and *between*) firmware components,
+ instead of from firmware to the operating system. Also, while operating
+ systems typically have a (sometimes extremely long) command line, firmware
+ binaries typically do not support this. The devicetree provides a more
+ structured approach in any case.
+
+properties:
+ $nodename:
+ const: options
+
+ "#address-cells": true
+ "#size-cells": true
+
+additionalProperties:
+ type: object
diff --git a/doc/device-tree-bindings/options/u-boot.yaml b/doc/device-tree-bindings/options/u-boot.yaml
new file mode 100644
index 00000000000..c9894ff5c48
--- /dev/null
+++ b/doc/device-tree-bindings/options/u-boot.yaml
@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+# Copyright 2021 Google LLC
+
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/options/u-boot.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: U-Boot configuration node
+
+maintainers:
+ - Simon Glass <sjg at chromium.org>
+
+description: |
+ The u-boot,config node provides basic configuration information to U-Boot,
+ for use during its execution. It can be used to control U-Boot's behaviour
+ in various ways.
+
+properties:
+ $nodename:
+ const: u-boot
+
+ compatible:
+ const: u-boot,config
+
+ bootcmd:
+ $ref: /schemas/types.yaml#/definitions/string
+ description: |
+ Allows overwriting of the boot command used by U-Boot on startup. If
+ present, U-Boot uses this command instead. Note that this feature can
+ work even if loading the environment is disabled, e.g. for security
+ reasons. See also bootsecure.
+
+ bootdelay-sec:
+ description: |
+ Allows selecting of the U-Boot bootdelay, to control whether U-Boot
+ waits on boot or for how long. This allows this option to be configured
+ by the build system or by a previous-stage binary. For example, if the
+ images is being packed for testing or a user holds down a button, it may
+ allow a delay, but disable it for production.
+
+ If this property is not present, a default value is used instead.
+
+ Note that this uses the 'sec' property unit, even though it allows a
+ negative value.
+
+ Values:
+
+ -1: no bootdelay and the user cannot interrupt boot
+ 0: no bootdelay but use user can still interrupt boot by holding down a
+ key, if enabled
+ >= 1: delay for this many seconds
+
+
+ bootsecure:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 0
+ maximum: 2
+ description: |
+ Controls the execution of the boot command in U-Boot, e.g. selecting
+ between using a special function to run commands, or the normal CLI. This
+ can be used in production images, to restrict the amount of parsing done
+ or the options available, to cut back on the available surface for
+ security attacks.
+
+ Values:
+
+ 0: normal boot using CLI (default if not present)
+ 1: use secure boot mechanism instead to parse and run commands
+ other values are reserved for future use
+ 2: use simplified command line (e.g. avoid hush)
+ 3... reserved
+
+ bootscr-address:
+ $ref: /schemas/types.yaml#/definitions/uint64
+ default: 0x0
+ description:
+ Holds the full address of the boot script file. It helps in making
+ automated flow easier by fetching the 64bit address directly from DT.
+ Value should be automatically copied to the U-Boot 'scriptaddr' variable.
+ When it is defined, bootscr-ram-offset property should be ignored.
+ Actually only one of them should be present in the DT.
+
+ bootscr-ram-offset:
+ $ref: /schemas/types.yaml#/definitions/uint64
+ default: 0x0
+ description:
+ Holds the boot script file offset from the start of the ram base address.
+ Platforms with run-time RAM-detection algorithms should use this property
+ because it is not clear exactly where the script address should be placed.
+ Using it will provide the option to specify boot script offset from
+ detected RAM start. The U-Boot 'scriptaddr' variable should be composed as
+ detected RAM start plus value of bootscr-ram-offset property.
+ It should be used only when bootscr-address is not defined.
+
+ silent-console:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ default: 0
+ maximum: 2
+ description: |
+ This allows the console to be silenced by default on boot. This can allow
+ easy disabling of console output on a production build, for example. When
+ suppressed, the console is still active. This feature only suppresses the
+ console output itself, on all output devices.
+
+ Values:
+
+ 0: console output appears as normal (default)
+ 1: console output is suppressed but console recording still operates (if
+ enabled)
+ 2: console output is suppressed and not recorded
+
+required:
+ - compatible
+
+if:
+ required:
+ - bootscr-address
+then:
+ properties:
+ bootscr-ram-offset: false
+
+additionalProperties: false
+
+examples:
+ - |
+ options {
+ u-boot {
+ compatible = "u-boot,config";
+ bootcmd = "vboot go auto";
+ bootdelay-sec = <(-1)>;
+ bootsecure = <1>;
+ bootscr-address = /bits/ 64 <0x1000>;
+ silent-console = <1>;
+ };
+ };
--
2.43.0
More information about the U-Boot
mailing list