[PATCH v4 18/21] upl: Add initial documentation

[Simon Glass]

Add some documentation to explain the basic concept along with a link
to the full spec.

Signed-off-by: Simon Glass <sjg at 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 at chromium.org>
+.. July 2024
-- 
2.34.1