1# SPDX-License-Identifier: GPL-2.0+
2
3Blob Lists - bloblist
4=====================
5
6Introduction
7------------
8
9A bloblist provides a way to store collections of binary information (blobs) in
10a central structure. Each record of information is assigned a tag so that its
11owner can find it and update it. Each record is generally described by a C
12structure defined by the code that owns it.
13
14
15Passing state through the boot process
16--------------------------------------
17
18The bloblist is created when the first U-Boot component runs (often SPL,
19sometimes TPL). It is passed through to each successive part of the boot and
20can be accessed as needed. This provides a way to transfer state from one part
21to the next. For example, TPL may determine that a watchdog reset occurred by
22reading an SoC register. Reading the register may reset the value, so that it
23cannot be read a second time. So TPL can store that in a bloblist record which
24can be passed through to SPL and U-Boot proper, which can print a message
25indicating that something went wrong and the watchdog fired.
26
27
28Blobs
29-----
30
31While each blob in the bloblist can be of any length, bloblists are designed to
32hold small amounts of data, typically a few KB at most. It is not possible to
33change the length of a blob once it has been written. Each blob is normally
34created from a C structure which can beused to access its fields.
35
36
37Blob tags
38---------
39
40Each blob has a tag which is a 32-bit number. This uniquely identifies the
41owner of the blob. Blob tags are listed in enum blob_tag_t and are named
42with a BLOBT_ prefix.
43
44
45Single structure
46----------------
47
48There is normally only one bloblist in U-Boot. Since a bloblist can store
49multiple blobs it does not seem useful to allow multiple bloblists. Of course
50there could be reasons for this, such as needing to spread the blobs around in
51different memory areas due to fragmented memory, but it is simpler to just have
52a single bloblist.
53
54
55API
56---
57
58Bloblist provides a fairly simple API which allows blobs to be created and
59found. All access is via the blob's tag. Blob records are zeroed when added.
60
61
62Finishing the bloblist
63----------------------
64
65When a part of U-Boot is about to jump to the next part, it can 'finish' the
66bloblist in preparation for the next stage. This involves adding a checksum so
67that the next stage can make sure that the data arrived safely. While the
68bloblist is in use, changes can be made which will affect the checksum, so it
69is easier to calculate the checksum at the end after all changes are made.
70
71
72Future work
73-----------
74
75Bootstage has a mechanism to 'stash' its records for passing to the next part.
76This should move to using bloblist, to avoid having its own mechanism for
77passing information between U-Boot parts.
78
79
80Simon Glass
81sjg@chromium.org
8212-Aug-2018
83