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