include: devicetree: Generate defines for map property

This change introduces generating definitions corresponding to
`*-map` property, which was currently discarded.

The `*-map` data is like a two-dimensional array, so it is difficult to
handle with the existing APIs, so we will also provide new APIs.

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

Author: soburi

dts/bindings/gpio/gpio-nexus.yaml

@@ -5,7 +5,7 @@
 
 properties:
   gpio-map:
-    type: compound
+    type: phandle-array
     required: true
 
   gpio-map-mask:

dts/bindings/iio/io-channel-nexus.yaml

@@ -5,7 +5,7 @@
 
 properties:
   io-channel-map:
-    type: compound
+    type: phandle-array
     required: true
 
   io-channel-map-mask:

dts/bindings/interrupt-controller/interrupt-nexus.yaml

@@ -5,7 +5,7 @@
 
 properties:
   interrupt-map:
-    type: compound
+    type: phandle-array
     required: true
 
   interrupt-map-mask:

dts/bindings/test/vnd,gpio-nexus.yaml

@@ -0,0 +1,8 @@
+# Copyright (c) 2025, TOKITA Hiroshi
+# SPDX-License-Identifier: Apache-2.0
+
+description: VND GPIO nexus
+
+include: [gpio-nexus.yaml]
+
+compatible: "vnd,gpio-nexus"

dts/bindings/test/vnd,intr-nexus.yaml

@@ -0,0 +1,8 @@
+# Copyright (c) 2025, TOKITA Hiroshi
+# SPDX-License-Identifier: Apache-2.0
+
+description: VND interrupt nexus
+
+include: [interrupt-nexus.yaml]
+
+compatible: "vnd,intr-nexus"

include/zephyr/devicetree.h

@@ -5343,5 +5343,6 @@
 #include <zephyr/devicetree/reset.h>
 #include <zephyr/devicetree/mbox.h>
 #include <zephyr/devicetree/port-endpoint.h>
+#include <zephyr/devicetree/map.h>
 
 #endif /* ZEPHYR_INCLUDE_DEVICETREE_H_ */

include/zephyr/devicetree/map.h

