bloblist.h 15 KB

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