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