[thirdparty/u-boot.git] / doc / README.bloblist

# SPDX-License-Identifier: GPL-2.0+

Blob Lists - bloblist
=====================

Introduction
------------

A bloblist provides a way to store collections of binary information (blobs) in
a central structure. Each record of information is assigned a tag so that its
owner can find it and update it. Each record is generally described by a C
structure defined by the code that owns it.


Passing state through the boot process
--------------------------------------

The bloblist is created when the first U-Boot component runs (often SPL,
sometimes TPL). It is passed through to each successive part of the boot and
can be accessed as needed. This provides a way to transfer state from one part
to the next. For example, TPL may determine that a watchdog reset occurred by
reading an SoC register. Reading the register may reset the value, so that it
cannot be read a second time. So TPL can store that in a bloblist record which
can be passed through to SPL and U-Boot proper, which can print a message
indicating that something went wrong and the watchdog fired.


Blobs
-----

While each blob in the bloblist can be of any length, bloblists are designed to
hold small amounts of data, typically a few KB at most. It is not possible to
change the length of a blob once it has been written. Each blob is normally
created from a C structure which can beused to access its fields.


Blob tags
---------

Each blob has a tag which is a 32-bit number. This uniquely identifies the
owner of the blob. Blob tags are listed in enum blob_tag_t and are named
with a BLOBT_ prefix.


Single structure
----------------

There is normally only one bloblist in U-Boot. Since a bloblist can store
multiple blobs it does not seem useful to allow multiple bloblists. Of course
there could be reasons for this, such as needing to spread the blobs around in
different memory areas due to fragmented memory, but it is simpler to just have
a single bloblist.


API
---

Bloblist provides a fairly simple API which allows blobs to be created and
found. All access is via the blob's tag. Blob records are zeroed when added.


Finishing the bloblist
----------------------

When a part of U-Boot is about to jump to the next part, it can 'finish' the
bloblist in preparation for the next stage. This involves adding a checksum so
that the next stage can make sure that the data arrived safely. While the
bloblist is in use, changes can be made which will affect the checksum, so it
is easier to calculate the checksum at the end after all changes are made.


Future work
-----------

Bootstage has a mechanism to 'stash' its records for passing to the next part.
This should move to using bloblist, to avoid having its own mechanism for
passing information between U-Boot parts.


Simon Glass
sjg@chromium.org
12-Aug-2018
Commit	Line	Data
cff88701 SG	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
b83994de SG	58	Bloblist provides a fairly simple API which allows blobs to be created and
b83994de SG	59	found. All access is via the blob's tag. Blob records are zeroed when added.
cff88701 SG	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