[PATCH RESEND] doc: tlv: add images and custom format documentation

[Jonas Rebmann]

Hi again,

On 2026-04-30 14:20, Jonas Rebmann wrote:
> Can we turn this into ASCII-art or DOT/Graphviz or similar?
> 
> Is there anything our sphinx setup already supports to turn into SVG on
> the fly?

We could use sphinx.ext.graphviz and represent your diagrams like so:

---8<---

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 9244bffe9e..13b74a8655 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -29,7 +29,9 @@ import re
  # Add any Sphinx extension module names here, as strings. They can be
  # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
  # ones.
-extensions = []
+extensions = ["sphinx.ext.graphviz"]
+
+graphviz_output_format = 'svg'

  # Add any paths that contain templates here, relative to this directory.
  templates_path = ['_templates']
diff --git a/Documentation/user/barebox-tlv.rst b/Documentation/user/barebox-tlv.rst
index 3884d17409..1a108235ad 100644
--- a/Documentation/user/barebox-tlv.rst
+++ b/Documentation/user/barebox-tlv.rst
@@ -10,9 +10,20 @@ 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.

-.. image:: figures/tlv_usage.svg
-  :width: 40%
-  :align: center
+.. graphviz::
+
+   digraph tlv_usage {
+       node [shape=box]
+
+       soc_id      [label="SOC ID\n(read from fuses)"]
+       tlv_pubkey  [label="TLV Public Key\n(compiled into barebox)"]
+       signed_tlv  [label="Signed TLV data\n(read from eeprom)"]
+       device_tree [label="Device-Tree"]
+
+       tlv_pubkey  -> signed_tlv  [label="Verifies"]
+       soc_id      -> signed_tlv  [label="Compared against" dir=both]
+       signed_tlv  -> device_tree [label="Updates"]
+   }

  barebox TLV consists of two components:

@@ -121,7 +132,41 @@ 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 ``scripts/bareboxtlv-generator/data-example.yaml``.

-.. image:: figures/tlv_generator.svg
+.. graphviz::
+
+    digraph tlv_generator {
+        node [shape=record fontname="Monospace"]
+
+        schema_yaml [label="{schema.yaml |
+              magic: 0x61bb95f3
+            \lmax_size: 0x1000
+            \ltags:
+            \l\  factory-timestamp:
+            \l\    tag: 0x0003
+            \l\    format: \"decimal\"
+            \l\    length: 8
+            \l\    example: 1636451762
+            \l\  featureset:
+            \l\    tag: 0x0006
+            \l\    format: \"string\"
+            \l\    example: \"base\"
+            \l\    purpose: For later use.
+            }" style=dashed]
+
+        data_yaml [label="{data.yaml |
+              factory-timestamp: 1636451762
+            \lfeatureset: \"base\"\l
+            }"]
+
+        tlv_key     [label="{tlv.key | PRIVATE KEY}"]
+        generator   [label="barebox-tlv-generator.py"]
+        signed_bin  [label="{TLV_signed.bin | Signed TLV data}"]
+
+        schema_yaml -> generator
+        data_yaml   -> generator
+        tlv_key     -> generator
+        generator   -> signed_bin
+    }

  With these information in place a TLV binary can be created:

---8<---

I didn't create another version of your patch because it lacked the
Signed-off-by, only signed off the (empty) message body/cover letter.

What do you think about using dot/graphviz for this?

Regards,
Jonas

-- 
Pengutronix e.K.                           | Jonas Rebmann               |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-9    |