scripts: dts: edtlib: Handle *-map property

Add `_map_phandle_val_list()` to handle `*-map` properties.
Since `*-map` properties are made able to be treated as a variation
of phandle-array, assign sequential cell names for each group of
specifiers
(child_specifier_0, child_specifier_1, ..., parent_specifier_0, ...).

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

Author: soburi

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

@@ -1499,9 +1499,8 @@ def _init_prop(self, prop_spec: PropertySpec,
                  "is different from the 'const' value specified in "
                  f"{self.binding_path} ({const!r})")
 
-        # Skip properties that start with '#', like '#size-cells', and mapping
-        # properties like 'gpio-map'/'interrupt-map'
-        if name[0] == "#" or name.endswith("-map"):
+        # Skip properties that start with '#', like '#size-cells'
+        if name[0] == "#":
             return
 
         self.props[name] = Property(prop_spec, val, self)
@@ -1598,7 +1597,10 @@ def _prop_val(
                      f"with '{name} = < &foo ... &bar 1 ... &baz 2 3 >' "
                      f"(a mix of phandles and numbers), not '{prop}'")
 
-            return self._standard_phandle_val_list(prop, specifier_space)
+            if prop.name.endswith("-map"):
+                return self._map_phandle_val_list(prop, specifier_space)
+            else:
+                return self._standard_phandle_val_list(prop, specifier_space)
 
         if prop_type == "path":
             return self.edt._node2enode[prop.to_path()]
@@ -1773,6 +1775,105 @@ def _init_interrupts(self) -> None:
 
         _add_names(node, "interrupt", self.interrupts)
 
