blob: 7fbdd622bcf663c00b5cf58622fc70fd87fb5eca [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 *
Simon Glass68ff6d32022-03-13 16:22:48 -06006 * It consists of a list of blobs of data, tagged with their owner / contents.
7 * The list resides in memory and can be updated by SPL, U-Boot, etc.
8 *
9 * Design goals for bloblist:
10 *
11 * 1. Small and efficient structure. This avoids UUIDs or 16-byte name fields,
12 * since a 32-bit tag provides enough space for all the tags we will even need.
13 * If UUIDs are desired, they can be added inside a particular blob.
14 *
15 * 2. Avoids use of pointers, so the structure can be relocated in memory. The
16 * data in each blob is inline, rather than using pointers.
17 *
18 * 3. Bloblist is designed to start small in TPL or SPL, when only a few things
19 * are needed, like the memory size or whether console output should be enabled.
20 * Then it can grow in U-Boot proper, e.g. to include space for ACPI tables.
21 *
22 * 4. The bloblist structure is simple enough that it can be implemented in a
23 * small amount of C code. The API does not require use of strings or UUIDs,
24 * which would add to code size. For Thumb-2 the code size needed in SPL is
25 * approximately 940 bytes (e.g. for chromebook_bob).
26 *
Simon Glassb6e83822023-12-27 13:07:07 -080027 * 5. Bloblist uses 8-byte alignment internally and is designed to start on a
28 * 8-byte boundary. Its headers are 8 bytes long. It is possible to achieve
29 * larger alignment (e.g. 16 bytes) by adding a dummy header, For use in SPL and
30 * TPL the alignment can be relaxed, since it can be relocated to an aligned
31 * address in U-Boot proper.
Simon Glass68ff6d32022-03-13 16:22:48 -060032 *
33 * 6. Bloblist is designed to be passed to Linux as reserved memory. While linux
34 * doesn't understand the bloblist header, it can be passed the indivdual blobs.
35 * For example, ACPI tables can reside in a blob and the address of those is
36 * passed to Linux, without Linux ever being away of the existence of a
37 * bloblist. Having all the blobs contiguous in memory simplifies the
38 * reserved-memory space.
39 *
40 * 7. Bloblist tags are defined in the enum below. There is an area for
41 * project-specific stuff (e.g. U-Boot, TF-A) and vendor-specific stuff, e.g.
42 * something used only on a particular SoC. There is also a private area for
43 * temporary, local use.
44 *
45 * 8. Bloblist includes a simple checksum, so that each boot phase can update
46 * this and allow the next phase to check that all is well. While the bloblist
47 * is small, this is quite cheap to calculate. When it grows (e.g. in U-Boot\
48 * proper), the CPU is likely running faster, so it is not prohibitive. Having
49 * said that, U-Boot is often the last phase that uses bloblist, so calculating
50 * the checksum there may not be necessary.
51 *
52 * 9. It would be possible to extend bloblist to support a non-contiguous
53 * structure, e.g. by creating a blob type that points to the next bloblist.
54 * This does not seem necessary for now. It adds complexity and code. We can
55 * always just copy it.
56 *
57 * 10. Bloblist is designed for simple structures, those that can be defined by
58 * a single C struct. More complex structures should be passed in a device tree.
59 * There are some exceptions, chiefly the various binary structures that Intel
60 * is fond of creating. But device tree provides a dictionary-type format which
61 * is fairly efficient (for use in U-Boot proper and Linux at least), along with
62 * a schema and a good set of tools. New formats should be designed around
63 * device tree rather than creating new binary formats, unless they are needed
64 * early in boot (where libfdt's 3KB of overhead is too large) and are trival
65 * enough to be described by a C struct.
Simon Glass9f407d42018-11-15 18:43:50 -070066 *
67 * Copyright 2018 Google, Inc
68 * Written by Simon Glass <sjg@chromium.org>
Simon Glasse266d272023-12-27 13:07:10 -080069 * Adjusted July 2023 to match Firmware handoff specification, Release 0.9
Simon Glass9f407d42018-11-15 18:43:50 -070070 */
71
72#ifndef __BLOBLIST_H
73#define __BLOBLIST_H
74
Simon Glassff3bd492022-01-12 19:26:16 -070075#include <mapmem.h>
76
Simon Glass9f407d42018-11-15 18:43:50 -070077enum {
Simon Glass0b9f77f2023-12-27 13:07:02 -080078 BLOBLIST_VERSION = 1,
Simon Glass5a53e562023-12-27 13:07:01 -080079 BLOBLIST_MAGIC = 0x4a0fb10b,
Simon Glass1a2e02f2023-12-27 13:07:00 -080080
Raymond Mao1c4751f2024-02-03 08:36:20 -080081 /*
82 * FIXME:
83 * Register convention version should be placed into a higher byte
84 * https://github.com/FirmwareHandoff/firmware_handoff/issues/32
85 */
86 BLOBLIST_REGCONV_VER = 1 << 24,
87
Simon Glassb6e83822023-12-27 13:07:07 -080088 BLOBLIST_BLOB_ALIGN_LOG2 = 3,
89 BLOBLIST_BLOB_ALIGN = 1 << BLOBLIST_BLOB_ALIGN_LOG2,
90
Simon Glass1a2e02f2023-12-27 13:07:00 -080091 BLOBLIST_ALIGN_LOG2 = 3,
92 BLOBLIST_ALIGN = 1 << BLOBLIST_ALIGN_LOG2,
Simon Glass9f407d42018-11-15 18:43:50 -070093};
94
Simon Glass4aed2272020-09-19 18:49:26 -060095/* Supported tags - add new ones to tag_name in bloblist.c */
Simon Glass9f407d42018-11-15 18:43:50 -070096enum bloblist_tag_t {
Simon Glasse748e4b2023-12-27 13:06:59 -080097 BLOBLISTT_VOID = 0,
Simon Glass9f407d42018-11-15 18:43:50 -070098
Simon Glassf16ec772022-01-12 19:26:19 -070099 /*
100 * Standard area to allocate blobs used across firmware components, for
101 * things that are very commonly used, particularly in multiple
102 * projects.
103 */
104 BLOBLISTT_AREA_FIRMWARE_TOP = 0x1,
Simon Glasse748e4b2023-12-27 13:06:59 -0800105 /*
106 * Devicetree for use by firmware. On some platforms this is passed to
107 * the OS also
108 */
109 BLOBLISTT_CONTROL_FDT = 1,
110 BLOBLISTT_HOB_BLOCK = 2,
111 BLOBLISTT_HOB_LIST = 3,
112 BLOBLISTT_ACPI_TABLES = 4,
113 BLOBLISTT_TPM_EVLOG = 5,
114 BLOBLISTT_TPM_CRB_BASE = 6,
Simon Glassf16ec772022-01-12 19:26:19 -0700115
116 /* Standard area to allocate blobs used across firmware components */
Simon Glasse748e4b2023-12-27 13:06:59 -0800117 BLOBLISTT_AREA_FIRMWARE = 0x10,
118 BLOBLISTT_TPM2_TCG_LOG = 0x10, /* TPM v2 log space */
119 BLOBLISTT_TCPA_LOG = 0x11, /* TPM log space */
Simon Glass99e555a2020-09-22 12:44:55 -0600120 /*
121 * Advanced Configuration and Power Interface Global Non-Volatile
122 * Sleeping table. This forms part of the ACPI tables passed to Linux.
123 */
Simon Glasse748e4b2023-12-27 13:06:59 -0800124 BLOBLISTT_ACPI_GNVS = 0x12,
Simon Glass4aed2272020-09-19 18:49:26 -0600125
Simon Glasse748e4b2023-12-27 13:06:59 -0800126 /* Standard area to allocate blobs used for Trusted Firmware */
127 BLOBLISTT_AREA_TF = 0x100,
128 BLOBLISTT_OPTEE_PAGABLE_PART = 0x100,
Simon Glassf16ec772022-01-12 19:26:19 -0700129
Simon Glasse748e4b2023-12-27 13:06:59 -0800130 /* Other standard area to allocate blobs */
131 BLOBLISTT_AREA_OTHER = 0x200,
132 BLOBLISTT_INTEL_VBT = 0x200, /* Intel Video-BIOS table */
133 BLOBLISTT_SMBIOS_TABLES = 0x201, /* SMBIOS tables for x86 */
134 BLOBLISTT_VBOOT_CTX = 0x202, /* Chromium OS verified boot context */
Simon Glassf16ec772022-01-12 19:26:19 -0700135
136 /*
137 * Tags from here are on reserved for private use within a single
138 * firmware binary (i.e. a single executable or phase of a project).
139 * These tags can be passed between binaries within a local
140 * implementation, but cannot be used in upstream code. Allocate a
141 * tag in one of the areas above if you want that.
142 *
Simon Glasse748e4b2023-12-27 13:06:59 -0800143 * Project-specific tags are permitted here. Projects can be open source
144 * or not, but the format of the data must be fuily documented in an
145 * open source project, including all fields, bits, etc. Naming should
146 * be: BLOBLISTT_<project>_<purpose_here>
147 *
148 * Vendor-specific tags are also permitted. Projects can be open source
149 * or not, but the format of the data must be fuily documented in an
150 * open source project, including all fields, bits, etc. Naming should
151 * be BLOBLISTT_<vendor>_<purpose_here>
Simon Glassf16ec772022-01-12 19:26:19 -0700152 */
Simon Glasse748e4b2023-12-27 13:06:59 -0800153 BLOBLISTT_PRIVATE_AREA = 0xfff000,
154 BLOBLISTT_U_BOOT_SPL_HANDOFF = 0xfff000, /* Hand-off info from SPL */
155 BLOBLISTT_VBE = 0xfff001, /* VBE per-phase state */
156 BLOBLISTT_U_BOOT_VIDEO = 0xfff002, /* Video info from SPL */
Simon Glass9f407d42018-11-15 18:43:50 -0700157};
158
159/**
160 * struct bloblist_hdr - header for the bloblist
161 *
162 * This is stored at the start of the bloblist which is always on a 16-byte
163 * boundary. Records follow this header. The bloblist normally stays in the
164 * same place in memory as SPL and U-Boot execute, but it can be safely moved
165 * around.
166 *
Simon Glass20a14932022-01-12 19:26:24 -0700167 * None of the bloblist headers themselves contain pointers but it is possible
168 * to put pointers inside a bloblist record if desired. This is not encouraged,
Simon Glass9f407d42018-11-15 18:43:50 -0700169 * since it can make part of the bloblist inaccessible if the pointer is
170 * no-longer valid. It is better to just store all the data inside a bloblist
171 * record.
172 *
173 * Each bloblist record is aligned to a 16-byte boundary and follows immediately
174 * from the last.
175 *
Simon Glassff3bd492022-01-12 19:26:16 -0700176 * @magic: BLOBLIST_MAGIC
Simon Glassb86b2d92023-12-27 13:07:08 -0800177 * @chksum: checksum for the entire bloblist allocated area. Since any of the
178 * blobs can be altered after being created, this checksum is only valid
179 * when the bloblist is finalized before jumping to the next stage of boot.
180 * This is the value needed to make all checksummed bytes sum to 0
Simon Glass9f407d42018-11-15 18:43:50 -0700181 * @version: BLOBLIST_VERSION
182 * @hdr_size: Size of this header, normally sizeof(struct bloblist_hdr). The
183 * first bloblist_rec starts at this offset from the start of the header
Simon Glassb86b2d92023-12-27 13:07:08 -0800184 * @align_log2: Power of two of the maximum alignment required by this list
185 * @used_size: Size allocated so far for this bloblist. This starts out as
Simon Glass9f407d42018-11-15 18:43:50 -0700186 * sizeof(bloblist_hdr) since we need at least that much space to store a
187 * valid bloblist
Simon Glassb86b2d92023-12-27 13:07:08 -0800188 * @total_size: The number of total bytes that the bloblist can occupy.
189 * Any blob producer must check if there is sufficient space before adding
190 * a record to the bloblist.
191 * @flags: Space for BLOBLISTF... flags (none yet)
Simon Glasse9b6b2c2020-09-19 18:49:30 -0600192 * @spare: Spare space (for future use)
Simon Glass9f407d42018-11-15 18:43:50 -0700193 */
194struct bloblist_hdr {
Simon Glassff3bd492022-01-12 19:26:16 -0700195 u32 magic;
Simon Glassb86b2d92023-12-27 13:07:08 -0800196 u8 chksum;
197 u8 version;
198 u8 hdr_size;
199 u8 align_log2;
200 u32 used_size;
201 u32 total_size;
Simon Glass9f407d42018-11-15 18:43:50 -0700202 u32 flags;
Simon Glass9f407d42018-11-15 18:43:50 -0700203 u32 spare;
Simon Glass9f407d42018-11-15 18:43:50 -0700204};
205
206/**
207 * struct bloblist_rec - record for the bloblist
208 *
Simon Glass9f407d42018-11-15 18:43:50 -0700209 * The bloblist contains a number of records each consisting of this record
210 * structure followed by the data contained. Each records is 16-byte aligned.
211 *
Simon Glass20a14932022-01-12 19:26:24 -0700212 * NOTE: Only exported for testing purposes. Do not use this struct.
213 *
Simon Glassb6e83822023-12-27 13:07:07 -0800214 * @tag_and_hdr_size: Tag indicating what the record contains (bottom 24 bits), and
215 * size of this header (top 8 bits), normally sizeof(struct bloblist_rec).
216 * The record's data starts at this offset from the start of the record
Simon Glass9f407d42018-11-15 18:43:50 -0700217 * @size: Size of record in bytes, excluding the header size. This does not
218 * need to be aligned (e.g. 3 is OK).
Simon Glass9f407d42018-11-15 18:43:50 -0700219 */
220struct bloblist_rec {
Simon Glassb6e83822023-12-27 13:07:07 -0800221 u32 tag_and_hdr_size;
Simon Glass9f407d42018-11-15 18:43:50 -0700222 u32 size;
Simon Glassb6e83822023-12-27 13:07:07 -0800223};
224
225enum {
226 BLOBLISTR_TAG_SHIFT = 0,
227 BLOBLISTR_TAG_MASK = 0xffffffU << BLOBLISTR_TAG_SHIFT,
228 BLOBLISTR_HDR_SIZE_SHIFT = 24,
229 BLOBLISTR_HDR_SIZE_MASK = 0xffU << BLOBLISTR_HDR_SIZE_SHIFT,
230
231 BLOBLIST_HDR_SIZE = sizeof(struct bloblist_hdr),
232 BLOBLIST_REC_HDR_SIZE = sizeof(struct bloblist_rec),
Simon Glass9f407d42018-11-15 18:43:50 -0700233};
234
235/**
Simon Glassff3bd492022-01-12 19:26:16 -0700236 * bloblist_check_magic() - return a bloblist if the magic matches
237 *
238 * @addr: Address to check
Simon Glass20a14932022-01-12 19:26:24 -0700239 * Return: pointer to bloblist, if the magic matches, else NULL
Simon Glassff3bd492022-01-12 19:26:16 -0700240 */
241static inline void *bloblist_check_magic(ulong addr)
242{
243 u32 *ptr;
244
245 if (!addr)
246 return NULL;
247 ptr = map_sysmem(addr, 0);
248 if (*ptr != BLOBLIST_MAGIC)
249 return NULL;
250
251 return ptr;
252}
253
254/**
Simon Glass9f407d42018-11-15 18:43:50 -0700255 * bloblist_find() - Find a blob
256 *
257 * Searches the bloblist and returns the blob with the matching tag
258 *
259 * @tag: Tag to search for (enum bloblist_tag_t)
Simon Glasse9b6b2c2020-09-19 18:49:30 -0600260 * @size: Expected size of the blob, or 0 for any size
Simon Glass20a14932022-01-12 19:26:24 -0700261 * Return: pointer to blob if found, or NULL if not found, or a blob was found
262 * but it is the wrong size
Simon Glass9f407d42018-11-15 18:43:50 -0700263 */
264void *bloblist_find(uint tag, int size);
265
266/**
267 * bloblist_add() - Add a new blob
268 *
269 * Add a new blob to the bloblist
270 *
271 * This should only be called if you konw there is no existing blob for a
272 * particular tag. It is typically safe to call in the first phase of U-Boot
273 * (e.g. TPL or SPL). After that, bloblist_ensure() should be used instead.
274 *
275 * @tag: Tag to add (enum bloblist_tag_t)
276 * @size: Size of the blob
Simon Glass1a2e02f2023-12-27 13:07:00 -0800277 * @align_log2: Alignment of the blob (in bytes log2), 0 for default
Simon Glass20a14932022-01-12 19:26:24 -0700278 * Return: pointer to the newly added block, or NULL if there is not enough
279 * space for the blob
Simon Glass9f407d42018-11-15 18:43:50 -0700280 */
Simon Glass1a2e02f2023-12-27 13:07:00 -0800281void *bloblist_add(uint tag, int size, int align_log2);
Simon Glass9f407d42018-11-15 18:43:50 -0700282
283/**
284 * bloblist_ensure_size() - Find or add a blob
285 *
286 * Find an existing blob, or add a new one if not found
287 *
288 * @tag: Tag to add (enum bloblist_tag_t)
289 * @size: Size of the blob
290 * @blobp: Returns a pointer to blob on success
Simon Glass1a2e02f2023-12-27 13:07:00 -0800291 * @align_log2: Alignment of the blob (in bytes log2), 0 for default
Simon Glass20a14932022-01-12 19:26:24 -0700292 * Return: 0 if OK, -ENOSPC if it is missing and could not be added due to lack
293 * of space, or -ESPIPE it exists but has the wrong size
Simon Glass9f407d42018-11-15 18:43:50 -0700294 */
Simon Glass1a2e02f2023-12-27 13:07:00 -0800295int bloblist_ensure_size(uint tag, int size, int align_log2, void **blobp);
Simon Glass9f407d42018-11-15 18:43:50 -0700296
297/**
298 * bloblist_ensure() - Find or add a blob
299 *
300 * Find an existing blob, or add a new one if not found
301 *
302 * @tag: Tag to add (enum bloblist_tag_t)
303 * @size: Size of the blob
Simon Glass20a14932022-01-12 19:26:24 -0700304 * Return: pointer to blob, or NULL if it is missing and could not be added due
305 * to lack of space, or it exists but has the wrong size
Simon Glass9f407d42018-11-15 18:43:50 -0700306 */
307void *bloblist_ensure(uint tag, int size);
308
309/**
Simon Glass5b044542020-01-27 08:49:50 -0700310 * bloblist_ensure_size_ret() - Find or add a blob
311 *
312 * Find an existing blob, or add a new one if not found
313 *
314 * @tag: Tag to add (enum bloblist_tag_t)
315 * @sizep: Size of the blob to create; returns size of actual blob
316 * @blobp: Returns a pointer to blob on success
Simon Glass20a14932022-01-12 19:26:24 -0700317 * Return: 0 if OK, -ENOSPC if it is missing and could not be added due to lack
318 * of space
Simon Glass5b044542020-01-27 08:49:50 -0700319 */
320int bloblist_ensure_size_ret(uint tag, int *sizep, void **blobp);
321
322/**
Simon Glass1fe59372021-07-05 16:32:53 -0600323 * bloblist_resize() - resize a blob
324 *
325 * Any blobs above this one are relocated up or down. The resized blob remains
326 * in the same place.
327 *
328 * @tag: Tag to add (enum bloblist_tag_t)
329 * @new_size: New size of the blob (>0 to expand, <0 to contract)
Simon Glass20a14932022-01-12 19:26:24 -0700330 * Return: 0 if OK, -ENOSPC if the bloblist does not have enough space, -ENOENT
331 * if the tag is not found
Simon Glass1fe59372021-07-05 16:32:53 -0600332 */
333int bloblist_resize(uint tag, int new_size);
334
335/**
Simon Glass9f407d42018-11-15 18:43:50 -0700336 * bloblist_new() - Create a new, empty bloblist of a given size
337 *
338 * @addr: Address of bloblist
339 * @size: Initial size for bloblist
340 * @flags: Flags to use for bloblist
Simon Glass7d790a82023-12-27 13:07:09 -0800341 * @align_log2: Log base 2 of maximum alignment provided by this bloblist
Simon Glass20a14932022-01-12 19:26:24 -0700342 * Return: 0 if OK, -EFAULT if addr is not aligned correctly, -ENOSPC is the
343 * area is not large enough
Simon Glass9f407d42018-11-15 18:43:50 -0700344 */
Simon Glass7d790a82023-12-27 13:07:09 -0800345int bloblist_new(ulong addr, uint size, uint flags, uint align_log2);
Simon Glass9f407d42018-11-15 18:43:50 -0700346
347/**
348 * bloblist_check() - Check if a bloblist exists
349 *
350 * @addr: Address of bloblist
Raymond Mao67254212024-02-03 08:36:21 -0800351 * @size: Reserved space size for blobsize, or 0 to use the total size
Simon Glass20a14932022-01-12 19:26:24 -0700352 * Return: 0 if OK, -ENOENT if the magic number doesn't match (indicating that
Raymond Mao67254212024-02-03 08:36:21 -0800353 * there problem is no bloblist at the given address) or any fields for header
354 * size, used size and total size do not match, -EPROTONOSUPPORT
Simon Glass20a14932022-01-12 19:26:24 -0700355 * if the version does not match, -EIO if the checksum does not match,
Raymond Mao67254212024-02-03 08:36:21 -0800356 * -EFBIG if the reserved space size is small than the total size or total size
357 * is 0
Simon Glass9f407d42018-11-15 18:43:50 -0700358 */
359int bloblist_check(ulong addr, uint size);
360
361/**
362 * bloblist_finish() - Set up the bloblist for the next U-Boot part
363 *
364 * This sets the correct checksum for the bloblist. This ensures that the
365 * bloblist will be detected correctly by the next phase of U-Boot.
366 *
Simon Glass20a14932022-01-12 19:26:24 -0700367 * Return: 0
Simon Glass9f407d42018-11-15 18:43:50 -0700368 */
369int bloblist_finish(void);
370
371/**
Simon Glass4aed2272020-09-19 18:49:26 -0600372 * bloblist_get_stats() - Get information about the bloblist
373 *
374 * This returns useful information about the bloblist
Simon Glassfaff5542021-07-05 16:32:54 -0600375 *
376 * @basep: Returns base address of bloblist
Simon Glassb86b2d92023-12-27 13:07:08 -0800377 * @tsizep: Returns the total number of bytes of the bloblist
378 * @usizep: Returns the number of used bytes of the bloblist
Simon Glass4aed2272020-09-19 18:49:26 -0600379 */
Simon Glassb86b2d92023-12-27 13:07:08 -0800380void bloblist_get_stats(ulong *basep, ulong *tsizep, ulong *usizep);
Simon Glass4aed2272020-09-19 18:49:26 -0600381
382/**
Simon Glasse50a24a2022-01-12 19:26:23 -0700383 * bloblist_get_base() - Get the base address of the bloblist
384 *
Simon Glass20a14932022-01-12 19:26:24 -0700385 * Return: base address of bloblist
Simon Glasse50a24a2022-01-12 19:26:23 -0700386 */
387ulong bloblist_get_base(void);
388
389/**
390 * bloblist_get_size() - Get the size of the bloblist
391 *
Simon Glass20a14932022-01-12 19:26:24 -0700392 * Return: the size in bytes
Simon Glasse50a24a2022-01-12 19:26:23 -0700393 */
394ulong bloblist_get_size(void);
395
396/**
Simon Glassb86b2d92023-12-27 13:07:08 -0800397 * bloblist_get_total_size() - Get the total size of the bloblist
398 *
399 * Return: the size in bytes
400 */
401ulong bloblist_get_total_size(void);
402
403/**
Simon Glass4aed2272020-09-19 18:49:26 -0600404 * bloblist_show_stats() - Show information about the bloblist
405 *
406 * This shows useful information about the bloblist on the console
407 */
408void bloblist_show_stats(void);
409
410/**
411 * bloblist_show_list() - Show a list of blobs in the bloblist
412 *
413 * This shows a list of blobs, showing their address, size and tag.
414 */
415void bloblist_show_list(void);
416
417/**
418 * bloblist_tag_name() - Get the name for a tag
419 *
420 * @tag: Tag to check
Simon Glass20a14932022-01-12 19:26:24 -0700421 * Return: name of tag, or "invalid" if an invalid tag is provided
Simon Glass4aed2272020-09-19 18:49:26 -0600422 */
423const char *bloblist_tag_name(enum bloblist_tag_t tag);
424
425/**
Simon Glass9fe06462021-01-13 20:29:43 -0700426 * bloblist_reloc() - Relocate the bloblist and optionally resize it
427 *
428 * @to: Pointer to new bloblist location (must not overlap old location)
Raymond Mao1ef43f32024-02-03 08:36:22 -0800429 * @to_size: New size for bloblist
430 * Return: 0 if OK, -ENOSPC if the new size is small than the bloblist total
431 * size.
Simon Glass9fe06462021-01-13 20:29:43 -0700432 */
Raymond Mao1ef43f32024-02-03 08:36:22 -0800433int bloblist_reloc(void *to, uint to_size);
Simon Glass9fe06462021-01-13 20:29:43 -0700434
435/**
Simon Glass9f407d42018-11-15 18:43:50 -0700436 * bloblist_init() - Init the bloblist system with a single bloblist
437 *
Simon Glass20a14932022-01-12 19:26:24 -0700438 * This locates and sets up the blocklist for use.
439 *
440 * If CONFIG_BLOBLIST_FIXED is selected, it uses CONFIG_BLOBLIST_ADDR and
441 * CONFIG_BLOBLIST_SIZE to set up a bloblist for use by U-Boot.
442 *
443 * If CONFIG_BLOBLIST_ALLOC is selected, it allocates memory for a bloblist of
444 * size CONFIG_BLOBLIST_SIZE.
445 *
446 * If CONFIG_BLOBLIST_PASSAGE is selected, it uses the bloblist in the incoming
447 * standard passage. The size is detected automatically so CONFIG_BLOBLIST_SIZE
448 * can be 0.
449 *
Simon Glass3d653182023-09-26 08:14:51 -0600450 * Sets GD_FLG_BLOBLIST_READY in global_data flags on success
451 *
Simon Glass20a14932022-01-12 19:26:24 -0700452 * Return: 0 if OK, -ve on error
Simon Glass9f407d42018-11-15 18:43:50 -0700453 */
454int bloblist_init(void);
455
Simon Glass3d653182023-09-26 08:14:51 -0600456#if CONFIG_IS_ENABLED(BLOBLIST)
457/**
458 * bloblist_maybe_init() - Init the bloblist system if not already done
459 *
460 * Calls bloblist_init() if the GD_FLG_BLOBLIST_READY flag is not et
461 *
462 * Return: 0 if OK, -ve on error
463 */
464int bloblist_maybe_init(void);
465#else
466static inline int bloblist_maybe_init(void)
467{
468 return 0;
469}
470#endif /* BLOBLIST */
471
Raymond Mao1c4751f2024-02-03 08:36:20 -0800472/**
473 * bloblist_check_reg_conv() - Check whether the bloblist is compliant to
474 * the register conventions according to the
475 * Firmware Handoff spec.
476 *
477 * @rfdt: Register that holds the FDT base address.
478 * @rzero: Register that must be zero.
479 * @rsig: Register that holds signature and register conventions version.
480 * Return: 0 if OK, -EIO if the bloblist is not compliant to the register
481 * conventions.
482 */
483int bloblist_check_reg_conv(ulong rfdt, ulong rzero, ulong rsig);
484
Raymond Mao66131312024-02-03 08:36:26 -0800485/**
486 * xferlist_from_boot_arg() - Get bloblist from the boot args and relocate it
487 * to the specified address.
488 *
489 * @addr: Address for the bloblist
490 * @size: Size of space reserved for the bloblist
491 * Return: 0 if OK, else on error
492 */
493int xferlist_from_boot_arg(ulong addr, ulong size);
494
Simon Glass9f407d42018-11-15 18:43:50 -0700495#endif /* __BLOBLIST_H */