Message-ID: <20250115085409.1629787-14-jirislaby@kernel.org>
Date: Wed, 15 Jan 2025 09:54:02 +0100
From: "Jiri Slaby (SUSE)" <jirislaby@...nel.org>
To: tglx@...utronix.de
Cc: maz@...nel.org,
	linux-kernel@...r.kernel.org,
	"Jiri Slaby (SUSE)" <jirislaby@...nel.org>,
	Jonathan Corbet <corbet@....net>,
	linux-doc@...r.kernel.org,
	Randy Dunlap <rdunlap@...radead.org>
Subject: [PATCH 13/18] irqdomain.h: Improve kernel-docs of functions

Many of irqdomain.h's functions are referenced in Documentation/ but are
not properly documented. Therefore, document these.

And use "Returns:" tag consistently, so that it is properly generated to
the resulting docs.

Signed-off-by: Jiri Slaby (SUSE) <jirislaby@...nel.org>
Cc: Jonathan Corbet <corbet@....net>
Cc: linux-doc@...r.kernel.org
Cc: Randy Dunlap <rdunlap@...radead.org>
---
 include/linux/irqdomain.h | 62 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 61 insertions(+), 1 deletion(-)

diff --git a/include/linux/irqdomain.h b/include/linux/irqdomain.h
index ca4628fa269d..6de8a9f3fecf 100644
--- a/include/linux/irqdomain.h
+++ b/include/linux/irqdomain.h
@@ -417,6 +417,26 @@ static inline struct irq_domain *irq_find_host(struct device_node *node)
 	return d;
 }
 
+/**
+ * irq_domain_add_simple_of_node() - Register an irq_domain and optionally map a range of irqs
+ * @of_node: pointer to interrupt controller's device tree node.
+ * @size: total number of irqs in mapping
+ * @first_irq: first number of irq block assigned to the domain,
+ *	pass zero to assign irqs on-the-fly. If first_irq is non-zero, then
+ *	pre-map all of the irqs in the domain to virqs starting at first_irq.
+ * @ops: domain callbacks
+ * @host_data: Controller private data pointer
+ *
+ * Allocates an irq_domain, and optionally if @first_irq is positive then also
+ * allocate irq_descs and map all of the hwirqs to virqs starting at @first_irq.
+ *
+ * This is intended to implement the expected behaviour for most
+ * interrupt controllers. If device tree is used, then @first_irq will be 0 and
+ * irqs get mapped dynamically on the fly. However, if the controller requires
+ * static virq assignments (non-DT boot) then it will set that up correctly.
+ *
+ * Returns: Newly created irq_domain
+ */
 static inline struct irq_domain *irq_domain_add_simple_of_node(struct device_node *of_node,
 						       unsigned int size,
 						       unsigned int first_irq,
@@ -486,6 +506,15 @@ static inline struct irq_domain *irq_domain_add_tree_of_node(struct device_node
 	return IS_ERR(d) ? NULL : d;
 }
 
+/**
+ * irq_domain_add_linear_fwnode() - Allocate and register a linear revmap irq_domain.
+ * @fwnode: pointer to interrupt controller's FW node.
+ * @size: Number of interrupts in the domain.
+ * @ops: map/unmap domain callbacks
+ * @host_data: Controller private data pointer
+ *
+ * Returns: Newly created irq_domain
+ */
 static inline struct irq_domain *irq_domain_add_linear_fwnode(struct fwnode_handle *fwnode,
 					 unsigned int size,
 					 const struct irq_domain_ops *ops,
@@ -532,6 +561,18 @@ unsigned int irq_create_mapping_affinity(struct irq_domain *domain,
 unsigned int irq_create_fwspec_mapping(struct irq_fwspec *fwspec);
 void irq_dispose_mapping(unsigned int virq);
 
+/**
+ * irq_create_mapping() - Map a hardware interrupt into linux irq space
+ * @domain: domain owning this hardware interrupt or NULL for default domain
+ * @hwirq: hardware irq number in that domain space
+ *
+ * Only one mapping per hardware interrupt is permitted.
+ *
+ * If the sense/trigger is to be specified, set_irq_type() should be called
+ * on the number returned from that call.
+ *
+ * Returns: Linux irq number or 0 on error
+ */
 static inline unsigned int irq_create_mapping(struct irq_domain *domain,
 					      irq_hw_number_t hwirq)
 {
@@ -542,6 +583,13 @@ struct irq_desc *__irq_resolve_mapping(struct irq_domain *domain,
 				       irq_hw_number_t hwirq,
 				       unsigned int *irq);
 
+/**
+ * irq_resolve_mapping() - Find a linux irq from a hw irq number.
+ * @domain: domain owning this hardware interrupt
+ * @hwirq: hardware irq number in that domain space
+ *
+ * Returns: Interrupt descriptor
+ */
 static inline struct irq_desc *irq_resolve_mapping(struct irq_domain *domain,
 						   irq_hw_number_t hwirq)
 {
@@ -552,6 +600,8 @@ static inline struct irq_desc *irq_resolve_mapping(struct irq_domain *domain,
  * irq_find_mapping() - Find a linux irq from a hw irq number.
  * @domain: domain owning this hardware interrupt
  * @hwirq: hardware irq number in that domain space
+ *
+ * Returns: Linux irq number or 0 if not found
  */
 static inline unsigned int irq_find_mapping(struct irq_domain *domain,
 					    irq_hw_number_t hwirq)
@@ -614,7 +664,8 @@ void irq_domain_reset_irq_data(struct irq_data *irq_data);
  *
  * If successful the parent is associated to the new domain and the
  * domain flags are set.
- * Returns pointer to IRQ domain, or NULL on failure.
+ *
+ * Returns: A pointer to IRQ domain, or %NULL on failure.
  */
 static inline struct irq_domain *irq_domain_add_hierarchy_fwnode(struct irq_domain *parent,
 					    unsigned int flags,
@@ -657,6 +708,15 @@ void irq_domain_free_irqs(unsigned int virq, unsigned int nr_irqs);
 int irq_domain_activate_irq(struct irq_data *irq_data, bool early);
 void irq_domain_deactivate_irq(struct irq_data *irq_data);
 
+/**
+ * irq_domain_alloc_irqs - Allocate IRQs from domain
+ * @domain:	domain to allocate from
+ * @nr_irqs:	number of IRQs to allocate
+ * @node:	NUMA node id for memory allocation
+ * @arg:	domain specific argument
+ *
+ * See __irq_domain_alloc_irqs()' documentation.
+ */
 static inline int irq_domain_alloc_irqs(struct irq_domain *domain,
 			unsigned int nr_irqs, int node, void *arg)
 {
-- 
2.48.0

Powered by blists - more mailing lists