blob: 85144010abea9e00edf67fddf288373e8f0303fc [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
22enum 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 */
67struct 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 */
94struct 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 */
111void *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 */
127void *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 */
140int 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 */
152void *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 */
163int 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 */
175int 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 */
185int 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 */
193int bloblist_init(void);
194
195#endif /* __BLOBLIST_H */