blob: 8cdce61187aa668dbdd666286f3aa4f4af93aefb [file] [log] [blame]
Simon Glass9f407d42018-11-15 18:43:50 -07001/* 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
16enum {
17 BLOBLIST_VERSION = 0,
18 BLOBLIST_MAGIC = 0xb00757a3,
19 BLOBLIST_ALIGN = 16,
20};
21
Simon Glass4aed2272020-09-19 18:49:26 -060022/* Supported tags - add new ones to tag_name in bloblist.c */
Simon Glass9f407d42018-11-15 18:43:50 -070023enum bloblist_tag_t {
24 BLOBLISTT_NONE = 0,
25
26 /* Vendor-specific tags are permitted here */
27 BLOBLISTT_EC_HOSTEVENT, /* Chromium OS EC host-event mask */
28 BLOBLISTT_SPL_HANDOFF, /* Hand-off info from SPL */
29 BLOBLISTT_VBOOT_CTX, /* Chromium OS verified boot context */
30 BLOBLISTT_VBOOT_HANDOFF, /* Chromium OS internal handoff info */
Simon Glass99e555a2020-09-22 12:44:55 -060031 /*
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,
Simon Glassc9cc37d2020-09-22 12:45:03 -060036 BLOBLISTT_INTEL_VBT, /* Intel Video-BIOS table */
Simon Glass9179c352020-09-22 12:45:32 -060037 BLOBLISTT_TPM2_TCG_LOG, /* TPM v2 log space */
Simon Glass77bb1c62020-09-22 12:45:33 -060038 BLOBLISTT_TCPA_LOG, /* TPM log space */
Simon Glassd2cb7a22020-11-04 09:57:25 -070039 BLOBLISTT_ACPI_TABLES, /* ACPI tables for x86 */
40 BLOBLISTT_SMBIOS_TABLES, /* SMBIOS tables for x86 */
Simon Glass4aed2272020-09-19 18:49:26 -060041
42 BLOBLISTT_COUNT
Simon Glass9f407d42018-11-15 18:43:50 -070043};
44
45/**
46 * struct bloblist_hdr - header for the bloblist
47 *
48 * This is stored at the start of the bloblist which is always on a 16-byte
49 * boundary. Records follow this header. The bloblist normally stays in the
50 * same place in memory as SPL and U-Boot execute, but it can be safely moved
51 * around.
52 *
53 * None of the bloblist structures contain pointers but it is possible to put
54 * pointers inside a bloblist record if desired. This is not encouraged,
55 * since it can make part of the bloblist inaccessible if the pointer is
56 * no-longer valid. It is better to just store all the data inside a bloblist
57 * record.
58 *
59 * Each bloblist record is aligned to a 16-byte boundary and follows immediately
60 * from the last.
61 *
62 * @version: BLOBLIST_VERSION
63 * @hdr_size: Size of this header, normally sizeof(struct bloblist_hdr). The
64 * first bloblist_rec starts at this offset from the start of the header
65 * @flags: Space for BLOBLISTF_... flags (none yet)
66 * @magic: BLOBLIST_MAGIC
67 * @size: Total size of all records (non-zero if valid) including this header.
68 * The bloblist extends for this many bytes from the start of this header.
69 * @alloced: Total size allocated for this bloblist. When adding new records,
70 * the bloblist can grow up to this size. This starts out as
71 * sizeof(bloblist_hdr) since we need at least that much space to store a
72 * valid bloblist
Simon Glasse9b6b2c2020-09-19 18:49:30 -060073 * @spare: Spare space (for future use)
Simon Glass9f407d42018-11-15 18:43:50 -070074 * @chksum: CRC32 for the entire bloblist allocated area. Since any of the
75 * blobs can be altered after being created, this checksum is only valid
76 * when the bloblist is finalised before jumping to the next stage of boot.
77 * Note: @chksum is last to make it easier to exclude it from the checksum
78 * calculation.
79 */
80struct bloblist_hdr {
81 u32 version;
82 u32 hdr_size;
83 u32 flags;
84 u32 magic;
85
86 u32 size;
87 u32 alloced;
88 u32 spare;
89 u32 chksum;
90};
91
92/**
93 * struct bloblist_rec - record for the bloblist
94 *
95 * NOTE: Only exported for testing purposes. Do not use this struct.
96 *
97 * The bloblist contains a number of records each consisting of this record
98 * structure followed by the data contained. Each records is 16-byte aligned.
99 *
100 * @tag: Tag indicating what the record contains
101 * @hdr_size: Size of this header, normally sizeof(struct bloblist_rec). The
102 * record's data starts at this offset from the start of the record
103 * @size: Size of record in bytes, excluding the header size. This does not
104 * need to be aligned (e.g. 3 is OK).
105 * @spare: Spare space for other things
106 */
107struct bloblist_rec {
108 u32 tag;
109 u32 hdr_size;
110 u32 size;
111 u32 spare;
112};
113
114/**
115 * bloblist_find() - Find a blob
116 *
117 * Searches the bloblist and returns the blob with the matching tag
118 *
119 * @tag: Tag to search for (enum bloblist_tag_t)
Simon Glasse9b6b2c2020-09-19 18:49:30 -0600120 * @size: Expected size of the blob, or 0 for any size
Simon Glass9f407d42018-11-15 18:43:50 -0700121 * @return pointer to blob if found, or NULL if not found, or a blob was found
122 * but it is the wrong size
123 */
124void *bloblist_find(uint tag, int size);
125
126/**
127 * bloblist_add() - Add a new blob
128 *
129 * Add a new blob to the bloblist
130 *
131 * This should only be called if you konw there is no existing blob for a
132 * particular tag. It is typically safe to call in the first phase of U-Boot
133 * (e.g. TPL or SPL). After that, bloblist_ensure() should be used instead.
134 *
135 * @tag: Tag to add (enum bloblist_tag_t)
136 * @size: Size of the blob
Simon Glass4c1497e2020-09-19 18:49:29 -0600137 * @align: Alignment of the blob (in bytes), 0 for default
Simon Glass9f407d42018-11-15 18:43:50 -0700138 * @return pointer to the newly added block, or NULL if there is not enough
139 * space for the blob
140 */
Simon Glass4c1497e2020-09-19 18:49:29 -0600141void *bloblist_add(uint tag, int size, int align);
Simon Glass9f407d42018-11-15 18:43:50 -0700142
143/**
144 * bloblist_ensure_size() - Find or add a blob
145 *
146 * Find an existing blob, or add a new one if not found
147 *
148 * @tag: Tag to add (enum bloblist_tag_t)
149 * @size: Size of the blob
150 * @blobp: Returns a pointer to blob on success
Simon Glass4c1497e2020-09-19 18:49:29 -0600151 * @align: Alignment of the blob (in bytes), 0 for default
Simon Glass9f407d42018-11-15 18:43:50 -0700152 * @return 0 if OK, -ENOSPC if it is missing and could not be added due to lack
153 * of space, or -ESPIPE it exists but has the wrong size
154 */
Simon Glass4c1497e2020-09-19 18:49:29 -0600155int bloblist_ensure_size(uint tag, int size, int align, void **blobp);
Simon Glass9f407d42018-11-15 18:43:50 -0700156
157/**
158 * bloblist_ensure() - Find or add a blob
159 *
160 * Find an existing blob, or add a new one if not found
161 *
162 * @tag: Tag to add (enum bloblist_tag_t)
163 * @size: Size of the blob
164 * @return pointer to blob, or NULL if it is missing and could not be added due
165 * to lack of space, or it exists but has the wrong size
166 */
167void *bloblist_ensure(uint tag, int size);
168
169/**
Simon Glass5b044542020-01-27 08:49:50 -0700170 * bloblist_ensure_size_ret() - Find or add a blob
171 *
172 * Find an existing blob, or add a new one if not found
173 *
174 * @tag: Tag to add (enum bloblist_tag_t)
175 * @sizep: Size of the blob to create; returns size of actual blob
176 * @blobp: Returns a pointer to blob on success
177 * @return 0 if OK, -ENOSPC if it is missing and could not be added due to lack
178 * of space
179 */
180int bloblist_ensure_size_ret(uint tag, int *sizep, void **blobp);
181
182/**
Simon Glass9f407d42018-11-15 18:43:50 -0700183 * bloblist_new() - Create a new, empty bloblist of a given size
184 *
185 * @addr: Address of bloblist
186 * @size: Initial size for bloblist
187 * @flags: Flags to use for bloblist
188 * @return 0 if OK, -EFAULT if addr is not aligned correctly, -ENOSPC is the
189 * area is not large enough
190 */
191int bloblist_new(ulong addr, uint size, uint flags);
192
193/**
194 * bloblist_check() - Check if a bloblist exists
195 *
196 * @addr: Address of bloblist
197 * @size: Expected size of blobsize, or 0 to detect the size
198 * @return 0 if OK, -ENOENT if the magic number doesn't match (indicating that
199 * there problem is no bloblist at the given address), -EPROTONOSUPPORT
200 * if the version does not match, -EIO if the checksum does not match,
Simon Glass02247c12020-01-27 08:49:51 -0700201 * -EFBIG if the expected size does not match the detected size, -ENOSPC
202 * if the size is not large enough to hold the headers
Simon Glass9f407d42018-11-15 18:43:50 -0700203 */
204int bloblist_check(ulong addr, uint size);
205
206/**
207 * bloblist_finish() - Set up the bloblist for the next U-Boot part
208 *
209 * This sets the correct checksum for the bloblist. This ensures that the
210 * bloblist will be detected correctly by the next phase of U-Boot.
211 *
212 * @return 0
213 */
214int bloblist_finish(void);
215
216/**
Simon Glass4aed2272020-09-19 18:49:26 -0600217 * bloblist_get_stats() - Get information about the bloblist
218 *
219 * This returns useful information about the bloblist
220 */
221void bloblist_get_stats(ulong *basep, ulong *sizep, ulong *allocedp);
222
223/**
224 * bloblist_show_stats() - Show information about the bloblist
225 *
226 * This shows useful information about the bloblist on the console
227 */
228void bloblist_show_stats(void);
229
230/**
231 * bloblist_show_list() - Show a list of blobs in the bloblist
232 *
233 * This shows a list of blobs, showing their address, size and tag.
234 */
235void bloblist_show_list(void);
236
237/**
238 * bloblist_tag_name() - Get the name for a tag
239 *
240 * @tag: Tag to check
241 * @return name of tag, or "invalid" if an invalid tag is provided
242 */
243const char *bloblist_tag_name(enum bloblist_tag_t tag);
244
245/**
Simon Glass9f407d42018-11-15 18:43:50 -0700246 * bloblist_init() - Init the bloblist system with a single bloblist
247 *
248 * This uses CONFIG_BLOBLIST_ADDR and CONFIG_BLOBLIST_SIZE to set up a bloblist
249 * for use by U-Boot.
250 */
251int bloblist_init(void);
252
253#endif /* __BLOBLIST_H */