[RFC PATCH 9/9] upl: Add initial documentation

[Heinrich Schuchardt]

Am 31. August 2023 01:29:23 MESZ schrieb Simon Glass <sjg at chromium.org>:
>Add some placeholder documentation to explain the basic concept. Once the
>spec is published, more can be added and this series applied.
>
>Signed-off-by: Simon Glass <sjg at chromium.org>
>---
>
> doc/usage/index.rst |  1 +
> doc/usage/upl.rst   | 27 +++++++++++++++++++++++++++
> 2 files changed, 28 insertions(+)
> create mode 100644 doc/usage/upl.rst
>
>diff --git a/doc/usage/index.rst b/doc/usage/index.rst
>index ed896dfb3a0..78665fd5759 100644
>--- a/doc/usage/index.rst
>+++ b/doc/usage/index.rst
>@@ -13,6 +13,7 @@ Use U-Boot
>    partitions
>    cmdline
>    semihosting
>+   upl
> 
> Shell commands
> --------------
>diff --git a/doc/usage/upl.rst b/doc/usage/upl.rst
>new file mode 100644
>index 00000000000..2ae4d4a1178
>--- /dev/null
>+++ b/doc/usage/upl.rst
>@@ -0,0 +1,27 @@
>+Universal Payload
>+~~~~~~~~~~~~~~~~~
>+
>+Universal Payload (UPL) is an upcoming 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.

Please, provide a link to the specification.

>+
>+UPL is defined in termns of two firmware components:

terms


>+
>+`Platform Init`
>+	Perhaps initial setup of the hardware and jumps to the payload.

%s/Perhaps/Possible/

>+
>+`Payload`
>+	Selects the OS to boot

IIRC the UPL payload typically is not the OS but other firmware or a boot loader.

Best regards

Heinrich

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