Eric Lee / smarc-uboot

Download as
Browse Code ยป

Commit cff887013147851e2199be7d31bfda034add7717

Authored by Simon Glass
Committed by Tom Rini
1 parent 919e7a8fb6
Exists in smarc_8mq_lf_v2020.04 and in 11 other branches 8qm-imx_v2020.04_5.4.70_2.3.0, emb_lf_v2022.04, pitx_8mp_lf_v2020.04, smarc-8m-android-10.0.0_2.6.0, smarc-8m-android-11.0.0_2.0.0, smarc-8mp-android-11.0.0_2.0.0, smarc_8m-imx_v2019.04_4.19.35_1.1.0, smarc_8mm-imx_v2019.04_4.19.35_1.1.0, smarc_8mm-imx_v2020.04_5.4.24_2.1.0, smarc_8mp_lf_v2020.04, smarc_8mq-imx_v2020.04_5.4.24_2.1.0

Add bloblist documentation 

Add a description of the purpose of bloblist and how to use it.

Signed-off-by: Simon Glass <sjg@chromium.org>

Showing 1 changed file with 82 additions and 0 deletions Side-by-side Diff

  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.
  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