include/bloblist.h

   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  */
  70
  71 #ifndef __BLOBLIST_H
  72 #define __BLOBLIST_H
  73
  74 #include <mapmem.h>
  75
  76 enum {
  77         BLOBLIST_VERSION        = 1,
  78         BLOBLIST_MAGIC          = 0x4a0fb10b,
  79
  80         BLOBLIST_BLOB_ALIGN_LOG2 = 3,
  81         BLOBLIST_BLOB_ALIGN      = 1 << BLOBLIST_BLOB_ALIGN_LOG2,
  82
  83         BLOBLIST_ALIGN_LOG2     = 3,
  84         BLOBLIST_ALIGN          = 1 << BLOBLIST_ALIGN_LOG2,
  85 };
  86
  87 /* Supported tags - add new ones to tag_name in bloblist.c */
  88 enum bloblist_tag_t {
  89         BLOBLISTT_VOID = 0,
  90
  91         /*
  92          * Standard area to allocate blobs used across firmware components, for
  93          * things that are very commonly used, particularly in multiple
  94          * projects.
  95          */
  96         BLOBLISTT_AREA_FIRMWARE_TOP = 0x1,
  97         /*
  98          * Devicetree for use by firmware. On some platforms this is passed to
  99          * the OS also
 100          */
 101         BLOBLISTT_CONTROL_FDT = 1,
 102         BLOBLISTT_HOB_BLOCK = 2,
 103         BLOBLISTT_HOB_LIST = 3,
 104         BLOBLISTT_ACPI_TABLES = 4,
 105         BLOBLISTT_TPM_EVLOG = 5,
 106         BLOBLISTT_TPM_CRB_BASE = 6,
 107
 108         /* Standard area to allocate blobs used across firmware components */
 109         BLOBLISTT_AREA_FIRMWARE = 0x10,
 110         BLOBLISTT_TPM2_TCG_LOG = 0x10,  /* TPM v2 log space */
 111         BLOBLISTT_TCPA_LOG = 0x11,      /* TPM log space */
 112         /*
 113          * Advanced Configuration and Power Interface Global Non-Volatile
 114          * Sleeping table. This forms part of the ACPI tables passed to Linux.
 115          */
 116         BLOBLISTT_ACPI_GNVS = 0x12,
 117
 118         /* Standard area to allocate blobs used for Trusted Firmware */
 119         BLOBLISTT_AREA_TF = 0x100,
 120         BLOBLISTT_OPTEE_PAGABLE_PART = 0x100,
 121
 122         /* Other standard area to allocate blobs */
 123         BLOBLISTT_AREA_OTHER = 0x200,
 124         BLOBLISTT_INTEL_VBT = 0x200,    /* Intel Video-BIOS table */
 125         BLOBLISTT_SMBIOS_TABLES = 0x201, /* SMBIOS tables for x86 */
 126         BLOBLISTT_VBOOT_CTX = 0x202,    /* Chromium OS verified boot context */
 127
 128         /*
 129          * Tags from here are on reserved for private use within a single
 130          * firmware binary (i.e. a single executable or phase of a project).
 131          * These tags can be passed between binaries within a local
 132          * implementation, but cannot be used in upstream code. Allocate a
 133          * tag in one of the areas above if you want that.
 134          *
 135          * Project-specific tags are permitted here. Projects can be open source
 136          * or not, but the format of the data must be fuily documented in an
 137          * open source project, including all fields, bits, etc. Naming should
 138          * be: BLOBLISTT_<project>_<purpose_here>
 139          *
 140          * Vendor-specific tags are also permitted. Projects can be open source
 141          * or not, but the format of the data must be fuily documented in an
 142          * open source project, including all fields, bits, etc. Naming should
 143          * be BLOBLISTT_<vendor>_<purpose_here>
 144          */
 145         BLOBLISTT_PRIVATE_AREA          = 0xfff000,
 146         BLOBLISTT_U_BOOT_SPL_HANDOFF    = 0xfff000, /* Hand-off info from SPL */
 147         BLOBLISTT_VBE                   = 0xfff001, /* VBE per-phase state */
 148         BLOBLISTT_U_BOOT_VIDEO          = 0xfff002, /* Video info from SPL */
 149 };
 150
 151 /**
 152  * struct bloblist_hdr - header for the bloblist
 153  *
 154  * This is stored at the start of the bloblist which is always on a 16-byte
 155  * boundary. Records follow this header. The bloblist normally stays in the
 156  * same place in memory as SPL and U-Boot execute, but it can be safely moved
 157  * around.
 158  *
 159  * None of the bloblist headers themselves contain pointers but it is possible
 160  * to put pointers inside a bloblist record if desired. This is not encouraged,
 161  * since it can make part of the bloblist inaccessible if the pointer is
 162  * no-longer valid. It is better to just store all the data inside a bloblist
 163  * record.
 164  *
 165  * Each bloblist record is aligned to a 16-byte boundary and follows immediately
 166  * from the last.
 167  *
 168  * @magic: BLOBLIST_MAGIC
 169  * @version: BLOBLIST_VERSION
 170  * @hdr_size: Size of this header, normally sizeof(struct bloblist_hdr). The
 171  *      first bloblist_rec starts at this offset from the start of the header
 172  * @flags: Space for BLOBLISTF... flags (none yet)
 173  * @size: Total size of the bloblist (non-zero if valid) including this header.
 174  *      The bloblist extends for this many bytes from the start of this header.
 175  *      When adding new records, the bloblist can grow up to this size.
 176  * @alloced: Total size allocated so far for this bloblist. This starts out as
 177  *      sizeof(bloblist_hdr) since we need at least that much space to store a
 178  *      valid bloblist
 179  * @spare: Spare space (for future use)
 180  * @chksum: checksum for the entire bloblist allocated area. Since any of the
 181  *      blobs can be altered after being created, this checksum is only valid
 182  *      when the bloblist is finalised before jumping to the next stage of boot.
 183  *      This is the value needed to make all checksummed bytes sum to 0
 184  */
 185 struct bloblist_hdr {
 186         u32 magic;
 187         u32 version;
 188         u32 hdr_size;
 189         u32 flags;
 190
 191         u32 size;
 192         u32 alloced;
 193         u32 spare;
 194         u32 chksum;
 195 };
 196
 197 /**
 198  * struct bloblist_rec - record for the bloblist
 199  *
 200  * The bloblist contains a number of records each consisting of this record
 201  * structure followed by the data contained. Each records is 16-byte aligned.
 202  *
 203  * NOTE: Only exported for testing purposes. Do not use this struct.
 204  *
 205  * @tag_and_hdr_size: Tag indicating what the record contains (bottom 24 bits), and
 206  *      size of this header (top 8 bits), normally sizeof(struct bloblist_rec).
 207  *      The record's data starts at this offset from the start of the record
 208  * @size: Size of record in bytes, excluding the header size. This does not
 209  *      need to be aligned (e.g. 3 is OK).
 210  */
 211 struct bloblist_rec {
 212         u32 tag_and_hdr_size;
 213         u32 size;
 214 };
 215
 216 enum {
 217         BLOBLISTR_TAG_SHIFT             = 0,
 218         BLOBLISTR_TAG_MASK              = 0xffffffU << BLOBLISTR_TAG_SHIFT,
 219         BLOBLISTR_HDR_SIZE_SHIFT        = 24,
 220         BLOBLISTR_HDR_SIZE_MASK         = 0xffU << BLOBLISTR_HDR_SIZE_SHIFT,
 221
 222         BLOBLIST_HDR_SIZE               = sizeof(struct bloblist_hdr),
 223         BLOBLIST_REC_HDR_SIZE           = sizeof(struct bloblist_rec),
 224 };
 225
 226 /**
 227  * bloblist_check_magic() - return a bloblist if the magic matches
 228  *
 229  * @addr: Address to check
 230  * Return: pointer to bloblist, if the magic matches, else NULL
 231  */
 232 static inline void *bloblist_check_magic(ulong addr)
 233 {
 234         u32 *ptr;
 235
 236         if (!addr)
 237                 return NULL;
 238         ptr = map_sysmem(addr, 0);
 239         if (*ptr != BLOBLIST_MAGIC)
 240                 return NULL;
 241
 242         return ptr;
 243 }
 244
 245 /**
 246  * bloblist_find() - Find a blob
 247  *
 248  * Searches the bloblist and returns the blob with the matching tag
 249  *
 250  * @tag:        Tag to search for (enum bloblist_tag_t)
 251  * @size:       Expected size of the blob, or 0 for any size
 252  * Return: pointer to blob if found, or NULL if not found, or a blob was found
 253  * but it is the wrong size
 254  */
 255 void *bloblist_find(uint tag, int size);
 256
 257 /**
 258  * bloblist_add() - Add a new blob
 259  *
 260  * Add a new blob to the bloblist
 261  *
 262  * This should only be called if you konw there is no existing blob for a
 263  * particular tag. It is typically safe to call in the first phase of U-Boot
 264  * (e.g. TPL or SPL). After that, bloblist_ensure() should be used instead.
 265  *
 266  * @tag:        Tag to add (enum bloblist_tag_t)
 267  * @size:       Size of the blob
 268  * @align_log2: Alignment of the blob (in bytes log2), 0 for default
 269  * Return: pointer to the newly added block, or NULL if there is not enough
 270  * space for the blob
 271  */
 272 void *bloblist_add(uint tag, int size, int align_log2);
 273
 274 /**
 275  * bloblist_ensure_size() - Find or add a blob
 276  *
 277  * Find an existing blob, or add a new one if not found
 278  *
 279  * @tag:        Tag to add (enum bloblist_tag_t)
 280  * @size:       Size of the blob
 281  * @blobp:      Returns a pointer to blob on success
 282  * @align_log2: Alignment of the blob (in bytes log2), 0 for default
 283  * Return: 0 if OK, -ENOSPC if it is missing and could not be added due to lack
 284  * of space, or -ESPIPE it exists but has the wrong size
 285  */
 286 int bloblist_ensure_size(uint tag, int size, int align_log2, void **blobp);
 287
 288 /**
 289  * bloblist_ensure() - Find or add a blob
 290  *
 291  * Find an existing blob, or add a new one if not found
 292  *
 293  * @tag:        Tag to add (enum bloblist_tag_t)
 294  * @size:       Size of the blob
 295  * Return: pointer to blob, or NULL if it is missing and could not be added due
 296  * to lack of space, or it exists but has the wrong size
 297  */
 298 void *bloblist_ensure(uint tag, int size);
 299
 300 /**
 301  * bloblist_ensure_size_ret() - Find or add a blob
 302  *
 303  * Find an existing blob, or add a new one if not found
 304  *
 305  * @tag:        Tag to add (enum bloblist_tag_t)
 306  * @sizep:      Size of the blob to create; returns size of actual blob
 307  * @blobp:      Returns a pointer to blob on success
 308  * Return: 0 if OK, -ENOSPC if it is missing and could not be added due to lack
 309  * of space
 310  */
 311 int bloblist_ensure_size_ret(uint tag, int *sizep, void **blobp);
 312
 313 /**
 314  * bloblist_resize() - resize a blob
 315  *
 316  * Any blobs above this one are relocated up or down. The resized blob remains
 317  * in the same place.
 318  *
 319  * @tag:        Tag to add (enum bloblist_tag_t)
 320  * @new_size:   New size of the blob (>0 to expand, <0 to contract)
 321  * Return: 0 if OK, -ENOSPC if the bloblist does not have enough space, -ENOENT
 322  * if the tag is not found
 323  */
 324 int bloblist_resize(uint tag, int new_size);
 325
 326 /**
 327  * bloblist_new() - Create a new, empty bloblist of a given size
 328  *
 329  * @addr: Address of bloblist
 330  * @size: Initial size for bloblist
 331  * @flags: Flags to use for bloblist
 332  * Return: 0 if OK, -EFAULT if addr is not aligned correctly, -ENOSPC is the
 333  * area is not large enough
 334  */
 335 int bloblist_new(ulong addr, uint size, uint flags);
 336
 337 /**
 338  * bloblist_check() - Check if a bloblist exists
 339  *
 340  * @addr: Address of bloblist
 341  * @size: Expected size of blobsize, or 0 to detect the size
 342  * Return: 0 if OK, -ENOENT if the magic number doesn't match (indicating that
 343  * there problem is no bloblist at the given address), -EPROTONOSUPPORT
 344  * if the version does not match, -EIO if the checksum does not match,
 345  * -EFBIG if the expected size does not match the detected size, -ENOSPC
 346  * if the size is not large enough to hold the headers
 347  */
 348 int bloblist_check(ulong addr, uint size);
 349
 350 /**
 351  * bloblist_finish() - Set up the bloblist for the next U-Boot part
 352  *
 353  * This sets the correct checksum for the bloblist. This ensures that the
 354  * bloblist will be detected correctly by the next phase of U-Boot.
 355  *
 356  * Return: 0
 357  */
 358 int bloblist_finish(void);
 359
 360 /**
 361  * bloblist_get_stats() - Get information about the bloblist
 362  *
 363  * This returns useful information about the bloblist
 364  *
 365  * @basep: Returns base address of bloblist
 366  * @sizep: Returns the number of bytes used in the bloblist
 367  * @allocedp: Returns the total space allocated to the bloblist
 368  */
 369 void bloblist_get_stats(ulong *basep, ulong *sizep, ulong *allocedp);
 370
 371 /**
 372  * bloblist_get_base() - Get the base address of the bloblist
 373  *
 374  * Return: base address of bloblist
 375  */
 376 ulong bloblist_get_base(void);
 377
 378 /**
 379  * bloblist_get_size() - Get the size of the bloblist
 380  *
 381  * Return: the size in bytes
 382  */
 383 ulong bloblist_get_size(void);
 384
 385 /**
 386  * bloblist_show_stats() - Show information about the bloblist
 387  *
 388  * This shows useful information about the bloblist on the console
 389  */
 390 void bloblist_show_stats(void);
 391
 392 /**
 393  * bloblist_show_list() - Show a list of blobs in the bloblist
 394  *
 395  * This shows a list of blobs, showing their address, size and tag.
 396  */
 397 void bloblist_show_list(void);
 398
 399 /**
 400  * bloblist_tag_name() - Get the name for a tag
 401  *
 402  * @tag: Tag to check
 403  * Return: name of tag, or "invalid" if an invalid tag is provided
 404  */
 405 const char *bloblist_tag_name(enum bloblist_tag_t tag);
 406
 407 /**
 408  * bloblist_reloc() - Relocate the bloblist and optionally resize it
 409  *
 410  * @to: Pointer to new bloblist location (must not overlap old location)
 411  * @to_size: New size for bloblist (must be larger than from_size)
 412  * @from: Pointer to bloblist to relocate
 413  * @from_size: Size of bloblist to relocate
 414  */
 415 void bloblist_reloc(void *to, uint to_size, void *from, uint from_size);
 416
 417 /**
 418  * bloblist_init() - Init the bloblist system with a single bloblist
 419  *
 420  * This locates and sets up the blocklist for use.
 421  *
 422  * If CONFIG_BLOBLIST_FIXED is selected, it uses CONFIG_BLOBLIST_ADDR and
 423  * CONFIG_BLOBLIST_SIZE to set up a bloblist for use by U-Boot.
 424  *
 425  * If CONFIG_BLOBLIST_ALLOC is selected, it allocates memory for a bloblist of
 426  * size CONFIG_BLOBLIST_SIZE.
 427  *
 428  * If CONFIG_BLOBLIST_PASSAGE is selected, it uses the bloblist in the incoming
 429  * standard passage. The size is detected automatically so CONFIG_BLOBLIST_SIZE
 430  * can be 0.
 431  *
 432  * Sets GD_FLG_BLOBLIST_READY in global_data flags on success
 433  *
 434  * Return: 0 if OK, -ve on error
 435  */
 436 int bloblist_init(void);
 437
 438 #if CONFIG_IS_ENABLED(BLOBLIST)
 439 /**
 440  * bloblist_maybe_init() - Init the bloblist system if not already done
 441  *
 442  * Calls bloblist_init() if the GD_FLG_BLOBLIST_READY flag is not et
 443  *
 444  * Return: 0 if OK, -ve on error
 445  */
 446 int bloblist_maybe_init(void);
 447 #else
 448 static inline int bloblist_maybe_init(void)
 449 {
 450         return 0;
 451 }
 452 #endif /* BLOBLIST */
 453
 454 #endif /* __BLOBLIST_H */