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 enum bloblist_tag_t {
  23         BLOBLISTT_NONE = 0,
  24
  25         /* Vendor-specific tags are permitted here */
  26         BLOBLISTT_EC_HOSTEVENT,         /* Chromium OS EC host-event mask */
  27         BLOBLISTT_SPL_HANDOFF,          /* Hand-off info from SPL */
  28         BLOBLISTT_VBOOT_CTX,            /* Chromium OS verified boot context */
  29         BLOBLISTT_VBOOT_HANDOFF,        /* Chromium OS internal handoff info */
  30         /*
  31          * Advanced Configuration and Power Interface Global Non-Volatile
  32          * Sleeping table. This forms part of the ACPI tables passed to Linux.
  33          */
  34         BLOBLISTT_ACPI_GNVS,
  35         BLOBLISTT_INTEL_VBT,            /* Intel Video-BIOS table */
  36         BLOBLISTT_TPM2_TCG_LOG,         /* TPM v2 log space */
  37         BLOBLISTT_TCPA_LOG,             /* TPM log space */
  38 };
  39
  40 /**
  41  * struct bloblist_hdr - header for the bloblist
  42  *
  43  * This is stored at the start of the bloblist which is always on a 16-byte
  44  * boundary. Records follow this header. The bloblist normally stays in the
  45  * same place in memory as SPL and U-Boot execute, but it can be safely moved
  46  * around.
  47  *
  48  * None of the bloblist structures contain pointers but it is possible to put
  49  * pointers inside a bloblist record if desired. This is not encouraged,
  50  * since it can make part of the bloblist inaccessible if the pointer is
  51  * no-longer valid. It is better to just store all the data inside a bloblist
  52  * record.
  53  *
  54  * Each bloblist record is aligned to a 16-byte boundary and follows immediately
  55  * from the last.
  56  *
  57  * @version: BLOBLIST_VERSION
  58  * @hdr_size: Size of this header, normally sizeof(struct bloblist_hdr). The
  59  *      first bloblist_rec starts at this offset from the start of the header
  60  * @flags: Space for BLOBLISTF_... flags (none yet)
  61  * @magic: BLOBLIST_MAGIC
  62  * @size: Total size of all records (non-zero if valid) including this header.
  63  *      The bloblist extends for this many bytes from the start of this header.
  64  * @alloced: Total size allocated for this bloblist. When adding new records,
  65  *      the bloblist can grow up to this size. This starts out as
  66  *      sizeof(bloblist_hdr) since we need at least that much space to store a
  67  *      valid bloblist
  68  * @spare: Space space
  69  * @chksum: CRC32 for the entire bloblist allocated area. Since any of the
  70  *      blobs can be altered after being created, this checksum is only valid
  71  *      when the bloblist is finalised before jumping to the next stage of boot.
  72  *      Note: @chksum is last to make it easier to exclude it from the checksum
  73  *      calculation.
  74  */
  75 struct bloblist_hdr {
  76         u32 version;
  77         u32 hdr_size;
  78         u32 flags;
  79         u32 magic;
  80
  81         u32 size;
  82         u32 alloced;
  83         u32 spare;
  84         u32 chksum;
  85 };
  86
  87 /**
  88  * struct bloblist_rec - record for the bloblist
  89  *
  90  * NOTE: Only exported for testing purposes. Do not use this struct.
  91  *
  92  * The bloblist contains a number of records each consisting of this record
  93  * structure followed by the data contained. Each records is 16-byte aligned.
  94  *
  95  * @tag: Tag indicating what the record contains
  96  * @hdr_size: Size of this header, normally sizeof(struct bloblist_rec). The
  97  *      record's data starts at this offset from the start of the record
  98  * @size: Size of record in bytes, excluding the header size. This does not
  99  *      need to be aligned (e.g. 3 is OK).
 100  * @spare: Spare space for other things
 101  */
 102 struct bloblist_rec {
 103         u32 tag;
 104         u32 hdr_size;
 105         u32 size;
 106         u32 spare;
 107 };
 108
 109 /**
 110  * bloblist_find() - Find a blob
 111  *
 112  * Searches the bloblist and returns the blob with the matching tag
 113  *
 114  * @tag:        Tag to search for (enum bloblist_tag_t)
 115  * @size:       Expected size of the blob
 116  * @return pointer to blob if found, or NULL if not found, or a blob was found
 117  *      but it is the wrong size
 118  */
 119 void *bloblist_find(uint tag, int size);
 120
 121 /**
 122  * bloblist_add() - Add a new blob
 123  *
 124  * Add a new blob to the bloblist
 125  *
 126  * This should only be called if you konw there is no existing blob for a
 127  * particular tag. It is typically safe to call in the first phase of U-Boot
 128  * (e.g. TPL or SPL). After that, bloblist_ensure() should be used instead.
 129  *
 130  * @tag:        Tag to add (enum bloblist_tag_t)
 131  * @size:       Size of the blob
 132  * @return pointer to the newly added block, or NULL if there is not enough
 133  *      space for the blob
 134  */
 135 void *bloblist_add(uint tag, int size);
 136
 137 /**
 138  * bloblist_ensure_size() - Find or add a blob
 139  *
 140  * Find an existing blob, or add a new one if not found
 141  *
 142  * @tag:        Tag to add (enum bloblist_tag_t)
 143  * @size:       Size of the blob
 144  * @blobp:      Returns a pointer to blob on success
 145  * @return 0 if OK, -ENOSPC if it is missing and could not be added due to lack
 146  *      of space, or -ESPIPE it exists but has the wrong size
 147  */
 148 int bloblist_ensure_size(uint tag, int size, void **blobp);
 149
 150 /**
 151  * bloblist_ensure() - Find or add a blob
 152  *
 153  * Find an existing blob, or add a new one if not found
 154  *
 155  * @tag:        Tag to add (enum bloblist_tag_t)
 156  * @size:       Size of the blob
 157  * @return pointer to blob, or NULL if it is missing and could not be added due
 158  *      to lack of space, or it exists but has the wrong size
 159  */
 160 void *bloblist_ensure(uint tag, int size);
 161
 162 /**
 163  * bloblist_ensure_size_ret() - Find or add a blob
 164  *
 165  * Find an existing blob, or add a new one if not found
 166  *
 167  * @tag:        Tag to add (enum bloblist_tag_t)
 168  * @sizep:      Size of the blob to create; returns size of actual blob
 169  * @blobp:      Returns a pointer to blob on success
 170  * @return 0 if OK, -ENOSPC if it is missing and could not be added due to lack
 171  *      of space
 172  */
 173 int bloblist_ensure_size_ret(uint tag, int *sizep, void **blobp);
 174
 175 /**
 176  * bloblist_new() - Create a new, empty bloblist of a given size
 177  *
 178  * @addr: Address of bloblist
 179  * @size: Initial size for bloblist
 180  * @flags: Flags to use for bloblist
 181  * @return 0 if OK, -EFAULT if addr is not aligned correctly, -ENOSPC is the
 182  *      area is not large enough
 183  */
 184 int bloblist_new(ulong addr, uint size, uint flags);
 185
 186 /**
 187  * bloblist_check() - Check if a bloblist exists
 188  *
 189  * @addr: Address of bloblist
 190  * @size: Expected size of blobsize, or 0 to detect the size
 191  * @return 0 if OK, -ENOENT if the magic number doesn't match (indicating that
 192  *      there problem is no bloblist at the given address), -EPROTONOSUPPORT
 193  *      if the version does not match, -EIO if the checksum does not match,
 194  *      -EFBIG if the expected size does not match the detected size, -ENOSPC
 195  *      if the size is not large enough to hold the headers
 196  */
 197 int bloblist_check(ulong addr, uint size);
 198
 199 /**
 200  * bloblist_finish() - Set up the bloblist for the next U-Boot part
 201  *
 202  * This sets the correct checksum for the bloblist. This ensures that the
 203  * bloblist will be detected correctly by the next phase of U-Boot.
 204  *
 205  * @return 0
 206  */
 207 int bloblist_finish(void);
 208
 209 /**
 210  * bloblist_init() - Init the bloblist system with a single bloblist
 211  *
 212  * This uses CONFIG_BLOBLIST_ADDR and CONFIG_BLOBLIST_SIZE to set up a bloblist
 213  * for use by U-Boot.
 214  */
 215 int bloblist_init(void);
 216
 217 #endif /* __BLOBLIST_H */