doc/README.bloblist

   1 # SPDX-License-Identifier: GPL-2.0+
   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
  42 with a BLOBT_ prefix.
  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
  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.
  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