1/* SPDX-License-Identifier: GPL-2.0+ BSD-3-Clause */ 2/* 3 * This provides a standard way of passing information between boot phases 4 * (TPL -> SPL -> U-Boot proper.) 5 * 6 * It consists of a list of blobs of data, tagged with their owner / contents. 7 * The list resides in memory and can be updated by SPL, U-Boot, etc. 8 * 9 * Design goals for bloblist: 10 * 11 * 1. Small and efficient structure. This avoids UUIDs or 16-byte name fields, 12 * since a 32-bit tag provides enough space for all the tags we will even need. 13 * If UUIDs are desired, they can be added inside a particular blob. 14 * 15 * 2. Avoids use of pointers, so the structure can be relocated in memory. The 16 * data in each blob is inline, rather than using pointers. 17 * 18 * 3. Bloblist is designed to start small in TPL or SPL, when only a few things 19 * are needed, like the memory size or whether console output should be enabled. 20 * Then it can grow in U-Boot proper, e.g. to include space for ACPI tables. 21 * 22 * 4. The bloblist structure is simple enough that it can be implemented in a 23 * small amount of C code. The API does not require use of strings or UUIDs, 24 * which would add to code size. For Thumb-2 the code size needed in SPL is 25 * approximately 940 bytes (e.g. for chromebook_bob). 26 * 27 * 5. Bloblist uses 8-byte alignment internally and is designed to start on a 28 * 8-byte boundary. Its headers are 8 bytes long. It is possible to achieve 29 * larger alignment (e.g. 16 bytes) by adding a dummy header, For use in SPL and 30 * TPL the alignment can be relaxed, since it can be relocated to an aligned 31 * address in U-Boot proper. 32 * 33 * 6. Bloblist is designed to be passed to Linux as reserved memory. While linux 34 * doesn't understand the bloblist header, it can be passed the indivdual blobs. 35 * For example, ACPI tables can reside in a blob and the address of those is 36 * passed to Linux, without Linux ever being away of the existence of a 37 * bloblist. Having all the blobs contiguous in memory simplifies the 38 * reserved-memory space. 39 * 40 * 7. Bloblist tags are defined in the enum below. There is an area for 41 * project-specific stuff (e.g. U-Boot, TF-A) and vendor-specific stuff, e.g. 42 * something used only on a particular SoC. There is also a private area for 43 * temporary, local use. 44 * 45 * 8. Bloblist includes a simple checksum, so that each boot phase can update 46 * this and allow the next phase to check that all is well. While the bloblist 47 * is small, this is quite cheap to calculate. When it grows (e.g. in U-Boot\ 48 * proper), the CPU is likely running faster, so it is not prohibitive. Having 49 * said that, U-Boot is often the last phase that uses bloblist, so calculating 50 * the checksum there may not be necessary. 51 * 52 * 9. It would be possible to extend bloblist to support a non-contiguous 53 * structure, e.g. by creating a blob type that points to the next bloblist. 54 * This does not seem necessary for now. It adds complexity and code. We can 55 * always just copy it. 56 * 57 * 10. Bloblist is designed for simple structures, those that can be defined by 58 * a single C struct. More complex structures should be passed in a device tree. 59 * There are some exceptions, chiefly the various binary structures that Intel 60 * is fond of creating. But device tree provides a dictionary-type format which 61 * is fairly efficient (for use in U-Boot proper and Linux at least), along with 62 * a schema and a good set of tools. New formats should be designed around 63 * device tree rather than creating new binary formats, unless they are needed 64 * early in boot (where libfdt's 3KB of overhead is too large) and are trival 65 * enough to be described by a C struct. 66 * 67 * Copyright 2018 Google, Inc 68 * Written by Simon Glass <sjg@chromium.org> 69 * Adjusted July 2023 to match Firmware handoff specification, Release 0.9 70 */ 71 72#ifndef __BLOBLIST_H 73#define __BLOBLIST_H 74 75#include <mapmem.h> 76 77enum { 78 BLOBLIST_VERSION = 1, 79 BLOBLIST_MAGIC = 0x4a0fb10b, 80 81 /* 82 * FIXME: 83 * Register convention version should be placed into a higher byte 84 * https://github.com/FirmwareHandoff/firmware_handoff/issues/32 85 */ 86 BLOBLIST_REGCONV_VER = 1 << 24, 87 88 BLOBLIST_BLOB_ALIGN_LOG2 = 3, 89 BLOBLIST_BLOB_ALIGN = 1 << BLOBLIST_BLOB_ALIGN_LOG2, 90 91 BLOBLIST_ALIGN_LOG2 = 3, 92 BLOBLIST_ALIGN = 1 << BLOBLIST_ALIGN_LOG2, 93}; 94 95/* Supported tags - add new ones to tag_name in bloblist.c */ 96enum bloblist_tag_t { 97 BLOBLISTT_VOID = 0, 98 99 /* 100 * Standard area to allocate blobs used across firmware components, for 101 * things that are very commonly used, particularly in multiple 102 * projects. 103 */ 104 BLOBLISTT_AREA_FIRMWARE_TOP = 0x1, 105 /* 106 * Devicetree for use by firmware. On some platforms this is passed to 107 * the OS also 108 */ 109 BLOBLISTT_CONTROL_FDT = 1, 110 BLOBLISTT_HOB_BLOCK = 2, 111 BLOBLISTT_HOB_LIST = 3, 112 BLOBLISTT_ACPI_TABLES = 4, 113 BLOBLISTT_TPM_EVLOG = 5, 114 BLOBLISTT_TPM_CRB_BASE = 6, 115 116 /* Standard area to allocate blobs used across firmware components */ 117 BLOBLISTT_AREA_FIRMWARE = 0x10, 118 BLOBLISTT_TPM2_TCG_LOG = 0x10, /* TPM v2 log space */ 119 BLOBLISTT_TCPA_LOG = 0x11, /* TPM log space */ 120 /* 121 * Advanced Configuration and Power Interface Global Non-Volatile 122 * Sleeping table. This forms part of the ACPI tables passed to Linux. 123 */ 124 BLOBLISTT_ACPI_GNVS = 0x12, 125 126 /* Standard area to allocate blobs used for Trusted Firmware */ 127 BLOBLISTT_AREA_TF = 0x100, 128 BLOBLISTT_OPTEE_PAGABLE_PART = 0x100, 129 130 /* Other standard area to allocate blobs */ 131 BLOBLISTT_AREA_OTHER = 0x200, 132 BLOBLISTT_INTEL_VBT = 0x200, /* Intel Video-BIOS table */ 133 BLOBLISTT_SMBIOS_TABLES = 0x201, /* SMBIOS tables for x86 */ 134 BLOBLISTT_VBOOT_CTX = 0x202, /* Chromium OS verified boot context */ 135 136 /* 137 * Tags from here are on reserved for private use within a single 138 * firmware binary (i.e. a single executable or phase of a project). 139 * These tags can be passed between binaries within a local 140 * implementation, but cannot be used in upstream code. Allocate a 141 * tag in one of the areas above if you want that. 142 * 143 * Project-specific tags are permitted here. Projects can be open source 144 * or not, but the format of the data must be fuily documented in an 145 * open source project, including all fields, bits, etc. Naming should 146 * be: BLOBLISTT_<project>_<purpose_here> 147 * 148 * Vendor-specific tags are also permitted. Projects can be open source 149 * or not, but the format of the data must be fuily documented in an 150 * open source project, including all fields, bits, etc. Naming should 151 * be BLOBLISTT_<vendor>_<purpose_here> 152 */ 153 BLOBLISTT_PRIVATE_AREA = 0xfff000, 154 BLOBLISTT_U_BOOT_SPL_HANDOFF = 0xfff000, /* Hand-off info from SPL */ 155 BLOBLISTT_VBE = 0xfff001, /* VBE per-phase state */ 156 BLOBLISTT_U_BOOT_VIDEO = 0xfff002, /* Video info from SPL */ 157}; 158 159/** 160 * struct bloblist_hdr - header for the bloblist 161 * 162 * This is stored at the start of the bloblist which is always on a 16-byte 163 * boundary. Records follow this header. The bloblist normally stays in the 164 * same place in memory as SPL and U-Boot execute, but it can be safely moved 165 * around. 166 * 167 * None of the bloblist headers themselves contain pointers but it is possible 168 * to put pointers inside a bloblist record if desired. This is not encouraged, 169 * since it can make part of the bloblist inaccessible if the pointer is 170 * no-longer valid. It is better to just store all the data inside a bloblist 171 * record. 172 * 173 * Each bloblist record is aligned to a 16-byte boundary and follows immediately 174 * from the last. 175 * 176 * @magic: BLOBLIST_MAGIC 177 * @chksum: checksum for the entire bloblist allocated area. Since any of the 178 * blobs can be altered after being created, this checksum is only valid 179 * when the bloblist is finalized before jumping to the next stage of boot. 180 * This is the value needed to make all checksummed bytes sum to 0 181 * @version: BLOBLIST_VERSION 182 * @hdr_size: Size of this header, normally sizeof(struct bloblist_hdr). The 183 * first bloblist_rec starts at this offset from the start of the header 184 * @align_log2: Power of two of the maximum alignment required by this list 185 * @used_size: Size allocated so far for this bloblist. This starts out as 186 * sizeof(bloblist_hdr) since we need at least that much space to store a 187 * valid bloblist 188 * @total_size: The number of total bytes that the bloblist can occupy. 189 * Any blob producer must check if there is sufficient space before adding 190 * a record to the bloblist. 191 * @flags: Space for BLOBLISTF... flags (none yet) 192 * @spare: Spare space (for future use) 193 */ 194struct bloblist_hdr { 195 u32 magic; 196 u8 chksum; 197 u8 version; 198 u8 hdr_size; 199 u8 align_log2; 200 u32 used_size; 201 u32 total_size; 202 u32 flags; 203 u32 spare; 204}; 205 206/** 207 * struct bloblist_rec - record for the bloblist 208 * 209 * The bloblist contains a number of records each consisting of this record 210 * structure followed by the data contained. Each records is 16-byte aligned. 211 * 212 * NOTE: Only exported for testing purposes. Do not use this struct. 213 * 214 * @tag_and_hdr_size: Tag indicating what the record contains (bottom 24 bits), and 215 * size of this header (top 8 bits), normally sizeof(struct bloblist_rec). 216 * The record's data starts at this offset from the start of the record 217 * @size: Size of record in bytes, excluding the header size. This does not 218 * need to be aligned (e.g. 3 is OK). 219 */ 220struct bloblist_rec { 221 u32 tag_and_hdr_size; 222 u32 size; 223}; 224 225enum { 226 BLOBLISTR_TAG_SHIFT = 0, 227 BLOBLISTR_TAG_MASK = 0xffffffU << BLOBLISTR_TAG_SHIFT, 228 BLOBLISTR_HDR_SIZE_SHIFT = 24, 229 BLOBLISTR_HDR_SIZE_MASK = 0xffU << BLOBLISTR_HDR_SIZE_SHIFT, 230 231 BLOBLIST_HDR_SIZE = sizeof(struct bloblist_hdr), 232 BLOBLIST_REC_HDR_SIZE = sizeof(struct bloblist_rec), 233}; 234 235/** 236 * bloblist_check_magic() - return a bloblist if the magic matches 237 * 238 * @addr: Address to check 239 * Return: pointer to bloblist, if the magic matches, else NULL 240 */ 241static inline void *bloblist_check_magic(ulong addr) 242{ 243 u32 *ptr; 244 245 if (!addr) 246 return NULL; 247 ptr = map_sysmem(addr, 0); 248 if (*ptr != BLOBLIST_MAGIC) 249 return NULL; 250 251 return ptr; 252} 253 254/** 255 * bloblist_find() - Find a blob 256 * 257 * Searches the bloblist and returns the blob with the matching tag 258 * 259 * @tag: Tag to search for (enum bloblist_tag_t) 260 * @size: Expected size of the blob, or 0 for any size 261 * Return: pointer to blob if found, or NULL if not found, or a blob was found 262 * but it is the wrong size 263 */ 264void *bloblist_find(uint tag, int size); 265 266/** 267 * bloblist_add() - Add a new blob 268 * 269 * Add a new blob to the bloblist 270 * 271 * This should only be called if you konw there is no existing blob for a 272 * particular tag. It is typically safe to call in the first phase of U-Boot 273 * (e.g. TPL or SPL). After that, bloblist_ensure() should be used instead. 274 * 275 * @tag: Tag to add (enum bloblist_tag_t) 276 * @size: Size of the blob 277 * @align_log2: Alignment of the blob (in bytes log2), 0 for default 278 * Return: pointer to the newly added block, or NULL if there is not enough 279 * space for the blob 280 */ 281void *bloblist_add(uint tag, int size, int align_log2); 282 283/** 284 * bloblist_ensure_size() - Find or add a blob 285 * 286 * Find an existing blob, or add a new one if not found 287 * 288 * @tag: Tag to add (enum bloblist_tag_t) 289 * @size: Size of the blob 290 * @blobp: Returns a pointer to blob on success 291 * @align_log2: Alignment of the blob (in bytes log2), 0 for default 292 * Return: 0 if OK, -ENOSPC if it is missing and could not be added due to lack 293 * of space, or -ESPIPE it exists but has the wrong size 294 */ 295int bloblist_ensure_size(uint tag, int size, int align_log2, void **blobp); 296 297/** 298 * bloblist_ensure() - Find or add a blob 299 * 300 * Find an existing blob, or add a new one if not found 301 * 302 * @tag: Tag to add (enum bloblist_tag_t) 303 * @size: Size of the blob 304 * Return: pointer to blob, or NULL if it is missing and could not be added due 305 * to lack of space, or it exists but has the wrong size 306 */ 307void *bloblist_ensure(uint tag, int size); 308 309/** 310 * bloblist_ensure_size_ret() - Find or add a blob 311 * 312 * Find an existing blob, or add a new one if not found 313 * 314 * @tag: Tag to add (enum bloblist_tag_t) 315 * @sizep: Size of the blob to create; returns size of actual blob 316 * @blobp: Returns a pointer to blob on success 317 * Return: 0 if OK, -ENOSPC if it is missing and could not be added due to lack 318 * of space 319 */ 320int bloblist_ensure_size_ret(uint tag, int *sizep, void **blobp); 321 322/** 323 * bloblist_resize() - resize a blob 324 * 325 * Any blobs above this one are relocated up or down. The resized blob remains 326 * in the same place. 327 * 328 * @tag: Tag to add (enum bloblist_tag_t) 329 * @new_size: New size of the blob (>0 to expand, <0 to contract) 330 * Return: 0 if OK, -ENOSPC if the bloblist does not have enough space, -ENOENT 331 * if the tag is not found 332 */ 333int bloblist_resize(uint tag, int new_size); 334 335/** 336 * bloblist_new() - Create a new, empty bloblist of a given size 337 * 338 * @addr: Address of bloblist 339 * @size: Initial size for bloblist 340 * @flags: Flags to use for bloblist 341 * @align_log2: Log base 2 of maximum alignment provided by this bloblist 342 * Return: 0 if OK, -EFAULT if addr is not aligned correctly, -ENOSPC is the 343 * area is not large enough 344 */ 345int bloblist_new(ulong addr, uint size, uint flags, uint align_log2); 346 347/** 348 * bloblist_check() - Check if a bloblist exists 349 * 350 * @addr: Address of bloblist 351 * @size: Reserved space size for blobsize, or 0 to use the total size 352 * Return: 0 if OK, -ENOENT if the magic number doesn't match (indicating that 353 * there problem is no bloblist at the given address) or any fields for header 354 * size, used size and total size do not match, -EPROTONOSUPPORT 355 * if the version does not match, -EIO if the checksum does not match, 356 * -EFBIG if the reserved space size is small than the total size or total size 357 * is 0 358 */ 359int bloblist_check(ulong addr, uint size); 360 361/** 362 * bloblist_finish() - Set up the bloblist for the next U-Boot part 363 * 364 * This sets the correct checksum for the bloblist. This ensures that the 365 * bloblist will be detected correctly by the next phase of U-Boot. 366 * 367 * Return: 0 368 */ 369int bloblist_finish(void); 370 371/** 372 * bloblist_get_stats() - Get information about the bloblist 373 * 374 * This returns useful information about the bloblist 375 * 376 * @basep: Returns base address of bloblist 377 * @tsizep: Returns the total number of bytes of the bloblist 378 * @usizep: Returns the number of used bytes of the bloblist 379 */ 380void bloblist_get_stats(ulong *basep, ulong *tsizep, ulong *usizep); 381 382/** 383 * bloblist_get_base() - Get the base address of the bloblist 384 * 385 * Return: base address of bloblist 386 */ 387ulong bloblist_get_base(void); 388 389/** 390 * bloblist_get_size() - Get the size of the bloblist 391 * 392 * Return: the size in bytes 393 */ 394ulong bloblist_get_size(void); 395 396/** 397 * bloblist_get_total_size() - Get the total size of the bloblist 398 * 399 * Return: the size in bytes 400 */ 401ulong bloblist_get_total_size(void); 402 403/** 404 * bloblist_show_stats() - Show information about the bloblist 405 * 406 * This shows useful information about the bloblist on the console 407 */ 408void bloblist_show_stats(void); 409 410/** 411 * bloblist_show_list() - Show a list of blobs in the bloblist 412 * 413 * This shows a list of blobs, showing their address, size and tag. 414 */ 415void bloblist_show_list(void); 416 417/** 418 * bloblist_tag_name() - Get the name for a tag 419 * 420 * @tag: Tag to check 421 * Return: name of tag, or "invalid" if an invalid tag is provided 422 */ 423const char *bloblist_tag_name(enum bloblist_tag_t tag); 424 425/** 426 * bloblist_reloc() - Relocate the bloblist and optionally resize it 427 * 428 * @to: Pointer to new bloblist location (must not overlap old location) 429 * @to_size: New size for bloblist 430 * Return: 0 if OK, -ENOSPC if the new size is small than the bloblist total 431 * size. 432 */ 433int bloblist_reloc(void *to, uint to_size); 434 435/** 436 * bloblist_init() - Init the bloblist system with a single bloblist 437 * 438 * This locates and sets up the blocklist for use. 439 * 440 * If CONFIG_BLOBLIST_FIXED is selected, it uses CONFIG_BLOBLIST_ADDR and 441 * CONFIG_BLOBLIST_SIZE to set up a bloblist for use by U-Boot. 442 * 443 * If CONFIG_BLOBLIST_ALLOC is selected, it allocates memory for a bloblist of 444 * size CONFIG_BLOBLIST_SIZE. 445 * 446 * If CONFIG_BLOBLIST_PASSAGE is selected, it uses the bloblist in the incoming 447 * standard passage. The size is detected automatically so CONFIG_BLOBLIST_SIZE 448 * can be 0. 449 * 450 * Sets GD_FLG_BLOBLIST_READY in global_data flags on success 451 * 452 * Return: 0 if OK, -ve on error 453 */ 454int bloblist_init(void); 455 456#if CONFIG_IS_ENABLED(BLOBLIST) 457/** 458 * bloblist_maybe_init() - Init the bloblist system if not already done 459 * 460 * Calls bloblist_init() if the GD_FLG_BLOBLIST_READY flag is not et 461 * 462 * Return: 0 if OK, -ve on error 463 */ 464int bloblist_maybe_init(void); 465#else 466static inline int bloblist_maybe_init(void) 467{ 468 return 0; 469} 470#endif /* BLOBLIST */ 471 472/** 473 * bloblist_check_reg_conv() - Check whether the bloblist is compliant to 474 * the register conventions according to the 475 * Firmware Handoff spec. 476 * 477 * @rfdt: Register that holds the FDT base address. 478 * @rzero: Register that must be zero. 479 * @rsig: Register that holds signature and register conventions version. 480 * Return: 0 if OK, -EIO if the bloblist is not compliant to the register 481 * conventions. 482 */ 483int bloblist_check_reg_conv(ulong rfdt, ulong rzero, ulong rsig); 484 485/** 486 * xferlist_from_boot_arg() - Get bloblist from the boot args and relocate it 487 * to the specified address. 488 * 489 * @addr: Address for the bloblist 490 * @size: Size of space reserved for the bloblist 491 * Return: 0 if OK, else on error 492 */ 493int xferlist_from_boot_arg(ulong addr, ulong size); 494 495#endif /* __BLOBLIST_H */ 496