of_irq_foreach_imap is an iterator designed to help a driver to parse
an interrupt-map property.

Indeed some drivers need to know details about the interrupt mapping
described in the device-tree in order to set internal registers
accordingly.

Signed-off-by: Herve Codina <herve.codina@bootlin.com>
---
 drivers/of/irq.c       | 70 ++++++++++++++++++++++++++++++++++++++++++
 include/linux/of_irq.h | 11 +++++++
 2 files changed, 81 insertions(+)

diff --git a/drivers/of/irq.c b/drivers/of/irq.c
index f8ad79b9b1c9..863b31eb3c1a 100644
--- a/drivers/of/irq.c
+++ b/drivers/of/irq.c
@@ -157,6 +157,76 @@ const __be32 *of_irq_parse_imap_parent(const __be32 *imap, int len, struct of_ph
 	return imap;
 }
 
+/**
+ * of_irq_foreach_imap - Iterate through interrupt-map items
+ * @np: device node where interrupt-map is available
+ * @func: function called on each interrupt-map items
+ * @data: data passe to @func
+ *
+ * This function iterates through interrupt-map items and calls @func on each
+ * item. The parent interrupt described in the interrupt-map item is parsed
+ * and passed to @func using a pointer to a struct of_phandle_args.
+ * Also the imap raw value is passed in order to allow @func to look at other
+ * values of the interrupt-map (child unit address and child interrupt
+ * specificer)
+ *
+ * If @func returns an error, the iteration stops and this error is returned.
+ */
+int of_irq_foreach_imap(struct device_node *np,
+			int (*func)(void *data,
+				    const __be32 *imap,
+				    const struct of_phandle_args *parent_args),
+			void *data)
+{
+	const __be32 *imap, *imap_end, *imap_parent, *imap_next;
+	struct of_phandle_args parent_args;
+	u32 tmp, parent_offset;
+	int imaplen;
+	int ret;
+
+	/*
+	 * parent_offset is the offset where the parent part is starting.
+	 * In other words, the offset where the parent interrupt controller
+	 * phandle is present.
+	 *
+	 * Compute this offset (child #interrupt-cells + child #address-cells)
+	 */
+	parent_offset = of_bus_n_addr_cells(np);
+
+	ret = of_property_read_u32(np, "#interrupt-cells", &tmp);
+	if (ret)
+		return ret;
+
+	parent_offset += tmp;
+
+	imap = of_get_property(np, "interrupt-map", &imaplen);
+	if (!imap)
+		return -ENOENT;
+
+	imaplen /= sizeof(*imap);
+	imap_end = imap + imaplen;
+
+	while (imap + parent_offset + 1 < imap_end) {
+		imap_parent = imap + parent_offset;
+
+		imap_next = of_irq_parse_imap_parent(imap_parent,
+						     imap_end - imap_parent,
+						     &parent_args);
+		if (!imap_next)
+			return -EINVAL;
+
+		ret = func(data, imap, &parent_args);
+		of_node_put(parent_args.np);
+		if (ret)
+			return ret;
+
+		imap = imap_next;
+	}
+
+	return 0;
+}
+EXPORT_SYMBOL_GPL(of_irq_foreach_imap);
+
 /**
  * of_irq_parse_raw - Low level interrupt tree parsing
  * @addr:	address specifier (start of "reg" property of the device) in be32 format
diff --git a/include/linux/of_irq.h b/include/linux/of_irq.h
index 6337ad4e5fe8..b89920c6ab55 100644
--- a/include/linux/of_irq.h
+++ b/include/linux/of_irq.h
@@ -47,6 +47,10 @@ extern int of_irq_get_byname(struct device_node *dev, const char *name);
 extern int of_irq_to_resource_table(struct device_node *dev,
 		struct resource *res, int nr_irqs);
 extern struct device_node *of_irq_find_parent(struct device_node *child);
+extern int of_irq_foreach_imap(struct device_node *np,
+			       int (*func)(void *data, const __be32 *imap,
+					   const struct of_phandle_args *parent_args),
+			       void *data);
 extern struct irq_domain *of_msi_get_domain(struct device *dev,
 					    const struct device_node *np,
 					    enum irq_domain_bus_token token);
@@ -85,6 +89,13 @@ static inline void *of_irq_find_parent(struct device_node *child)
 {
 	return NULL;
 }
+static inline int of_irq_foreach_imap(struct device_node *np,
+				      int (*func)(void *data, const __be32 *imap,
+						  const struct of_phandle_args *parent_args),
+				      void *data)
+{
+	return -EINVAL;
+}
 
 static inline struct irq_domain *of_msi_get_domain(struct device *dev,
 						   struct device_node *np,
-- 
2.50.1

On Fri, Jul 25, 2025 at 05:26:13PM +0200, Herve Codina wrote:
> of_irq_foreach_imap is an iterator designed to help a driver to parse
> an interrupt-map property.
> 
> Indeed some drivers need to know details about the interrupt mapping
> described in the device-tree in order to set internal registers
> accordingly.

I would like to see some existing user converted to make sure it works 
for other cases.

> 
> Signed-off-by: Herve Codina <herve.codina@bootlin.com>
> ---
>  drivers/of/irq.c       | 70 ++++++++++++++++++++++++++++++++++++++++++
>  include/linux/of_irq.h | 11 +++++++
>  2 files changed, 81 insertions(+)
> 
> diff --git a/drivers/of/irq.c b/drivers/of/irq.c
> index f8ad79b9b1c9..863b31eb3c1a 100644
> --- a/drivers/of/irq.c
> +++ b/drivers/of/irq.c
> @@ -157,6 +157,76 @@ const __be32 *of_irq_parse_imap_parent(const __be32 *imap, int len, struct of_ph
>  	return imap;
>  }
>  
> +/**
> + * of_irq_foreach_imap - Iterate through interrupt-map items
> + * @np: device node where interrupt-map is available
> + * @func: function called on each interrupt-map items
> + * @data: data passe to @func
> + *
> + * This function iterates through interrupt-map items and calls @func on each
> + * item. The parent interrupt described in the interrupt-map item is parsed
> + * and passed to @func using a pointer to a struct of_phandle_args.
> + * Also the imap raw value is passed in order to allow @func to look at other
> + * values of the interrupt-map (child unit address and child interrupt
> + * specificer)
> + *
> + * If @func returns an error, the iteration stops and this error is returned.
> + */
> +int of_irq_foreach_imap(struct device_node *np,
> +			int (*func)(void *data,
> +				    const __be32 *imap,
> +				    const struct of_phandle_args *parent_args),
> +			void *data)

