Recognize per-index IRQ controller macros

doc/build/dts/macros.bnf

@@ -1,4 +1,4 @@
 ; An RFC 7405 ABNF grammar for devicetree macros.
 ;
 ; This does *not* cover macros pulled out of DT via Kconfig,
 ; like CONFIG_SRAM_BASE_ADDRESS, etc. It only describes the
@@ -42,6 +42,7 @@
 node-macro =/ %s"DT_N" path-id %s"_IRQ_IDX_" DIGIT "_EXISTS"
 node-macro =/ %s"DT_N" path-id %s"_IRQ_IDX_" DIGIT
               %s"_VAL_" dt-name [ %s"_EXISTS" ]
+node-macro =/ %s"DT_N" path-id %s"_IRQ_IDX_" DIGIT %s"_CONTROLLER"
 node-macro =/ %s"DT_N" path-id %s"_CONTROLLER"
 node-macro =/ %s"DT_N" path-id %s"_IRQ_NAME_" dt-name
               %s"_VAL_" dt-name [ %s"_EXISTS" ]
@@ -57,7 +58,7 @@
 node-macro =/ %s"DT_N" path-id %s"_FOREACH_RANGE"
 ; Subnodes of the fixed-partitions compatible get macros which contain
 ; a unique ordinal value for each partition
-node-macro =/ %s"DT_N" path-id %s"_PARTITION_ID" DIGIT
+node-macro =/ %s"DT_N" path-id %s"_PARTITION_ID"
 ; Macros are generated for each of a node's compatibles;
 ; dt-name in this case is something like "vnd_device".
 node-macro =/ %s"DT_N" path-id %s"_COMPAT_MATCHES_" dt-name
@@ -74,6 +75,44 @@
 node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_FOREACH_PROP_ELEM_SEP"
 node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_FOREACH_PROP_ELEM_VARGS"
 node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_FOREACH_PROP_ELEM_SEP_VARGS"
+; Map properties generate additional macros consumed by DT_MAP_* APIs.
+; The following examples assume something like this mapping nexus:
+;
+;     connector {
+;             gpio-map = <1 2 &{/gpio-map-test/parent} 3
+;                         4 5 &{/gpio-map-test/parent} 6>;
+;     };
+;
+; Total number of entries in the mapping array.
+;
+;   #define DT_N_<connector path>_P_gpio_map_MAP_LEN 2
+node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_MAP_LEN"
+; Each mapping entry expands to the child specifier cells, the parent node,
+; and the parent specifier cells. DT_MAP_BY_IDX() retrieves this list.
+;
+;   #define DT_N_<connector path>_P_gpio_map_MAP_IDX_0 1, 2, DT_N_<parent path>, 3
+node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_MAP_IDX_" DIGIT
+; Offsets for the child specifier cells within an entry. These support
+; DT_MAP_CHILD_SPECIFIER_ARGS_BY_IDX(), which slices out just those cells.
+;
+;   #define DT_N_<connector path>_P_gpio_map_MAP_IDX_0_CHILD_SPECIFIER_POS 0
+;   #define DT_N_<connector path>_P_gpio_map_MAP_IDX_0_CHILD_SPECIFIER_LEN 2
+node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_MAP_IDX_" DIGIT %s"_CHILD_SPECIFIER_POS"
+node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_MAP_IDX_" DIGIT %s"_CHILD_SPECIFIER_LEN"
+; Offsets for the parent node argument. DT_MAP_PARENT_ARG_BY_IDX() uses
+; these to extract the parent node identifier.
+;
+;   #define DT_N_<connector path>_P_gpio_map_MAP_IDX_0_PARENT_POS 2
+;   #define DT_N_<connector path>_P_gpio_map_MAP_IDX_0_PARENT_LEN 1
+node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_MAP_IDX_" DIGIT %s"_PARENT_POS"
+node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_MAP_IDX_" DIGIT %s"_PARENT_LEN"
+; Offsets for the parent specifier cells used by
+; DT_MAP_PARENT_SPECIFIER_ARGS_BY_IDX().
+;
+;   #define DT_N_<connector path>_P_gpio_map_MAP_IDX_0_PARENT_SPECIFIER_POS 3
+;   #define DT_N_<connector path>_P_gpio_map_MAP_IDX_0_PARENT_SPECIFIER_LEN 1
+node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_MAP_IDX_" DIGIT %s"_PARENT_SPECIFIER_POS"
+node-macro =/ %s"DT_N" path-id %s"_P_" prop-id %s"_MAP_IDX_" DIGIT %s"_PARENT_SPECIFIER_LEN"
 ; These are used by DT_CHILD_NUM and DT_CHILD_NUM_STATUS_OKAY macros
 node-macro =/ %s"DT_N" path-id %s"_CHILD_NUM"
 node-macro =/ %s"DT_N" path-id %s"_CHILD_NUM_STATUS_OKAY"
@@ -106,10 +145,20 @@
 node-macro =/ %s"DT_N" path-id %s"_PATH"
 ; The node's name@unit-addr, as a string literal
 node-macro =/ %s"DT_N" path-id %s"_FULL_NAME"
+; The node's name@unit-addr without surrounding quotes.
+node-macro =/ %s"DT_N" path-id %s"_FULL_NAME_UNQUOTED"
+; Tokenized variants of the node's name@unit-addr.
+node-macro =/ %s"DT_N" path-id %s"_FULL_NAME_TOKEN"
+node-macro =/ %s"DT_N" path-id %s"_FULL_NAME_UPPER_TOKEN"
 ; The dependency ordinals of a node's requirements (direct dependencies).
 node-macro =/ %s"DT_N" path-id %s"_REQUIRES_ORDS"
 ; The dependency ordinals of a node supports (reverse direct dependencies).
 node-macro =/ %s"DT_N" path-id %s"_SUPPORTS_ORDS"
