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