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