Add some documentation to explain the basic concept along with a link to the full spec.
Signed-off-by: Simon Glass sjg@chromium.org ---
(no changes since v2)
Changes in v2: - Add a link to the command - Add a link to the spec
MAINTAINERS | 1 + doc/usage/cmd/upl.rst | 4 ++-- doc/usage/index.rst | 1 + doc/usage/upl.rst | 46 +++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 50 insertions(+), 2 deletions(-) create mode 100644 doc/usage/upl.rst
diff --git a/MAINTAINERS b/MAINTAINERS index 43d430c603a..215ffd02b45 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1716,6 +1716,7 @@ T: git https://source.denx.de/u-boot/custodians/u-boot-dm.git F: boot/upl* F: cmd/upl.c F: common/spl/spl_upl.c +F: doc/usage/upl.rst F: doc/usage/cmd/upl.rst F: include/upl.h F: test/boot/upl.c diff --git a/doc/usage/cmd/upl.rst b/doc/usage/cmd/upl.rst index a64063d42d5..8d6ea5daa37 100644 --- a/doc/usage/cmd/upl.rst +++ b/doc/usage/cmd/upl.rst @@ -16,8 +16,8 @@ Description -----------
The *upl* command is used to test U-Boot's support for the Universal Payload -Specification (UPL) firmware standard. It allows creation of a fake handoff for -use in testing. +Specification (UPL) firmware standard (see :doc:`../upl`). It allows creation of +a fake handoff for use in testing.
upl write diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 4246c06d97d..b058c2254fb 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -15,6 +15,7 @@ Use U-Boot cmdline semihosting measured_boot + upl
Shell commands -------------- diff --git a/doc/usage/upl.rst b/doc/usage/upl.rst new file mode 100644 index 00000000000..3c4a10c862c --- /dev/null +++ b/doc/usage/upl.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Universal Payload +----------------- + +`Universal Payload (UPL) https://universalpayload.github.io/spec/index.html`_ +is an Industry Standard for firmware components. UPL +is designed to improve interoperability within the firmware industry, allowing +mixing and matching of projects with less friction and fewer project-specific +implementations. UPL is cross-platform, supporting ARM, x86 and RISC-V +initially. + +UPL is defined in termns of two firmware components: + +`Platform Init` + Perhaps initial setup of the hardware and jumps to the payload. + +`Payload` + Selects the OS to boot + +In practice UPL can be used to handle any number of handoffs through the +firmware startup process, with one program acting as platform init and another +acting as the payload. + +UPL provides a standard for three main pieces: + +- file format for the payload, which may comprise multiple images to load +- handoff format for the information the payload needs, such as serial port, + memory layout, etc. +- machine state and register settings at the point of handoff + +See also the :doc:`cmd/upl`. + +UPL in U-Boot +~~~~~~~~~~~~~ + +U-Boot supports: + +- writing a UPL handoff (devicetree) in SPL +- reading a UPL handoff in U-Boot proper +- creating a FIT + +There are some new FIT features in UPL which are not yet supported in U-Boot. + +.. sectionauthor:: Simon Glass sjg@chromium.org +.. July 2024