[PATCH 09/10] doc: Add User-Documentation for Barebox TLV

[Ahmad Fatoum <a.fatoum@pengutronix.de>]

From: Chris Fiege <cfi@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 <cfi@pengutronix.de>
Signed-off-by: Ahmad Fatoum <a.fatoum@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