+    def _map_phandle_val_list(
+        self, prop: dtlib_Property, specifier_space: Optional[str]
+    ) -> list[Optional[ControllerAndData]]:
+        if not specifier_space:
+            specifier_space = prop.name[:-4]  # Strip '-map'
+
+        res: list[Optional[ControllerAndData]] = []
+
+        raw = prop.value
+        while raw:
+            if len(raw) < 4:
+                # Not enough room for phandle
+                _err("bad value for " + repr(prop))
+
+            def count_cells_num(node: dtlib_Node, specifier: str) -> int:
+                """
+                Calculate the number of cells in the node.
+                When calculating the number of interrupt cells,
+                add up the values of the address and size cells.
+                """
+
+                if not node:
+                    _err("node is None.")
+
+                num = node.props[f"#{specifier}-cells"].to_num()
+
+                if specifier == "interrupt":
+                    parent_props = None
+                    if node.parent:
+                        parent_props = node.parent.props
+
+                    if "#address-cells" in node.props:
+                        num = num + node.props["#address-cells"].to_num()
+                    elif parent_props and "#address-cells" in parent_props:
+                        num = num + parent_props["#address-cells"].to_num()
+                    else:
+                        _err("Neither the node nor its parent has `#address-cells` property")
+
+                    if "#size-cells" in node.props:
+                        num = num + node.props["#size-cells"].to_num()
+                    elif parent_props and "#address-cells" in parent_props:
+                        num = num + parent_props["#size-cells"].to_num()
+                    else:
+                        _err("Neither the node nor its parent has `#size-cells` property")
+
+                return num
+
+            child_specifier_num = count_cells_num(prop.node, specifier_space)
+
+            child_specifiers = to_nums(raw[: 4 * child_specifier_num])
+            raw = raw[4 * child_specifier_num :]
+            phandle = to_num(raw[:4])
+            raw = raw[4:]
+
+            controller_node: dtlib_Node = prop.node.dt.phandle2node.get(phandle)
+            if not controller_node:
+                _err(f"controller node cannot be found from phandle:{phandle}")
+
+            parent_specifier_num = count_cells_num(controller_node, specifier_space)
+            parent_specifiers = to_nums(raw[: 4 * parent_specifier_num])
+            raw = raw[4 * parent_specifier_num :]
+
+            # Although this is rare, if a cell-name is specified for the map node,
+            # it will be reflected.
+            # If not specified, the name of child_specifier_[i] will be set.
+            values: dict[str, int] = {}
+            for i, v in enumerate(child_specifiers):
+                cell_name = f"child_specifier_{i}"
+                if specifier_space in self._binding.specifier2cells and (
+                    i < len(self._binding.specifier2cells)
+                ):
+                    cell_name = self._bindings.specifier2cells[i]
+
+                values[cell_name] = v
+
+            # The cell name for parent_specifier cannot be determined.
+            # For convenience, we assign it the name parent_specifier_[i].
+            for i, v in enumerate(parent_specifiers):
+                values[f"parent_specifier_{i}"] = v
+
+            controller: Node = self.edt._node2enode[controller_node]
+            if not controller:
+                _err("controller cannot be found from: " + repr(controller_node))
+
+            res.append(
+                ControllerAndData(
+                    node=self,
+                    controller=controller,
+                    data=values,
+                    name=None,
+                    basename=specifier_space,
+                )
+            )
+
+        if len(raw) != 0:
+            _err(f"unexpected prop.value remainings: {raw}")
+
+        return res
+
     def _standard_phandle_val_list(
             self,
             prop: dtlib_Property,
@@ -2717,9 +2818,10 @@ def _check_prop_by_type(prop_name: str,
 
     if (prop_type == "phandle-array"
         and not prop_name.endswith("s")
+        and not prop_name.endswith("-map")
         and "specifier-space" not in options):
         _err(f"'{prop_name}' in 'properties:' in {binding_path} "
-             f"has type 'phandle-array' and its name does not end in 's', "
+             f"has type 'phandle-array' and its name does not end in 's' or '-map', "
              f"but no 'specifier-space' was provided.")
 
     # If you change const_types, be sure to update the type annotation

scripts/dts/python-devicetree/tests/test-bindings/gpio-nexus.yaml

@@ -0,0 +1,22 @@
+# Copyright (c) 2025 TOKITA Hiroshi
+# SPDX-License-Identifier: Apache-2.0
+
+compatible: "gpio-nexus"
+
+description: gpio-nexus definition
+
+properties:
+  gpio-map:
+    type: phandle-array
+    required: true
+
+  gpio-map-mask:
+    type: array
+
+  gpio-map-pass-thru:
+    type: array
+
+  "#gpio-cells":
+    type: int
+    required: true
+    description: Number of items to expect in a gpio specifier

scripts/dts/python-devicetree/tests/test-bindings/interrupt-nexus.yaml

@@ -0,0 +1,22 @@
+# Copyright (c) 2025 TOKITA Hiroshi
+# SPDX-License-Identifier: Apache-2.0
+
+compatible: "interrupt-nexus"
+
+description: interrupt-nexus definition
+
+properties:
+  interrupt-map:
+    type: phandle-array
+    required: true
+
+  interrupt-map-mask:
+    type: array
+
+  interrupt-map-pass-thru:
+    type: array
+
+  "#interrupt-cells":
+    type: int
+    required: true
+    description: Number of items to expect in a interrupt specifier

scripts/dts/python-devicetree/tests/test.dts

@@ -71,6 +71,7 @@
 			interrupt-controller;
 		};
 		nexus {
+			compatible = "interrupt-nexus";
 			#interrupt-cells = <2>;
 			interrupt-map = <
 				0 0  0 0  &{/interrupt-map-test/controller-0}  0      0
@@ -104,6 +105,7 @@
 			interrupt-controller;
 		};
 		nexus {
+			compatible = "interrupt-nexus";
 			#interrupt-cells = <2>;
 			interrupt-map = <
 			    6 6  6 6  &{/interrupt-map-bitops-test/controller}  2 1
@@ -399,6 +401,7 @@
 				     &{/gpio-map/connector} 1 2>;
 		};
 		connector {
+			compatible = "gpio-nexus";
 			#gpio-cells = <2>;
 			// Use different data lengths for source and
 			// destination to make it a bit trickier

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

@@ -209,6 +209,51 @@ def verify_regs(node, expected_tuples):
     verify_regs(edt.get_node("/reg-nested-ranges/grandparent/parent/node"),
                 [(None, 0x30000000200000001, 0x1)])
 
+def test_map():
+    '''Tests for map properties'''
+    with from_here():
+        edt = edtlib.EDT("test.dts", ["test-bindings"])
+
+    def verify_maps(
+        node,
+        specifier,
+        expected_maps,
+        expected_child_cell,
+        expected_child_addr,
+        expected_parent_cells,
+        expected_parent_addrs,
+    ):
+
+        maps = []
+        for d in node.props[specifier +'-map'].val:
+            parent_specs = len([k for k in d.data if k.startswith('parent_specifier_')])
+            maps.extend(list(d.data.values())[:-parent_specs])
+            maps.extend([d.controller.path])
+            maps.extend(list(d.data.values())[-parent_specs:])
+
+        assert maps == expected_maps
+
+    verify_maps(edt.get_node("/interrupt-map-test/nexus"), specifier="interrupt",
+                expected_maps=[0, 0, 0, 0, "/interrupt-map-test/controller-0", 0, 0,
+                               0, 0, 0, 1, "/interrupt-map-test/controller-1", 0, 0, 0, 1,
+                               0, 0, 0, 2, "/interrupt-map-test/controller-2", 0, 0, 0, 0, 0, 2,
+                               0, 1, 0, 0, "/interrupt-map-test/controller-0", 0, 3,
+                               0, 1, 0, 1, "/interrupt-map-test/controller-1", 0, 0, 0, 4,
+                               0, 1, 0, 2, "/interrupt-map-test/controller-2", 0, 0, 0, 0, 0, 5],
+                expected_child_cell=2, expected_child_addr=2,
+                expected_parent_cells=[1, 2, 3, 1, 2, 3], expected_parent_addrs=[1, 2, 3, 1, 2, 3])
+
+    verify_maps(edt.get_node("/interrupt-map-bitops-test/nexus"), specifier="interrupt",
+                expected_maps=[6, 6, 6, 6, "/interrupt-map-bitops-test/controller", 2, 1],
+                expected_child_cell=2, expected_child_addr=2,
+                expected_parent_cells=[2], expected_parent_addrs=[0])
+
+    verify_maps(edt.get_node("/gpio-map/connector"), specifier="gpio",
+                expected_maps=[1, 2, "/gpio-map/destination", 5,
+                               3, 4, "/gpio-map/destination", 6],
+                expected_child_cell=2, expected_child_addr=0,
+                expected_parent_cells=[1, 1], expected_parent_addrs=[0, 0])
+
 def test_pinctrl():
     '''Test 'pinctrl-<index>'.'''
     with from_here():