| 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 | |
| 62 | Finishing the bloblist |
| 63 | ---------------------- |
| 64 | |
| 65 | When a part of U-Boot is about to jump to the next part, it can 'finish' the |
| 66 | bloblist in preparation for the next stage. This involves adding a checksum so |
| 67 | that the next stage can make sure that the data arrived safely. While the |
| 68 | bloblist is in use, changes can be made which will affect the checksum, so it |
| 69 | is easier to calculate the checksum at the end after all changes are made. |
| 70 | |
| 71 | |
| 72 | Future work |
| 73 | ----------- |
| 74 | |
| 75 | Bootstage has a mechanism to 'stash' its records for passing to the next part. |
| 76 | This should move to using bloblist, to avoid having its own mechanism for |
| 77 | passing information between U-Boot parts. |
| 78 | |
| 79 | |
| 80 | Simon Glass |
| 81 | sjg@chromium.org |
| 82 | 12-Aug-2018 |