From 3a1a3d549b8f9e795af2066625d91a03c21ae322 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 7 Aug 2024 16:47:36 -0600 Subject: [PATCH] upl: Add initial documentation Add some documentation to explain the basic concept along with a link to the full spec. Signed-off-by: Simon Glass --- 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 43d430c603..215ffd02b4 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 a64063d42d..8d6ea5daa3 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 4246c06d97..b058c2254f 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 0000000000..3c4a10c862 --- /dev/null +++ b/doc/usage/upl.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Universal Payload +----------------- + +`Universal Payload (UPL) `_ +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 +.. July 2024 -- 2.39.5