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