bloblist.h 7.0 KB

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