scripts: dts: dtlib: Add to_compound() to handle ...-map entry

Add a method `to_compould()` to get a compound type value
consisting of a number and a phandle, like `...-map`.

Signed-off-by: TOKITA Hiroshi <[email protected]>

Author: soburi

scripts/dts/python-devicetree/src/devicetree/dtlib.py

@@ -583,6 +583,53 @@ def to_path(self) -> Node:
 
         return ret  # The separate 'return' appeases the type checker.
 
+    def to_compound(self) -> list[Union[int, str, 'Node']]:
+        """
+        Returns a list with the numbers, strings and nodes..
+        A DT error is raised if the property contains anything other types.
+        This can be used to parse the properties of a phandle with cells.
+        """
+
+        varlist: list[Union[int, str, 'Node']] = []
+        phandle2node = self.node.dt.phandle2node
+
+        for i, (pos, marker_type, _ref) in enumerate(self._markers):
+            if i < len(self._markers) - 1:
+                next_marker = self._markers[i + 1]
+            else:
+                next_marker = None
+
+            # End of current marker
+            end = next_marker[0] if next_marker else len(self.value)
+
+            if marker_type is _MarkerType.STRING:
+                # end - 1 to strip off the null terminator
+                varlist.append(self.value[pos:end - 1].decode('utf-8'))
+            else:
+                if marker_type is _MarkerType.PHANDLE:
+                    node = phandle2node[int.from_bytes(self.value[pos : pos + 4], "big")]
+                    varlist.append(node)
+                    pos += 4
+                elif marker_type in (
+                    _MarkerType.UINT8,
+                    _MarkerType.UINT16,
+                    _MarkerType.UINT32,
+                    _MarkerType.UINT64,
+                ):
+                    elm_size = _TYPE_TO_N_BYTES[marker_type]
+                else:
+                    _err(
+                        f"expected property '{self.name}' on {self.node.path} "
+                        f"should contain only PHANDLE and numbers"
+                    )
+
+                while pos != end:
+                    num = int.from_bytes(self.value[pos : pos + elm_size], "big")
+                    varlist.append(num)
+                    pos += elm_size
+
+        return varlist
+
     def __str__(self):
         s = "".join(label + ": " for label in self.labels) + self.name
         if not self.value:

scripts/dts/python-devicetree/tests/test_dtlib.py

@@ -1650,6 +1650,10 @@ def test_prop_type_casting():
 	refs = <&{/target} &{/target2}>;
 	refs2 = <&{/target}>, <&{/target2}>;
 	path = &{/target};
+	compound1 = < 1 >, [ 02 ];
+	compound2 = "foo", < >;
+	compound3 = <&{/target} 1 &{/target2} 3>;
+	compound4 = <&{/target} 1 &{/target2} 3>, "4";
 	manualpath = "/target";
 	missingpath = "/missing";
 
@@ -1873,6 +1877,25 @@ def verify_to_path_error_matches(prop, expected_re):
         "property 'missingpath' on / in .* points to the non-existent node "
         '"/missing"')
 
+    # Test Property.to_compound()
+
+    def verify_to_compound(prop, expected_types, expected_values):
+        def node_to_path(n):
+            return n if isinstance(n, (int | str)) else n.path
+        actual_types = list(map(type, dt.root.props[prop].to_compound()))
+        actual_values = list(map(node_to_path, dt.root.props[prop].to_compound()))
+        assert actual_types == expected_types, \
+            f"{prop} gives wrong types"
+        assert actual_values == expected_values, \
+            f"{prop} gives wrong values"
+
+    verify_to_compound("compound1", [int, int], [1, 2])
+    verify_to_compound("compound2", [str], ['foo'])
+    verify_to_compound("compound3", [dtlib.Node, int, dtlib.Node, int],
+                                    ['/target', 1, '/target2', 3])
+    verify_to_compound("compound4", [dtlib.Node, int, dtlib.Node, int, str],
+                                    ['/target', 1, '/target2', 3, "4"])
+
     # Test top-level to_num() and to_nums()
 
     def verify_raw_to_num(fn, prop, length, signed, expected):