Merge patch series "Universal Payload initial series"

Simon Glass <[email protected]> says:

Universal Payload (UPL) is an Industry Standard for firmware
components[1]. 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.

This series provides some initial support for this, targeting 0.9.1 and
sandbox only.

Features still to come include:
- Support for architectures
- FIT validation
- Handoff validation
- Interoperability tests

5 files changed, 421 insertions, 3 deletions

diff --git a/include/asm-generic/global_data.h b/include/asm-generic/global_data.h
index 27aa75e7036..19c66e1fe5d 100644
--- a/include/asm-generic/global_data.h
+++ b/include/asm-generic/global_data.h
@@ -30,6 +30,7 @@
 
 struct acpi_ctx;
 struct driver_rt;
+struct upl;
 
 typedef struct global_data gd_t;
 
@@ -491,6 +492,12 @@ struct global_data {
 	 * @dmtag_list: List of DM tags
 	 */
 	struct list_head dmtag_list;
+#if CONFIG_IS_ENABLED(UPL)
+	/**
+	 * @upl: Universal Payload-handoff information
+	 */
+	struct upl *upl;
+#endif
 };
 #ifndef DO_DEPS_ONLY
 static_assert(sizeof(struct global_data) == GD_SIZE);
@@ -590,6 +597,14 @@ static_assert(sizeof(struct global_data) == GD_SIZE);
 #define gd_malloc_ptr()		0L
 #endif
 
+#if CONFIG_IS_ENABLED(UPL)
+#define gd_upl()		gd->upl
+#define gd_set_upl(_val)	gd->upl = (_val)
+#else
+#define gd_upl()		NULL
+#define gd_set_upl(val)
+#endif
+
 /**
  * enum gd_flags - global data flags
  *
@@ -701,6 +716,10 @@ enum gd_flags {
 	 * @GD_FLG_HUSH_MODERN_PARSER: Use hush 2021 parser.
 	 */
 	GD_FLG_HUSH_MODERN_PARSER = 0x2000000,
+	/**
+	 * @GD_FLG_UPL: Read/write a Universal Payload (UPL) handoff
+	 */
+	GD_FLG_UPL = 0x4000000,
 };
 
 #endif /* __ASSEMBLY__ */
diff --git a/include/os.h b/include/os.h
index 877404a6c13..4371270a1ee 100644
--- a/include/os.h
+++ b/include/os.h
@@ -29,7 +29,7 @@ int os_printf(const char *format, ...);
  * @fd:		File descriptor as returned by os_open()
  * @buf:	Buffer to place data
  * @count:	Number of bytes to read
- * Return:	number of bytes read, or -1 on error
+ * Return:	number of bytes read, or -errno on error
  */
 ssize_t os_read(int fd, void *buf, size_t count);
 
@@ -39,7 +39,7 @@ ssize_t os_read(int fd, void *buf, size_t count);
  * @fd:		File descriptor as returned by os_open()
  * @buf:	Buffer containing data to write
  * @count:	Number of bytes to write
- * Return:	number of bytes written, or -1 on error
+ * Return:	number of bytes written, or -errno on error
  */
 ssize_t os_write(int fd, const void *buf, size_t count);
 
@@ -49,7 +49,7 @@ ssize_t os_write(int fd, const void *buf, size_t count);
  * @fd:		File descriptor as returned by os_open()
  * @offset:	File offset (based on whence)
  * @whence:	Position offset is relative to (see below)
- * Return:	new file offset
+ * Return:	new file offset, or -errno on error
  */
 off_t os_lseek(int fd, off_t offset, int whence);
 
diff --git a/include/spl.h b/include/spl.h
index 1eebea3f981..f92089b69ea 100644
--- a/include/spl.h
+++ b/include/spl.h
@@ -1073,4 +1073,20 @@ static inline bool spl_decompression_enabled(void)
 {
 	return IS_ENABLED(CONFIG_SPL_GZIP) || IS_ENABLED(CONFIG_SPL_LZMA);
 }
+
+/**
+ * spl_write_upl_handoff() - Write a Universal Payload hand-off structure
+ *
+ * @spl_image: Information about the image being booted
+ * Return: 0 if OK, -ve on error
+ */
+int spl_write_upl_handoff(struct spl_image_info *spl_image);
+
+/**
+ * spl_upl_init() - Get UPL ready for information to be added
+ *
+ * This must be called before upl_add_image(), etc.
+ */
+void spl_upl_init(void);
+
 #endif
