Commit 2272a78b authored by Jiri Slaby (SUSE)'s avatar Jiri Slaby (SUSE) Committed by Thomas Gleixner
Browse files

irqdomain: 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 in
the resulting docs.

Signed-off-by: default avatarJiri Slaby (SUSE) <jirislaby@kernel.org>
Signed-off-by: default avatarThomas Gleixner <tglx@linutronix.de>
Link: https://lore.kernel.org/all/20250319092951.37667-53-jirislaby@kernel.org
parent 66cbf17f

include/linux/irqdomain.h

+41 −1
Original line number Diff line number Diff line
@@ -411,6 +411,15 @@ static inline struct irq_domain *irq_domain_create_nomap(struct fwnode_handle *f 
unsigned int irq_create_direct_mapping(struct irq_domain *domain);

#endif



/**

 * irq_domain_create_linear - 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_create_linear(struct fwnode_handle *fwnode,

					 unsigned int size,

					 const struct irq_domain_ops *ops,
@@ -457,6 +466,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)

{
@@ -467,6 +488,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)

{
@@ -477,6 +505,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)
@@ -539,7 +569,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_create_hierarchy(struct irq_domain *parent,

					    unsigned int flags,
@@ -570,6 +601,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)

{