@@ -0,0 +1,273 @@
+/*
+ * Copyright (c) 2025 TOKITA Hiroshi
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_DEVICETREE_MAP_H_
+#define ZEPHYR_INCLUDE_DEVICETREE_MAP_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @defgroup devicetree-map Devicetree Map API
+ *
+ * @brief Helper macros for handling map properties.
+ *
+ * This module provides helper macros that facilitate interrupt mapping and
+ * specifier mapping based on DeviceTree specifications. It enables the extraction
+ * and interpretation of mapping data represented as phandle-arrays.
+ *
+ * In a typical DeviceTree fragment, properties ending with "-map" specify:
+ *  - The child specifier to be mapped.
+ *  - The parent node (phandle) to which the mapping applies.
+ *  - The parent specifier associated with the mapping.
+ *
+ * For example,  when the following DeviceTree snippet are defined:
+ *
+ * @code{.dts}
+ *     n: node {
+ *         gpio-map = <0 1 &gpio0 2 3>, <4 5 &gpio0 6 7>;
+ *     };
+ * @endcode
+ *
+ * In the first mapping entry:
+ *  - `0 1` are the child specifiers.
+ *  - &gpio0 is the parent node.
+ *  - `2 3` are the parent specifiers.
+ *
+ * Since map properties are implemented as phandle-arrays, macros such as
+ * DT_PHANDLE_BY_IDX() and DT_PHA_BY_IDX() can be used to access individual elements.
+ *
+ * Both child and parent specifiers are treated as cells in a phandle-array.
+ * By default, each group of specifiers is given a sequential cell name
+ * (child_specifier_0, child_specifier_1, ..., parent_specifier_0, ...).
+ *
+ * If cell names are specified in dt-bindings, they will be used for the child specifier cell names.
+ * Parent specifiers always use the default naming convention.
+ *
+ * Example usage:
+ *
+ * A mapping entry is a phandle-array whose elements can be referenced as follows:
+ *  - Child specifiers can be accessed via names such as `child_specifier_0`,
+ *    `child_specifier_1`, ...
+ *  - The parent node is accessed via DT_PHANDLE_BY_IDX().
+ *  - Parent specifiers are accessed via names such as `parent_specifier_0`,
+ *    `parent_specifier_1`, ...
+ *
+ * @code{.c}
+ *     int cspec_0 = DT_PHA_BY_IDX(DT_NODELABEL(n), gpio_map, 0, child_specifier_0); // 0
+ *     int cspec_1 = DT_PHA_BY_IDX(DT_NODELABEL(n), gpio_map, 0, child_specifier_1); // 1
+ *     const struct device *parent =
+ *         device_get_binding(DT_PHANDLE_BY_IDX(DT_NODELABEL(n), gpio_map, 0)); // &gpio0
+ *     int pspec_0 = DT_PHA_BY_IDX(DT_NODELABEL(n), gpio_map, 0, parent_specifier_0); // 2
+ *     int pspec_1 = DT_PHA_BY_IDX(DT_NODELABEL(n), gpio_map, 0, parent_specifier_1); // 3
+ * @endcode
+ *
+ * The map helper API also provides the following macros for convenient access to
+ * specific parts of a mapping entry:
+ *  - DT_MAP_CHILD_SPECIFIER_ARGS()
+ *  - DT_MAP_PARENT_SPECIFIER_ARGS()
+ *  - DT_MAP_PARENT_ARG()
+ *
+ * These macros extract, respectively, the child specifier arguments, the parent specifier
+ * arguments, and the parent node argument from a mapping element identified by its node ID,
+ * property name, and index.
+ *
+ * For instance:
+ *
+ * @code{.c}
+ *     #define SRC_AND_DST(node_id, prop, idx) \
+ *         { GET_ARG_N(1, DT_MAP_CHILD_SPECIFIER_ARGS(node_id, prop, idx)), \
+ *           GET_ARG_N(1, DT_MAP_PARENT_SPECIFIER_ARGS(node_id, prop, idx)) }
+ *
+ *     int src_and_dst[2][] = {
+ *         DT_FOREACH_PROP_ELEM_SEP(DT_NODELABEL(n), gpio_map, SRC_AND_DST, (,))
+ *     };
+ * @endcode
+ *
+ * The above expansion yields:
+ *
+ * @code{.c}
+ *     int src_and_dst[2][] = {{0, 2}, {4, 6}};
+ * @endcode
+ *
+ * @ingroup devicetree
+ * @{
+ */
+
+/**
+ * @brief Extracts a specified range of arguments.
+ *
+ * This helper macro first skips a given number of arguments and then selects
+ * the first @p len arguments from the remaining list.
+ *
+ * @param start The number of arguments to skip.
+ * @param len The number of arguments to extract after skipping.
+ * @param ... The list of input arguments.
+ */
+#define DT_MAP_HELPER_DO_ARGS_RANGE(start, len, ...)                                               \
+	GET_ARGS_FIRST_N(len, GET_ARGS_LESS_N(start, __VA_ARGS__))
+
+/**
+ * @brief Extracts a range of mapping arguments for a specific field.
+ *
+ * This macro concatenates the field name with the appropriate suffixes to determine
+ * the starting index and length of the arguments for a map entry, and then extracts
+ * those arguments.
+ *
+ * @param name The mapping field name (e.g., CHILD_SPECIFIER, PARENT).
+ * @param node_id The node identifier.
+ * @param prop The property name in lowercase and underscores.
+ * @param idx The index of the mapping entry.
+ * @param ... Additional arguments corresponding to the mapping entry.
+ */
+#define DT_MAP_HELPER_ARGS_RANGE(name, node_id, prop, idx, ...)                                    \
+	DT_MAP_HELPER_DO_ARGS_RANGE(DT_CAT3(DT_MAP_, name, _IDX)(node_id, prop, idx),              \
+				    DT_CAT3(DT_MAP_, name, _LEN)(node_id, prop, idx), __VA_ARGS__)
+
+/**
+ * @brief Extracts arguments by skipping a specified number of elements.
+ *
+ * This helper macro applies GET_ARGS_LESS_N to the provided argument list.
+ *
+ * @param N The number of arguments to skip.
+ * @param ... The list of input arguments.
+ */
+#define DT_MAP_HELPER_ARGS_LESS_N(N, ...) GET_ARGS_LESS_N(N, __VA_ARGS__)
+
+/**
+ * @brief Retrieves the mapping entry at the specified index.
+ *
+ * @param node_id The node identifier.
+ * @param prop The property name in lowercase with underscores.
+ * @param idx The mapping entry index.
+ * @return The mapping entry as a list of comma-separated values.
+ */
+#define DT_MAP_IDX(node_id, prop, idx) DT_CAT5(node_id, _P_, prop, _MAP_IDX_, idx)
+
+/**
+ * @brief Returns the number of mapping entries for the given property.
+ *
+ * @param node_id The node identifier.
+ * @param prop The property name in lowercase with underscores.
+ * @return The total count of mapping entries.
+ */
+#define DT_MAP_LEN(node_id, prop) DT_CAT4(node_id, _P_, prop, _MAP_LEN)
+
+/**
+ * @brief Retrieves the starting index of the child specifier cell within a mapping entry.
+ *
+ * @param node_id The node identifier.
+ * @param prop The property name.
+ * @param idx The mapping entry index.
+ * @return The starting index of the child specifier cell.
+ */
+#define DT_MAP_CHILD_SPECIFIER_IDX(node_id, prop, idx)                                             \
+	DT_CAT7(node_id, _P_, prop, _MAP_IDX_, idx, _, CHILD_SPECIFIER_IDX)
+
+/**
+ * @brief Returns the length (number of cells) of the child specifier within a mapping entry.
+ *
+ * @param node_id The node identifier.
+ * @param prop The property name.
+ * @param idx The mapping entry index.
+ * @return The length (in cells) of the child specifier.
+ */
+#define DT_MAP_CHILD_SPECIFIER_LEN(node_id, prop, idx)                                             \
+	DT_CAT7(node_id, _P_, prop, _MAP_IDX_, idx, _, CHILD_SPECIFIER_LEN)
+
+/**
+ * @brief Retrieves the starting index of the parent cell in a mapping entry.
+ *
+ * @param node_id The node identifier.
+ * @param prop The property name.
+ * @param idx The mapping entry index.
+ * @return The starting index of the parent cell.
+ */
+#define DT_MAP_PARENT_IDX(node_id, prop, idx)                                                      \
+	DT_CAT7(node_id, _P_, prop, _MAP_IDX_, idx, _, PARENT_IDX)
+
+/**
+ * @brief Returns the length (number of cells) of the parent cell in a mapping entry.
+ *
+ * @param node_id The node identifier.
+ * @param prop The property name.
+ * @param idx The mapping entry index.
+ * @return The length (in cells) of the parent cell.
+ */
+#define DT_MAP_PARENT_LEN(node_id, prop, idx)                                                      \
+	DT_CAT7(node_id, _P_, prop, _MAP_IDX_, idx, _, PARENT_LEN)
+
+/**
+ * @brief Retrieves the starting index of the parent specifier cell within a mapping entry.
+ *
+ * @param node_id The node identifier.
+ * @param prop The property name.
+ * @param idx The mapping entry index.
+ * @return The starting index of the parent specifier cell.
+ */
+#define DT_MAP_PARENT_SPECIFIER_IDX(node_id, prop, idx)                                            \
+	DT_CAT7(node_id, _P_, prop, _MAP_IDX_, idx, _, PARENT_SPECIFIER_IDX)
+
+/**
+ * @brief Returns the length (number of cells) of the parent specifier in a mapping entry.
+ *
+ * @param node_id The node identifier.
+ * @param prop The property name.
+ * @param idx The mapping entry index.
+ * @return The length (in cells) of the parent specifier.
+ */
+#define DT_MAP_PARENT_SPECIFIER_LEN(node_id, prop, idx)                                            \
+	DT_CAT7(node_id, _P_, prop, _MAP_IDX_, idx, _, PARENT_SPECIFIER_LEN)
+
+/**
+ * @brief Extracts the child specifier arguments from a mapping entry.
+ *
+ * This macro returns the comma-separated list of arguments for the child specifier.
+ *
+ * @param node_id The node identifier.
+ * @param prop The property name in lowercase with underscores.
+ * @param idx The mapping entry index.
+ * @return The child specifier arguments.
+ */
+#define DT_MAP_CHILD_SPECIFIER_ARGS(node_id, prop, idx)                                            \
+	DT_MAP_HELPER_ARGS_RANGE(CHILD_SPECIFIER, node_id, prop, idx,                              \
+				 DT_MAP_IDX(node_id, prop, idx))
+
+/**
+ * @brief Extracts the parent node argument from a mapping entry.
+ *
+ * @param node_id The node identifier.
+ * @param prop The property name in lowercase with underscores.
+ * @param idx The mapping entry index.
+ * @return The parent node argument.
+ */
+#define DT_MAP_PARENT_ARG(node_id, prop, idx)                                                      \
+	DT_MAP_HELPER_ARGS_RANGE(PARENT, node_id, prop, idx, DT_MAP_IDX(node_id, prop, idx))
+
+/**
+ * @brief Extracts the parent specifier arguments from a mapping entry.
+ *
+ * This macro returns the comma-separated list of arguments for the parent specifier.
+ *
+ * @param node_id The node identifier.
+ * @param prop The property name in lowercase with underscores.
+ * @param idx The mapping entry index.
+ * @return The parent specifier arguments.
+ */
+#define DT_MAP_PARENT_SPECIFIER_ARGS(node_id, prop, idx)                                           \
+	DT_MAP_HELPER_ARGS_RANGE(PARENT_SPECIFIER, node_id, prop, idx,                             \
+				 DT_MAP_IDX(node_id, prop, idx))
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ZEPHYR_INCLUDE_DEVICETREE_MAP_H_ */