diff --git a/include/test/suites.h b/include/test/suites.h
index 365d5f20dfe..2ceef577f7f 100644
--- a/include/test/suites.h
+++ b/include/test/suites.h
@@ -63,5 +63,6 @@ int do_ut_str(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[]);
 int do_ut_time(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[]);
 int do_ut_unicode(struct cmd_tbl *cmdtp, int flag, int argc,
 		  char *const argv[]);
+int do_ut_upl(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[]);
 
 #endif /* __TEST_SUITES_H__ */
diff --git a/include/upl.h b/include/upl.h
new file mode 100644
index 00000000000..2ec5ef1b5cf
--- /dev/null
+++ b/include/upl.h
@@ -0,0 +1,382 @@
+/* SPDX-License-Identifier: GPL-2.0+ */
+/*
+ * UPL handoff generation
+ *
+ * Copyright 2024 Google LLC
+ * Written by Simon Glass <[email protected]>
+ */
+
+#ifndef __UPL_WRITE_H
+#define __UPL_WRITE_H
+
+#ifndef USE_HOSTCC
+
+#include <alist.h>
+#include <image.h>
+#include <dm/ofnode_decl.h>
+
+struct unit_test_state;
+
+#define UPLP_ADDRESS_CELLS	"#address-cells"
+#define UPLP_SIZE_CELLS		"#size-cells"
+
+#define UPLN_OPTIONS		"options"
+#define UPLN_UPL_PARAMS		"upl-params"
+#define UPLP_SMBIOS		"smbios"
+#define UPLP_ACPI		"acpi"
+#define UPLP_BOOTMODE		"bootmode"
+#define UPLP_ADDR_WIDTH		"addr-width"
+#define UPLP_ACPI_NVS_SIZE	"acpi-nvs-size"
+
+#define UPLPATH_UPL_IMAGE	"/options/upl-image"
+#define UPLN_UPL_IMAGE		"upl-image"
+#define UPLN_IMAGE		"image"
+#define UPLP_FIT		"fit"
+#define UPLP_CONF_OFFSET	"conf-offset"
+#define UPLP_LOAD		"load"
+#define UPLP_SIZE		"size"
+#define UPLP_OFFSET		"offset"
+#define UPLP_DESCRIPTION	"description"
+
+#define UPLN_MEMORY		"memory"
+#define UPLP_HOTPLUGGABLE	"hotpluggable"
+
+#define UPLPATH_MEMORY_MAP	"/memory-map"
+#define UPLN_MEMORY_MAP		"memory-map"
+#define UPLP_USAGE		"usage"
+
+#define UPLN_MEMORY_RESERVED	"reserved-memory"
+#define UPLPATH_MEMORY_RESERVED	"/reserved-memory"
+#define UPLP_NO_MAP		"no-map"
+
+#define UPLN_SERIAL		"serial"
+#define UPLP_REG		"reg"
+#define UPLP_COMPATIBLE		"compatible"
+#define UPLP_CLOCK_FREQUENCY	"clock-frequency"
+#define UPLP_CURRENT_SPEED	"current-speed"
+#define UPLP_REG_IO_SHIFT	"reg-io-shift"
+#define UPLP_REG_OFFSET		"reg-offset"
+#define UPLP_REG_IO_WIDTH	"reg-io-width"
+#define UPLP_VIRTUAL_REG	"virtual-reg"
+#define UPLP_ACCESS_TYPE	"access-type"
+
+#define UPLN_GRAPHICS		"framebuffer"
+#define UPLC_GRAPHICS		"simple-framebuffer"
+#define UPLP_WIDTH		"width"
+#define UPLP_HEIGHT		"height"
+#define UPLP_STRIDE		"stride"
+#define UPLP_GRAPHICS_FORMAT	"format"
+
+/**
+ * enum upl_boot_mode - Encodes the boot mode
+ *
+ * Each is a bit number from the boot_mode mask
+ */
+enum upl_boot_mode {
+	UPLBM_FULL,
+	UPLBM_MINIMAL,
+	UPLBM_FAST,
+	UPLBM_DIAG,
+	UPLBM_DEFAULT,
+	UPLBM_S2,
+	UPLBM_S3,
+	UPLBM_S4,
+	UPLBM_S5,
+	UPLBM_FACTORY,
+	UPLBM_FLASH,
+	UPLBM_RECOVERY,
+
+	UPLBM_COUNT,
+};
+
+/**
+ * struct upl_image - UPL image informaiton
+ *
+ * @load: Address image was loaded to
+ * @size: Size of image in bytes
+ * @offset: Offset of the image in the FIT (0=none)
+ * @desc: Description of the iamge (taken from the FIT)
+ */
+struct upl_image {
+	ulong load;
+	ulong size;
+	uint offset;
+	const char *description;
+};
+
+/**
+ * struct memregion - Information about a region of memory
+ *
+ * @base: Base address
+ * @size: Size in bytes
+ */
+struct memregion {
+	ulong base;
+	ulong size;
+};
+
+/**
+ * struct upl_mem - Information about physical-memory layout
+ *
+ * TODO: Figure out initial-mapped-area
+ *
+ * @region: Memory region list (struct memregion)
+ * @hotpluggable: true if hotpluggable
+ */
+struct upl_mem {
+	struct alist region;
+	bool hotpluggable;
+};
+
+/**
+ * enum upl_usage - Encodes the usage
+ *
+ * Each is a bit number from the usage mask
+ */
+enum upl_usage {
+	UPLUS_ACPI_RECLAIM,
+	UPLUS_ACPI_NVS,
+	UPLUS_BOOT_CODE,
+	UPLUS_BOOT_DATA,
+	UPLUS_RUNTIME_CODE,
+	UPLUS_RUNTIME_DATA,
+	UPLUS_COUNT
+};
+
+/**
+ * struct upl_memmap - Information about logical-memory layout
+ *
+ * @name: Node name to use
+ * @region: Memory region list (struct memregion)
+ * @usage: Memory-usage mask (enum upl_usage)
+ */
+struct upl_memmap {
+	const char *name;
+	struct alist region;
+	uint usage;
+};
+
+/**
+ * struct upl_memres - Reserved memory
+ *
+ * @name: Node name to use
+ * @region: Reserved memory region list (struct memregion)
+ * @no_map: true to indicate that a virtual mapping must not be created
+ */
+struct upl_memres {
+	const char *name;
+	struct alist region;
+	bool no_map;
+};
+
+enum upl_serial_access_type {
+	UPLSAT_MMIO,
+	UPLSAT_IO,
+};
+
+/* serial defaults */
+enum {
+	UPLD_REG_IO_SHIFT	= 0,
+	UPLD_REG_OFFSET		= 0,
+	UPLD_REG_IO_WIDTH	= 1,
+};
+
+/**
+ * enum upl_access_type - Access types
+ *
+ * @UPLAT_MMIO: Memory-mapped I/O
+ * @UPLAT_IO: Separate I/O
+ */
+enum upl_access_type {
+	UPLAT_MMIO,
+	UPLAT_IO,
+};
+
+/**
+ * struct upl_serial - Serial console
+ *
+ * @compatible: Compatible string (NULL if there is no serial console)
+ * @clock_frequency: Input clock frequency of UART
+ * @current_speed: Current baud rate of UART
+ * @reg: List of base address and size of registers (struct memregion)
+ * @reg_shift_log2: log2 of distance between each register
+ * @reg_offset: Offset of registers from the base address
+ * @reg_width: Register width in bytes
+ * @virtual_reg: Virtual register access (0 for none)
+ * @access_type: Register access type to use
+ */
+struct upl_serial {
+	const char *compatible;
+	uint clock_frequency;
+	uint current_speed;
+	struct alist reg;
+	uint reg_io_shift;
+	uint reg_offset;
+	uint reg_io_width;
+	ulong virtual_reg;
+	enum upl_serial_access_type access_type;
+};
+
+/**
+ * enum upl_graphics_format - Graphics formats
+ *
+ * @UPLGF_ARGB32: 32bpp format using 0xaarrggbb
+ * @UPLGF_ABGR32: 32bpp format using 0xaabbggrr
+ * @UPLGF_ARGB64: 64bpp format using 0xaaaabbbbggggrrrr
+ */
+enum upl_graphics_format {
+	UPLGF_ARGB32,
+	UPLGF_ABGR32,
+	UPLGF_ABGR64,
+};
+
+/**
+ * @reg: List of base address and size of registers (struct memregion)
+ * @width: Width of display in pixels
+ * @height: Height of display in pixels
+ * @stride: Number of bytes from one line to the next
+ * @format: Pixel format
+ */
+struct upl_graphics {
+	struct alist reg;
+	uint width;
+	uint height;
+	uint stride;
+	enum upl_graphics_format format;
+};
+
+/*
+ * Information about the UPL state
+ *
+ * @addr_cells: Number of address cells used in the handoff
+ * @size_cells: Number of size cells used in the handoff
+ * @bootmode: Boot-mode mask (enum upl_boot_mode)
+ * @fit: Address of FIT image that was loaded
+ * @conf_offset: Offset in FIT of the configuration that was selected
+ * @addr_width: Adress-bus width of machine, e.g. 46 for 46 bits
+ * @acpi_nvs_size: Size of the ACPI non-volatile-storage area in bytes
+ * @image: Information about each image (struct upl_image)
+ * @mem: Information about physical-memory regions (struct upl_mem)
+ * @nennap: Information about logical-memory regions (struct upl_memmap)
+ * @nennap: Information about reserved-memory regions (struct upl_memres)
+ */
+struct upl {
+	int addr_cells;
+	int size_cells;
+
+	ulong smbios;
+	ulong acpi;
+	uint bootmode;
+	ulong fit;
+	uint conf_offset;
+	uint addr_width;
+	uint acpi_nvs_size;
+
+	struct alist image;
+	struct alist mem;
+	struct alist memmap;
+	struct alist memres;
+	struct upl_serial serial;
+	struct upl_graphics graphics;
+};
+
+/**
+ * upl_write_handoff() - Write a Unversal Payload handoff structure
+ *
+ * upl: UPL state to write
+ * @root: root node to write it to
+ * @skip_existing: Avoid recreating any nodes which already exist in the
+ * devicetree. For example, if there is a serial node, just leave it alone,
+ * since don't need to create a new one
+ * Return: 0 on success, -ve on error
+ */
+int upl_write_handoff(const struct upl *upl, ofnode root, bool skip_existing);
+
+/**
+ * upl_create_handoff_tree() - Write a Unversal Payload handoff structure
+ *
+ * upl: UPL state to write
+ * @treep: Returns a new tree containing the handoff
+ * Return: 0 on success, -ve on error
+ */
+int upl_create_handoff_tree(const struct upl *upl, oftree *treep);
+
+/**
+ * upl_read_handoff() - Read a Unversal Payload handoff structure
+ *
+ * upl: UPL state to read into
+ * @tree: Devicetree containing the data to read
+ * Return: 0 on success, -ve on error
+ */
+int upl_read_handoff(struct upl *upl, oftree tree);
+
+/**
+ * upl_get_test_data() - Fill a UPL with some test data
+ *
+ * @uts: Test state (can be uninited)
+ * @upl: Returns test data
+ * Return: 0 on success, 1 on error
+ */
+int upl_get_test_data(struct unit_test_state *uts, struct upl *upl);
+#endif /* USE_HOSTCC */
+
+#if CONFIG_IS_ENABLED(UPL) && defined(CONFIG_SPL_BUILD)
+
+/**
+ * upl_set_fit_info() - Set up basic info about the FIT
+ *
+ * @fit: Address of FIT
+ * @conf_offset: Configuration node being used
+ * @entry_addr: Entry address for next phase
+ */
+void upl_set_fit_info(ulong fit, int conf_offset, ulong entry_addr);
+
+/**
+ * upl_set_fit_addr() - Set up the address of the FIT
+ *
+ * @fit: Address of FIT
+ */
+void upl_set_fit_addr(ulong fit);
+
+#else
+static inline void upl_set_fit_addr(ulong fit) {}
+static inline void upl_set_fit_info(ulong fit, int conf_offset,
+				    ulong entry_addr) {}
+#endif /* UPL && SPL */
+
+/**
+ * _upl_add_image() - Internal function to add a new image to the UPL
+ *
+ * @node: Image node offset in FIT
+ * @load_addr: Address to which images was loaded
+ * @size: Image size in bytes
+ * @desc: Description of image
+ * Return: 0 if OK, -ENOMEM if out of memory
+ */
+int _upl_add_image(int node, ulong load_addr, ulong size, const char *desc);
+
+/**
+ * upl_add_image() - Add a new image to the UPL
+ *
+ * @fit: Pointer to FIT
+ * @node: Image node offset in FIT
+ * @load_addr: Address to which images was loaded
+ * @size: Image size in bytes
+ * Return: 0 if OK, -ENOMEM if out of memory
+ */
+static inline int upl_add_image(const void *fit, int node, ulong load_addr,
+				ulong size)
+{
+	if (CONFIG_IS_ENABLED(UPL) && IS_ENABLED(CONFIG_SPL_BUILD)) {
+		const char *desc = fdt_getprop(fit, node, FIT_DESC_PROP, NULL);
+
+		return _upl_add_image(node, load_addr, size, desc);
+	}
+
+	return 0;
+}
+
+/** upl_init() - Set up a UPL struct */
+void upl_init(struct upl *upl);
+
+#endif /* __UPL_WRITE_H */