The func callback is a departure from other DT iterators. Look at the 
'ranges' iterator which keeps the state on each iteration.

Rob

Hi Rob,

On Tue, 29 Jul 2025 14:51:51 -0500
Rob Herring <robh@kernel.org> wrote:

> On Fri, Jul 25, 2025 at 05:26:13PM +0200, Herve Codina wrote:
> > of_irq_foreach_imap is an iterator designed to help a driver to parse
> > an interrupt-map property.
> > 
> > Indeed some drivers need to know details about the interrupt mapping
> > described in the device-tree in order to set internal registers
> > accordingly.  
> 
> I would like to see some existing user converted to make sure it works 
> for other cases.

I will see what I can do for the next iteration.
Maybe I will propose a unit test for this new API.

> 
> > 
> > Signed-off-by: Herve Codina <herve.codina@bootlin.com>
> > ---
> >  drivers/of/irq.c       | 70 ++++++++++++++++++++++++++++++++++++++++++
> >  include/linux/of_irq.h | 11 +++++++
> >  2 files changed, 81 insertions(+)
> > 
> > diff --git a/drivers/of/irq.c b/drivers/of/irq.c
> > index f8ad79b9b1c9..863b31eb3c1a 100644
> > --- a/drivers/of/irq.c
> > +++ b/drivers/of/irq.c
> > @@ -157,6 +157,76 @@ const __be32 *of_irq_parse_imap_parent(const __be32 *imap, int len, struct of_ph
> >  	return imap;
> >  }
> >  
> > +/**
> > + * of_irq_foreach_imap - Iterate through interrupt-map items
> > + * @np: device node where interrupt-map is available
> > + * @func: function called on each interrupt-map items
> > + * @data: data passe to @func
> > + *
> > + * This function iterates through interrupt-map items and calls @func on each
> > + * item. The parent interrupt described in the interrupt-map item is parsed
> > + * and passed to @func using a pointer to a struct of_phandle_args.
> > + * Also the imap raw value is passed in order to allow @func to look at other
> > + * values of the interrupt-map (child unit address and child interrupt
> > + * specificer)
> > + *
> > + * If @func returns an error, the iteration stops and this error is returned.
> > + */
> > +int of_irq_foreach_imap(struct device_node *np,
> > +			int (*func)(void *data,
> > +				    const __be32 *imap,
> > +				    const struct of_phandle_args *parent_args),
> > +			void *data)  
> 
> The func callback is a departure from other DT iterators. Look at the 
> 'ranges' iterator which keeps the state on each iteration.
> 

I see, I will propose a reworked version in the next iteration to have
something similar to ranges:
  - of_irq_imap_parser_init()
  - for_each_of_range() with something like
       for (; of_irq_imap_parser_one(parser, imap);)
  - of_irq_imap_parser_one()
  - of_irq_imap_parser_exit(): Not sure, will see if I need to release something

Best regards,
Hervé