+; Helper macros that iterate over the node's ancestors.
+node-macro =/ %s"DT_N" path-id %s"_FOREACH_ANCESTOR"
+; Node specific hash and sortable dependency strings.
+node-macro =/ %s"DT_N" path-id %s"_HASH"
+node-macro =/ %s"DT_N" path-id %s"_ORD_STR_SORTABLE"
 
 ; --------------------------------------------------------------------
 ; pinctrl-macro: a macro related to the pinctrl properties in a node
@@ -136,6 +185,11 @@
 ;     #define DT_N_<node path>_PINCTRL_IDX_0_EXISTS 1
 ;     #define DT_N_<node path>_PINCTRL_IDX_1_EXISTS 1
 pinctrl-macro =/ %s"DT_N" path-id %s"_PINCTRL_IDX_" DIGIT %s"_EXISTS"
+; Tokenized variants of a given pinctrl-DIGIT property.
+; These mirror the node FULL_NAME token macros to make use of existing
+; helpers that expect both lower and upper token forms.
+pinctrl-macro =/ %s"DT_N" path-id %s"_PINCTRL_IDX_" DIGIT %s"_TOKEN"
+pinctrl-macro =/ %s"DT_N" path-id %s"_PINCTRL_IDX_" DIGIT %s"_UPPER_TOKEN"
 ; A given pinctrl property name exists.
 ;
 ;     #define DT_N_<node path>_PINCTRL_NAME_default_EXISTS 1
@@ -187,12 +241,12 @@
 ;
 ;   #define DT_N_<node-1 path>_GPIO_HOGS_EXISTS 1
 ;   #define DT_N_<node-2 path>_GPIO_HOGS_EXISTS 1
-gpioshogs-macro = %s"DT_N" path-id %s"_GPIO_HOGS_EXISTS"
+gpiohogs-macro = %s"DT_N" path-id %s"_GPIO_HOGS_EXISTS"
 ; Number of hogged GPIOs in a node.
 ;
 ;   #define DT_N_<node-1 path>_GPIO_HOGS_NUM 2
 ;   #define DT_N_<node-2 path>_GPIO_HOGS_NUM 1
-gpioshogs-macro =/ %s"DT_N" path-id %s"_GPIO_HOGS_NUM"
+gpiohogs-macro =/ %s"DT_N" path-id %s"_GPIO_HOGS_NUM"
 ; A given logical GPIO hog array index exists.
 ;
 ;   #define DT_N_<node-1 path>_GPIO_HOGS_IDX_0_EXISTS 1
@@ -206,6 +260,10 @@
 ;   #define DT_N_<node-1 path>_GPIO_HOGS_IDX_1_PH <node id for 'gpio1'>
 ;   #define DT_N_<node-2 path>_GPIO_HOGS_IDX_0_PH <node id for 'gpio1'>
 gpiohogs-macro =/ %s"DT_N" path-id %s"_GPIO_HOGS_IDX_" DIGIT %s"_PH"
+; Iteration helpers for the specifier cells exposed by DT_FOREACH_* macros.
+gpiohogs-macro =/ %s"DT_N" path-id %s"_GPIO_HOGS_IDX_" DIGIT %s"_FOREACH_CELL"
+gpiohogs-macro =/ %s"DT_N" path-id %s"_GPIO_HOGS_IDX_" DIGIT %s"_FOREACH_CELL_SEP"
+gpiohogs-macro =/ %s"DT_N" path-id %s"_GPIO_HOGS_IDX_" DIGIT %s"_NUM_CELLS"
 ; The pin cell of a logical index in the GPIO hogs array exists.
 ;
 ;   #define DT_N_<node-1 path>_GPIO_HOGS_IDX_0_VAL_pin_EXISTS 1
@@ -272,8 +330,9 @@
 ;           };
 ;   };
 ;
-; has path-id "_S_foo_123_S_bar_baz".
-path-id = 1*( %s"_S_" dt-name )
+; has path-id "_S_foo_123_S_bar_baz". The root node "/" has an empty
+; path-id, which results in a bare "DT_N" identifier.
+path-id = *( %s"_S_" dt-name )
 
 ; ----------------------------------------------------------------------
 ; prop-id: a property identifier
@@ -341,6 +400,7 @@
 other-macro =/ %s"DT_FOREACH_OKAY_INST_VARGS_" dt-name
 ; E.g.: #define DT_CHOSEN_zephyr_flash
 other-macro =/ %s"DT_CHOSEN_" dt-name
+other-macro =/ %s"DT_CHOSEN_" dt-name %s"_EXISTS"
 ; Declares that a compatible has at least one node on a bus.
 ; Example:
 ;
@@ -354,7 +414,12 @@
 ; Currently used to allow mapping a lowercase-and-underscores "label"
 ; property to a fixed-partitions node. See the flash map API docs
 ; for an example.
-other-macro =/ %s"DT_COMPAT_" dt-name %s"_LABEL_" dt-name
+other-macro =/ %s"DT_COMPAT_" dt-name %s"_LABEL_" dt-name [ %s"_EXISTS" ]
+; Helper macros expanded while iterating over nodes.
+other-macro =/ %s"DT_FOREACH_VARGS_HELPER"
+other-macro =/ %s"DT_FOREACH_OKAY_VARGS_HELPER"
+; Removes brackets while expanding variadic helper macros.
+other-macro =/ %s"DT_DEBRACKET_INTERNAL"
 
 ; --------------------------------------------------------------------
 ; alternate-id: another way to specify a node besides a path-id