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
14For the design goals of bloblist, please see the comments at the top of the
15`bloblist.h` header file.
16
17Passing state through the boot process
18--------------------------------------
19
20The bloblist is created when the first U-Boot component runs (often SPL,
21sometimes TPL). It is passed through to each successive part of the boot and
22can be accessed as needed. This provides a way to transfer state from one part
23to the next. For example, TPL may determine that a watchdog reset occurred by
24reading an SoC register. Reading the register may reset the value, so that it
25cannot be read a second time. So TPL can store that in a bloblist record which
26can be passed through to SPL and U-Boot proper, which can print a message
27indicating that something went wrong and the watchdog fired.
28
29
30Blobs
31-----
32
33While each blob in the bloblist can be of any length, bloblists are designed to
34hold small amounts of data, typically a few KB at most. It is not possible to
35change the length of a blob once it has been written. Each blob is normally
36created from a C structure which can be used to access its fields.
37
38
39Blob tags
40---------
41
42Each blob has a tag which is a 32-bit number. This uniquely identifies the
43owner of the blob. Blob tags are listed in enum blob_tag_t and are named
44with a `BLOBT_` prefix.
45
46
47Single structure
48----------------
49
50There is normally only one bloblist in U-Boot. Since a bloblist can store
51multiple blobs it does not seem useful to allow multiple bloblists. Of course
52there could be reasons for this, such as needing to spread the blobs around in
53different memory areas due to fragmented memory, but it is simpler to just have
54a single bloblist.
55
56
57API
58---
59
60Bloblist provides a fairly simple API which allows blobs to be created and
61found. All access is via the blob's tag. Blob records are zeroed when added.
62
63
64Placing the bloblist
65--------------------
66
67The bloblist is typically positioned at a fixed address by TPL, or SPL. This
68is controlled by `CONFIG_BLOBLIST_ADDR`. But in some cases it is preferable to
69allocate the bloblist in the malloc() space. Use the `CONFIG_BLOBLIST_ALLOC`
70option to enable this.
71
72The bloblist is automatically relocated as part of U-Boot relocation. Sometimes
73it is useful to expand the bloblist in U-Boot proper, since it may want to add
74information for use by Linux. Note that this does not mean that Linux needs to
75know anything about the bloblist format, just that it is convenient to use
76bloblist to place things contiguously in memory. Set
77`CONFIG_BLOBLIST_SIZE_RELOC` to define the expanded size, if needed.
78
79
80Finishing the bloblist
81----------------------
82
83When a part of U-Boot is about to jump to the next part, it can 'finish' the
84bloblist in preparation for the next stage. This involves adding a checksum so
85that the next stage can make sure that the data arrived safely. While the
86bloblist is in use, changes can be made which will affect the checksum, so it
87is easier to calculate the checksum at the end after all changes are made.
88
89
90Future work
91-----------
92
93Bootstage has a mechanism to 'stash' its records for passing to the next part.
94This should move to using bloblist, to avoid having its own mechanism for
95passing information between U-Boot parts.
96
97
98API documentation
99-----------------
100
101.. kernel-doc:: include/bloblist.h
102
103
104Simon Glass
105sjg@chromium.org
10612-Aug-2018
107