smallsolar/u-boot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: Add devicetree bindings for options

Browse Source 
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@chromium.org>
This commit is contained in:
Simon Glass
2024-11-02 18:33:17 -06:00
parent 5f10f9427e
commit c68ddff0c0
2 changed files with 215 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
doc/device-tree-bindings/options.yaml Normal file
View File

@@ -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@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

136
doc/device-tree-bindings/options/u-boot.yaml Normal file
View File

@@ -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@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>;
};
};