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_new() - Create a new, empty bloblist of a given size 156 * 157 * @addr: Address of bloblist 158 * @size: Initial size for bloblist 159 * @flags: Flags to use for bloblist 160 * @return 0 if OK, -EFAULT if addr is not aligned correctly, -ENOSPC is the 161 * area is not large enough 162 */ 163 int bloblist_new(ulong addr, uint size, uint flags); 164 165 /** 166 * bloblist_check() - Check if a bloblist exists 167 * 168 * @addr: Address of bloblist 169 * @size: Expected size of blobsize, or 0 to detect the size 170 * @return 0 if OK, -ENOENT if the magic number doesn't match (indicating that 171 * there problem is no bloblist at the given address), -EPROTONOSUPPORT 172 * if the version does not match, -EIO if the checksum does not match, 173 * -EFBIG if the expected size does not match the detected size 174 */ 175 int bloblist_check(ulong addr, uint size); 176 177 /** 178 * bloblist_finish() - Set up the bloblist for the next U-Boot part 179 * 180 * This sets the correct checksum for the bloblist. This ensures that the 181 * bloblist will be detected correctly by the next phase of U-Boot. 182 * 183 * @return 0 184 */ 185 int bloblist_finish(void); 186 187 /** 188 * bloblist_init() - Init the bloblist system with a single bloblist 189 * 190 * This uses CONFIG_BLOBLIST_ADDR and CONFIG_BLOBLIST_SIZE to set up a bloblist 191 * for use by U-Boot. 192 */ 193 int bloblist_init(void); 194 195 #endif /* __BLOBLIST_H */ 196