bloblist.h 11 KB

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