[PATCH v2] common: tlv clarify the difference between mac list and sequence

[Jonas Rebmann <jre@pengutronix.de>]

The tlv_handle_eth_address (here 0x001) and tlv_handle_eth_address_seq
(here 0x0012) correspond to the mac-list and mac-sequence formats
respectively.

A single MAC address as well as a list of MAC-Addresses is to be
generated using "mac-list" and handled by tlv_handle_eth_address, while
-sequence/_seq is a special case of generating multiple sequential
addresses.

This is under-documented and set up in a confusing way.

Even more confusingly, both examples in bareboxtlv-generator.py show
0x0012 as "tag".

To improve the situation in a backwards compatible way:

 - Correct and clarify comments in common/tlv/barebox.c
 - Re-order documentation and code in
   scripts/bareboxtlv-generator/bareboxtlv-generator.py so the order
   matches that in the barebox side, and the ordering of the default
   tags; and so that the more obvious case of single address or list
   comes first.
 - Fix tags in examples

Signed-off-by: Jonas Rebmann <jre@pengutronix.de>
---
Changes in v2:
- Fix the tags in the inline examples of bareboxtlv-generator.py
- Link to v1: https://lore.barebox.org/barebox/20260129-tlveth-v1-1-b612375ea3bf@pengutronix.de
---
 common/tlv/barebox.c                               |  4 +--
 .../bareboxtlv-generator/bareboxtlv-generator.py   | 40 +++++++++++-----------
 2 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/common/tlv/barebox.c b/common/tlv/barebox.c
index 88961942eb..6fdfe94028 100644
--- a/common/tlv/barebox.c
+++ b/common/tlv/barebox.c
@@ -186,9 +186,9 @@ struct tlv_mapping barebox_tlv_v1_mappings[] = {
 	{ 0x0007, tlv_format_str, "pcba-serial-number"},
 	/* Printed Circuit Board Assembly hardware release */
 	{ 0x0008, tlv_format_str, "pcba-hardware-release"},
-	/* A single Ethernet address */
+	/* A list of Ethernet addresses or a single Ethernet address */
 	{ 0x0011, tlv_handle_eth_address, "ethernet-address" },
-	/* A sequence of multiple Ethernet addresses */
+	/* A sequence of subsequent Ethernet addresses, by number and starting address */
 	{ 0x0012, tlv_handle_eth_address_seq, "ethernet-address" },
 	/* Reject TLV if supplied binary data does not match UID SoC register */
 	{ 0x0024, tlv_bind_soc_uid, "bound-soc-uid"},
diff --git a/scripts/bareboxtlv-generator/bareboxtlv-generator.py b/scripts/bareboxtlv-generator/bareboxtlv-generator.py
index 1fd5a45d43..2eba0aeb23 100755
--- a/scripts/bareboxtlv-generator/bareboxtlv-generator.py
+++ b/scripts/bareboxtlv-generator/bareboxtlv-generator.py
@@ -267,6 +267,14 @@ class FactoryDataset:
             |    tag: 0x0005
             |    format: decimal
             |    length: 1
+        * mac-list:
+          - A list of MAC addresses or a signle MAC address
+          - Input data must be an iterable of MAC addresses: (first_mac: int, second_mac: int, ...)
+          - MAC-addresses are represented as python ints
+          - Schema example:
+            |  ethernet-address:
+            |    tag: 0x0011
+            |    format: "mac-list"
         * mac-sequence:
           - Describes a consecutive number of MAC addresses
           - Contains a starting address and a count
@@ -276,14 +284,6 @@ class FactoryDataset:
             |  ethernet-address:
             |    tag: 0x0012
             |    format: "mac-sequence"
-        * mac-list:
-          - A list of MAC addresses
-          - Input data must be an iterable of MAC addresses: (first_mac: int, second_mac: int, ...)
-          - MAC-addresses are represented as python ints
-          - Schema example:
-            |  ethernet-address:
-            |    tag: 0x0012
-            |    format: "mac-list"
         * linear-calibration
           - Linear calibration data for analog channels
           - Input data must be an iterable of floats: (c1: float, c2: float, ...)
@@ -346,6 +346,12 @@ class FactoryDataset:
                     raise ValueError(f"Decimal {name} has invalid len {fmtl}. Must be in [1, 2, 4, 8]!")
                 bin = abs(int(value))
 
+            elif tag_format == "mac-list":
+                bin = b""
+                for mac in value:
+                    bin += struct.pack(">Q", mac)[2:]
+                fmt = f"{len(value) * 6}s"
+
             elif tag_format == "mac-sequence":
                 if len(value) != 2:
                     raise ValueError(f"mac-sequence {name} must be in format (base_mac: int, count: int)")
@@ -353,12 +359,6 @@ class FactoryDataset:
                 mac = struct.pack(">Q", value[0])[2:]
                 bin = struct.pack(">B6s", value[1], mac)
 
-            elif tag_format == "mac-list":
-                bin = b""
-                for mac in value:
-                    bin += struct.pack(">Q", mac)[2:]
-                fmt = f"{len(value) * 6}s"
-
             elif tag_format == "calibration":
                 bin = b""
                 if len(value) != tag["length"]:
@@ -465,12 +465,6 @@ class FactoryDataset:
                 value = bin[data_ptr : data_ptr + tag_len].decode("UTF-8")  # noqa E203
             elif tag_schema["format"] == "bytes":
                 value = bin[data_ptr : data_ptr + tag_len].hex()
-            elif tag_schema["format"] == "mac-sequence":
-                if tag_len != 7:
-                    raise ValueError(f"Tag {name} has wrong length {hex(tag_len)} but expected 0x7.")
-                count, base_mac = struct.unpack_from(">B6s", bin, data_ptr)
-                base_mac = struct.unpack(">Q", b"\x00\x00" + base_mac)[0]
-                value = [base_mac, count]
             elif tag_schema["format"] == "mac-list":
                 if tag_len % 6 != 0:
                     raise ValueError(f"Tag {name} has wrong length {hex(tag_id)}. Must be multiple of 0x6.")
@@ -479,6 +473,12 @@ class FactoryDataset:
                     mac = struct.unpack_from(">6s", bin, data_ptr + int(i * 6))[0]
                     mac = struct.unpack(">Q", b"\x00\x00" + mac)[0]
                     value.append(mac)
+            elif tag_schema["format"] == "mac-sequence":
+                if tag_len != 7:
+                    raise ValueError(f"Tag {name} has wrong length {hex(tag_len)} but expected 0x7.")
+                count, base_mac = struct.unpack_from(">B6s", bin, data_ptr)
+                base_mac = struct.unpack(">Q", b"\x00\x00" + base_mac)[0]
+                value = [base_mac, count]
             elif tag_schema["format"] == "calibration":
                 if tag_len % 4 != 0:
                     raise ValueError(f"Tag {name} has wrong length {hex(tag_id)}. Must be multiple of 0x4.")

---
base-commit: 378bc32467af0afbbcb9d9e3cc1bfd5fb429a826
change-id: 20260129-tlveth-4fb9d2c67aff

Best regards,
--  
Jonas Rebmann <jre@pengutronix.de>