scripts: dts: Add handling for *-map property

soburi · soburi · commit 5b3e050e77ea · 2025-04-14T08:30:35.000+09:00
This change introduces generating definitions corresponding to
`*-map` property, which was currently discarded.

For `*-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, ...).

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 &lt;tokita.hiroshi@gmail.com&gt;
diff --git a/include/zephyr/devicetree.h b/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_ */
diff --git a/include/zephyr/devicetree/map.h b/include/zephyr/devicetree/map.h
@@ -0,0 +1,263 @@
+/*
+ * 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 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_ */
diff --git a/scripts/dts/gen_defines.py b/scripts/dts/gen_defines.py
@@ -288,6 +288,7 @@ def write_special_props(node: edtlib.Node) -> None:
     write_pinctrls(node)
     write_fixed_partitions(node)
     write_gpio_hogs(node)
+    write_maps(node)
 
 
 def write_ranges(node: edtlib.Node) -> None:
@@ -579,6 +580,72 @@ def write_gpio_hogs(node: edtlib.Node) -> None:
             out_dt_define(macro, val)
 
 
+def write_maps(node: edtlib.Node) -> None:
+    if len(node.maps) == 0:
+        return
+
+    out_comment("Map properties:")
+
+    basename = str2ident(node.maps[0].basename)
+    macro = f"{node.z_path_id}_P_{basename}_map"
+    macro2val = {}
+
+    for i, cd in enumerate(node.maps):
+        if basename != str2ident(cd.basename):
+            err(f"Map basename mismatch: {basename} != {str2ident(cd.basename)}")
+
+        macro2val.update(controller_and_data_macros(cd, i, macro))
+
+    prop_id = f"{basename}_map"
+    plen = len(node.maps)
+    # DT_N_<node-id>_P_<prop-id>_FOREACH_PROP_ELEM
+    macro2val[f"{macro}_FOREACH_PROP_ELEM(fn)"] = ' \\\n\t'.join(
+        f'fn(DT_{node.z_path_id}, {prop_id}, {i})' for i in range(plen)
+    )
+
+    # DT_N_<node-id>_P_<prop-id>_FOREACH_PROP_ELEM_SEP
+    macro2val[f"{macro}_FOREACH_PROP_ELEM_SEP(fn, sep)"] = ' DT_DEBRACKET_INTERNAL sep \\\n\t'.join(
+        f'fn(DT_{node.z_path_id}, {prop_id}, {i})' for i in range(plen)
+    )
+
+    # DT_N_<node-id>_P_<prop-id>_FOREACH_PROP_ELEM_VARGS
+    macro2val[f"{macro}_FOREACH_PROP_ELEM_VARGS(fn, ...)"] = ' \\\n\t'.join(
+        f'fn(DT_{node.z_path_id}, {prop_id}, {i}, __VA_ARGS__)' for i in range(plen)
+    )
+
+    # DT_N_<node-id>_P_<prop-id>_FOREACH_PROP_ELEM_SEP_VARGS
+    macro2val[f"{macro}_FOREACH_PROP_ELEM_SEP_VARGS(fn, sep, ...)"] = (
+        ' DT_DEBRACKET_INTERNAL sep \\\n\t'.join(
+            f'fn(DT_{node.z_path_id}, {prop_id}, {i}, __VA_ARGS__)' for i in range(plen)
+        )
+    )
+
+    macro2val[f"{macro}_LEN"] = plen
+    macro2val[f"{macro}_EXISTS"] = 1
+
+    for i, cd in enumerate(node.maps):
+        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])
+
+        macro2val[f"{macro}_MAP_IDX_{i}"] = ", ".join(args)
+        macro2val[f"{macro}_MAP_IDX_{i}_CHILD_SPECIFIER_IDX"] = 0
+        macro2val[f"{macro}_MAP_IDX_{i}_CHILD_SPECIFIER_LEN"] = child_specifier_len
+        macro2val[f"{macro}_MAP_IDX_{i}_PARENT_IDX"] = child_specifier_len
+        macro2val[f"{macro}_MAP_IDX_{i}_PARENT_LEN"] = 1
+        macro2val[f"{macro}_MAP_IDX_{i}_PARENT_SPECIFIER_IDX"] = child_specifier_len + 1
+        macro2val[f"{macro}_MAP_IDX_{i}_PARENT_SPECIFIER_LEN"] = parent_specifier_len
+
+    for mc, val in macro2val.items():
+        out_dt_define(mc, val)
+
+
 def write_vanilla_props(node: edtlib.Node) -> None:
     # Writes macros for any and all properties defined in the
     # "properties" section of the binding for the node.
diff --git a/scripts/dts/python-devicetree/src/devicetree/edtlib.py b/scripts/dts/python-devicetree/src/devicetree/edtlib.py
