blob: d0e128acf1031cb61488dabb8d190834b24dc4fc [file] [log] [blame]
Simon Glass6c9e3d12022-01-12 19:26:25 -07001/* SPDX-License-Identifier: GPL-2.0+ BSD-3-Clause */
Simon Glass9f407d42018-11-15 18:43:50 -07002/*
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
Simon Glassff3bd492022-01-12 19:26:16 -070016#include <mapmem.h>
17
Simon Glass9f407d42018-11-15 18:43:50 -070018enum {
19 BLOBLIST_VERSION = 0,
20 BLOBLIST_MAGIC = 0xb00757a3,
21 BLOBLIST_ALIGN = 16,
22};
23
Simon Glass4aed2272020-09-19 18:49:26 -060024/* Supported tags - add new ones to tag_name in bloblist.c */
Simon Glass9f407d42018-11-15 18:43:50 -070025enum bloblist_tag_t {
26 BLOBLISTT_NONE = 0,
27
Simon Glassf16ec772022-01-12 19:26:19 -070028 /*
29 * Standard area to allocate blobs used across firmware components, for
30 * things that are very commonly used, particularly in multiple
31 * projects.
32 */
33 BLOBLISTT_AREA_FIRMWARE_TOP = 0x1,
34
35 /* Standard area to allocate blobs used across firmware components */
36 BLOBLISTT_AREA_FIRMWARE = 0x100,
Simon Glass99e555a2020-09-22 12:44:55 -060037 /*
38 * Advanced Configuration and Power Interface Global Non-Volatile
39 * Sleeping table. This forms part of the ACPI tables passed to Linux.
40 */
Simon Glassf16ec772022-01-12 19:26:19 -070041 BLOBLISTT_ACPI_GNVS = 0x100,
42 BLOBLISTT_INTEL_VBT = 0x101, /* Intel Video-BIOS table */
43 BLOBLISTT_TPM2_TCG_LOG = 0x102, /* TPM v2 log space */
44 BLOBLISTT_TCPA_LOG = 0x103, /* TPM log space */
45 BLOBLISTT_ACPI_TABLES = 0x104, /* ACPI tables for x86 */
46 BLOBLISTT_SMBIOS_TABLES = 0x105, /* SMBIOS tables for x86 */
47 BLOBLISTT_VBOOT_CTX = 0x106, /* Chromium OS verified boot context */
Simon Glass4aed2272020-09-19 18:49:26 -060048
Simon Glassf16ec772022-01-12 19:26:19 -070049 /*
50 * Project-specific tags are permitted here. Projects can be open source
51 * or not, but the format of the data must be fuily documented in an
52 * open source project, including all fields, bits, etc. Naming should
53 * be: BLOBLISTT_<project>_<purpose_here>
54 */
55 BLOBLISTT_PROJECT_AREA = 0x8000,
56 BLOBLISTT_U_BOOT_SPL_HANDOFF = 0x8000, /* Hand-off info from SPL */
57
58 /*
59 * Vendor-specific tags are permitted here. Projects can be open source
60 * or not, but the format of the data must be fuily documented in an
61 * open source project, including all fields, bits, etc. Naming should
62 * be BLOBLISTT_<vendor>_<purpose_here>
63 */
64 BLOBLISTT_VENDOR_AREA = 0xc000,
65
66 /* Tags after this are not allocated for now */
67 BLOBLISTT_EXPANSION = 0x10000,
68
69 /*
70 * Tags from here are on reserved for private use within a single
71 * firmware binary (i.e. a single executable or phase of a project).
72 * These tags can be passed between binaries within a local
73 * implementation, but cannot be used in upstream code. Allocate a
74 * tag in one of the areas above if you want that.
75 *
76 * This area may move in future.
77 */
78 BLOBLISTT_PRIVATE_AREA = 0xffff0000,
Simon Glass9f407d42018-11-15 18:43:50 -070079};
80
81/**
82 * struct bloblist_hdr - header for the bloblist
83 *
84 * This is stored at the start of the bloblist which is always on a 16-byte
85 * boundary. Records follow this header. The bloblist normally stays in the
86 * same place in memory as SPL and U-Boot execute, but it can be safely moved
87 * around.
88 *
Simon Glass20a14932022-01-12 19:26:24 -070089 * None of the bloblist headers themselves contain pointers but it is possible
90 * to put pointers inside a bloblist record if desired. This is not encouraged,
Simon Glass9f407d42018-11-15 18:43:50 -070091 * since it can make part of the bloblist inaccessible if the pointer is
92 * no-longer valid. It is better to just store all the data inside a bloblist
93 * record.
94 *
95 * Each bloblist record is aligned to a 16-byte boundary and follows immediately
96 * from the last.
97 *
Simon Glassff3bd492022-01-12 19:26:16 -070098 * @magic: BLOBLIST_MAGIC
Simon Glass9f407d42018-11-15 18:43:50 -070099 * @version: BLOBLIST_VERSION
100 * @hdr_size: Size of this header, normally sizeof(struct bloblist_hdr). The
101 * first bloblist_rec starts at this offset from the start of the header
Simon Glass20a14932022-01-12 19:26:24 -0700102 * @flags: Space for BLOBLISTF... flags (none yet)
Simon Glassfaff5542021-07-05 16:32:54 -0600103 * @size: Total size of the bloblist (non-zero if valid) including this header.
Simon Glass9f407d42018-11-15 18:43:50 -0700104 * The bloblist extends for this many bytes from the start of this header.
Simon Glassfaff5542021-07-05 16:32:54 -0600105 * When adding new records, the bloblist can grow up to this size.
106 * @alloced: Total size allocated so far for this bloblist. This starts out as
Simon Glass9f407d42018-11-15 18:43:50 -0700107 * sizeof(bloblist_hdr) since we need at least that much space to store a
108 * valid bloblist
Simon Glasse9b6b2c2020-09-19 18:49:30 -0600109 * @spare: Spare space (for future use)
Simon Glass9f407d42018-11-15 18:43:50 -0700110 * @chksum: CRC32 for the entire bloblist allocated area. Since any of the
111 * blobs can be altered after being created, this checksum is only valid
112 * when the bloblist is finalised before jumping to the next stage of boot.
Simon Glass20a14932022-01-12 19:26:24 -0700113 * Note that chksum is last to make it easier to exclude it from the
114 * checksum calculation.
Simon Glass9f407d42018-11-15 18:43:50 -0700115 */
116struct bloblist_hdr {
Simon Glassff3bd492022-01-12 19:26:16 -0700117 u32 magic;
Simon Glass9f407d42018-11-15 18:43:50 -0700118 u32 version;
119 u32 hdr_size;
120 u32 flags;
Simon Glass9f407d42018-11-15 18:43:50 -0700121
122 u32 size;
123 u32 alloced;
124 u32 spare;
125 u32 chksum;
126};
127
128/**
129 * struct bloblist_rec - record for the bloblist
130 *
Simon Glass9f407d42018-11-15 18:43:50 -0700131 * The bloblist contains a number of records each consisting of this record
132 * structure followed by the data contained. Each records is 16-byte aligned.
133 *
Simon Glass20a14932022-01-12 19:26:24 -0700134 * NOTE: Only exported for testing purposes. Do not use this struct.
135 *
Simon Glass9f407d42018-11-15 18:43:50 -0700136 * @tag: Tag indicating what the record contains
137 * @hdr_size: Size of this header, normally sizeof(struct bloblist_rec). The
138 * record's data starts at this offset from the start of the record
139 * @size: Size of record in bytes, excluding the header size. This does not
140 * need to be aligned (e.g. 3 is OK).
141 * @spare: Spare space for other things
142 */
143struct bloblist_rec {
144 u32 tag;
145 u32 hdr_size;
146 u32 size;
147 u32 spare;
148};
149
150/**
Simon Glassff3bd492022-01-12 19:26:16 -0700151 * bloblist_check_magic() - return a bloblist if the magic matches
152 *
153 * @addr: Address to check
Simon Glass20a14932022-01-12 19:26:24 -0700154 * Return: pointer to bloblist, if the magic matches, else NULL
Simon Glassff3bd492022-01-12 19:26:16 -0700155 */
156static inline void *bloblist_check_magic(ulong addr)
157{
158 u32 *ptr;
159
160 if (!addr)
161 return NULL;
162 ptr = map_sysmem(addr, 0);
163 if (*ptr != BLOBLIST_MAGIC)
164 return NULL;
165
166 return ptr;
167}
168
169/**
Simon Glass9f407d42018-11-15 18:43:50 -0700170 * bloblist_find() - Find a blob
171 *
172 * Searches the bloblist and returns the blob with the matching tag
173 *
174 * @tag: Tag to search for (enum bloblist_tag_t)
Simon Glasse9b6b2c2020-09-19 18:49:30 -0600175 * @size: Expected size of the blob, or 0 for any size
Simon Glass20a14932022-01-12 19:26:24 -0700176 * Return: pointer to blob if found, or NULL if not found, or a blob was found
177 * but it is the wrong size
Simon Glass9f407d42018-11-15 18:43:50 -0700178 */
179void *bloblist_find(uint tag, int size);
180
181/**
182 * bloblist_add() - Add a new blob
183 *
184 * Add a new blob to the bloblist
185 *
186 * This should only be called if you konw there is no existing blob for a
187 * particular tag. It is typically safe to call in the first phase of U-Boot
188 * (e.g. TPL or SPL). After that, bloblist_ensure() should be used instead.
189 *
190 * @tag: Tag to add (enum bloblist_tag_t)
191 * @size: Size of the blob
Simon Glass4c1497e2020-09-19 18:49:29 -0600192 * @align: Alignment of the blob (in bytes), 0 for default
Simon Glass20a14932022-01-12 19:26:24 -0700193 * Return: pointer to the newly added block, or NULL if there is not enough
194 * space for the blob
Simon Glass9f407d42018-11-15 18:43:50 -0700195 */
Simon Glass4c1497e2020-09-19 18:49:29 -0600196void *bloblist_add(uint tag, int size, int align);
Simon Glass9f407d42018-11-15 18:43:50 -0700197
198/**
199 * bloblist_ensure_size() - Find or add a blob
200 *
201 * Find an existing blob, or add a new one if not found
202 *
203 * @tag: Tag to add (enum bloblist_tag_t)
204 * @size: Size of the blob
205 * @blobp: Returns a pointer to blob on success
Simon Glass4c1497e2020-09-19 18:49:29 -0600206 * @align: Alignment of the blob (in bytes), 0 for default
Simon Glass20a14932022-01-12 19:26:24 -0700207 * Return: 0 if OK, -ENOSPC if it is missing and could not be added due to lack
208 * of space, or -ESPIPE it exists but has the wrong size
Simon Glass9f407d42018-11-15 18:43:50 -0700209 */
Simon Glass4c1497e2020-09-19 18:49:29 -0600210int bloblist_ensure_size(uint tag, int size, int align, void **blobp);
Simon Glass9f407d42018-11-15 18:43:50 -0700211
212/**
213 * bloblist_ensure() - Find or add a blob
214 *
215 * Find an existing blob, or add a new one if not found
216 *
217 * @tag: Tag to add (enum bloblist_tag_t)
218 * @size: Size of the blob
Simon Glass20a14932022-01-12 19:26:24 -0700219 * Return: pointer to blob, or NULL if it is missing and could not be added due
220 * to lack of space, or it exists but has the wrong size
Simon Glass9f407d42018-11-15 18:43:50 -0700221 */
222void *bloblist_ensure(uint tag, int size);
223
224/**
Simon Glass5b044542020-01-27 08:49:50 -0700225 * bloblist_ensure_size_ret() - Find or add a blob
226 *
227 * Find an existing blob, or add a new one if not found
228 *
229 * @tag: Tag to add (enum bloblist_tag_t)
230 * @sizep: Size of the blob to create; returns size of actual blob
231 * @blobp: Returns a pointer to blob on success
Simon Glass20a14932022-01-12 19:26:24 -0700232 * Return: 0 if OK, -ENOSPC if it is missing and could not be added due to lack
233 * of space
Simon Glass5b044542020-01-27 08:49:50 -0700234 */
235int bloblist_ensure_size_ret(uint tag, int *sizep, void **blobp);
236
237/**
Simon Glass1fe59372021-07-05 16:32:53 -0600238 * bloblist_resize() - resize a blob
239 *
240 * Any blobs above this one are relocated up or down. The resized blob remains
241 * in the same place.
242 *
243 * @tag: Tag to add (enum bloblist_tag_t)
244 * @new_size: New size of the blob (>0 to expand, <0 to contract)
Simon Glass20a14932022-01-12 19:26:24 -0700245 * Return: 0 if OK, -ENOSPC if the bloblist does not have enough space, -ENOENT
246 * if the tag is not found
Simon Glass1fe59372021-07-05 16:32:53 -0600247 */
248int bloblist_resize(uint tag, int new_size);
249
250/**
Simon Glass9f407d42018-11-15 18:43:50 -0700251 * bloblist_new() - Create a new, empty bloblist of a given size
252 *
253 * @addr: Address of bloblist
254 * @size: Initial size for bloblist
255 * @flags: Flags to use for bloblist
Simon Glass20a14932022-01-12 19:26:24 -0700256 * Return: 0 if OK, -EFAULT if addr is not aligned correctly, -ENOSPC is the
257 * area is not large enough
Simon Glass9f407d42018-11-15 18:43:50 -0700258 */
259int bloblist_new(ulong addr, uint size, uint flags);
260
261/**
262 * bloblist_check() - Check if a bloblist exists
263 *
264 * @addr: Address of bloblist
265 * @size: Expected size of blobsize, or 0 to detect the size
Simon Glass20a14932022-01-12 19:26:24 -0700266 * Return: 0 if OK, -ENOENT if the magic number doesn't match (indicating that
267 * there problem is no bloblist at the given address), -EPROTONOSUPPORT
268 * if the version does not match, -EIO if the checksum does not match,
269 * -EFBIG if the expected size does not match the detected size, -ENOSPC
270 * if the size is not large enough to hold the headers
Simon Glass9f407d42018-11-15 18:43:50 -0700271 */
272int bloblist_check(ulong addr, uint size);
273
274/**
275 * bloblist_finish() - Set up the bloblist for the next U-Boot part
276 *
277 * This sets the correct checksum for the bloblist. This ensures that the
278 * bloblist will be detected correctly by the next phase of U-Boot.
279 *
Simon Glass20a14932022-01-12 19:26:24 -0700280 * Return: 0
Simon Glass9f407d42018-11-15 18:43:50 -0700281 */
282int bloblist_finish(void);
283
284/**
Simon Glass4aed2272020-09-19 18:49:26 -0600285 * bloblist_get_stats() - Get information about the bloblist
286 *
287 * This returns useful information about the bloblist
Simon Glassfaff5542021-07-05 16:32:54 -0600288 *
289 * @basep: Returns base address of bloblist
290 * @sizep: Returns the number of bytes used in the bloblist
291 * @allocedp: Returns the total space allocated to the bloblist
Simon Glass4aed2272020-09-19 18:49:26 -0600292 */
293void bloblist_get_stats(ulong *basep, ulong *sizep, ulong *allocedp);
294
295/**
Simon Glasse50a24a2022-01-12 19:26:23 -0700296 * bloblist_get_base() - Get the base address of the bloblist
297 *
Simon Glass20a14932022-01-12 19:26:24 -0700298 * Return: base address of bloblist
Simon Glasse50a24a2022-01-12 19:26:23 -0700299 */
300ulong bloblist_get_base(void);
301
302/**
303 * bloblist_get_size() - Get the size of the bloblist
304 *
Simon Glass20a14932022-01-12 19:26:24 -0700305 * Return: the size in bytes
Simon Glasse50a24a2022-01-12 19:26:23 -0700306 */
307ulong bloblist_get_size(void);
308
309/**
Simon Glass4aed2272020-09-19 18:49:26 -0600310 * bloblist_show_stats() - Show information about the bloblist
311 *
312 * This shows useful information about the bloblist on the console
313 */
314void bloblist_show_stats(void);
315
316/**
317 * bloblist_show_list() - Show a list of blobs in the bloblist
318 *
319 * This shows a list of blobs, showing their address, size and tag.
320 */
321void bloblist_show_list(void);
322
323/**
324 * bloblist_tag_name() - Get the name for a tag
325 *
326 * @tag: Tag to check
Simon Glass20a14932022-01-12 19:26:24 -0700327 * Return: name of tag, or "invalid" if an invalid tag is provided
Simon Glass4aed2272020-09-19 18:49:26 -0600328 */
329const char *bloblist_tag_name(enum bloblist_tag_t tag);
330
331/**
Simon Glass9fe06462021-01-13 20:29:43 -0700332 * bloblist_reloc() - Relocate the bloblist and optionally resize it
333 *
334 * @to: Pointer to new bloblist location (must not overlap old location)
Simon Glass20a14932022-01-12 19:26:24 -0700335 * @to_size: New size for bloblist (must be larger than from_size)
Simon Glass9fe06462021-01-13 20:29:43 -0700336 * @from: Pointer to bloblist to relocate
337 * @from_size: Size of bloblist to relocate
338 */
339void bloblist_reloc(void *to, uint to_size, void *from, uint from_size);
340
341/**
Simon Glass9f407d42018-11-15 18:43:50 -0700342 * bloblist_init() - Init the bloblist system with a single bloblist
343 *
Simon Glass20a14932022-01-12 19:26:24 -0700344 * This locates and sets up the blocklist for use.
345 *
346 * If CONFIG_BLOBLIST_FIXED is selected, it uses CONFIG_BLOBLIST_ADDR and
347 * CONFIG_BLOBLIST_SIZE to set up a bloblist for use by U-Boot.
348 *
349 * If CONFIG_BLOBLIST_ALLOC is selected, it allocates memory for a bloblist of
350 * size CONFIG_BLOBLIST_SIZE.
351 *
352 * If CONFIG_BLOBLIST_PASSAGE is selected, it uses the bloblist in the incoming
353 * standard passage. The size is detected automatically so CONFIG_BLOBLIST_SIZE
354 * can be 0.
355 *
356 * Return: 0 if OK, -ve on error
Simon Glass9f407d42018-11-15 18:43:50 -0700357 */
358int bloblist_init(void);
359
360#endif /* __BLOBLIST_H */