include/bloblist.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * This provides a standard way of passing information between boot phases
   4  * (TPL -> SPL -> U-Boot proper.)
   5  *
   6  * A list of blobs of data, tagged with their owner. The list resides in memory
   7  * and can be updated by SPL, U-Boot, etc.
   8  *
   9  * Copyright 2018 Google, Inc
  10  * Written by Simon Glass <sjg@chromium.org>
  11  */
  12
  13 #ifndef __BLOBLIST_H
  14 #define __BLOBLIST_H
  15
  16 enum {
  17         BLOBLIST_VERSION        = 0,
  18         BLOBLIST_MAGIC          = 0xb00757a3,
  19         BLOBLIST_ALIGN          = 16,
  20 };
  21
  22 /* Supported tags - add new ones to tag_name in bloblist.c */
  23 enum bloblist_tag_t {
  24         BLOBLISTT_NONE = 0,
  25
  26         /* Vendor-specific tags are permitted here */
  27         BLOBLISTT_EC_HOSTEVENT,         /* Chromium OS EC host-event mask */
  28         BLOBLISTT_SPL_HANDOFF,          /* Hand-off info from SPL */
  29         BLOBLISTT_VBOOT_CTX,            /* Chromium OS verified boot context */
  30         BLOBLISTT_VBOOT_HANDOFF,        /* Chromium OS internal handoff info */
  31         /*
  32          * Advanced Configuration and Power Interface Global Non-Volatile
  33          * Sleeping table. This forms part of the ACPI tables passed to Linux.
  34          */
  35         BLOBLISTT_ACPI_GNVS,
  36         BLOBLISTT_INTEL_VBT,            /* Intel Video-BIOS table */
  37         BLOBLISTT_TPM2_TCG_LOG,         /* TPM v2 log space */
  38         BLOBLISTT_TCPA_LOG,             /* TPM log space */
  39         BLOBLISTT_ACPI_TABLES,          /* ACPI tables for x86 */
  40         BLOBLISTT_SMBIOS_TABLES,        /* SMBIOS tables for x86 */
  41
  42         BLOBLISTT_COUNT
  43 };
  44
  45 /**
  46  * struct bloblist_hdr - header for the bloblist
  47  *
  48  * This is stored at the start of the bloblist which is always on a 16-byte
  49  * boundary. Records follow this header. The bloblist normally stays in the
  50  * same place in memory as SPL and U-Boot execute, but it can be safely moved
  51  * around.
  52  *
  53  * None of the bloblist structures contain pointers but it is possible to put
  54  * pointers inside a bloblist record if desired. This is not encouraged,
  55  * since it can make part of the bloblist inaccessible if the pointer is
  56  * no-longer valid. It is better to just store all the data inside a bloblist
  57  * record.
  58  *
  59  * Each bloblist record is aligned to a 16-byte boundary and follows immediately
  60  * from the last.
  61  *
  62  * @version: BLOBLIST_VERSION
  63  * @hdr_size: Size of this header, normally sizeof(struct bloblist_hdr). The
  64  *      first bloblist_rec starts at this offset from the start of the header
  65  * @flags: Space for BLOBLISTF_... flags (none yet)
  66  * @magic: BLOBLIST_MAGIC
  67  * @size: Total size of the bloblist (non-zero if valid) including this header.
  68  *      The bloblist extends for this many bytes from the start of this header.
  69  *      When adding new records, the bloblist can grow up to this size.
  70  * @alloced: Total size allocated so far for this bloblist. This starts out as
  71  *      sizeof(bloblist_hdr) since we need at least that much space to store a
  72  *      valid bloblist
  73  * @spare: Spare space (for future use)
  74  * @chksum: CRC32 for the entire bloblist allocated area. Since any of the
  75  *      blobs can be altered after being created, this checksum is only valid
  76  *      when the bloblist is finalised before jumping to the next stage of boot.
  77  *      Note: @chksum is last to make it easier to exclude it from the checksum
  78  *      calculation.
  79  */
  80 struct bloblist_hdr {
  81         u32 version;
  82         u32 hdr_size;
  83         u32 flags;
  84         u32 magic;
  85
  86         u32 size;
  87         u32 alloced;
  88         u32 spare;
  89         u32 chksum;
  90 };
  91
  92 /**
  93  * struct bloblist_rec - record for the bloblist
  94  *
  95  * NOTE: Only exported for testing purposes. Do not use this struct.
  96  *
  97  * The bloblist contains a number of records each consisting of this record
  98  * structure followed by the data contained. Each records is 16-byte aligned.
  99  *
 100  * @tag: Tag indicating what the record contains
 101  * @hdr_size: Size of this header, normally sizeof(struct bloblist_rec). The
 102  *      record's data starts at this offset from the start of the record
 103  * @size: Size of record in bytes, excluding the header size. This does not
 104  *      need to be aligned (e.g. 3 is OK).
 105  * @spare: Spare space for other things
 106  */
 107 struct bloblist_rec {
 108         u32 tag;
 109         u32 hdr_size;
 110         u32 size;
 111         u32 spare;
 112 };
 113
 114 /**
 115  * bloblist_find() - Find a blob
 116  *
 117  * Searches the bloblist and returns the blob with the matching tag
 118  *
 119  * @tag:        Tag to search for (enum bloblist_tag_t)
 120  * @size:       Expected size of the blob, or 0 for any size
 121  * @return pointer to blob if found, or NULL if not found, or a blob was found
 122  *      but it is the wrong size
 123  */
 124 void *bloblist_find(uint tag, int size);
 125
 126 /**
 127  * bloblist_add() - Add a new blob
 128  *
 129  * Add a new blob to the bloblist
 130  *
 131  * This should only be called if you konw there is no existing blob for a
 132  * particular tag. It is typically safe to call in the first phase of U-Boot
 133  * (e.g. TPL or SPL). After that, bloblist_ensure() should be used instead.
 134  *
 135  * @tag:        Tag to add (enum bloblist_tag_t)
 136  * @size:       Size of the blob
 137  * @align:      Alignment of the blob (in bytes), 0 for default
 138  * @return pointer to the newly added block, or NULL if there is not enough
 139  *      space for the blob
 140  */
 141 void *bloblist_add(uint tag, int size, int align);
 142
 143 /**
 144  * bloblist_ensure_size() - Find or add a blob
 145  *
 146  * Find an existing blob, or add a new one if not found
 147  *
 148  * @tag:        Tag to add (enum bloblist_tag_t)
 149  * @size:       Size of the blob
 150  * @blobp:      Returns a pointer to blob on success
 151  * @align:      Alignment of the blob (in bytes), 0 for default
 152  * @return 0 if OK, -ENOSPC if it is missing and could not be added due to lack
 153  *      of space, or -ESPIPE it exists but has the wrong size
 154  */
 155 int bloblist_ensure_size(uint tag, int size, int align, void **blobp);
 156
 157 /**
 158  * bloblist_ensure() - Find or add a blob
 159  *
 160  * Find an existing blob, or add a new one if not found
 161  *
 162  * @tag:        Tag to add (enum bloblist_tag_t)
 163  * @size:       Size of the blob
 164  * @return pointer to blob, or NULL if it is missing and could not be added due
 165  *      to lack of space, or it exists but has the wrong size
 166  */
 167 void *bloblist_ensure(uint tag, int size);
 168
 169 /**
 170  * bloblist_ensure_size_ret() - Find or add a blob
 171  *
 172  * Find an existing blob, or add a new one if not found
 173  *
 174  * @tag:        Tag to add (enum bloblist_tag_t)
 175  * @sizep:      Size of the blob to create; returns size of actual blob
 176  * @blobp:      Returns a pointer to blob on success
 177  * @return 0 if OK, -ENOSPC if it is missing and could not be added due to lack
 178  *      of space
 179  */
 180 int bloblist_ensure_size_ret(uint tag, int *sizep, void **blobp);
 181
 182 /**
 183  * bloblist_resize() - resize a blob
 184  *
 185  * Any blobs above this one are relocated up or down. The resized blob remains
 186  * in the same place.
 187  *
 188  * @tag:        Tag to add (enum bloblist_tag_t)
 189  * @new_size:   New size of the blob (>0 to expand, <0 to contract)
 190  * @return 0 if OK, -ENOSPC if the bloblist does not have enough space, -ENOENT
 191  *      if the tag is not found
 192  */
 193 int bloblist_resize(uint tag, int new_size);
 194
 195 /**
 196  * bloblist_new() - Create a new, empty bloblist of a given size
 197  *
 198  * @addr: Address of bloblist
 199  * @size: Initial size for bloblist
 200  * @flags: Flags to use for bloblist
 201  * @return 0 if OK, -EFAULT if addr is not aligned correctly, -ENOSPC is the
 202  *      area is not large enough
 203  */
 204 int bloblist_new(ulong addr, uint size, uint flags);
 205
 206 /**
 207  * bloblist_check() - Check if a bloblist exists
 208  *
 209  * @addr: Address of bloblist
 210  * @size: Expected size of blobsize, or 0 to detect the size
 211  * @return 0 if OK, -ENOENT if the magic number doesn't match (indicating that
 212  *      there problem is no bloblist at the given address), -EPROTONOSUPPORT
 213  *      if the version does not match, -EIO if the checksum does not match,
 214  *      -EFBIG if the expected size does not match the detected size, -ENOSPC
 215  *      if the size is not large enough to hold the headers
 216  */
 217 int bloblist_check(ulong addr, uint size);
 218
 219 /**
 220  * bloblist_finish() - Set up the bloblist for the next U-Boot part
 221  *
 222  * This sets the correct checksum for the bloblist. This ensures that the
 223  * bloblist will be detected correctly by the next phase of U-Boot.
 224  *
 225  * @return 0
 226  */
 227 int bloblist_finish(void);
 228
 229 /**
 230  * bloblist_get_stats() - Get information about the bloblist
 231  *
 232  * This returns useful information about the bloblist
 233  *
 234  * @basep: Returns base address of bloblist
 235  * @sizep: Returns the number of bytes used in the bloblist
 236  * @allocedp: Returns the total space allocated to the bloblist
 237  */
 238 void bloblist_get_stats(ulong *basep, ulong *sizep, ulong *allocedp);
 239
 240 /**
 241  * bloblist_show_stats() - Show information about the bloblist
 242  *
 243  * This shows useful information about the bloblist on the console
 244  */
 245 void bloblist_show_stats(void);
 246
 247 /**
 248  * bloblist_show_list() - Show a list of blobs in the bloblist
 249  *
 250  * This shows a list of blobs, showing their address, size and tag.
 251  */
 252 void bloblist_show_list(void);
 253
 254 /**
 255  * bloblist_tag_name() - Get the name for a tag
 256  *
 257  * @tag: Tag to check
 258  * @return name of tag, or "invalid" if an invalid tag is provided
 259  */
 260 const char *bloblist_tag_name(enum bloblist_tag_t tag);
 261
 262 /**
 263  * bloblist_reloc() - Relocate the bloblist and optionally resize it
 264  *
 265  * @to: Pointer to new bloblist location (must not overlap old location)
 266  * @to:size: New size for bloblist (must be larger than from_size)
 267  * @from: Pointer to bloblist to relocate
 268  * @from_size: Size of bloblist to relocate
 269  */
 270 void bloblist_reloc(void *to, uint to_size, void *from, uint from_size);
 271
 272 /**
 273  * bloblist_init() - Init the bloblist system with a single bloblist
 274  *
 275  * This uses CONFIG_BLOBLIST_ADDR and CONFIG_BLOBLIST_SIZE to set up a bloblist
 276  * for use by U-Boot.
 277  */
 278 int bloblist_init(void);
 279
 280 #endif /* __BLOBLIST_H */