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  * 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 #include <mapmem.h>
  17
  18 enum {
  19         BLOBLIST_VERSION        = 0,
  20         BLOBLIST_MAGIC          = 0xb00757a3,
  21         BLOBLIST_ALIGN          = 16,
  22 };
  23
  24 /* Supported tags - add new ones to tag_name in bloblist.c */
  25 enum bloblist_tag_t {
  26         BLOBLISTT_NONE = 0,
  27
  28         /*
  29          * Standard area to allocate blobs used across firmware components, for
  30          * things that are very commonly used, particularly in multiple
  31          * projects.
  32          */
  33         BLOBLISTT_AREA_FIRMWARE_TOP = 0x1,
  34
  35         /* Standard area to allocate blobs used across firmware components */
  36         BLOBLISTT_AREA_FIRMWARE = 0x100,
  37         /*
  38          * Advanced Configuration and Power Interface Global Non-Volatile
  39          * Sleeping table. This forms part of the ACPI tables passed to Linux.
  40          */
  41         BLOBLISTT_ACPI_GNVS = 0x100,
  42         BLOBLISTT_INTEL_VBT = 0x101,    /* Intel Video-BIOS table */
  43         BLOBLISTT_TPM2_TCG_LOG = 0x102, /* TPM v2 log space */
  44         BLOBLISTT_TCPA_LOG = 0x103,     /* TPM log space */
  45         BLOBLISTT_ACPI_TABLES = 0x104,  /* ACPI tables for x86 */
  46         BLOBLISTT_SMBIOS_TABLES = 0x105, /* SMBIOS tables for x86 */
  47         BLOBLISTT_VBOOT_CTX = 0x106,    /* Chromium OS verified boot context */
  48
  49         /*
  50          * Project-specific tags are permitted here. Projects can be open source
  51          * or not, but the format of the data must be fuily documented in an
  52          * open source project, including all fields, bits, etc. Naming should
  53          * be: BLOBLISTT_<project>_<purpose_here>
  54          */
  55         BLOBLISTT_PROJECT_AREA = 0x8000,
  56         BLOBLISTT_U_BOOT_SPL_HANDOFF = 0x8000, /* Hand-off info from SPL */
  57
  58         /*
  59          * Vendor-specific tags are permitted here. Projects can be open source
  60          * or not, but the format of the data must be fuily documented in an
  61          * open source project, including all fields, bits, etc. Naming should
  62          * be BLOBLISTT_<vendor>_<purpose_here>
  63          */
  64         BLOBLISTT_VENDOR_AREA = 0xc000,
  65
  66         /* Tags after this are not allocated for now */
  67         BLOBLISTT_EXPANSION = 0x10000,
  68
  69         /*
  70          * Tags from here are on reserved for private use within a single
  71          * firmware binary (i.e. a single executable or phase of a project).
  72          * These tags can be passed between binaries within a local
  73          * implementation, but cannot be used in upstream code. Allocate a
  74          * tag in one of the areas above if you want that.
  75          *
  76          * This area may move in future.
  77          */
  78         BLOBLISTT_PRIVATE_AREA = 0xffff0000,
  79 };
  80
  81 /**
  82  * struct bloblist_hdr - header for the bloblist
  83  *
  84  * This is stored at the start of the bloblist which is always on a 16-byte
  85  * boundary. Records follow this header. The bloblist normally stays in the
  86  * same place in memory as SPL and U-Boot execute, but it can be safely moved
  87  * around.
  88  *
  89  * None of the bloblist headers themselves contain pointers but it is possible
  90  * to put pointers inside a bloblist record if desired. This is not encouraged,
  91  * since it can make part of the bloblist inaccessible if the pointer is
  92  * no-longer valid. It is better to just store all the data inside a bloblist
  93  * record.
  94  *
  95  * Each bloblist record is aligned to a 16-byte boundary and follows immediately
  96  * from the last.
  97  *
  98  * @magic: BLOBLIST_MAGIC
  99  * @version: BLOBLIST_VERSION
 100  * @hdr_size: Size of this header, normally sizeof(struct bloblist_hdr). The
 101  *      first bloblist_rec starts at this offset from the start of the header
 102  * @flags: Space for BLOBLISTF... flags (none yet)
 103  * @size: Total size of the bloblist (non-zero if valid) including this header.
 104  *      The bloblist extends for this many bytes from the start of this header.
 105  *      When adding new records, the bloblist can grow up to this size.
 106  * @alloced: Total size allocated so far for this bloblist. This starts out as
 107  *      sizeof(bloblist_hdr) since we need at least that much space to store a
 108  *      valid bloblist
 109  * @spare: Spare space (for future use)
 110  * @chksum: CRC32 for the entire bloblist allocated area. Since any of the
 111  *      blobs can be altered after being created, this checksum is only valid
 112  *      when the bloblist is finalised before jumping to the next stage of boot.
 113  *      Note that chksum is last to make it easier to exclude it from the
 114  *      checksum calculation.
 115  */
 116 struct bloblist_hdr {
 117         u32 magic;
 118         u32 version;
 119         u32 hdr_size;
 120         u32 flags;
 121
 122         u32 size;
 123         u32 alloced;
 124         u32 spare;
 125         u32 chksum;
 126 };
 127
 128 /**
 129  * struct bloblist_rec - record for the bloblist
 130  *
 131  * The bloblist contains a number of records each consisting of this record
 132  * structure followed by the data contained. Each records is 16-byte aligned.
 133  *
 134  * NOTE: Only exported for testing purposes. Do not use this struct.
 135  *
 136  * @tag: Tag indicating what the record contains
 137  * @hdr_size: Size of this header, normally sizeof(struct bloblist_rec). The
 138  *      record's data starts at this offset from the start of the record
 139  * @size: Size of record in bytes, excluding the header size. This does not
 140  *      need to be aligned (e.g. 3 is OK).
 141  * @spare: Spare space for other things
 142  */
 143 struct bloblist_rec {
 144         u32 tag;
 145         u32 hdr_size;
 146         u32 size;
 147         u32 spare;
 148 };
 149
 150 /* access CONFIG_BLOBLIST_ADDR, dealing with it possibly not being defined */
 151 static inline ulong bloblist_addr(void)
 152 {
 153 #ifdef CONFIG_BLOBLIST_FIXED
 154         return CONFIG_BLOBLIST_ADDR;
 155 #else
 156         return 0;
 157 #endif
 158 }
 159
 160 /**
 161  * bloblist_check_magic() - return a bloblist if the magic matches
 162  *
 163  * @addr: Address to check
 164  * Return: pointer to bloblist, if the magic matches, else NULL
 165  */
 166 static inline void *bloblist_check_magic(ulong addr)
 167 {
 168         u32 *ptr;
 169
 170         if (!addr)
 171                 return NULL;
 172         ptr = map_sysmem(addr, 0);
 173         if (*ptr != BLOBLIST_MAGIC)
 174                 return NULL;
 175
 176         return ptr;
 177 }
 178
 179 /**
 180  * bloblist_find() - Find a blob
 181  *
 182  * Searches the bloblist and returns the blob with the matching tag
 183  *
 184  * @tag:        Tag to search for (enum bloblist_tag_t)
 185  * @size:       Expected size of the blob, or 0 for any size
 186  * Return: pointer to blob if found, or NULL if not found, or a blob was found
 187  * but it is the wrong size
 188  */
 189 void *bloblist_find(uint tag, int size);
 190
 191 /**
 192  * bloblist_add() - Add a new blob
 193  *
 194  * Add a new blob to the bloblist
 195  *
 196  * This should only be called if you konw there is no existing blob for a
 197  * particular tag. It is typically safe to call in the first phase of U-Boot
 198  * (e.g. TPL or SPL). After that, bloblist_ensure() should be used instead.
 199  *
 200  * @tag:        Tag to add (enum bloblist_tag_t)
 201  * @size:       Size of the blob
 202  * @align:      Alignment of the blob (in bytes), 0 for default
 203  * Return: pointer to the newly added block, or NULL if there is not enough
 204  * space for the blob
 205  */
 206 void *bloblist_add(uint tag, int size, int align);
 207
 208 /**
 209  * bloblist_ensure_size() - Find or add a blob
 210  *
 211  * Find an existing blob, or add a new one if not found
 212  *
 213  * @tag:        Tag to add (enum bloblist_tag_t)
 214  * @size:       Size of the blob
 215  * @blobp:      Returns a pointer to blob on success
 216  * @align:      Alignment of the blob (in bytes), 0 for default
 217  * Return: 0 if OK, -ENOSPC if it is missing and could not be added due to lack
 218  * of space, or -ESPIPE it exists but has the wrong size
 219  */
 220 int bloblist_ensure_size(uint tag, int size, int align, void **blobp);
 221
 222 /**
 223  * bloblist_ensure() - Find or add a blob
 224  *
 225  * Find an existing blob, or add a new one if not found
 226  *
 227  * @tag:        Tag to add (enum bloblist_tag_t)
 228  * @size:       Size of the blob
 229  * Return: pointer to blob, or NULL if it is missing and could not be added due
 230  * to lack of space, or it exists but has the wrong size
 231  */
 232 void *bloblist_ensure(uint tag, int size);
 233
 234 /**
 235  * bloblist_ensure_size_ret() - Find or add a blob
 236  *
 237  * Find an existing blob, or add a new one if not found
 238  *
 239  * @tag:        Tag to add (enum bloblist_tag_t)
 240  * @sizep:      Size of the blob to create; returns size of actual blob
 241  * @blobp:      Returns a pointer to blob on success
 242  * Return: 0 if OK, -ENOSPC if it is missing and could not be added due to lack
 243  * of space
 244  */
 245 int bloblist_ensure_size_ret(uint tag, int *sizep, void **blobp);
 246
 247 /**
 248  * bloblist_resize() - resize a blob
 249  *
 250  * Any blobs above this one are relocated up or down. The resized blob remains
 251  * in the same place.
 252  *
 253  * @tag:        Tag to add (enum bloblist_tag_t)
 254  * @new_size:   New size of the blob (>0 to expand, <0 to contract)
 255  * Return: 0 if OK, -ENOSPC if the bloblist does not have enough space, -ENOENT
 256  * if the tag is not found
 257  */
 258 int bloblist_resize(uint tag, int new_size);
 259
 260 /**
 261  * bloblist_new() - Create a new, empty bloblist of a given size
 262  *
 263  * @addr: Address of bloblist
 264  * @size: Initial size for bloblist
 265  * @flags: Flags to use for bloblist
 266  * Return: 0 if OK, -EFAULT if addr is not aligned correctly, -ENOSPC is the
 267  * area is not large enough
 268  */
 269 int bloblist_new(ulong addr, uint size, uint flags);
 270
 271 /**
 272  * bloblist_check() - Check if a bloblist exists
 273  *
 274  * @addr: Address of bloblist
 275  * @size: Expected size of blobsize, or 0 to detect the size
 276  * Return: 0 if OK, -ENOENT if the magic number doesn't match (indicating that
 277  * there problem is no bloblist at the given address), -EPROTONOSUPPORT
 278  * if the version does not match, -EIO if the checksum does not match,
 279  * -EFBIG if the expected size does not match the detected size, -ENOSPC
 280  * if the size is not large enough to hold the headers
 281  */
 282 int bloblist_check(ulong addr, uint size);
 283
 284 /**
 285  * bloblist_finish() - Set up the bloblist for the next U-Boot part
 286  *
 287  * This sets the correct checksum for the bloblist. This ensures that the
 288  * bloblist will be detected correctly by the next phase of U-Boot.
 289  *
 290  * Return: 0
 291  */
 292 int bloblist_finish(void);
 293
 294 /**
 295  * bloblist_get_stats() - Get information about the bloblist
 296  *
 297  * This returns useful information about the bloblist
 298  *
 299  * @basep: Returns base address of bloblist
 300  * @sizep: Returns the number of bytes used in the bloblist
 301  * @allocedp: Returns the total space allocated to the bloblist
 302  */
 303 void bloblist_get_stats(ulong *basep, ulong *sizep, ulong *allocedp);
 304
 305 /**
 306  * bloblist_get_base() - Get the base address of the bloblist
 307  *
 308  * Return: base address of bloblist
 309  */
 310 ulong bloblist_get_base(void);
 311
 312 /**
 313  * bloblist_get_size() - Get the size of the bloblist
 314  *
 315  * Return: the size in bytes
 316  */
 317 ulong bloblist_get_size(void);
 318
 319 /**
 320  * bloblist_show_stats() - Show information about the bloblist
 321  *
 322  * This shows useful information about the bloblist on the console
 323  */
 324 void bloblist_show_stats(void);
 325
 326 /**
 327  * bloblist_show_list() - Show a list of blobs in the bloblist
 328  *
 329  * This shows a list of blobs, showing their address, size and tag.
 330  */
 331 void bloblist_show_list(void);
 332
 333 /**
 334  * bloblist_tag_name() - Get the name for a tag
 335  *
 336  * @tag: Tag to check
 337  * Return: name of tag, or "invalid" if an invalid tag is provided
 338  */
 339 const char *bloblist_tag_name(enum bloblist_tag_t tag);
 340
 341 /**
 342  * bloblist_reloc() - Relocate the bloblist and optionally resize it
 343  *
 344  * @to: Pointer to new bloblist location (must not overlap old location)
 345  * @to_size: New size for bloblist (must be larger than from_size)
 346  * @from: Pointer to bloblist to relocate
 347  * @from_size: Size of bloblist to relocate
 348  */
 349 void bloblist_reloc(void *to, uint to_size, void *from, uint from_size);
 350
 351 /**
 352  * bloblist_init() - Init the bloblist system with a single bloblist
 353  *
 354  * This locates and sets up the blocklist for use.
 355  *
 356  * If CONFIG_BLOBLIST_FIXED is selected, it uses CONFIG_BLOBLIST_ADDR and
 357  * CONFIG_BLOBLIST_SIZE to set up a bloblist for use by U-Boot.
 358  *
 359  * If CONFIG_BLOBLIST_ALLOC is selected, it allocates memory for a bloblist of
 360  * size CONFIG_BLOBLIST_SIZE.
 361  *
 362  * If CONFIG_BLOBLIST_PASSAGE is selected, it uses the bloblist in the incoming
 363  * standard passage. The size is detected automatically so CONFIG_BLOBLIST_SIZE
 364  * can be 0.
 365  *
 366  * Return: 0 if OK, -ve on error
 367  */
 368 int bloblist_init(void);
 369
 370 #endif /* __BLOBLIST_H */