From ff3bd4983c1fe53975e44668619b07e10f8a0cd9 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 12 Jan 2022 19:26:16 -0700 Subject: bloblist: Put the magic number first It seems best to put the magic number right at the start of the bloblist header, so it is easier to check. This is how devicetree works. Make this change now, before other projects make use of bloblist. Other changes may be needed / discussed, but that is TBD. Add a checker function as well. Signed-off-by: Simon Glass --- include/bloblist.h | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) (limited to 'include/bloblist.h') diff --git a/include/bloblist.h b/include/bloblist.h index 9f007c7a94d..29ea5a768a6 100644 --- a/include/bloblist.h +++ b/include/bloblist.h @@ -13,6 +13,8 @@ #ifndef __BLOBLIST_H #define __BLOBLIST_H +#include + enum { BLOBLIST_VERSION = 0, BLOBLIST_MAGIC = 0xb00757a3, @@ -59,11 +61,11 @@ enum bloblist_tag_t { * Each bloblist record is aligned to a 16-byte boundary and follows immediately * from the last. * + * @magic: BLOBLIST_MAGIC * @version: BLOBLIST_VERSION * @hdr_size: Size of this header, normally sizeof(struct bloblist_hdr). The * first bloblist_rec starts at this offset from the start of the header * @flags: Space for BLOBLISTF_... flags (none yet) - * @magic: BLOBLIST_MAGIC * @size: Total size of the bloblist (non-zero if valid) including this header. * The bloblist extends for this many bytes from the start of this header. * When adding new records, the bloblist can grow up to this size. @@ -78,10 +80,10 @@ enum bloblist_tag_t { * calculation. */ struct bloblist_hdr { + u32 magic; u32 version; u32 hdr_size; u32 flags; - u32 magic; u32 size; u32 alloced; @@ -111,6 +113,25 @@ struct bloblist_rec { u32 spare; }; +/** + * bloblist_check_magic() - return a bloblist if the magic matches + * + * @addr: Address to check + * @return pointer to bloblist, if the magic matches, else NULL + */ +static inline void *bloblist_check_magic(ulong addr) +{ + u32 *ptr; + + if (!addr) + return NULL; + ptr = map_sysmem(addr, 0); + if (*ptr != BLOBLIST_MAGIC) + return NULL; + + return ptr; +} + /** * bloblist_find() - Find a blob * -- cgit v1.2.3 From 7f3b79af548264ea2f482eaeffee6b1d716ce274 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 12 Jan 2022 19:26:17 -0700 Subject: bloblist: Rename the SPL tag Add a U_BOOT prefix to this tag since it is specific to the U-Boot project. Signed-off-by: Simon Glass --- include/bloblist.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include/bloblist.h') diff --git a/include/bloblist.h b/include/bloblist.h index 29ea5a768a6..d4d48f76ff4 100644 --- a/include/bloblist.h +++ b/include/bloblist.h @@ -27,7 +27,7 @@ enum bloblist_tag_t { /* Vendor-specific tags are permitted here */ BLOBLISTT_EC_HOSTEVENT, /* Chromium OS EC host-event mask */ - BLOBLISTT_SPL_HANDOFF, /* Hand-off info from SPL */ + BLOBLISTT_U_BOOT_SPL_HANDOFF, /* Hand-off info from SPL */ BLOBLISTT_VBOOT_CTX, /* Chromium OS verified boot context */ BLOBLISTT_VBOOT_HANDOFF, /* Chromium OS internal handoff info */ /* -- cgit v1.2.3 From f9abc1cac1130279b486c51056b2e6fba99633b1 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 12 Jan 2022 19:26:18 -0700 Subject: bloblist: Drop unused tags The EC event log tag is no-longer used. The vboot handoff is now handled by the vboot context instead. Drop these unused tags. Signed-off-by: Simon Glass --- include/bloblist.h | 2 -- 1 file changed, 2 deletions(-) (limited to 'include/bloblist.h') diff --git a/include/bloblist.h b/include/bloblist.h index d4d48f76ff4..fac25907c07 100644 --- a/include/bloblist.h +++ b/include/bloblist.h @@ -26,10 +26,8 @@ enum bloblist_tag_t { BLOBLISTT_NONE = 0, /* Vendor-specific tags are permitted here */ - BLOBLISTT_EC_HOSTEVENT, /* Chromium OS EC host-event mask */ BLOBLISTT_U_BOOT_SPL_HANDOFF, /* Hand-off info from SPL */ BLOBLISTT_VBOOT_CTX, /* Chromium OS verified boot context */ - BLOBLISTT_VBOOT_HANDOFF, /* Chromium OS internal handoff info */ /* * Advanced Configuration and Power Interface Global Non-Volatile * Sleeping table. This forms part of the ACPI tables passed to Linux. -- cgit v1.2.3 From f16ec77784b4a2ffdba82bc4044581131aea44e4 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 12 Jan 2022 19:26:19 -0700 Subject: bloblist: Use explicit numbering for the tags At present if someone adds a tag in the middle of the list it works well enough within a U-Boot build. But if these tags are used in another project, or with an older version of SPL, the numbers make become inconsistent. Use explicit tag numbers that never change, to resolve this problem. Allocate areas for existing U-Boot tags and set up an area for use by projects and vendors, as well as for private use. Keep tags above 0x10000 unallocated for now. Update bloblist_tag_name() and the tests to work with this new setup. Signed-off-by: Simon Glass --- include/bloblist.h | 58 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 47 insertions(+), 11 deletions(-) (limited to 'include/bloblist.h') diff --git a/include/bloblist.h b/include/bloblist.h index fac25907c07..5de4545160e 100644 --- a/include/bloblist.h +++ b/include/bloblist.h @@ -25,21 +25,57 @@ enum { enum bloblist_tag_t { BLOBLISTT_NONE = 0, - /* Vendor-specific tags are permitted here */ - BLOBLISTT_U_BOOT_SPL_HANDOFF, /* Hand-off info from SPL */ - BLOBLISTT_VBOOT_CTX, /* Chromium OS verified boot context */ + /* + * Standard area to allocate blobs used across firmware components, for + * things that are very commonly used, particularly in multiple + * projects. + */ + BLOBLISTT_AREA_FIRMWARE_TOP = 0x1, + + /* Standard area to allocate blobs used across firmware components */ + BLOBLISTT_AREA_FIRMWARE = 0x100, /* * Advanced Configuration and Power Interface Global Non-Volatile * Sleeping table. This forms part of the ACPI tables passed to Linux. */ - BLOBLISTT_ACPI_GNVS, - BLOBLISTT_INTEL_VBT, /* Intel Video-BIOS table */ - BLOBLISTT_TPM2_TCG_LOG, /* TPM v2 log space */ - BLOBLISTT_TCPA_LOG, /* TPM log space */ - BLOBLISTT_ACPI_TABLES, /* ACPI tables for x86 */ - BLOBLISTT_SMBIOS_TABLES, /* SMBIOS tables for x86 */ - - BLOBLISTT_COUNT + BLOBLISTT_ACPI_GNVS = 0x100, + BLOBLISTT_INTEL_VBT = 0x101, /* Intel Video-BIOS table */ + BLOBLISTT_TPM2_TCG_LOG = 0x102, /* TPM v2 log space */ + BLOBLISTT_TCPA_LOG = 0x103, /* TPM log space */ + BLOBLISTT_ACPI_TABLES = 0x104, /* ACPI tables for x86 */ + BLOBLISTT_SMBIOS_TABLES = 0x105, /* SMBIOS tables for x86 */ + BLOBLISTT_VBOOT_CTX = 0x106, /* Chromium OS verified boot context */ + + /* + * Project-specific tags are permitted here. Projects can be open source + * or not, but the format of the data must be fuily documented in an + * open source project, including all fields, bits, etc. Naming should + * be: BLOBLISTT__ + */ + BLOBLISTT_PROJECT_AREA = 0x8000, + BLOBLISTT_U_BOOT_SPL_HANDOFF = 0x8000, /* Hand-off info from SPL */ + + /* + * Vendor-specific tags are permitted here. Projects can be open source + * or not, but the format of the data must be fuily documented in an + * open source project, including all fields, bits, etc. Naming should + * be BLOBLISTT__ + */ + BLOBLISTT_VENDOR_AREA = 0xc000, + + /* Tags after this are not allocated for now */ + BLOBLISTT_EXPANSION = 0x10000, + + /* + * Tags from here are on reserved for private use within a single + * firmware binary (i.e. a single executable or phase of a project). + * These tags can be passed between binaries within a local + * implementation, but cannot be used in upstream code. Allocate a + * tag in one of the areas above if you want that. + * + * This area may move in future. + */ + BLOBLISTT_PRIVATE_AREA = 0xffff0000, }; /** -- cgit v1.2.3 From 99047f5d7f9cb013f7040edd7d20a70cc30646b5 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 12 Jan 2022 19:26:22 -0700 Subject: bloblist: Refactor Kconfig to support alloc or fixed At present we do support allocating the bloblist but the Kconfig is a bit strange, since we still have to specify an address in that case. Partly this is because it is a pain to have CONFIG options that disappears when its dependency is enabled. It means that we must have #ifdefs in the code, either in the C code or header file. Make use of IF_ENABLED_INT() and its friend to solve that problem, so we can separate out the location of bloblist into a choice. Put the address and size into variables so we can log the result. Add the options for SPL as well, so we can use CONFIG_IS_ENABLED(). Signed-off-by: Simon Glass --- include/bloblist.h | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'include/bloblist.h') diff --git a/include/bloblist.h b/include/bloblist.h index 5de4545160e..13f2b3f1009 100644 --- a/include/bloblist.h +++ b/include/bloblist.h @@ -147,6 +147,16 @@ struct bloblist_rec { u32 spare; }; +/* access CONFIG_BLOBLIST_ADDR, dealing with it possibly not being defined */ +static inline ulong bloblist_addr(void) +{ +#ifdef CONFIG_BLOBLIST_FIXED + return CONFIG_BLOBLIST_ADDR; +#else + return 0; +#endif +} + /** * bloblist_check_magic() - return a bloblist if the magic matches * -- cgit v1.2.3 From e50a24a0456c07d28c0d589e061dd0576f6bb917 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 12 Jan 2022 19:26:23 -0700 Subject: bloblist: Add functions to obtain base address and size Add a few convenience functions to obtain useful information about the bloblist. Signed-off-by: Simon Glass --- include/bloblist.h | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'include/bloblist.h') diff --git a/include/bloblist.h b/include/bloblist.h index 13f2b3f1009..d9e108d8618 100644 --- a/include/bloblist.h +++ b/include/bloblist.h @@ -302,6 +302,20 @@ int bloblist_finish(void); */ void bloblist_get_stats(ulong *basep, ulong *sizep, ulong *allocedp); +/** + * bloblist_get_base() - Get the base address of the bloblist + * + * @returns base address of bloblist + */ +ulong bloblist_get_base(void); + +/** + * bloblist_get_size() - Get the size of the bloblist + * + * @returns the size in bytes + */ +ulong bloblist_get_size(void); + /** * bloblist_show_stats() - Show information about the bloblist * -- cgit v1.2.3 From 20a149353097967cfac3ec1a77eab08215427b0d Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 12 Jan 2022 19:26:24 -0700 Subject: bloblist: doc: Bring in the API documentation FIx up various minor errors and add the API documentation to the bloblist docs, since it is quite useful to see it in the same place. Signed-off-by: Simon Glass --- include/bloblist.h | 79 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 45 insertions(+), 34 deletions(-) (limited to 'include/bloblist.h') diff --git a/include/bloblist.h b/include/bloblist.h index d9e108d8618..798babe9235 100644 --- a/include/bloblist.h +++ b/include/bloblist.h @@ -86,8 +86,8 @@ enum bloblist_tag_t { * same place in memory as SPL and U-Boot execute, but it can be safely moved * around. * - * None of the bloblist structures contain pointers but it is possible to put - * pointers inside a bloblist record if desired. This is not encouraged, + * None of the bloblist headers themselves contain pointers but it is possible + * to put pointers inside a bloblist record if desired. This is not encouraged, * since it can make part of the bloblist inaccessible if the pointer is * no-longer valid. It is better to just store all the data inside a bloblist * record. @@ -99,7 +99,7 @@ enum bloblist_tag_t { * @version: BLOBLIST_VERSION * @hdr_size: Size of this header, normally sizeof(struct bloblist_hdr). The * first bloblist_rec starts at this offset from the start of the header - * @flags: Space for BLOBLISTF_... flags (none yet) + * @flags: Space for BLOBLISTF... flags (none yet) * @size: Total size of the bloblist (non-zero if valid) including this header. * The bloblist extends for this many bytes from the start of this header. * When adding new records, the bloblist can grow up to this size. @@ -110,8 +110,8 @@ enum bloblist_tag_t { * @chksum: CRC32 for the entire bloblist allocated area. Since any of the * blobs can be altered after being created, this checksum is only valid * when the bloblist is finalised before jumping to the next stage of boot. - * Note: @chksum is last to make it easier to exclude it from the checksum - * calculation. + * Note that chksum is last to make it easier to exclude it from the + * checksum calculation. */ struct bloblist_hdr { u32 magic; @@ -128,11 +128,11 @@ struct bloblist_hdr { /** * struct bloblist_rec - record for the bloblist * - * NOTE: Only exported for testing purposes. Do not use this struct. - * * The bloblist contains a number of records each consisting of this record * structure followed by the data contained. Each records is 16-byte aligned. * + * NOTE: Only exported for testing purposes. Do not use this struct. + * * @tag: Tag indicating what the record contains * @hdr_size: Size of this header, normally sizeof(struct bloblist_rec). The * record's data starts at this offset from the start of the record @@ -161,7 +161,7 @@ static inline ulong bloblist_addr(void) * bloblist_check_magic() - return a bloblist if the magic matches * * @addr: Address to check - * @return pointer to bloblist, if the magic matches, else NULL + * Return: pointer to bloblist, if the magic matches, else NULL */ static inline void *bloblist_check_magic(ulong addr) { @@ -183,8 +183,8 @@ static inline void *bloblist_check_magic(ulong addr) * * @tag: Tag to search for (enum bloblist_tag_t) * @size: Expected size of the blob, or 0 for any size - * @return pointer to blob if found, or NULL if not found, or a blob was found - * but it is the wrong size + * Return: pointer to blob if found, or NULL if not found, or a blob was found + * but it is the wrong size */ void *bloblist_find(uint tag, int size); @@ -200,8 +200,8 @@ void *bloblist_find(uint tag, int size); * @tag: Tag to add (enum bloblist_tag_t) * @size: Size of the blob * @align: Alignment of the blob (in bytes), 0 for default - * @return pointer to the newly added block, or NULL if there is not enough - * space for the blob + * Return: pointer to the newly added block, or NULL if there is not enough + * space for the blob */ void *bloblist_add(uint tag, int size, int align); @@ -214,8 +214,8 @@ void *bloblist_add(uint tag, int size, int align); * @size: Size of the blob * @blobp: Returns a pointer to blob on success * @align: Alignment of the blob (in bytes), 0 for default - * @return 0 if OK, -ENOSPC if it is missing and could not be added due to lack - * of space, or -ESPIPE it exists but has the wrong size + * Return: 0 if OK, -ENOSPC if it is missing and could not be added due to lack + * of space, or -ESPIPE it exists but has the wrong size */ int bloblist_ensure_size(uint tag, int size, int align, void **blobp); @@ -226,8 +226,8 @@ int bloblist_ensure_size(uint tag, int size, int align, void **blobp); * * @tag: Tag to add (enum bloblist_tag_t) * @size: Size of the blob - * @return pointer to blob, or NULL if it is missing and could not be added due - * to lack of space, or it exists but has the wrong size + * Return: pointer to blob, or NULL if it is missing and could not be added due + * to lack of space, or it exists but has the wrong size */ void *bloblist_ensure(uint tag, int size); @@ -239,8 +239,8 @@ void *bloblist_ensure(uint tag, int size); * @tag: Tag to add (enum bloblist_tag_t) * @sizep: Size of the blob to create; returns size of actual blob * @blobp: Returns a pointer to blob on success - * @return 0 if OK, -ENOSPC if it is missing and could not be added due to lack - * of space + * Return: 0 if OK, -ENOSPC if it is missing and could not be added due to lack + * of space */ int bloblist_ensure_size_ret(uint tag, int *sizep, void **blobp); @@ -252,8 +252,8 @@ int bloblist_ensure_size_ret(uint tag, int *sizep, void **blobp); * * @tag: Tag to add (enum bloblist_tag_t) * @new_size: New size of the blob (>0 to expand, <0 to contract) - * @return 0 if OK, -ENOSPC if the bloblist does not have enough space, -ENOENT - * if the tag is not found + * Return: 0 if OK, -ENOSPC if the bloblist does not have enough space, -ENOENT + * if the tag is not found */ int bloblist_resize(uint tag, int new_size); @@ -263,8 +263,8 @@ int bloblist_resize(uint tag, int new_size); * @addr: Address of bloblist * @size: Initial size for bloblist * @flags: Flags to use for bloblist - * @return 0 if OK, -EFAULT if addr is not aligned correctly, -ENOSPC is the - * area is not large enough + * Return: 0 if OK, -EFAULT if addr is not aligned correctly, -ENOSPC is the + * area is not large enough */ int bloblist_new(ulong addr, uint size, uint flags); @@ -273,11 +273,11 @@ int bloblist_new(ulong addr, uint size, uint flags); * * @addr: Address of bloblist * @size: Expected size of blobsize, or 0 to detect the size - * @return 0 if OK, -ENOENT if the magic number doesn't match (indicating that - * there problem is no bloblist at the given address), -EPROTONOSUPPORT - * if the version does not match, -EIO if the checksum does not match, - * -EFBIG if the expected size does not match the detected size, -ENOSPC - * if the size is not large enough to hold the headers + * Return: 0 if OK, -ENOENT if the magic number doesn't match (indicating that + * there problem is no bloblist at the given address), -EPROTONOSUPPORT + * if the version does not match, -EIO if the checksum does not match, + * -EFBIG if the expected size does not match the detected size, -ENOSPC + * if the size is not large enough to hold the headers */ int bloblist_check(ulong addr, uint size); @@ -287,7 +287,7 @@ int bloblist_check(ulong addr, uint size); * This sets the correct checksum for the bloblist. This ensures that the * bloblist will be detected correctly by the next phase of U-Boot. * - * @return 0 + * Return: 0 */ int bloblist_finish(void); @@ -305,14 +305,14 @@ void bloblist_get_stats(ulong *basep, ulong *sizep, ulong *allocedp); /** * bloblist_get_base() - Get the base address of the bloblist * - * @returns base address of bloblist + * Return: base address of bloblist */ ulong bloblist_get_base(void); /** * bloblist_get_size() - Get the size of the bloblist * - * @returns the size in bytes + * Return: the size in bytes */ ulong bloblist_get_size(void); @@ -334,7 +334,7 @@ void bloblist_show_list(void); * bloblist_tag_name() - Get the name for a tag * * @tag: Tag to check - * @return name of tag, or "invalid" if an invalid tag is provided + * Return: name of tag, or "invalid" if an invalid tag is provided */ const char *bloblist_tag_name(enum bloblist_tag_t tag); @@ -342,7 +342,7 @@ const char *bloblist_tag_name(enum bloblist_tag_t tag); * bloblist_reloc() - Relocate the bloblist and optionally resize it * * @to: Pointer to new bloblist location (must not overlap old location) - * @to:size: New size for bloblist (must be larger than from_size) + * @to_size: New size for bloblist (must be larger than from_size) * @from: Pointer to bloblist to relocate * @from_size: Size of bloblist to relocate */ @@ -351,8 +351,19 @@ void bloblist_reloc(void *to, uint to_size, void *from, uint from_size); /** * bloblist_init() - Init the bloblist system with a single bloblist * - * This uses CONFIG_BLOBLIST_ADDR and CONFIG_BLOBLIST_SIZE to set up a bloblist - * for use by U-Boot. + * This locates and sets up the blocklist for use. + * + * If CONFIG_BLOBLIST_FIXED is selected, it uses CONFIG_BLOBLIST_ADDR and + * CONFIG_BLOBLIST_SIZE to set up a bloblist for use by U-Boot. + * + * If CONFIG_BLOBLIST_ALLOC is selected, it allocates memory for a bloblist of + * size CONFIG_BLOBLIST_SIZE. + * + * If CONFIG_BLOBLIST_PASSAGE is selected, it uses the bloblist in the incoming + * standard passage. The size is detected automatically so CONFIG_BLOBLIST_SIZE + * can be 0. + * + * Return: 0 if OK, -ve on error */ int bloblist_init(void); -- cgit v1.2.3 From 6c9e3d1fc085977b5b38dfe610f65d1a7f48081b Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 12 Jan 2022 19:26:25 -0700 Subject: bloblist: Relicense to allow BSD-3-Clause This implementation is intended to be copied to other projects and modified, to as to foster a standard means of communcating runtime information between firmware projects. The GPL-2 license is too restrictive for some projects, e.g. those intended as reference implementations rather than designed for collaborative open-source development. Update the license to make this easier to share. Signed-off-by: Simon Glass --- include/bloblist.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'include/bloblist.h') diff --git a/include/bloblist.h b/include/bloblist.h index 798babe9235..173129b0273 100644 --- a/include/bloblist.h +++ b/include/bloblist.h @@ -1,4 +1,4 @@ -/* SPDX-License-Identifier: GPL-2.0+ */ +/* SPDX-License-Identifier: GPL-2.0+ BSD-3-Clause */ /* * This provides a standard way of passing information between boot phases * (TPL -> SPL -> U-Boot proper.) -- cgit v1.2.3