scripts/dts/gen_defines.py

@@ -832,6 +832,36 @@ def phandle_macros(prop: edtlib.Property, macro: str) -> dict:
 
             ret.update(controller_and_data_macros(entry, i, macro))
 
+        if prop.name.endswith("-map"):
+            ret.update(map_macros(prop, macro))
+
+    return ret
+
+
+def map_macros(prop: edtlib.Property, macro: str) -> dict:
+    ret = {}
+
+    for i, cd in enumerate(prop.val):
+        parent_specifier_len = len([k for k in cd.data if k.startswith('parent_specifier_')])
+        child_specifiers = list(cd.data.values())[:-parent_specifier_len]
+        parent_specifiers = list(cd.data.values())[-parent_specifier_len:]
+        child_specifier_len = len(child_specifiers)
+
+        args = []
+        args.extend([str(v) for v in child_specifiers])
+        args.extend(["DT_" + node_z_path_id(cd.controller)])
+        args.extend([str(v) for v in parent_specifiers])
+
+        ret[f"{macro}_MAP_IDX_{i}_CHILD_SPECIFIER_IDX"] = 0
+        ret[f"{macro}_MAP_IDX_{i}_CHILD_SPECIFIER_LEN"] = child_specifier_len
+        ret[f"{macro}_MAP_IDX_{i}_PARENT_IDX"] = child_specifier_len
+        ret[f"{macro}_MAP_IDX_{i}_PARENT_LEN"] = 1
+        ret[f"{macro}_MAP_IDX_{i}_PARENT_SPECIFIER_IDX"] = child_specifier_len + 1
+        ret[f"{macro}_MAP_IDX_{i}_PARENT_SPECIFIER_LEN"] = parent_specifier_len
+        ret[f"{macro}_MAP_IDX_{i}"] = ", ".join(args)
+
+    ret[f"{macro}_MAP_LEN"] = len(prop.val)
+
     return ret