From: Chris Fiege <c...@pengutronix.de>
With this stub users can hopefully discover the Barebox TLV
functionality.
Additionally it discusses some key concepts of the implementation, that
are not obvious from the actual implementations.
Signed-off-by: Chris Fiege <c...@pengutronix.de>
Signed-off-by: Ahmad Fatoum <a.fat...@pengutronix.de>
---
Documentation/user/barebox-tlv.rst | 93 ++++++++++++++++++++++++++++++
Documentation/user/user-manual.rst | 1 +
2 files changed, 94 insertions(+)
create mode 100644 Documentation/user/barebox-tlv.rst
diff --git a/Documentation/user/barebox-tlv.rst
b/Documentation/user/barebox-tlv.rst
new file mode 100644
index 000000000000..3db13ec88b22
--- /dev/null
+++ b/Documentation/user/barebox-tlv.rst
@@ -0,0 +1,93 @@
+barebox TLV - Non-Volatile Factory Data Storage
+===============================================
+
+barebox TLV is a system to store and retrieve a device's (read-only)
+meta-data from non-volatile memory.
+It is intended to handle information that are usually only set in
+the factory - like serial number, MAC-addresses, analog calibration
+data, etc.
+Data is stored in a tag-length-value format (hence the name) and read
+from non-volatile memory during startup.
+Unpacked values are stored in the devicetree ``chosen``-node.
+
+barebox TLV consists of two components:
+
+* The parser inside barebox (``common/tlv``).
+ This code parses the non-volatile memory during startup.
+* A Python-Tool (``scripts/bareboxtlv-generator``).
+ This script is intended to generate the TLV binaries in the factory.
+
+Data Format
+-----------
+
+The TLV binary has the following format:
+
+.. code-block:: C
+
+ struct tlv {
+ be16 tag; /* 2 bytes */
+ be16 len; /* 2 bytes */
+ u8 payload[];
+ };
+
+ struct binfile {
+ be32 magic_version;
+ be32 length_tlv; /* 4 bytes */
+ be32 length_sig; /* 4 bytes */
+ struct tlv tlvs[];
+ be32 crc32;
+ };
+
+.. note::
+ Even though the header has a ``length_sig`` field,
+ there is currently no support for cryptographic signatures.
+
+Tags
+----
+
+Tags are defined as 32-bit integers.
+A tag defines the following attributes:
+
+* **Data format:**
+ The data format can be something like ``string``, ``decimal`` or
+ ``serial-number``.
+* **Name of the entry:**
+ This is the name under which the value is stored in ``chosen``-node.
+
+The tag range ``0x0000`` to ``0x7FFF`` is intended for common tags,
+that can be used in every schema.
+These common tags are defined in ``common/tlv/barebox.c``.
+
+The tag range ``0x8000`` to ``0xFFFF`` is intended for custom extensions.
+Parsing must be handled by board-specific extensions.
+
+Data Types
+----------
+
+barebox defines a number of common data types.
+These are defined in ``common/tlv/barebox.c``.
+
+Board-specific extensions can add additional data types as needed.
+
+TLV Binary Generation
+---------------------
+
+To generate a TLV binary the schema for the specific TLV must be defined.
+Schemas are yaml-files that represent what the actual parser in barebox
expects.
+
+An example schema can be found in
``srcipts/bareboxtlv-generator/schema-example.yaml``.
+This schema defines some well-known tags and two board-specific tags.
+
+Afterwards another yaml-file with the data for the TLV binary is needed.
+An example can be found in ``srcipts/bareboxtlv-generator/data-example.yaml``.
+
+With these information in place a TLV binary can be created:
+
+.. code-block:: shell
+
+ ./bareboxtlv-generator.py --input-data data-example.yaml \
+ schema-example.yaml tlv.bin
+
+.. note::
+ The ``FactoryDataset`` class in ``bareboxtlv-generator.py``
+ is intended to be used as a library.
diff --git a/Documentation/user/user-manual.rst
b/Documentation/user/user-manual.rst
index 83ba9e4c3505..53a94f4e2933 100644
--- a/Documentation/user/user-manual.rst
+++ b/Documentation/user/user-manual.rst
@@ -39,6 +39,7 @@ Contents:
watchdog
reboot-mode
virtio
+ barebox-tlv
* :ref:`search`
* :ref:`genindex`
--
2.39.5
