Skip to contentSkip to conversation

irqdomain: Cleanups and Documentation

PATCH Applied Jiri Slaby (SUSE) 20 participants 273 messages Mar 19, 2025 – May 16, 2025 Page 4 of 4

Subsystems (144)
lore
Share & tools
lore
#190 lore raw

[tip: irq/cleanups] sh: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     f569ac9cabfd983d3d3904dbc9d7dbbf13368f4b
Gitweb:        https://git.kernel.org/tip/f569ac9cabfd983d3d3904dbc9d7dbbf13368f4b
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:35 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Fri, 16 May 2025 21:06:12 +02:00

sh: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 arch/sh/boards/mach-se/7343/irq.c | 2 +-
 arch/sh/boards/mach-se/7722/irq.c | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
arch/sh/boards/mach-se/7343/irq.c +1 -1
index 8241bde..730c01b 100644
@@ -71,7 +71,7 @@ static void __init se7343_gc_init(void)
 	struct irq_chip_type *ct;
 	unsigned int irq_base;
 
-	irq_base = irq_linear_revmap(se7343_irq_domain, 0);
+	irq_base = irq_find_mapping(se7343_irq_domain, 0);
 
 	gc = irq_alloc_generic_chip(DRV_NAME, 1, irq_base, se7343_irq_regs,
 				    handle_level_irq);
arch/sh/boards/mach-se/7722/irq.c +1 -1
index 9a460a8..49aa3a2 100644
@@ -69,7 +69,7 @@ static void __init se7722_gc_init(void)
 	struct irq_chip_type *ct;
 	unsigned int irq_base;
 
-	irq_base = irq_linear_revmap(se7722_irq_domain, 0);
+	irq_base = irq_find_mapping(se7722_irq_domain, 0);
 
 	gc = irq_alloc_generic_chip(DRV_NAME, 1, irq_base, se7722_irq_regs,
 				    handle_level_irq);
#191 lore raw

PATCH v2 43/57 irqdomain: gpio: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

---
 drivers/gpio/gpio-idt3243x.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpio/gpio-idt3243x.c +1 -1
index 00f547d26254..535f25514455 100644
@@ -37,7 +37,7 @@ static void idt_gpio_dispatch(struct irq_desc *desc)
 	pending = readl(ctrl->pic + IDT_PIC_IRQ_PEND);
 	pending &= ~ctrl->mask_cache;
 	for_each_set_bit(bit, &pending, gc->ngpio) {
-		virq = irq_linear_revmap(gc->irq.domain, bit);
+		virq = irq_find_mapping(gc->irq.domain, bit);
 		if (virq)
 			generic_handle_irq(virq);
 	}
Signature · 1 line
2.49.0
#193 lore raw

[tip: irq/cleanups] gpio: idt3243x: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     709457a648ec7e6b2513b948b1b592c08c00d3f6
Gitweb:        https://git.kernel.org/tip/709457a648ec7e6b2513b948b1b592c08c00d3f6
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:36 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Tue, 06 May 2025 14:59:08 +02:00

gpio: idt3243x: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 drivers/gpio/gpio-idt3243x.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpio/gpio-idt3243x.c +1 -1
index 00f547d..535f255 100644
@@ -37,7 +37,7 @@ static void idt_gpio_dispatch(struct irq_desc *desc)
 	pending = readl(ctrl->pic + IDT_PIC_IRQ_PEND);
 	pending &= ~ctrl->mask_cache;
 	for_each_set_bit(bit, &pending, gc->ngpio) {
-		virq = irq_linear_revmap(gc->irq.domain, bit);
+		virq = irq_find_mapping(gc->irq.domain, bit);
 		if (virq)
 			generic_handle_irq(virq);
 	}
#194 lore raw

[tip: irq/cleanups] gpio: idt3243x: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     438ff42640f0c2e5dfff92cfed8a7bec10110a96
Gitweb:        https://git.kernel.org/tip/438ff42640f0c2e5dfff92cfed8a7bec10110a96
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:36 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 09:53:24 +02:00

gpio: idt3243x: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 drivers/gpio/gpio-idt3243x.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpio/gpio-idt3243x.c +1 -1
index 00f547d..535f255 100644
@@ -37,7 +37,7 @@ static void idt_gpio_dispatch(struct irq_desc *desc)
 	pending = readl(ctrl->pic + IDT_PIC_IRQ_PEND);
 	pending &= ~ctrl->mask_cache;
 	for_each_set_bit(bit, &pending, gc->ngpio) {
-		virq = irq_linear_revmap(gc->irq.domain, bit);
+		virq = irq_find_mapping(gc->irq.domain, bit);
 		if (virq)
 			generic_handle_irq(virq);
 	}
#195 lore raw

[tip: irq/cleanups] gpio: idt3243x: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     0b2f024f813c8996500636011b848d1bdedd8990
Gitweb:        https://git.kernel.org/tip/0b2f024f813c8996500636011b848d1bdedd8990
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:36 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 15:39:41 +02:00

gpio: idt3243x: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 drivers/gpio/gpio-idt3243x.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpio/gpio-idt3243x.c +1 -1
index 00f547d..535f255 100644
@@ -37,7 +37,7 @@ static void idt_gpio_dispatch(struct irq_desc *desc)
 	pending = readl(ctrl->pic + IDT_PIC_IRQ_PEND);
 	pending &= ~ctrl->mask_cache;
 	for_each_set_bit(bit, &pending, gc->ngpio) {
-		virq = irq_linear_revmap(gc->irq.domain, bit);
+		virq = irq_find_mapping(gc->irq.domain, bit);
 		if (virq)
 			generic_handle_irq(virq);
 	}
#196 lore raw

[tip: irq/cleanups] gpio: idt3243x: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     30b6692ceda0dae971e9471479285b6b2b914aee
Gitweb:        https://git.kernel.org/tip/30b6692ceda0dae971e9471479285b6b2b914aee
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:36 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Fri, 16 May 2025 21:06:12 +02:00

gpio: idt3243x: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 drivers/gpio/gpio-idt3243x.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpio/gpio-idt3243x.c +1 -1
index 00f547d..535f255 100644
@@ -37,7 +37,7 @@ static void idt_gpio_dispatch(struct irq_desc *desc)
 	pending = readl(ctrl->pic + IDT_PIC_IRQ_PEND);
 	pending &= ~ctrl->mask_cache;
 	for_each_set_bit(bit, &pending, gc->ngpio) {
-		virq = irq_linear_revmap(gc->irq.domain, bit);
+		virq = irq_find_mapping(gc->irq.domain, bit);
 		if (virq)
 			generic_handle_irq(virq);
 	}
#197 lore raw

PATCH v2 44/57 irqdomain: gpu: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

---
 drivers/gpu/ipu-v3/ipu-common.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
drivers/gpu/ipu-v3/ipu-common.c +2 -2
index 223e6d563a6b..333f36e0a715 100644
@@ -1008,7 +1008,7 @@ int ipu_map_irq(struct ipu_soc *ipu, int irq)
 {
 	int virq;
 
-	virq = irq_linear_revmap(ipu->domain, irq);
+	virq = irq_find_mapping(ipu->domain, irq);
 	if (!virq)
 		virq = irq_create_mapping(ipu->domain, irq);
 
@@ -1219,7 +1219,7 @@ static void ipu_irq_exit(struct ipu_soc *ipu)
 	/* TODO: remove irq_domain_generic_chips */
 
 	for (i = 0; i < IPU_NUM_IRQS; i++) {
-		irq = irq_linear_revmap(ipu->domain, i);
+		irq = irq_find_mapping(ipu->domain, i);
 		if (irq)
 			irq_dispose_mapping(irq);
 	}
Signature · 1 line
2.49.0
#198 lore raw

[tip: irq/cleanups] gpu: ipu-v3: Switch to irq_find_mapping()

The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     20f9224bb56fb699238f9d13b9da76a068705b0f
Gitweb:        https://git.kernel.org/tip/20f9224bb56fb699238f9d13b9da76a068705b0f
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:37 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Tue, 06 May 2025 14:59:08 +02:00

gpu: ipu-v3: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 drivers/gpu/ipu-v3/ipu-common.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
drivers/gpu/ipu-v3/ipu-common.c +2 -2
index 223e6d5..333f36e 100644
@@ -1008,7 +1008,7 @@ int ipu_map_irq(struct ipu_soc *ipu, int irq)
 {
 	int virq;
 
-	virq = irq_linear_revmap(ipu->domain, irq);
+	virq = irq_find_mapping(ipu->domain, irq);
 	if (!virq)
 		virq = irq_create_mapping(ipu->domain, irq);
 
@@ -1219,7 +1219,7 @@ static void ipu_irq_exit(struct ipu_soc *ipu)
 	/* TODO: remove irq_domain_generic_chips */
 
 	for (i = 0; i < IPU_NUM_IRQS; i++) {
-		irq = irq_linear_revmap(ipu->domain, i);
+		irq = irq_find_mapping(ipu->domain, i);
 		if (irq)
 			irq_dispose_mapping(irq);
 	}
#199 lore raw

[tip: irq/cleanups] gpu: ipu-v3: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     9195834aad740c8f4550bdda89a7152c3f5d0d32
Gitweb:        https://git.kernel.org/tip/9195834aad740c8f4550bdda89a7152c3f5d0d32
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:37 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 09:53:24 +02:00

gpu: ipu-v3: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 drivers/gpu/ipu-v3/ipu-common.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
drivers/gpu/ipu-v3/ipu-common.c +2 -2
index 223e6d5..333f36e 100644
@@ -1008,7 +1008,7 @@ int ipu_map_irq(struct ipu_soc *ipu, int irq)
 {
 	int virq;
 
-	virq = irq_linear_revmap(ipu->domain, irq);
+	virq = irq_find_mapping(ipu->domain, irq);
 	if (!virq)
 		virq = irq_create_mapping(ipu->domain, irq);
 
@@ -1219,7 +1219,7 @@ static void ipu_irq_exit(struct ipu_soc *ipu)
 	/* TODO: remove irq_domain_generic_chips */
 
 	for (i = 0; i < IPU_NUM_IRQS; i++) {
-		irq = irq_linear_revmap(ipu->domain, i);
+		irq = irq_find_mapping(ipu->domain, i);
 		if (irq)
 			irq_dispose_mapping(irq);
 	}
#200 lore raw

[tip: irq/cleanups] gpu: ipu-v3: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     76f5c9a3fac46eadd93c012a4cdeb3b620cc9604
Gitweb:        https://git.kernel.org/tip/76f5c9a3fac46eadd93c012a4cdeb3b620cc9604
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:37 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 15:39:41 +02:00

gpu: ipu-v3: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 drivers/gpu/ipu-v3/ipu-common.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
drivers/gpu/ipu-v3/ipu-common.c +2 -2
index 223e6d5..333f36e 100644
@@ -1008,7 +1008,7 @@ int ipu_map_irq(struct ipu_soc *ipu, int irq)
 {
 	int virq;
 
-	virq = irq_linear_revmap(ipu->domain, irq);
+	virq = irq_find_mapping(ipu->domain, irq);
 	if (!virq)
 		virq = irq_create_mapping(ipu->domain, irq);
 
@@ -1219,7 +1219,7 @@ static void ipu_irq_exit(struct ipu_soc *ipu)
 	/* TODO: remove irq_domain_generic_chips */
 
 	for (i = 0; i < IPU_NUM_IRQS; i++) {
-		irq = irq_linear_revmap(ipu->domain, i);
+		irq = irq_find_mapping(ipu->domain, i);
 		if (irq)
 			irq_dispose_mapping(irq);
 	}
#201 lore raw

[tip: irq/cleanups] gpu: ipu-v3: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     e68664c08e3980f394d0bf22c64ce3cd2a3929e2
Gitweb:        https://git.kernel.org/tip/e68664c08e3980f394d0bf22c64ce3cd2a3929e2
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:37 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Fri, 16 May 2025 21:06:12 +02:00

gpu: ipu-v3: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 drivers/gpu/ipu-v3/ipu-common.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
drivers/gpu/ipu-v3/ipu-common.c +2 -2
index 223e6d5..333f36e 100644
@@ -1008,7 +1008,7 @@ int ipu_map_irq(struct ipu_soc *ipu, int irq)
 {
 	int virq;
 
-	virq = irq_linear_revmap(ipu->domain, irq);
+	virq = irq_find_mapping(ipu->domain, irq);
 	if (!virq)
 		virq = irq_create_mapping(ipu->domain, irq);
 
@@ -1219,7 +1219,7 @@ static void ipu_irq_exit(struct ipu_soc *ipu)
 	/* TODO: remove irq_domain_generic_chips */
 
 	for (i = 0; i < IPU_NUM_IRQS; i++) {
-		irq = irq_linear_revmap(ipu->domain, i);
+		irq = irq_find_mapping(ipu->domain, i);
 		if (irq)
 			irq_dispose_mapping(irq);
 	}
#202 lore raw

PATCH v2 45/57 irqdomain: i2c: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

---
 drivers/i2c/muxes/i2c-mux-pca954x.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/i2c/muxes/i2c-mux-pca954x.c +1 -1
index f6430db6c115..5bb26af0f532 100644
@@ -414,7 +414,7 @@ static irqreturn_t pca954x_irq_handler(int irq, void *dev_id)
 
 	pending = (ret >> PCA954X_IRQ_OFFSET) & (BIT(data->chip->nchans) - 1);
 	for_each_set_bit(i, &pending, data->chip->nchans)
-		handle_nested_irq(irq_linear_revmap(data->irq, i));
+		handle_nested_irq(irq_find_mapping(data->irq, i));
 
 	return IRQ_RETVAL(pending);
 }
Signature · 1 line
2.49.0
author
#204 lore raw

Re: [PATCH v2 45/57] irqdomain: i2c: Switch to irq_find_mapping()

Quoted 10 lines · Wolfram Sang
Quoted 6 lines · Jiri Slaby (SUSE)

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

I can apply this independently of the other I2C change which needs a v3, right?

Right.

thanks,

Signature · 2 lines
js
suse labs
#206 lore raw

PATCH v2 46/57 irqdomain: irqchip: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

Cc Andrew Lunn <[email protected]>
Cc Gregory Clement <[email protected]>
Cc Sebastian Hesselbarth <[email protected]>
Cc Thomas Gleixner <[email protected]>
---
 drivers/irqchip/irq-armada-370-xp.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
drivers/irqchip/irq-armada-370-xp.c +2 -2
index e51612992735..67b672a78862 100644
@@ -546,7 +546,7 @@ static void mpic_reenable_percpu(struct mpic *mpic)
 {
 	/* Re-enable per-CPU interrupts that were enabled before suspend */
 	for (irq_hw_number_t i = 0; i < MPIC_PER_CPU_IRQS_NR; i++) {
-		unsigned int virq = irq_linear_revmap(mpic->domain, i);
+		unsigned int virq = irq_find_mapping(mpic->domain, i);
 		struct irq_data *d;
 
 		if (!virq || !irq_percpu_is_enabled(virq))
@@ -740,7 +740,7 @@ static void mpic_resume(void)
 
 	/* Re-enable interrupts */
 	for (irq_hw_number_t i = 0; i < mpic->domain->hwirq_max; i++) {
-		unsigned int virq = irq_linear_revmap(mpic->domain, i);
+		unsigned int virq = irq_find_mapping(mpic->domain, i);
 		struct irq_data *d;
 
 		if (!virq)
Signature · 1 line
2.49.0
#207 lore raw

[tip: irq/cleanups] irqchip/armada-370-xp: Switch to irq_find_mapping()

The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     cfe07876012ce9c50d646286a60698f4bc210f2d
Gitweb:        https://git.kernel.org/tip/cfe07876012ce9c50d646286a60698f4bc210f2d
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:39 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Tue, 06 May 2025 14:59:08 +02:00

irqchip/armada-370-xp: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 drivers/irqchip/irq-armada-370-xp.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
drivers/irqchip/irq-armada-370-xp.c +2 -2
index e516129..67b672a 100644
@@ -546,7 +546,7 @@ static void mpic_reenable_percpu(struct mpic *mpic)
 {
 	/* Re-enable per-CPU interrupts that were enabled before suspend */
 	for (irq_hw_number_t i = 0; i < MPIC_PER_CPU_IRQS_NR; i++) {
-		unsigned int virq = irq_linear_revmap(mpic->domain, i);
+		unsigned int virq = irq_find_mapping(mpic->domain, i);
 		struct irq_data *d;
 
 		if (!virq || !irq_percpu_is_enabled(virq))
@@ -740,7 +740,7 @@ static void mpic_resume(void)
 
 	/* Re-enable interrupts */
 	for (irq_hw_number_t i = 0; i < mpic->domain->hwirq_max; i++) {
-		unsigned int virq = irq_linear_revmap(mpic->domain, i);
+		unsigned int virq = irq_find_mapping(mpic->domain, i);
 		struct irq_data *d;
 
 		if (!virq)
#208 lore raw

[tip: irq/cleanups] irqchip/armada-370-xp: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     e5b0222f7e5d30ba52f4f3b6a85893d9d7d7af92
Gitweb:        https://git.kernel.org/tip/e5b0222f7e5d30ba52f4f3b6a85893d9d7d7af92
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:39 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 09:53:24 +02:00

irqchip/armada-370-xp: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 drivers/irqchip/irq-armada-370-xp.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
drivers/irqchip/irq-armada-370-xp.c +2 -2
index e516129..67b672a 100644
@@ -546,7 +546,7 @@ static void mpic_reenable_percpu(struct mpic *mpic)
 {
 	/* Re-enable per-CPU interrupts that were enabled before suspend */
 	for (irq_hw_number_t i = 0; i < MPIC_PER_CPU_IRQS_NR; i++) {
-		unsigned int virq = irq_linear_revmap(mpic->domain, i);
+		unsigned int virq = irq_find_mapping(mpic->domain, i);
 		struct irq_data *d;
 
 		if (!virq || !irq_percpu_is_enabled(virq))
@@ -740,7 +740,7 @@ static void mpic_resume(void)
 
 	/* Re-enable interrupts */
 	for (irq_hw_number_t i = 0; i < mpic->domain->hwirq_max; i++) {
-		unsigned int virq = irq_linear_revmap(mpic->domain, i);
+		unsigned int virq = irq_find_mapping(mpic->domain, i);
 		struct irq_data *d;
 
 		if (!virq)
#209 lore raw

[tip: irq/cleanups] irqchip/armada-370-xp: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     3a6a7c4537e61e0e4b922f2a5b4f6bcd820c87c1
Gitweb:        https://git.kernel.org/tip/3a6a7c4537e61e0e4b922f2a5b4f6bcd820c87c1
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:39 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 15:39:41 +02:00

irqchip/armada-370-xp: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 drivers/irqchip/irq-armada-370-xp.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
drivers/irqchip/irq-armada-370-xp.c +2 -2
index e516129..67b672a 100644
@@ -546,7 +546,7 @@ static void mpic_reenable_percpu(struct mpic *mpic)
 {
 	/* Re-enable per-CPU interrupts that were enabled before suspend */
 	for (irq_hw_number_t i = 0; i < MPIC_PER_CPU_IRQS_NR; i++) {
-		unsigned int virq = irq_linear_revmap(mpic->domain, i);
+		unsigned int virq = irq_find_mapping(mpic->domain, i);
 		struct irq_data *d;
 
 		if (!virq || !irq_percpu_is_enabled(virq))
@@ -740,7 +740,7 @@ static void mpic_resume(void)
 
 	/* Re-enable interrupts */
 	for (irq_hw_number_t i = 0; i < mpic->domain->hwirq_max; i++) {
-		unsigned int virq = irq_linear_revmap(mpic->domain, i);
+		unsigned int virq = irq_find_mapping(mpic->domain, i);
 		struct irq_data *d;
 
 		if (!virq)
#210 lore raw

[tip: irq/cleanups] irqchip/armada-370-xp: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     31b3ad400245b5ddf8081394330ba460f8b431e7
Gitweb:        https://git.kernel.org/tip/31b3ad400245b5ddf8081394330ba460f8b431e7
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:39 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Fri, 16 May 2025 21:06:12 +02:00

irqchip/armada-370-xp: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 drivers/irqchip/irq-armada-370-xp.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
drivers/irqchip/irq-armada-370-xp.c +2 -2
index e516129..67b672a 100644
@@ -546,7 +546,7 @@ static void mpic_reenable_percpu(struct mpic *mpic)
 {
 	/* Re-enable per-CPU interrupts that were enabled before suspend */
 	for (irq_hw_number_t i = 0; i < MPIC_PER_CPU_IRQS_NR; i++) {
-		unsigned int virq = irq_linear_revmap(mpic->domain, i);
+		unsigned int virq = irq_find_mapping(mpic->domain, i);
 		struct irq_data *d;
 
 		if (!virq || !irq_percpu_is_enabled(virq))
@@ -740,7 +740,7 @@ static void mpic_resume(void)
 
 	/* Re-enable interrupts */
 	for (irq_hw_number_t i = 0; i < mpic->domain->hwirq_max; i++) {
-		unsigned int virq = irq_linear_revmap(mpic->domain, i);
+		unsigned int virq = irq_find_mapping(mpic->domain, i);
 		struct irq_data *d;
 
 		if (!virq)
#211 lore raw

PATCH v2 47/57 irqdomain: pinctrl: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

---
 drivers/pinctrl/pinctrl-keembay.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/pinctrl/pinctrl-keembay.c +1 -1
index b693f4787044..0d7cc8280ea2 100644
@@ -1268,7 +1268,7 @@ static void keembay_gpio_irq_handler(struct irq_desc *desc)
 	for_each_set_clump8(bit, clump, &reg, BITS_PER_TYPE(typeof(reg))) {
 		pin = clump & ~KEEMBAY_GPIO_IRQ_ENABLE;
 		val = keembay_read_pin(kpc->base0 + KEEMBAY_GPIO_DATA_IN, pin);
-		kmb_irq = irq_linear_revmap(gc->irq.domain, pin);
+		kmb_irq = irq_find_mapping(gc->irq.domain, pin);
 
 		/* Checks if the interrupt is enabled */
 		if (val && (clump & KEEMBAY_GPIO_IRQ_ENABLE))
Signature · 1 line
2.49.0
#213 lore raw

[tip: irq/cleanups] pinctrl: keembay: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     159111fb9adbc45515bde074969ef651f531c5cf
Gitweb:        https://git.kernel.org/tip/159111fb9adbc45515bde074969ef651f531c5cf
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:40 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Tue, 06 May 2025 14:59:08 +02:00

pinctrl: keembay: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 drivers/pinctrl/pinctrl-keembay.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/pinctrl/pinctrl-keembay.c +1 -1
index b693f47..0d7cc82 100644
@@ -1268,7 +1268,7 @@ static void keembay_gpio_irq_handler(struct irq_desc *desc)
 	for_each_set_clump8(bit, clump, &reg, BITS_PER_TYPE(typeof(reg))) {
 		pin = clump & ~KEEMBAY_GPIO_IRQ_ENABLE;
 		val = keembay_read_pin(kpc->base0 + KEEMBAY_GPIO_DATA_IN, pin);
-		kmb_irq = irq_linear_revmap(gc->irq.domain, pin);
+		kmb_irq = irq_find_mapping(gc->irq.domain, pin);
 
 		/* Checks if the interrupt is enabled */
 		if (val && (clump & KEEMBAY_GPIO_IRQ_ENABLE))
#214 lore raw

[tip: irq/cleanups] pinctrl: keembay: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     219e99b99b848f20eca692cf663c25178c15dd3b
Gitweb:        https://git.kernel.org/tip/219e99b99b848f20eca692cf663c25178c15dd3b
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:40 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 09:53:24 +02:00

pinctrl: keembay: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 drivers/pinctrl/pinctrl-keembay.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/pinctrl/pinctrl-keembay.c +1 -1
index b693f47..0d7cc82 100644
@@ -1268,7 +1268,7 @@ static void keembay_gpio_irq_handler(struct irq_desc *desc)
 	for_each_set_clump8(bit, clump, &reg, BITS_PER_TYPE(typeof(reg))) {
 		pin = clump & ~KEEMBAY_GPIO_IRQ_ENABLE;
 		val = keembay_read_pin(kpc->base0 + KEEMBAY_GPIO_DATA_IN, pin);
-		kmb_irq = irq_linear_revmap(gc->irq.domain, pin);
+		kmb_irq = irq_find_mapping(gc->irq.domain, pin);
 
 		/* Checks if the interrupt is enabled */
 		if (val && (clump & KEEMBAY_GPIO_IRQ_ENABLE))
#215 lore raw

[tip: irq/cleanups] pinctrl: keembay: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     377c6a8184bd97b6ea7c6a15ea6561008d710b15
Gitweb:        https://git.kernel.org/tip/377c6a8184bd97b6ea7c6a15ea6561008d710b15
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:40 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 15:39:42 +02:00

pinctrl: keembay: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 drivers/pinctrl/pinctrl-keembay.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/pinctrl/pinctrl-keembay.c +1 -1
index b693f47..0d7cc82 100644
@@ -1268,7 +1268,7 @@ static void keembay_gpio_irq_handler(struct irq_desc *desc)
 	for_each_set_clump8(bit, clump, &reg, BITS_PER_TYPE(typeof(reg))) {
 		pin = clump & ~KEEMBAY_GPIO_IRQ_ENABLE;
 		val = keembay_read_pin(kpc->base0 + KEEMBAY_GPIO_DATA_IN, pin);
-		kmb_irq = irq_linear_revmap(gc->irq.domain, pin);
+		kmb_irq = irq_find_mapping(gc->irq.domain, pin);
 
 		/* Checks if the interrupt is enabled */
 		if (val && (clump & KEEMBAY_GPIO_IRQ_ENABLE))
#216 lore raw

[tip: irq/cleanups] pinctrl: keembay: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     609f900ad6093af6f97a313c4bacf4ca3757db4a
Gitweb:        https://git.kernel.org/tip/609f900ad6093af6f97a313c4bacf4ca3757db4a
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:40 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Fri, 16 May 2025 21:06:12 +02:00

pinctrl: keembay: Switch to irq_find_mapping()

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

[ tglx: Fix up subject prefix ]

---
 drivers/pinctrl/pinctrl-keembay.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/pinctrl/pinctrl-keembay.c +1 -1
index b693f47..0d7cc82 100644
@@ -1268,7 +1268,7 @@ static void keembay_gpio_irq_handler(struct irq_desc *desc)
 	for_each_set_clump8(bit, clump, &reg, BITS_PER_TYPE(typeof(reg))) {
 		pin = clump & ~KEEMBAY_GPIO_IRQ_ENABLE;
 		val = keembay_read_pin(kpc->base0 + KEEMBAY_GPIO_DATA_IN, pin);
-		kmb_irq = irq_linear_revmap(gc->irq.domain, pin);
+		kmb_irq = irq_find_mapping(gc->irq.domain, pin);
 
 		/* Checks if the interrupt is enabled */
 		if (val && (clump & KEEMBAY_GPIO_IRQ_ENABLE))
#217 lore raw

PATCH v2 48/57 irqdomain: soc: Switch to irq_find_mapping()

In reply to Jiri Slaby (SUSE)

irq_linear_revmap() is deprecated, so remove all its uses and supersede them by an identical call to irq_find_mapping().

---
 drivers/soc/fsl/qe/qe_ic.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
drivers/soc/fsl/qe/qe_ic.c +2 -2
index e5831c298ad6..e4b6ff2cc76b 100644
@@ -344,7 +344,7 @@ static unsigned int qe_ic_get_low_irq(struct qe_ic *qe_ic)
 	if (irq == 0)
 		return 0;
 
-	return irq_linear_revmap(qe_ic->irqhost, irq);
+	return irq_find_mapping(qe_ic->irqhost, irq);
 }
 
 /* Return an interrupt vector or 0 if no interrupt is pending. */
@@ -360,7 +360,7 @@ static unsigned int qe_ic_get_high_irq(struct qe_ic *qe_ic)
 	if (irq == 0)
 		return 0;
 
-	return irq_linear_revmap(qe_ic->irqhost, irq);
+	return irq_find_mapping(qe_ic->irqhost, irq);
 }
 
 static void qe_ic_cascade_low(struct irq_desc *desc)
Signature · 1 line
2.49.0
#218 lore raw

PATCH v2 49/57 irqdomain: Drop irq_linear_revmap()

In reply to Jiri Slaby (SUSE)

irq_linear_revmap() is deprecated and unused now. So remove it.

Cc Alex Shi <[email protected]>
Cc Yanteng Si <[email protected]>
Cc Dongliang Mu <[email protected]>
Cc Jonathan Corbet <[email protected]>
---
 Documentation/core-api/irq/irq-domain.rst                   | 2 --
 .../translations/zh_CN/core-api/irq/irq-domain.rst          | 2 --
 include/linux/irqdomain.h                                   | 6 ------
 3 files changed, 10 deletions(-)
Documentation/core-api/irq/irq-domain.rst +0 -2
index e26ed303819d..775dd43b3340 100644
@@ -63,8 +63,6 @@ variety of methods:
   mapping.
 - irq_find_mapping() returns a Linux IRQ number for a given domain and
   hwirq number, and 0 if there was no mapping
-- irq_linear_revmap() is now identical to irq_find_mapping(), and is
-  deprecated
 - generic_handle_domain_irq() handles an interrupt described by a
   domain and a hwirq number
 
Documentation/translations/zh_CN/core-api/irq/irq-domain.rst +0 -2
index 913c3eda3f74..4a2d3b27aa4d 100644
@@ -60,8 +60,6 @@ irq_domain和一个hwirq号作为参数。 如果hwirq的映射还不存在,
 
 - irq_find_mapping()返回给定域和hwirq的Linux IRQ号,如果没有映射则返回0。
 
-- irq_linear_revmap()现与irq_find_mapping()相同,已被废弃。
-
 - generic_handle_domain_irq()处理一个由域和hwirq号描述的中断。
 
 请注意,irq域的查找必须发生在与RCU读临界区兼容的上下文中。
include/linux/irqdomain.h +0 -6
index bd02550df6e6..d5c9e32ff0a2 100644
@@ -492,12 +492,6 @@ static inline unsigned int irq_find_mapping(struct irq_domain *domain,
 	return 0;
 }
 
-static inline unsigned int irq_linear_revmap(struct irq_domain *domain,
-					     irq_hw_number_t hwirq)
-{
-	return irq_find_mapping(domain, hwirq);
-}
-
 extern const struct irq_domain_ops irq_domain_simple_ops;
 
 /* stock xlate functions */
Signature · 1 line
2.49.0
#219 lore raw

[tip: irq/cleanups] irqdomain: Drop irq_linear_revmap()

The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     8db535d609d73bb3811a81be0027bd7c2c89b4b7
Gitweb:        https://git.kernel.org/tip/8db535d609d73bb3811a81be0027bd7c2c89b4b7
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:42 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Tue, 06 May 2025 14:59:08 +02:00

irqdomain: Drop irq_linear_revmap()

irq_linear_revmap() is deprecated and unused now. So remove it.

---
 Documentation/core-api/irq/irq-domain.rst                    | 2 --
 Documentation/translations/zh_CN/core-api/irq/irq-domain.rst | 2 --
 include/linux/irqdomain.h                                    | 6 ------
 3 files changed, 10 deletions(-)
Documentation/core-api/irq/irq-domain.rst +0 -2
index 7624607..c365c3e 100644
@@ -62,8 +62,6 @@ variety of methods:
   mapping.
 - irq_find_mapping() returns a Linux IRQ number for a given domain and
   hwirq number, and 0 if there was no mapping
-- irq_linear_revmap() is now identical to irq_find_mapping(), and is
-  deprecated
 - generic_handle_domain_irq() handles an interrupt described by a
   domain and a hwirq number
 
Documentation/translations/zh_CN/core-api/irq/irq-domain.rst +0 -2
index 913c3ed..4a2d3b2 100644
@@ -60,8 +60,6 @@ irq_domain和一个hwirq号作为参数。 如果hwirq的映射还不存在,�
 
 - irq_find_mapping()返回给定域和hwirq的Linux IRQ号,如果没有映射则返回0。
 
-- irq_linear_revmap()现与irq_find_mapping()相同,已被废弃。
-
 - generic_handle_domain_irq()处理一个由域和hwirq号描述的中断。
 
 请注意,irq域的查找必须发生在与RCU读临界区兼容的上下文中。
include/linux/irqdomain.h +0 -6
index 712c662..c8e55cd 100644
@@ -492,12 +492,6 @@ static inline unsigned int irq_find_mapping(struct irq_domain *domain,
 	return 0;
 }
 
-static inline unsigned int irq_linear_revmap(struct irq_domain *domain,
-					     irq_hw_number_t hwirq)
-{
-	return irq_find_mapping(domain, hwirq);
-}
-
 extern const struct irq_domain_ops irq_domain_simple_ops;
 
 /* stock xlate functions */
#220 lore raw

[tip: irq/cleanups] irqdomain: Drop irq_linear_revmap()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     506cc474ce456fa992bde54ad8cc682c2587a820
Gitweb:        https://git.kernel.org/tip/506cc474ce456fa992bde54ad8cc682c2587a820
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:42 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 09:53:24 +02:00

irqdomain: Drop irq_linear_revmap()

irq_linear_revmap() is deprecated and unused now. So remove it.

---
 Documentation/core-api/irq/irq-domain.rst                    | 2 --
 Documentation/translations/zh_CN/core-api/irq/irq-domain.rst | 2 --
 include/linux/irqdomain.h                                    | 6 ------
 3 files changed, 10 deletions(-)
Documentation/core-api/irq/irq-domain.rst +0 -2
index 7624607..c365c3e 100644
@@ -62,8 +62,6 @@ variety of methods:
   mapping.
 - irq_find_mapping() returns a Linux IRQ number for a given domain and
   hwirq number, and 0 if there was no mapping
-- irq_linear_revmap() is now identical to irq_find_mapping(), and is
-  deprecated
 - generic_handle_domain_irq() handles an interrupt described by a
   domain and a hwirq number
 
Documentation/translations/zh_CN/core-api/irq/irq-domain.rst +0 -2
index 913c3ed..4a2d3b2 100644
@@ -60,8 +60,6 @@ irq_domain和一个hwirq号作为参数。 如果hwirq的映射还不存在,�
 
 - irq_find_mapping()返回给定域和hwirq的Linux IRQ号,如果没有映射则返回0。
 
-- irq_linear_revmap()现与irq_find_mapping()相同,已被废弃。
-
 - generic_handle_domain_irq()处理一个由域和hwirq号描述的中断。
 
 请注意,irq域的查找必须发生在与RCU读临界区兼容的上下文中。
include/linux/irqdomain.h +0 -6
index 712c662..c8e55cd 100644
@@ -492,12 +492,6 @@ static inline unsigned int irq_find_mapping(struct irq_domain *domain,
 	return 0;
 }
 
-static inline unsigned int irq_linear_revmap(struct irq_domain *domain,
-					     irq_hw_number_t hwirq)
-{
-	return irq_find_mapping(domain, hwirq);
-}
-
 extern const struct irq_domain_ops irq_domain_simple_ops;
 
 /* stock xlate functions */
#221 lore raw

[tip: irq/cleanups] irqdomain: Drop irq_linear_revmap()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     4d90cc80aa1f48a01ef31a936e68dcca22430de0
Gitweb:        https://git.kernel.org/tip/4d90cc80aa1f48a01ef31a936e68dcca22430de0
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:42 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 15:39:42 +02:00

irqdomain: Drop irq_linear_revmap()

irq_linear_revmap() is deprecated and unused now. So remove it.

---
 Documentation/core-api/irq/irq-domain.rst                    | 2 --
 Documentation/translations/zh_CN/core-api/irq/irq-domain.rst | 2 --
 include/linux/irqdomain.h                                    | 6 ------
 3 files changed, 10 deletions(-)
Documentation/core-api/irq/irq-domain.rst +0 -2
index 7624607..c365c3e 100644
@@ -62,8 +62,6 @@ variety of methods:
   mapping.
 - irq_find_mapping() returns a Linux IRQ number for a given domain and
   hwirq number, and 0 if there was no mapping
-- irq_linear_revmap() is now identical to irq_find_mapping(), and is
-  deprecated
 - generic_handle_domain_irq() handles an interrupt described by a
   domain and a hwirq number
 
Documentation/translations/zh_CN/core-api/irq/irq-domain.rst +0 -2
index 913c3ed..4a2d3b2 100644
@@ -60,8 +60,6 @@ irq_domain和一个hwirq号作为参数。 如果hwirq的映射还不存在,�
 
 - irq_find_mapping()返回给定域和hwirq的Linux IRQ号,如果没有映射则返回0。
 
-- irq_linear_revmap()现与irq_find_mapping()相同,已被废弃。
-
 - generic_handle_domain_irq()处理一个由域和hwirq号描述的中断。
 
 请注意,irq域的查找必须发生在与RCU读临界区兼容的上下文中。
include/linux/irqdomain.h +0 -6
index 712c662..c8e55cd 100644
@@ -492,12 +492,6 @@ static inline unsigned int irq_find_mapping(struct irq_domain *domain,
 	return 0;
 }
 
-static inline unsigned int irq_linear_revmap(struct irq_domain *domain,
-					     irq_hw_number_t hwirq)
-{
-	return irq_find_mapping(domain, hwirq);
-}
-
 extern const struct irq_domain_ops irq_domain_simple_ops;
 
 /* stock xlate functions */
#222 lore raw

[tip: irq/cleanups] irqdomain: Drop irq_linear_revmap()

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     14ebb11ba895c9223d9a453a17df2fd81410c96c
Gitweb:        https://git.kernel.org/tip/14ebb11ba895c9223d9a453a17df2fd81410c96c
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:42 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Fri, 16 May 2025 21:06:12 +02:00

irqdomain: Drop irq_linear_revmap()

irq_linear_revmap() is deprecated and unused now. So remove it.

---
 Documentation/core-api/irq/irq-domain.rst                    | 2 --
 Documentation/translations/zh_CN/core-api/irq/irq-domain.rst | 2 --
 include/linux/irqdomain.h                                    | 6 ------
 3 files changed, 10 deletions(-)
Documentation/core-api/irq/irq-domain.rst +0 -2
index 7624607..c365c3e 100644
@@ -62,8 +62,6 @@ variety of methods:
   mapping.
 - irq_find_mapping() returns a Linux IRQ number for a given domain and
   hwirq number, and 0 if there was no mapping
-- irq_linear_revmap() is now identical to irq_find_mapping(), and is
-  deprecated
 - generic_handle_domain_irq() handles an interrupt described by a
   domain and a hwirq number
 
Documentation/translations/zh_CN/core-api/irq/irq-domain.rst +0 -2
index 913c3ed..4a2d3b2 100644
@@ -60,8 +60,6 @@ irq_domain和一个hwirq号作为参数。 如果hwirq的映射还不存在,�
 
 - irq_find_mapping()返回给定域和hwirq的Linux IRQ号,如果没有映射则返回0。
 
-- irq_linear_revmap()现与irq_find_mapping()相同,已被废弃。
-
 - generic_handle_domain_irq()处理一个由域和hwirq号描述的中断。
 
 请注意,irq域的查找必须发生在与RCU读临界区兼容的上下文中。
include/linux/irqdomain.h +0 -6
index 712c662..c8e55cd 100644
@@ -492,12 +492,6 @@ static inline unsigned int irq_find_mapping(struct irq_domain *domain,
 	return 0;
 }
 
-static inline unsigned int irq_linear_revmap(struct irq_domain *domain,
-					     irq_hw_number_t hwirq)
-{
-	return irq_find_mapping(domain, hwirq);
-}
-
 extern const struct irq_domain_ops irq_domain_simple_ops;
 
 /* stock xlate functions */
#223 lore raw

PATCH v2 50/57 irqdomain: Use irq_domain_instantiate() retvals as initializers

In reply to Jiri Slaby (SUSE)

I was thinking whether add a \n before the 'return' or this. And this looks both more compact and more readable.

Note irq_domain_create_hierarchy()'s handling of size is now part of info's initializer (using the ternary operator). That makes more sense while reading it.

---
 include/linux/irqdomain.h | 17 +++++------------
 1 file changed, 5 insertions(+), 12 deletions(-)
include/linux/irqdomain.h +5 -12
index d5c9e32ff0a2..bf52a08f3255 100644
@@ -403,9 +403,8 @@ static inline struct irq_domain *irq_domain_create_nomap(struct fwnode_handle *f
 		.ops		= ops,
 		.host_data	= host_data,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
@@ -424,9 +423,8 @@ static inline struct irq_domain *irq_domain_create_linear(struct fwnode_handle *
 		.ops		= ops,
 		.host_data	= host_data,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
@@ -440,9 +438,8 @@ static inline struct irq_domain *irq_domain_create_tree(struct fwnode_handle *fw
 		.ops		= ops,
 		.host_data	= host_data,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
@@ -554,18 +551,14 @@ static inline struct irq_domain *irq_domain_create_hierarchy(struct irq_domain *
 	struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.size		= size,
-		.hwirq_max	= size,
+		.hwirq_max	= size ? : ~0U,
 		.ops		= ops,
 		.host_data	= host_data,
 		.domain_flags	= flags,
 		.parent		= parent,
 	};
-	struct irq_domain *d;
-
-	if (!info.size)
-		info.hwirq_max = ~0U;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
Signature · 1 line
2.49.0
#224 lore raw

[tip: irq/cleanups] irqdomain: Use irq_domain_instantiate()'s return value as initializers

The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     62ba4b718c7f032fdf418964916bb9cae291c5be
Gitweb:        https://git.kernel.org/tip/62ba4b718c7f032fdf418964916bb9cae291c5be
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:43 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Tue, 06 May 2025 14:59:08 +02:00

irqdomain: Use irq_domain_instantiate()'s return value as initializers

This makes the code more compact.

Note that irq_domain_create_hierarchy()'s handling of size is now part of info's initializer (using the ternary operator). That makes more sense while reading it.

---
 include/linux/irqdomain.h | 17 +++++------------
 1 file changed, 5 insertions(+), 12 deletions(-)
include/linux/irqdomain.h +5 -12
index c8e55cd..1e38584 100644
@@ -403,9 +403,8 @@ static inline struct irq_domain *irq_domain_create_nomap(struct fwnode_handle *f
 		.ops		= ops,
 		.host_data	= host_data,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
@@ -424,9 +423,8 @@ static inline struct irq_domain *irq_domain_create_linear(struct fwnode_handle *
 		.ops		= ops,
 		.host_data	= host_data,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
@@ -440,9 +438,8 @@ static inline struct irq_domain *irq_domain_create_tree(struct fwnode_handle *fw
 		.ops		= ops,
 		.host_data	= host_data,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
@@ -554,18 +551,14 @@ static inline struct irq_domain *irq_domain_create_hierarchy(struct irq_domain *
 	struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.size		= size,
-		.hwirq_max	= size,
+		.hwirq_max	= size ? : ~0U,
 		.ops		= ops,
 		.host_data	= host_data,
 		.domain_flags	= flags,
 		.parent		= parent,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	if (!info.size)
-		info.hwirq_max = ~0U;
-
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
#225 lore raw

[tip: irq/cleanups] irqdomain: Use irq_domain_instantiate()'s return value as initializers

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     087a483741e262967b2ab71a8d2d314512d3f178
Gitweb:        https://git.kernel.org/tip/087a483741e262967b2ab71a8d2d314512d3f178
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:43 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 09:53:25 +02:00

irqdomain: Use irq_domain_instantiate()'s return value as initializers

This makes the code more compact.

Note that irq_domain_create_hierarchy()'s handling of size is now part of info's initializer (using the ternary operator). That makes more sense while reading it.

---
 include/linux/irqdomain.h | 17 +++++------------
 1 file changed, 5 insertions(+), 12 deletions(-)
include/linux/irqdomain.h +5 -12
index c8e55cd..1e38584 100644
@@ -403,9 +403,8 @@ static inline struct irq_domain *irq_domain_create_nomap(struct fwnode_handle *f
 		.ops		= ops,
 		.host_data	= host_data,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
@@ -424,9 +423,8 @@ static inline struct irq_domain *irq_domain_create_linear(struct fwnode_handle *
 		.ops		= ops,
 		.host_data	= host_data,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
@@ -440,9 +438,8 @@ static inline struct irq_domain *irq_domain_create_tree(struct fwnode_handle *fw
 		.ops		= ops,
 		.host_data	= host_data,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
@@ -554,18 +551,14 @@ static inline struct irq_domain *irq_domain_create_hierarchy(struct irq_domain *
 	struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.size		= size,
-		.hwirq_max	= size,
+		.hwirq_max	= size ? : ~0U,
 		.ops		= ops,
 		.host_data	= host_data,
 		.domain_flags	= flags,
 		.parent		= parent,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	if (!info.size)
-		info.hwirq_max = ~0U;
-
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
#226 lore raw

[tip: irq/cleanups] irqdomain: Use irq_domain_instantiate()'s return value as initializers

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     d42b432f05c255ddead54dd44adaaf8886c2eed3
Gitweb:        https://git.kernel.org/tip/d42b432f05c255ddead54dd44adaaf8886c2eed3
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:43 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 15:39:42 +02:00

irqdomain: Use irq_domain_instantiate()'s return value as initializers

This makes the code more compact.

Note that irq_domain_create_hierarchy()'s handling of size is now part of info's initializer (using the ternary operator). That makes more sense while reading it.

---
 include/linux/irqdomain.h | 17 +++++------------
 1 file changed, 5 insertions(+), 12 deletions(-)
include/linux/irqdomain.h +5 -12
index c8e55cd..1e38584 100644
@@ -403,9 +403,8 @@ static inline struct irq_domain *irq_domain_create_nomap(struct fwnode_handle *f
 		.ops		= ops,
 		.host_data	= host_data,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
@@ -424,9 +423,8 @@ static inline struct irq_domain *irq_domain_create_linear(struct fwnode_handle *
 		.ops		= ops,
 		.host_data	= host_data,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
@@ -440,9 +438,8 @@ static inline struct irq_domain *irq_domain_create_tree(struct fwnode_handle *fw
 		.ops		= ops,
 		.host_data	= host_data,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
@@ -554,18 +551,14 @@ static inline struct irq_domain *irq_domain_create_hierarchy(struct irq_domain *
 	struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.size		= size,
-		.hwirq_max	= size,
+		.hwirq_max	= size ? : ~0U,
 		.ops		= ops,
 		.host_data	= host_data,
 		.domain_flags	= flags,
 		.parent		= parent,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	if (!info.size)
-		info.hwirq_max = ~0U;
-
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
#227 lore raw

[tip: irq/cleanups] irqdomain: Use irq_domain_instantiate()'s return value as initializers

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     18e743e911020eb74cc4eaf549c18ed12a5acb9a
Gitweb:        https://git.kernel.org/tip/18e743e911020eb74cc4eaf549c18ed12a5acb9a
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:43 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Fri, 16 May 2025 21:06:12 +02:00

irqdomain: Use irq_domain_instantiate()'s return value as initializers

This makes the code more compact.

Note that irq_domain_create_hierarchy()'s handling of size is now part of info's initializer (using the ternary operator). That makes more sense while reading it.

---
 include/linux/irqdomain.h | 17 +++++------------
 1 file changed, 5 insertions(+), 12 deletions(-)
include/linux/irqdomain.h +5 -12
index c8e55cd..1e38584 100644
@@ -403,9 +403,8 @@ static inline struct irq_domain *irq_domain_create_nomap(struct fwnode_handle *f
 		.ops		= ops,
 		.host_data	= host_data,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
@@ -424,9 +423,8 @@ static inline struct irq_domain *irq_domain_create_linear(struct fwnode_handle *
 		.ops		= ops,
 		.host_data	= host_data,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
@@ -440,9 +438,8 @@ static inline struct irq_domain *irq_domain_create_tree(struct fwnode_handle *fw
 		.ops		= ops,
 		.host_data	= host_data,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
@@ -554,18 +551,14 @@ static inline struct irq_domain *irq_domain_create_hierarchy(struct irq_domain *
 	struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.size		= size,
-		.hwirq_max	= size,
+		.hwirq_max	= size ? : ~0U,
 		.ops		= ops,
 		.host_data	= host_data,
 		.domain_flags	= flags,
 		.parent		= parent,
 	};
-	struct irq_domain *d;
+	struct irq_domain *d = irq_domain_instantiate(&info);
 
-	if (!info.size)
-		info.hwirq_max = ~0U;
-
-	d = irq_domain_instantiate(&info);
 	return IS_ERR(d) ? NULL : d;
 }
 
#228 lore raw

PATCH v2 51/57 irqdomain: Make struct irq_domain_info variables const

In reply to Jiri Slaby (SUSE)

This is just expressing it explicitly as irq_domain_instantiate() takes const already. No functional change.

---
 include/linux/irqdomain.h | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
include/linux/irqdomain.h +4 -4
index bf52a08f3255..472f6bb91e9a 100644
@@ -396,7 +396,7 @@ static inline struct irq_domain *irq_domain_create_nomap(struct fwnode_handle *f
 					 const struct irq_domain_ops *ops,
 					 void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.hwirq_max	= max_irq,
 		.direct_max	= max_irq,
@@ -416,7 +416,7 @@ static inline struct irq_domain *irq_domain_create_linear(struct fwnode_handle *
 					 const struct irq_domain_ops *ops,
 					 void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.size		= size,
 		.hwirq_max	= size,
@@ -432,7 +432,7 @@ static inline struct irq_domain *irq_domain_create_tree(struct fwnode_handle *fw
 					 const struct irq_domain_ops *ops,
 					 void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.hwirq_max	= ~0,
 		.ops		= ops,
@@ -548,7 +548,7 @@ static inline struct irq_domain *irq_domain_create_hierarchy(struct irq_domain *
 					    const struct irq_domain_ops *ops,
 					    void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.size		= size,
 		.hwirq_max	= size ? : ~0U,
Signature · 1 line
2.49.0
#229 lore raw

[tip: irq/cleanups] irqdomain: Make struct irq_domain_info variables const

The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     d206007c2bb99da5241ad60222f71d058cce6f7a
Gitweb:        https://git.kernel.org/tip/d206007c2bb99da5241ad60222f71d058cce6f7a
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:44 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Tue, 06 May 2025 14:59:08 +02:00

irqdomain: Make struct irq_domain_info variables const

This is just expressing it explicitly as irq_domain_instantiate() takes const already. No functional change.

---
 include/linux/irqdomain.h | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
include/linux/irqdomain.h +4 -4
index 1e38584..66a26df 100644
@@ -396,7 +396,7 @@ static inline struct irq_domain *irq_domain_create_nomap(struct fwnode_handle *f
 					 const struct irq_domain_ops *ops,
 					 void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.hwirq_max	= max_irq,
 		.direct_max	= max_irq,
@@ -416,7 +416,7 @@ static inline struct irq_domain *irq_domain_create_linear(struct fwnode_handle *
 					 const struct irq_domain_ops *ops,
 					 void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.size		= size,
 		.hwirq_max	= size,
@@ -432,7 +432,7 @@ static inline struct irq_domain *irq_domain_create_tree(struct fwnode_handle *fw
 					 const struct irq_domain_ops *ops,
 					 void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.hwirq_max	= ~0,
 		.ops		= ops,
@@ -548,7 +548,7 @@ static inline struct irq_domain *irq_domain_create_hierarchy(struct irq_domain *
 					    const struct irq_domain_ops *ops,
 					    void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.size		= size,
 		.hwirq_max	= size ? : ~0U,
#230 lore raw

[tip: irq/cleanups] irqdomain: Make struct irq_domain_info variables const

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     43466b23b056a2478b97ca6594d839a9336b465c
Gitweb:        https://git.kernel.org/tip/43466b23b056a2478b97ca6594d839a9336b465c
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:44 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 09:53:25 +02:00

irqdomain: Make struct irq_domain_info variables const

This is just expressing it explicitly as irq_domain_instantiate() takes const already. No functional change.

---
 include/linux/irqdomain.h | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
include/linux/irqdomain.h +4 -4
index 1e38584..66a26df 100644
@@ -396,7 +396,7 @@ static inline struct irq_domain *irq_domain_create_nomap(struct fwnode_handle *f
 					 const struct irq_domain_ops *ops,
 					 void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.hwirq_max	= max_irq,
 		.direct_max	= max_irq,
@@ -416,7 +416,7 @@ static inline struct irq_domain *irq_domain_create_linear(struct fwnode_handle *
 					 const struct irq_domain_ops *ops,
 					 void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.size		= size,
 		.hwirq_max	= size,
@@ -432,7 +432,7 @@ static inline struct irq_domain *irq_domain_create_tree(struct fwnode_handle *fw
 					 const struct irq_domain_ops *ops,
 					 void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.hwirq_max	= ~0,
 		.ops		= ops,
@@ -548,7 +548,7 @@ static inline struct irq_domain *irq_domain_create_hierarchy(struct irq_domain *
 					    const struct irq_domain_ops *ops,
 					    void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.size		= size,
 		.hwirq_max	= size ? : ~0U,
#231 lore raw

[tip: irq/cleanups] irqdomain: Make struct irq_domain_info variables const

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     91854572f918c0f88d39a7013731dc3b7d3a1cf5
Gitweb:        https://git.kernel.org/tip/91854572f918c0f88d39a7013731dc3b7d3a1cf5
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:44 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 15:39:42 +02:00

irqdomain: Make struct irq_domain_info variables const

This is just expressing it explicitly as irq_domain_instantiate() takes const already. No functional change.

---
 include/linux/irqdomain.h | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
include/linux/irqdomain.h +4 -4
index 1e38584..66a26df 100644
@@ -396,7 +396,7 @@ static inline struct irq_domain *irq_domain_create_nomap(struct fwnode_handle *f
 					 const struct irq_domain_ops *ops,
 					 void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.hwirq_max	= max_irq,
 		.direct_max	= max_irq,
@@ -416,7 +416,7 @@ static inline struct irq_domain *irq_domain_create_linear(struct fwnode_handle *
 					 const struct irq_domain_ops *ops,
 					 void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.size		= size,
 		.hwirq_max	= size,
@@ -432,7 +432,7 @@ static inline struct irq_domain *irq_domain_create_tree(struct fwnode_handle *fw
 					 const struct irq_domain_ops *ops,
 					 void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.hwirq_max	= ~0,
 		.ops		= ops,
@@ -548,7 +548,7 @@ static inline struct irq_domain *irq_domain_create_hierarchy(struct irq_domain *
 					    const struct irq_domain_ops *ops,
 					    void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.size		= size,
 		.hwirq_max	= size ? : ~0U,
#232 lore raw

[tip: irq/cleanups] irqdomain: Make struct irq_domain_info variables const

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     66cbf17fe67156608421e717975c415a85c08466
Gitweb:        https://git.kernel.org/tip/66cbf17fe67156608421e717975c415a85c08466
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:44 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Fri, 16 May 2025 21:06:13 +02:00

irqdomain: Make struct irq_domain_info variables const

This is just expressing it explicitly as irq_domain_instantiate() takes const already. No functional change.

---
 include/linux/irqdomain.h | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
include/linux/irqdomain.h +4 -4
index 1e38584..66a26df 100644
@@ -396,7 +396,7 @@ static inline struct irq_domain *irq_domain_create_nomap(struct fwnode_handle *f
 					 const struct irq_domain_ops *ops,
 					 void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.hwirq_max	= max_irq,
 		.direct_max	= max_irq,
@@ -416,7 +416,7 @@ static inline struct irq_domain *irq_domain_create_linear(struct fwnode_handle *
 					 const struct irq_domain_ops *ops,
 					 void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.size		= size,
 		.hwirq_max	= size,
@@ -432,7 +432,7 @@ static inline struct irq_domain *irq_domain_create_tree(struct fwnode_handle *fw
 					 const struct irq_domain_ops *ops,
 					 void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.hwirq_max	= ~0,
 		.ops		= ops,
@@ -548,7 +548,7 @@ static inline struct irq_domain *irq_domain_create_hierarchy(struct irq_domain *
 					    const struct irq_domain_ops *ops,
 					    void *host_data)
 {
-	struct irq_domain_info info = {
+	const struct irq_domain_info info = {
 		.fwnode		= fwnode,
 		.size		= size,
 		.hwirq_max	= size ? : ~0U,
#233 lore raw

PATCH v2 52/57 irqdomain.h: Improve kernel-docs of functions

In reply to Jiri Slaby (SUSE)

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.

---
[v2] no () for functions names in the comments' headers

---
 include/linux/irqdomain.h | 42 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)
include/linux/irqdomain.h +41 -1
index 472f6bb91e9a..3e7103645c63 100644
@@ -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)
 {
Signature · 1 line
2.49.0
#234 lore raw

[tip: irq/cleanups] irqdomain: Improve kernel-docs of functions

The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     fad0b7bbf9a698b4655efd49fca6926f664f9d02
Gitweb:        https://git.kernel.org/tip/fad0b7bbf9a698b4655efd49fca6926f664f9d02
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:45 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Tue, 06 May 2025 14:59:09 +02:00

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.

---
 include/linux/irqdomain.h | 42 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)
include/linux/irqdomain.h +41 -1
index 66a26df..a70e2ba 100644
@@ -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)
 {
#235 lore raw

[tip: irq/cleanups] irqdomain: Improve kernel-docs of functions

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     c48bbbd6e857e9e92b693a565a3c87823fdd4169
Gitweb:        https://git.kernel.org/tip/c48bbbd6e857e9e92b693a565a3c87823fdd4169
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:45 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 09:53:25 +02:00

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.

---
 include/linux/irqdomain.h | 42 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)
include/linux/irqdomain.h +41 -1
index 66a26df..a70e2ba 100644
@@ -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)
 {
#236 lore raw

[tip: irq/cleanups] irqdomain: Improve kernel-docs of functions

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     ece27dde1fe1a70f9b0e791e168ec823d62e455a
Gitweb:        https://git.kernel.org/tip/ece27dde1fe1a70f9b0e791e168ec823d62e455a
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:45 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 15:39:42 +02:00

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.

---
 include/linux/irqdomain.h | 42 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)
include/linux/irqdomain.h +41 -1
index 66a26df..a70e2ba 100644
@@ -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)
 {
#237 lore raw

[tip: irq/cleanups] irqdomain: Improve kernel-docs of functions

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     2272a78b3f4a7a1621f00ac6e9c9232d12b7ff01
Gitweb:        https://git.kernel.org/tip/2272a78b3f4a7a1621f00ac6e9c9232d12b7ff01
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:45 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Fri, 16 May 2025 21:06:13 +02:00

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.

---
 include/linux/irqdomain.h | 42 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)
include/linux/irqdomain.h +41 -1
index 66a26df..a70e2ba 100644
@@ -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)
 {
#238 lore raw

PATCH v2 53/57 docs: irq/concepts: Add commas and reflow

In reply to Jiri Slaby (SUSE)

For easier reading, it is always desired to add commas at some places in text. Like before adverbs or after fronted sentences.

---
 Documentation/core-api/irq/concepts.rst | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)
Documentation/core-api/irq/concepts.rst +9 -10
index 4273806a606b..f166006a81f6 100644
@@ -2,23 +2,22 @@
 What is an IRQ?
 ===============
 
-An IRQ is an interrupt request from a device.
-Currently they can come in over a pin, or over a packet.
-Several devices may be connected to the same pin thus
-sharing an IRQ.
+An IRQ is an interrupt request from a device. Currently, they can come
+in over a pin, or over a packet. Several devices may be connected to
+the same pin thus sharing an IRQ.
 
 An IRQ number is a kernel identifier used to talk about a hardware
-interrupt source.  Typically this is an index into the global irq_desc
-array, but except for what linux/interrupt.h implements the details
+interrupt source. Typically, this is an index into the global irq_desc
+array, but except for what linux/interrupt.h implements, the details
 are architecture specific.
 
 An IRQ number is an enumeration of the possible interrupt sources on a
-machine.  Typically what is enumerated is the number of input pins on
-all of the interrupt controller in the system.  In the case of ISA
+machine. Typically, what is enumerated is the number of input pins on
+all of the interrupt controllers in the system. In the case of ISA,
 what is enumerated are the 16 input pins on the two i8259 interrupt
 controllers.
 
 Architectures can assign additional meaning to the IRQ numbers, and
-are encouraged to in the case  where there is any manual configuration
-of the hardware involved.  The ISA IRQs are a classic example of
+are encouraged to in the case where there is any manual configuration
+of the hardware involved. The ISA IRQs are a classic example of
 assigning this kind of additional meaning.
Signature · 1 line
2.49.0
#239 lore raw

[tip: irq/cleanups] Documentation: irq/concepts: Add commas and reflow

The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     343b4bf2869da43caf40906a0026f929ead85e22
Gitweb:        https://git.kernel.org/tip/343b4bf2869da43caf40906a0026f929ead85e22
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:46 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Tue, 06 May 2025 14:59:09 +02:00

Documentation: irq/concepts: Add commas and reflow

For easier reading, it is always desired to add commas at some places in text. Like before adverbs or after fronted sentences.

[ tglx: Fix up subject prefix ]

---
 Documentation/core-api/irq/concepts.rst | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)
Documentation/core-api/irq/concepts.rst +9 -10
index 4273806..f166006 100644
@@ -2,23 +2,22 @@
 What is an IRQ?
 ===============
 
-An IRQ is an interrupt request from a device.
-Currently they can come in over a pin, or over a packet.
-Several devices may be connected to the same pin thus
-sharing an IRQ.
+An IRQ is an interrupt request from a device. Currently, they can come
+in over a pin, or over a packet. Several devices may be connected to
+the same pin thus sharing an IRQ.
 
 An IRQ number is a kernel identifier used to talk about a hardware
-interrupt source.  Typically this is an index into the global irq_desc
-array, but except for what linux/interrupt.h implements the details
+interrupt source. Typically, this is an index into the global irq_desc
+array, but except for what linux/interrupt.h implements, the details
 are architecture specific.
 
 An IRQ number is an enumeration of the possible interrupt sources on a
-machine.  Typically what is enumerated is the number of input pins on
-all of the interrupt controller in the system.  In the case of ISA
+machine. Typically, what is enumerated is the number of input pins on
+all of the interrupt controllers in the system. In the case of ISA,
 what is enumerated are the 16 input pins on the two i8259 interrupt
 controllers.
 
 Architectures can assign additional meaning to the IRQ numbers, and
-are encouraged to in the case  where there is any manual configuration
-of the hardware involved.  The ISA IRQs are a classic example of
+are encouraged to in the case where there is any manual configuration
+of the hardware involved. The ISA IRQs are a classic example of
 assigning this kind of additional meaning.
#240 lore raw

[tip: irq/cleanups] Documentation: irq/concepts: Add commas and reflow

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     401dec9125415fc670d5d093190a2942ddb1963b
Gitweb:        https://git.kernel.org/tip/401dec9125415fc670d5d093190a2942ddb1963b
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:46 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 09:53:25 +02:00

Documentation: irq/concepts: Add commas and reflow

For easier reading, it is always desired to add commas at some places in text. Like before adverbs or after fronted sentences.

[ tglx: Fix up subject prefix ]

---
 Documentation/core-api/irq/concepts.rst | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)
Documentation/core-api/irq/concepts.rst +9 -10
index 4273806..f166006 100644
@@ -2,23 +2,22 @@
 What is an IRQ?
 ===============
 
-An IRQ is an interrupt request from a device.
-Currently they can come in over a pin, or over a packet.
-Several devices may be connected to the same pin thus
-sharing an IRQ.
+An IRQ is an interrupt request from a device. Currently, they can come
+in over a pin, or over a packet. Several devices may be connected to
+the same pin thus sharing an IRQ.
 
 An IRQ number is a kernel identifier used to talk about a hardware
-interrupt source.  Typically this is an index into the global irq_desc
-array, but except for what linux/interrupt.h implements the details
+interrupt source. Typically, this is an index into the global irq_desc
+array, but except for what linux/interrupt.h implements, the details
 are architecture specific.
 
 An IRQ number is an enumeration of the possible interrupt sources on a
-machine.  Typically what is enumerated is the number of input pins on
-all of the interrupt controller in the system.  In the case of ISA
+machine. Typically, what is enumerated is the number of input pins on
+all of the interrupt controllers in the system. In the case of ISA,
 what is enumerated are the 16 input pins on the two i8259 interrupt
 controllers.
 
 Architectures can assign additional meaning to the IRQ numbers, and
-are encouraged to in the case  where there is any manual configuration
-of the hardware involved.  The ISA IRQs are a classic example of
+are encouraged to in the case where there is any manual configuration
+of the hardware involved. The ISA IRQs are a classic example of
 assigning this kind of additional meaning.
#241 lore raw

[tip: irq/cleanups] Documentation: irq/concepts: Add commas and reflow

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     55ec529a4e4189f7359d50f7c444e4a3589e2d12
Gitweb:        https://git.kernel.org/tip/55ec529a4e4189f7359d50f7c444e4a3589e2d12
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:46 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 15:39:42 +02:00

Documentation: irq/concepts: Add commas and reflow

For easier reading, it is always desired to add commas at some places in text. Like before adverbs or after fronted sentences.

[ tglx: Fix up subject prefix ]

---
 Documentation/core-api/irq/concepts.rst | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)
Documentation/core-api/irq/concepts.rst +9 -10
index 4273806..f166006 100644
@@ -2,23 +2,22 @@
 What is an IRQ?
 ===============
 
-An IRQ is an interrupt request from a device.
-Currently they can come in over a pin, or over a packet.
-Several devices may be connected to the same pin thus
-sharing an IRQ.
+An IRQ is an interrupt request from a device. Currently, they can come
+in over a pin, or over a packet. Several devices may be connected to
+the same pin thus sharing an IRQ.
 
 An IRQ number is a kernel identifier used to talk about a hardware
-interrupt source.  Typically this is an index into the global irq_desc
-array, but except for what linux/interrupt.h implements the details
+interrupt source. Typically, this is an index into the global irq_desc
+array, but except for what linux/interrupt.h implements, the details
 are architecture specific.
 
 An IRQ number is an enumeration of the possible interrupt sources on a
-machine.  Typically what is enumerated is the number of input pins on
-all of the interrupt controller in the system.  In the case of ISA
+machine. Typically, what is enumerated is the number of input pins on
+all of the interrupt controllers in the system. In the case of ISA,
 what is enumerated are the 16 input pins on the two i8259 interrupt
 controllers.
 
 Architectures can assign additional meaning to the IRQ numbers, and
-are encouraged to in the case  where there is any manual configuration
-of the hardware involved.  The ISA IRQs are a classic example of
+are encouraged to in the case where there is any manual configuration
+of the hardware involved. The ISA IRQs are a classic example of
 assigning this kind of additional meaning.
#242 lore raw

[tip: irq/cleanups] Documentation: irq/concepts: Add commas and reflow

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     2f7bd3293e4512323fd5334ef13cf2826de27666
Gitweb:        https://git.kernel.org/tip/2f7bd3293e4512323fd5334ef13cf2826de27666
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:46 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Fri, 16 May 2025 21:06:13 +02:00

Documentation: irq/concepts: Add commas and reflow

For easier reading, it is always desired to add commas at some places in text. Like before adverbs or after fronted sentences.

[ tglx: Fix up subject prefix ]

---
 Documentation/core-api/irq/concepts.rst | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)
Documentation/core-api/irq/concepts.rst +9 -10
index 4273806..f166006 100644
@@ -2,23 +2,22 @@
 What is an IRQ?
 ===============
 
-An IRQ is an interrupt request from a device.
-Currently they can come in over a pin, or over a packet.
-Several devices may be connected to the same pin thus
-sharing an IRQ.
+An IRQ is an interrupt request from a device. Currently, they can come
+in over a pin, or over a packet. Several devices may be connected to
+the same pin thus sharing an IRQ.
 
 An IRQ number is a kernel identifier used to talk about a hardware
-interrupt source.  Typically this is an index into the global irq_desc
-array, but except for what linux/interrupt.h implements the details
+interrupt source. Typically, this is an index into the global irq_desc
+array, but except for what linux/interrupt.h implements, the details
 are architecture specific.
 
 An IRQ number is an enumeration of the possible interrupt sources on a
-machine.  Typically what is enumerated is the number of input pins on
-all of the interrupt controller in the system.  In the case of ISA
+machine. Typically, what is enumerated is the number of input pins on
+all of the interrupt controllers in the system. In the case of ISA,
 what is enumerated are the 16 input pins on the two i8259 interrupt
 controllers.
 
 Architectures can assign additional meaning to the IRQ numbers, and
-are encouraged to in the case  where there is any manual configuration
-of the hardware involved.  The ISA IRQs are a classic example of
+are encouraged to in the case where there is any manual configuration
+of the hardware involved. The ISA IRQs are a classic example of
 assigning this kind of additional meaning.
#243 lore raw

PATCH v2 54/57 docs: irq/concepts: Minor improvements

In reply to Jiri Slaby (SUSE)

Just note in the docs:
1) A PCI as an example for shared interrupts,
2) a sparse tree can be used for interrupts too, and
3) two i8259s have 8 pins.

---
 Documentation/core-api/irq/concepts.rst | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)
Documentation/core-api/irq/concepts.rst +7 -5
index f166006a81f6..7c4564f3cbdf 100644
@@ -4,18 +4,20 @@ What is an IRQ?
 
 An IRQ is an interrupt request from a device. Currently, they can come
 in over a pin, or over a packet. Several devices may be connected to
-the same pin thus sharing an IRQ.
+the same pin thus sharing an IRQ. Such as on legacy PCI bus: All devices
+typically share 4 lanes/pins. Note that each device can request an
+interrupt on each of the lanes.
 
 An IRQ number is a kernel identifier used to talk about a hardware
 interrupt source. Typically, this is an index into the global irq_desc
-array, but except for what linux/interrupt.h implements, the details
-are architecture specific.
+array or sparse_irqs tree. But except for what linux/interrupt.h
+implements, the details are architecture specific.
 
 An IRQ number is an enumeration of the possible interrupt sources on a
 machine. Typically, what is enumerated is the number of input pins on
 all of the interrupt controllers in the system. In the case of ISA,
-what is enumerated are the 16 input pins on the two i8259 interrupt
-controllers.
+what is enumerated are the 8 input pins on each of the two i8259
+interrupt controllers.
 
 Architectures can assign additional meaning to the IRQ numbers, and
 are encouraged to in the case where there is any manual configuration
Signature · 1 line
2.49.0
#244 lore raw

[tip: irq/cleanups] Documentation: irq/concepts: Minor improvements

The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     22909d92a0298a22a6cbe39644a03af6d62983e2
Gitweb:        https://git.kernel.org/tip/22909d92a0298a22a6cbe39644a03af6d62983e2
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:47 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Tue, 06 May 2025 14:59:09 +02:00

Documentation: irq/concepts: Minor improvements

Just note in the docs:

1) A PCI device as an example for shared interrupts
2) A sparse tree can be used for interrupts too
3) i8259s which have 8 pins

[ tglx: Fix up subject prefix ]

---
 Documentation/core-api/irq/concepts.rst | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)
Documentation/core-api/irq/concepts.rst +7 -5
index f166006..7c4564f 100644
@@ -4,18 +4,20 @@ What is an IRQ?
 
 An IRQ is an interrupt request from a device. Currently, they can come
 in over a pin, or over a packet. Several devices may be connected to
-the same pin thus sharing an IRQ.
+the same pin thus sharing an IRQ. Such as on legacy PCI bus: All devices
+typically share 4 lanes/pins. Note that each device can request an
+interrupt on each of the lanes.
 
 An IRQ number is a kernel identifier used to talk about a hardware
 interrupt source. Typically, this is an index into the global irq_desc
-array, but except for what linux/interrupt.h implements, the details
-are architecture specific.
+array or sparse_irqs tree. But except for what linux/interrupt.h
+implements, the details are architecture specific.
 
 An IRQ number is an enumeration of the possible interrupt sources on a
 machine. Typically, what is enumerated is the number of input pins on
 all of the interrupt controllers in the system. In the case of ISA,
-what is enumerated are the 16 input pins on the two i8259 interrupt
-controllers.
+what is enumerated are the 8 input pins on each of the two i8259
+interrupt controllers.
 
 Architectures can assign additional meaning to the IRQ numbers, and
 are encouraged to in the case where there is any manual configuration
#245 lore raw

[tip: irq/cleanups] Documentation: irq/concepts: Minor improvements

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     457a114de9a95948e2cc6ddecc4a73392a82aa4e
Gitweb:        https://git.kernel.org/tip/457a114de9a95948e2cc6ddecc4a73392a82aa4e
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:47 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 09:53:25 +02:00

Documentation: irq/concepts: Minor improvements

Just note in the docs:

1) A PCI device as an example for shared interrupts
2) A sparse tree can be used for interrupts too
3) i8259s which have 8 pins

[ tglx: Fix up subject prefix ]

---
 Documentation/core-api/irq/concepts.rst | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)
Documentation/core-api/irq/concepts.rst +7 -5
index f166006..7c4564f 100644
@@ -4,18 +4,20 @@ What is an IRQ?
 
 An IRQ is an interrupt request from a device. Currently, they can come
 in over a pin, or over a packet. Several devices may be connected to
-the same pin thus sharing an IRQ.
+the same pin thus sharing an IRQ. Such as on legacy PCI bus: All devices
+typically share 4 lanes/pins. Note that each device can request an
+interrupt on each of the lanes.
 
 An IRQ number is a kernel identifier used to talk about a hardware
 interrupt source. Typically, this is an index into the global irq_desc
-array, but except for what linux/interrupt.h implements, the details
-are architecture specific.
+array or sparse_irqs tree. But except for what linux/interrupt.h
+implements, the details are architecture specific.
 
 An IRQ number is an enumeration of the possible interrupt sources on a
 machine. Typically, what is enumerated is the number of input pins on
 all of the interrupt controllers in the system. In the case of ISA,
-what is enumerated are the 16 input pins on the two i8259 interrupt
-controllers.
+what is enumerated are the 8 input pins on each of the two i8259
+interrupt controllers.
 
 Architectures can assign additional meaning to the IRQ numbers, and
 are encouraged to in the case where there is any manual configuration
#246 lore raw

[tip: irq/cleanups] Documentation: irq/concepts: Minor improvements

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     809997b2b2d14b762e24829a0ce63a4a75e6185b
Gitweb:        https://git.kernel.org/tip/809997b2b2d14b762e24829a0ce63a4a75e6185b
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:47 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 15:39:42 +02:00

Documentation: irq/concepts: Minor improvements

Just note in the docs:

1) A PCI device as an example for shared interrupts
2) A sparse tree can be used for interrupts too
3) i8259s which have 8 pins

[ tglx: Fix up subject prefix ]

---
 Documentation/core-api/irq/concepts.rst | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)
Documentation/core-api/irq/concepts.rst +7 -5
index f166006..7c4564f 100644
@@ -4,18 +4,20 @@ What is an IRQ?
 
 An IRQ is an interrupt request from a device. Currently, they can come
 in over a pin, or over a packet. Several devices may be connected to
-the same pin thus sharing an IRQ.
+the same pin thus sharing an IRQ. Such as on legacy PCI bus: All devices
+typically share 4 lanes/pins. Note that each device can request an
+interrupt on each of the lanes.
 
 An IRQ number is a kernel identifier used to talk about a hardware
 interrupt source. Typically, this is an index into the global irq_desc
-array, but except for what linux/interrupt.h implements, the details
-are architecture specific.
+array or sparse_irqs tree. But except for what linux/interrupt.h
+implements, the details are architecture specific.
 
 An IRQ number is an enumeration of the possible interrupt sources on a
 machine. Typically, what is enumerated is the number of input pins on
 all of the interrupt controllers in the system. In the case of ISA,
-what is enumerated are the 16 input pins on the two i8259 interrupt
-controllers.
+what is enumerated are the 8 input pins on each of the two i8259
+interrupt controllers.
 
 Architectures can assign additional meaning to the IRQ numbers, and
 are encouraged to in the case where there is any manual configuration
#247 lore raw

[tip: irq/cleanups] Documentation: irq/concepts: Minor improvements

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     225942f06e93dc4c24ce50df92e0eb5bcd2afbac
Gitweb:        https://git.kernel.org/tip/225942f06e93dc4c24ce50df92e0eb5bcd2afbac
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:47 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Fri, 16 May 2025 21:06:13 +02:00

Documentation: irq/concepts: Minor improvements

Just note in the docs:

1) A PCI device as an example for shared interrupts
2) A sparse tree can be used for interrupts too
3) i8259s which have 8 pins

[ tglx: Fix up subject prefix ]

---
 Documentation/core-api/irq/concepts.rst | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)
Documentation/core-api/irq/concepts.rst +7 -5
index f166006..7c4564f 100644
@@ -4,18 +4,20 @@ What is an IRQ?
 
 An IRQ is an interrupt request from a device. Currently, they can come
 in over a pin, or over a packet. Several devices may be connected to
-the same pin thus sharing an IRQ.
+the same pin thus sharing an IRQ. Such as on legacy PCI bus: All devices
+typically share 4 lanes/pins. Note that each device can request an
+interrupt on each of the lanes.
 
 An IRQ number is a kernel identifier used to talk about a hardware
 interrupt source. Typically, this is an index into the global irq_desc
-array, but except for what linux/interrupt.h implements, the details
-are architecture specific.
+array or sparse_irqs tree. But except for what linux/interrupt.h
+implements, the details are architecture specific.
 
 An IRQ number is an enumeration of the possible interrupt sources on a
 machine. Typically, what is enumerated is the number of input pins on
 all of the interrupt controllers in the system. In the case of ISA,
-what is enumerated are the 16 input pins on the two i8259 interrupt
-controllers.
+what is enumerated are the 8 input pins on each of the two i8259
+interrupt controllers.
 
 Architectures can assign additional meaning to the IRQ numbers, and
 are encouraged to in the case where there is any manual configuration
#248 lore raw

PATCH v2 55/57 docs: irq-domain.rst: Simple improvements

In reply to Jiri Slaby (SUSE)

The improvements include:
* Capitals in headlines.
* Added commas: for easier reading, it is always desired to add commas at some places in text. Like before adverbs or after fronted sentences.
* 3rd person -> add 's' to verbs.
* End some sentences with period and start a new one. Avoid thus heavy sentences.

---
 Documentation/core-api/irq/irq-domain.rst | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)
Documentation/core-api/irq/irq-domain.rst +11 -11
index 775dd43b3340..c2f2728b1a35 100644
@@ -1,19 +1,19 @@
 ===============================================
-The irq_domain interrupt number mapping library
+The irq_domain Interrupt Number Mapping Library
 ===============================================
 
 The current design of the Linux kernel uses a single large number
 space where each separate IRQ source is assigned a different number.
 This is simple when there is only one interrupt controller, but in
-systems with multiple interrupt controllers the kernel must ensure
+systems with multiple interrupt controllers, the kernel must ensure
 that each one gets assigned non-overlapping allocations of Linux
 IRQ numbers.
 
 The number of interrupt controllers registered as unique irqchips
-show a rising tendency: for example subdrivers of different kinds
+shows a rising tendency. For example, subdrivers of different kinds
 such as GPIO controllers avoid reimplementing identical callback
 mechanisms as the IRQ core system by modelling their interrupt
-handlers as irqchips, i.e. in effect cascading interrupt controllers.
+handlers as irqchips. I.e. in effect cascading interrupt controllers.
 
 Here the interrupt number loose all kind of correspondence to
 hardware interrupt numbers: whereas in the past, IRQ numbers could
@@ -21,15 +21,15 @@ be chosen so they matched the hardware IRQ line into the root
 interrupt controller (i.e. the component actually fireing the
 interrupt line to the CPU) nowadays this number is just a number.
 
-For this reason we need a mechanism to separate controller-local
-interrupt numbers, called hardware irq's, from Linux IRQ numbers.
+For this reason, we need a mechanism to separate controller-local
+interrupt numbers, called hardware IRQs, from Linux IRQ numbers.
 
 The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of
 irq numbers, but they don't provide any support for reverse mapping of
 the controller-local IRQ (hwirq) number into the Linux IRQ number
 space.
 
-The irq_domain library adds mapping between hwirq and IRQ numbers on
+The irq_domain library adds a mapping between hwirq and IRQ numbers on
 top of the irq_alloc_desc*() API.  An irq_domain to manage mapping is
 preferred over interrupt controller drivers open coding their own
 reverse mapping scheme.
@@ -38,7 +38,7 @@ irq_domain also implements translation from an abstract irq_fwspec
 structure to hwirq numbers (Device Tree and ACPI GSI so far), and can
 be easily extended to support other IRQ topology data sources.
 
-irq_domain usage
+irq_domain Usage
 ================
 
 An interrupt controller driver creates and registers an irq_domain by
@@ -77,7 +77,7 @@ If the driver has the Linux IRQ number or the irq_data pointer, and
 needs to know the associated hwirq number (such as in the irq_chip
 callbacks) then it can be directly obtained from irq_data->hwirq.
 
-Types of irq_domain mappings
+Types of irq_domain Mappings
 ============================
 
 There are several mechanisms available for reverse mapping from hwirq
@@ -102,7 +102,7 @@ map are fixed time lookup for IRQ numbers, and irq_descs are only
 allocated for in-use IRQs.  The disadvantage is that the table must be
 as large as the largest possible hwirq number.
 
-The majority of drivers should use the linear map.
+The majority of drivers should use the Linear map.
 
 Tree
 ----
@@ -190,7 +190,7 @@ that the driver using the simple domain call irq_create_mapping()
 before any irq_find_mapping() since the latter will actually work
 for the static IRQ assignment case.
 
-Hierarchy IRQ domain
+Hierarchy IRQ Domain
 --------------------
 
 On some architectures, there may be multiple interrupt controllers
Signature · 1 line
2.49.0
reviewer
#249 lore raw

Re: [PATCH v2 55/57] docs: irq-domain.rst: Simple improvements

Hi,

Quoted 25 lines · Jiri Slaby (SUSE)

The improvements include:
* Capitals in headlines.
* Added commas: for easier reading, it is always desired to add commas at some places in text. Like before adverbs or after fronted sentences.
* 3rd person -> add 's' to verbs.
* End some sentences with period and start a new one. Avoid thus heavy sentences.

---
 Documentation/core-api/irq/irq-domain.rst | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)
Documentation/core-api/irq/irq-domain.rst +1 -1
index 775dd43b3340..c2f2728b1a35 100644
@@ -1,19 +1,19 @@
 ===============================================
-The irq_domain interrupt number mapping library
+The irq_domain Interrupt Number Mapping Library

Documentation/core-api/irq/irq-domain.rst line 11

Quoted 10 lines
Documentation/core-api/irq/irq-domain.rst +1 -1
 ===============================================
 
 The current design of the Linux kernel uses a single large number
 space where each separate IRQ source is assigned a different number.
 This is simple when there is only one interrupt controller, but in
-systems with multiple interrupt controllers the kernel must ensure
+systems with multiple interrupt controllers, the kernel must ensure
 that each one gets assigned non-overlapping allocations of Linux
 IRQ numbers.
 

(I'm OK with all of the changes here except this one:)

Documentation/core-api/irq/irq-domain.rst line 16

Quoted 6 lines
Documentation/core-api/irq/irq-domain.rst +2 -1
 The number of interrupt controllers registered as unique irqchips> -show a rising tendency: for example subdrivers of different kinds
+shows a rising tendency. For example, subdrivers of different kinds
 such as GPIO controllers avoid reimplementing identical callback
 mechanisms as the IRQ core system by modelling their interrupt
-handlers as irqchips, i.e. in effect cascading interrupt controllers.
+handlers as irqchips. I.e. in effect cascading interrupt controllers.

I would just add a comma after "i.e.". In the new + line, the "I.e." part is not a sentence.

Quoted 50 lines
Documentation/core-api/irq/irq-domain.rst +6 -6
 Here the interrupt number loose all kind of correspondence to
 hardware interrupt numbers: whereas in the past, IRQ numbers could
@@ -21,15 +21,15 @@ be chosen so they matched the hardware IRQ line into the root
 interrupt controller (i.e. the component actually fireing the
 interrupt line to the CPU) nowadays this number is just a number.
 
-For this reason we need a mechanism to separate controller-local
-interrupt numbers, called hardware irq's, from Linux IRQ numbers.
+For this reason, we need a mechanism to separate controller-local
+interrupt numbers, called hardware IRQs, from Linux IRQ numbers.
 
 The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of
 irq numbers, but they don't provide any support for reverse mapping of
 the controller-local IRQ (hwirq) number into the Linux IRQ number
 space.
 
-The irq_domain library adds mapping between hwirq and IRQ numbers on
+The irq_domain library adds a mapping between hwirq and IRQ numbers on
 top of the irq_alloc_desc*() API.  An irq_domain to manage mapping is
 preferred over interrupt controller drivers open coding their own
 reverse mapping scheme.
@@ -38,7 +38,7 @@ irq_domain also implements translation from an abstract irq_fwspec
 structure to hwirq numbers (Device Tree and ACPI GSI so far), and can
 be easily extended to support other IRQ topology data sources.
 
-irq_domain usage
+irq_domain Usage
 ================
 
 An interrupt controller driver creates and registers an irq_domain by
@@ -77,7 +77,7 @@ If the driver has the Linux IRQ number or the irq_data pointer, and
 needs to know the associated hwirq number (such as in the irq_chip
 callbacks) then it can be directly obtained from irq_data->hwirq.
 
-Types of irq_domain mappings
+Types of irq_domain Mappings
 ============================
 
 There are several mechanisms available for reverse mapping from hwirq
@@ -102,7 +102,7 @@ map are fixed time lookup for IRQ numbers, and irq_descs are only
 allocated for in-use IRQs.  The disadvantage is that the table must be
 as large as the largest possible hwirq number.
 
-The majority of drivers should use the linear map.
+The majority of drivers should use the Linear map.
 
 Tree
 ----

Documentation/core-api/irq/irq-domain.rst that the driver using the simple domain call irq_create_mapping() · line 196

Quoted 8 lines
Documentation/core-api/irq/irq-domain.rst +1 -1
@@ -190,7 +190,7 @@ that the driver using the simple domain call irq_create_mapping()
 before any irq_find_mapping() since the latter will actually work
 for the static IRQ assignment case.
 
-Hierarchy IRQ domain
+Hierarchy IRQ Domain
 --------------------
 
 On some architectures, there may be multiple interrupt controllers

thanks.

Signature · 1 line
~Randy
author
#250 lore raw

Re: [PATCH v2 55/57] docs: irq-domain.rst: Simple improvements

Quoted 41 lines · Randy Dunlap

Hi,

Quoted 25 lines · Jiri Slaby (SUSE)

The improvements include:
* Capitals in headlines.
* Added commas: for easier reading, it is always desired to add commas at some places in text. Like before adverbs or after fronted sentences.
* 3rd person -> add 's' to verbs.
* End some sentences with period and start a new one. Avoid thus heavy sentences.

---
  Documentation/core-api/irq/irq-domain.rst | 22 +++++++++++-----------
  1 file changed, 11 insertions(+), 11 deletions(-)
Documentation/core-api/irq/irq-domain.rst +1 -1
index 775dd43b3340..c2f2728b1a35 100644
@@ -1,19 +1,19 @@
  ===============================================
-The irq_domain interrupt number mapping library
+The irq_domain Interrupt Number Mapping Library

Documentation/core-api/irq/irq-domain.rst line 11

Quoted 10 lines
Documentation/core-api/irq/irq-domain.rst +1 -1
  ===============================================
 
  The current design of the Linux kernel uses a single large number
  space where each separate IRQ source is assigned a different number.
  This is simple when there is only one interrupt controller, but in
-systems with multiple interrupt controllers the kernel must ensure
+systems with multiple interrupt controllers, the kernel must ensure
  that each one gets assigned non-overlapping allocations of Linux
  IRQ numbers.
 

(I'm OK with all of the changes here except this one:)

Quoted 9 lines

Documentation/core-api/irq/irq-domain.rst line 16

Quoted 6 lines
Documentation/core-api/irq/irq-domain.rst +2 -1
  The number of interrupt controllers registered as unique irqchips> -show a rising tendency: for example subdrivers of different kinds
+shows a rising tendency. For example, subdrivers of different kinds
  such as GPIO controllers avoid reimplementing identical callback
  mechanisms as the IRQ core system by modelling their interrupt
-handlers as irqchips, i.e. in effect cascading interrupt controllers.
+handlers as irqchips. I.e. in effect cascading interrupt controllers.

I would just add a comma after "i.e.". In the new + line, the "I.e." part is not a sentence.

Thanks. Of course, so now, I have:

The number of interrupt controllers registered as unique irqchips shows a rising tendency. For example, subdrivers of different kinds such as GPIO controllers avoid reimplementing identical callback mechanisms as the IRQ core system by modelling their interrupt handlers as irqchips, i.e., in effect cascading interrupt controllers.

Signature · 2 lines
js
suse labs
#251 lore raw

[tip: irq/cleanups] Documentation: irq-domain.rst: Simple improvements

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     3701ae11de5fdcde0d129a7083032c8d87fd7e04
Gitweb:        https://git.kernel.org/tip/3701ae11de5fdcde0d129a7083032c8d87fd7e04
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:48 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Tue, 06 May 2025 14:59:09 +02:00

Documentation: irq-domain.rst: Simple improvements

The improvements include:

* Capitals in headlines.
* Add commas: for easier reading, it is always desired to add commas at some places in text. Like before adverbs or after fronted sentences.
* 3rd person -> add 's' to verbs.
* End some sentences with period and start a new one. Avoid thus heavy sentences.

[ tglx: Fix up subject prefix ]

---
 Documentation/core-api/irq/irq-domain.rst | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)
Documentation/core-api/irq/irq-domain.rst +11 -11
index c365c3e..cb25649 100644
@@ -1,19 +1,19 @@
 ===============================================
-The irq_domain interrupt number mapping library
+The irq_domain Interrupt Number Mapping Library
 ===============================================
 
 The current design of the Linux kernel uses a single large number
 space where each separate IRQ source is assigned a different number.
 This is simple when there is only one interrupt controller, but in
-systems with multiple interrupt controllers the kernel must ensure
+systems with multiple interrupt controllers, the kernel must ensure
 that each one gets assigned non-overlapping allocations of Linux
 IRQ numbers.
 
 The number of interrupt controllers registered as unique irqchips
-show a rising tendency: for example subdrivers of different kinds
+shows a rising tendency. For example, subdrivers of different kinds
 such as GPIO controllers avoid reimplementing identical callback
 mechanisms as the IRQ core system by modelling their interrupt
-handlers as irqchips, i.e. in effect cascading interrupt controllers.
+handlers as irqchips. I.e. in effect cascading interrupt controllers.
 
 Here the interrupt number loose all kind of correspondence to
 hardware interrupt numbers: whereas in the past, IRQ numbers could
@@ -21,15 +21,15 @@ be chosen so they matched the hardware IRQ line into the root
 interrupt controller (i.e. the component actually fireing the
 interrupt line to the CPU) nowadays this number is just a number.
 
-For this reason we need a mechanism to separate controller-local
-interrupt numbers, called hardware irq's, from Linux IRQ numbers.
+For this reason, we need a mechanism to separate controller-local
+interrupt numbers, called hardware IRQs, from Linux IRQ numbers.
 
 The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of
 irq numbers, but they don't provide any support for reverse mapping of
 the controller-local IRQ (hwirq) number into the Linux IRQ number
 space.
 
-The irq_domain library adds mapping between hwirq and IRQ numbers on
+The irq_domain library adds a mapping between hwirq and IRQ numbers on
 top of the irq_alloc_desc*() API.  An irq_domain to manage mapping is
 preferred over interrupt controller drivers open coding their own
 reverse mapping scheme.
@@ -38,7 +38,7 @@ irq_domain also implements translation from an abstract irq_fwspec
 structure to hwirq numbers (Device Tree and ACPI GSI so far), and can
 be easily extended to support other IRQ topology data sources.
 
-irq_domain usage
+irq_domain Usage
 ================
 
 An interrupt controller driver creates and registers an irq_domain by
@@ -76,7 +76,7 @@ If the driver has the Linux IRQ number or the irq_data pointer, and
 needs to know the associated hwirq number (such as in the irq_chip
 callbacks) then it can be directly obtained from irq_data->hwirq.
 
-Types of irq_domain mappings
+Types of irq_domain Mappings
 ============================
 
 There are several mechanisms available for reverse mapping from hwirq
@@ -101,7 +101,7 @@ map are fixed time lookup for IRQ numbers, and irq_descs are only
 allocated for in-use IRQs.  The disadvantage is that the table must be
 as large as the largest possible hwirq number.
 
-The majority of drivers should use the linear map.
+The majority of drivers should use the Linear map.
 
 Tree
 ----
@@ -189,7 +189,7 @@ that the driver using the simple domain call irq_create_mapping()
 before any irq_find_mapping() since the latter will actually work
 for the static IRQ assignment case.
 
-Hierarchy IRQ domain
+Hierarchy IRQ Domain
 --------------------
 
 On some architectures, there may be multiple interrupt controllers
#252 lore raw

[tip: irq/cleanups] Documentation: irq-domain.rst: Simple improvements

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     2a6b9324654859d1b3482664c919f07f3c363f13
Gitweb:        https://git.kernel.org/tip/2a6b9324654859d1b3482664c919f07f3c363f13
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:48 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 09:53:25 +02:00

Documentation: irq-domain.rst: Simple improvements

The improvements include:

* Capitals in headlines.
* Add commas: for easier reading, it is always desired to add commas at some places in text. Like before adverbs or after fronted sentences.
* 3rd person -> add 's' to verbs.
* End some sentences with period and start a new one. Avoid thus heavy sentences.

[ tglx: Fix up subject prefix ]

---
 Documentation/core-api/irq/irq-domain.rst | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)
Documentation/core-api/irq/irq-domain.rst +11 -11
index c365c3e..cb25649 100644
@@ -1,19 +1,19 @@
 ===============================================
-The irq_domain interrupt number mapping library
+The irq_domain Interrupt Number Mapping Library
 ===============================================
 
 The current design of the Linux kernel uses a single large number
 space where each separate IRQ source is assigned a different number.
 This is simple when there is only one interrupt controller, but in
-systems with multiple interrupt controllers the kernel must ensure
+systems with multiple interrupt controllers, the kernel must ensure
 that each one gets assigned non-overlapping allocations of Linux
 IRQ numbers.
 
 The number of interrupt controllers registered as unique irqchips
-show a rising tendency: for example subdrivers of different kinds
+shows a rising tendency. For example, subdrivers of different kinds
 such as GPIO controllers avoid reimplementing identical callback
 mechanisms as the IRQ core system by modelling their interrupt
-handlers as irqchips, i.e. in effect cascading interrupt controllers.
+handlers as irqchips. I.e. in effect cascading interrupt controllers.
 
 Here the interrupt number loose all kind of correspondence to
 hardware interrupt numbers: whereas in the past, IRQ numbers could
@@ -21,15 +21,15 @@ be chosen so they matched the hardware IRQ line into the root
 interrupt controller (i.e. the component actually fireing the
 interrupt line to the CPU) nowadays this number is just a number.
 
-For this reason we need a mechanism to separate controller-local
-interrupt numbers, called hardware irq's, from Linux IRQ numbers.
+For this reason, we need a mechanism to separate controller-local
+interrupt numbers, called hardware IRQs, from Linux IRQ numbers.
 
 The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of
 irq numbers, but they don't provide any support for reverse mapping of
 the controller-local IRQ (hwirq) number into the Linux IRQ number
 space.
 
-The irq_domain library adds mapping between hwirq and IRQ numbers on
+The irq_domain library adds a mapping between hwirq and IRQ numbers on
 top of the irq_alloc_desc*() API.  An irq_domain to manage mapping is
 preferred over interrupt controller drivers open coding their own
 reverse mapping scheme.
@@ -38,7 +38,7 @@ irq_domain also implements translation from an abstract irq_fwspec
 structure to hwirq numbers (Device Tree and ACPI GSI so far), and can
 be easily extended to support other IRQ topology data sources.
 
-irq_domain usage
+irq_domain Usage
 ================
 
 An interrupt controller driver creates and registers an irq_domain by
@@ -76,7 +76,7 @@ If the driver has the Linux IRQ number or the irq_data pointer, and
 needs to know the associated hwirq number (such as in the irq_chip
 callbacks) then it can be directly obtained from irq_data->hwirq.
 
-Types of irq_domain mappings
+Types of irq_domain Mappings
 ============================
 
 There are several mechanisms available for reverse mapping from hwirq
@@ -101,7 +101,7 @@ map are fixed time lookup for IRQ numbers, and irq_descs are only
 allocated for in-use IRQs.  The disadvantage is that the table must be
 as large as the largest possible hwirq number.
 
-The majority of drivers should use the linear map.
+The majority of drivers should use the Linear map.
 
 Tree
 ----
@@ -189,7 +189,7 @@ that the driver using the simple domain call irq_create_mapping()
 before any irq_find_mapping() since the latter will actually work
 for the static IRQ assignment case.
 
-Hierarchy IRQ domain
+Hierarchy IRQ Domain
 --------------------
 
 On some architectures, there may be multiple interrupt controllers
#253 lore raw

[tip: irq/cleanups] Documentation: irq-domain.rst: Simple improvements

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     31395072ee01f3fb969d72cece54a3458182b474
Gitweb:        https://git.kernel.org/tip/31395072ee01f3fb969d72cece54a3458182b474
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:48 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 15:39:43 +02:00

Documentation: irq-domain.rst: Simple improvements

The improvements include:

* Capitals in headlines.
* Add commas: for easier reading, it is always desired to add commas at some places in text. Like before adverbs or after fronted sentences.
* 3rd person -> add 's' to verbs.
* End some sentences with period and start a new one. Avoid thus heavy sentences.

[ tglx: Fix up subject prefix ]

---
 Documentation/core-api/irq/irq-domain.rst | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)
Documentation/core-api/irq/irq-domain.rst +11 -11
index c365c3e..cb25649 100644
@@ -1,19 +1,19 @@
 ===============================================
-The irq_domain interrupt number mapping library
+The irq_domain Interrupt Number Mapping Library
 ===============================================
 
 The current design of the Linux kernel uses a single large number
 space where each separate IRQ source is assigned a different number.
 This is simple when there is only one interrupt controller, but in
-systems with multiple interrupt controllers the kernel must ensure
+systems with multiple interrupt controllers, the kernel must ensure
 that each one gets assigned non-overlapping allocations of Linux
 IRQ numbers.
 
 The number of interrupt controllers registered as unique irqchips
-show a rising tendency: for example subdrivers of different kinds
+shows a rising tendency. For example, subdrivers of different kinds
 such as GPIO controllers avoid reimplementing identical callback
 mechanisms as the IRQ core system by modelling their interrupt
-handlers as irqchips, i.e. in effect cascading interrupt controllers.
+handlers as irqchips. I.e. in effect cascading interrupt controllers.
 
 Here the interrupt number loose all kind of correspondence to
 hardware interrupt numbers: whereas in the past, IRQ numbers could
@@ -21,15 +21,15 @@ be chosen so they matched the hardware IRQ line into the root
 interrupt controller (i.e. the component actually fireing the
 interrupt line to the CPU) nowadays this number is just a number.
 
-For this reason we need a mechanism to separate controller-local
-interrupt numbers, called hardware irq's, from Linux IRQ numbers.
+For this reason, we need a mechanism to separate controller-local
+interrupt numbers, called hardware IRQs, from Linux IRQ numbers.
 
 The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of
 irq numbers, but they don't provide any support for reverse mapping of
 the controller-local IRQ (hwirq) number into the Linux IRQ number
 space.
 
-The irq_domain library adds mapping between hwirq and IRQ numbers on
+The irq_domain library adds a mapping between hwirq and IRQ numbers on
 top of the irq_alloc_desc*() API.  An irq_domain to manage mapping is
 preferred over interrupt controller drivers open coding their own
 reverse mapping scheme.
@@ -38,7 +38,7 @@ irq_domain also implements translation from an abstract irq_fwspec
 structure to hwirq numbers (Device Tree and ACPI GSI so far), and can
 be easily extended to support other IRQ topology data sources.
 
-irq_domain usage
+irq_domain Usage
 ================
 
 An interrupt controller driver creates and registers an irq_domain by
@@ -76,7 +76,7 @@ If the driver has the Linux IRQ number or the irq_data pointer, and
 needs to know the associated hwirq number (such as in the irq_chip
 callbacks) then it can be directly obtained from irq_data->hwirq.
 
-Types of irq_domain mappings
+Types of irq_domain Mappings
 ============================
 
 There are several mechanisms available for reverse mapping from hwirq
@@ -101,7 +101,7 @@ map are fixed time lookup for IRQ numbers, and irq_descs are only
 allocated for in-use IRQs.  The disadvantage is that the table must be
 as large as the largest possible hwirq number.
 
-The majority of drivers should use the linear map.
+The majority of drivers should use the Linear map.
 
 Tree
 ----
@@ -189,7 +189,7 @@ that the driver using the simple domain call irq_create_mapping()
 before any irq_find_mapping() since the latter will actually work
 for the static IRQ assignment case.
 
-Hierarchy IRQ domain
+Hierarchy IRQ Domain
 --------------------
 
 On some architectures, there may be multiple interrupt controllers
#254 lore raw

[tip: irq/cleanups] Documentation: irq-domain.rst: Simple improvements

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     95cfac1b2f85ed883b1748d7955e00f0980c1bb3
Gitweb:        https://git.kernel.org/tip/95cfac1b2f85ed883b1748d7955e00f0980c1bb3
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:48 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Fri, 16 May 2025 21:06:13 +02:00

Documentation: irq-domain.rst: Simple improvements

The improvements include:

* Capitals in headlines.
* Add commas: for easier reading, it is always desired to add commas at some places in text. Like before adverbs or after fronted sentences.
* 3rd person -> add 's' to verbs.
* End some sentences with period and start a new one. Avoid thus heavy sentences.

[ tglx: Fix up subject prefix ]

---
 Documentation/core-api/irq/irq-domain.rst | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)
Documentation/core-api/irq/irq-domain.rst +11 -11
index c365c3e..cb25649 100644
@@ -1,19 +1,19 @@
 ===============================================
-The irq_domain interrupt number mapping library
+The irq_domain Interrupt Number Mapping Library
 ===============================================
 
 The current design of the Linux kernel uses a single large number
 space where each separate IRQ source is assigned a different number.
 This is simple when there is only one interrupt controller, but in
-systems with multiple interrupt controllers the kernel must ensure
+systems with multiple interrupt controllers, the kernel must ensure
 that each one gets assigned non-overlapping allocations of Linux
 IRQ numbers.
 
 The number of interrupt controllers registered as unique irqchips
-show a rising tendency: for example subdrivers of different kinds
+shows a rising tendency. For example, subdrivers of different kinds
 such as GPIO controllers avoid reimplementing identical callback
 mechanisms as the IRQ core system by modelling their interrupt
-handlers as irqchips, i.e. in effect cascading interrupt controllers.
+handlers as irqchips. I.e. in effect cascading interrupt controllers.
 
 Here the interrupt number loose all kind of correspondence to
 hardware interrupt numbers: whereas in the past, IRQ numbers could
@@ -21,15 +21,15 @@ be chosen so they matched the hardware IRQ line into the root
 interrupt controller (i.e. the component actually fireing the
 interrupt line to the CPU) nowadays this number is just a number.
 
-For this reason we need a mechanism to separate controller-local
-interrupt numbers, called hardware irq's, from Linux IRQ numbers.
+For this reason, we need a mechanism to separate controller-local
+interrupt numbers, called hardware IRQs, from Linux IRQ numbers.
 
 The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of
 irq numbers, but they don't provide any support for reverse mapping of
 the controller-local IRQ (hwirq) number into the Linux IRQ number
 space.
 
-The irq_domain library adds mapping between hwirq and IRQ numbers on
+The irq_domain library adds a mapping between hwirq and IRQ numbers on
 top of the irq_alloc_desc*() API.  An irq_domain to manage mapping is
 preferred over interrupt controller drivers open coding their own
 reverse mapping scheme.
@@ -38,7 +38,7 @@ irq_domain also implements translation from an abstract irq_fwspec
 structure to hwirq numbers (Device Tree and ACPI GSI so far), and can
 be easily extended to support other IRQ topology data sources.
 
-irq_domain usage
+irq_domain Usage
 ================
 
 An interrupt controller driver creates and registers an irq_domain by
@@ -76,7 +76,7 @@ If the driver has the Linux IRQ number or the irq_data pointer, and
 needs to know the associated hwirq number (such as in the irq_chip
 callbacks) then it can be directly obtained from irq_data->hwirq.
 
-Types of irq_domain mappings
+Types of irq_domain Mappings
 ============================
 
 There are several mechanisms available for reverse mapping from hwirq
@@ -101,7 +101,7 @@ map are fixed time lookup for IRQ numbers, and irq_descs are only
 allocated for in-use IRQs.  The disadvantage is that the table must be
 as large as the largest possible hwirq number.
 
-The majority of drivers should use the linear map.
+The majority of drivers should use the Linear map.
 
 Tree
 ----
@@ -189,7 +189,7 @@ that the driver using the simple domain call irq_create_mapping()
 before any irq_find_mapping() since the latter will actually work
 for the static IRQ assignment case.
 
-Hierarchy IRQ domain
+Hierarchy IRQ Domain
 --------------------
 
 On some architectures, there may be multiple interrupt controllers
#255 lore raw

PATCH v2 56/57 docs: irqdomain: Update

In reply to Jiri Slaby (SUSE)

The irqdomain documentaion became obsolete over time. Update and extend it a bit with respect to the current code and HW.

Most notably the doubled documentation of irq_domain (from .rst and .h) was unified and let only in .rst. A reference link was added to .h.

Furthermore:
* Some 'struct' keywords added, so that the respective structs are hyperlinked.
* :c:member: used where appropriate to mark a member of a struct.
* Some wording rephrased to improve readability/understanding.

---
 Documentation/core-api/irq/irq-domain.rst | 122 +++++++++++++---------
 include/linux/irqdomain.h                 |  26 +----
 2 files changed, 76 insertions(+), 72 deletions(-)
Documentation/core-api/irq/irq-domain.rst +74 -48
index c2f2728b1a35..7a418b3135de 100644
@@ -3,8 +3,8 @@ The irq_domain Interrupt Number Mapping Library
 ===============================================
 
 The current design of the Linux kernel uses a single large number
-space where each separate IRQ source is assigned a different number.
-This is simple when there is only one interrupt controller, but in
+space where each separate IRQ source is assigned a unique number.
+This is simple when there is only one interrupt controller. But in
 systems with multiple interrupt controllers, the kernel must ensure
 that each one gets assigned non-overlapping allocations of Linux
 IRQ numbers.
@@ -15,45 +15,64 @@ such as GPIO controllers avoid reimplementing identical callback
 mechanisms as the IRQ core system by modelling their interrupt
 handlers as irqchips. I.e. in effect cascading interrupt controllers.
 
-Here the interrupt number loose all kind of correspondence to
-hardware interrupt numbers: whereas in the past, IRQ numbers could
-be chosen so they matched the hardware IRQ line into the root
-interrupt controller (i.e. the component actually fireing the
-interrupt line to the CPU) nowadays this number is just a number.
+So in the past, IRQ numbers could be chosen so that they match the
+hardware IRQ line into the root interrupt controller (i.e. the
+component actually firing the interrupt line to the CPU). Nowadays,
+this number is just a number and the number loose all kind of
+correspondence to hardware interrupt numbers.
 
 For this reason, we need a mechanism to separate controller-local
 interrupt numbers, called hardware IRQs, from Linux IRQ numbers.
 
 The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of
-irq numbers, but they don't provide any support for reverse mapping of
+IRQ numbers, but they don't provide any support for reverse mapping of
 the controller-local IRQ (hwirq) number into the Linux IRQ number
 space.
 
 The irq_domain library adds a mapping between hwirq and IRQ numbers on
-top of the irq_alloc_desc*() API.  An irq_domain to manage mapping is
-preferred over interrupt controller drivers open coding their own
+top of the irq_alloc_desc*() API. An irq_domain to manage the mapping
+is preferred over interrupt controller drivers open coding their own
 reverse mapping scheme.
 
-irq_domain also implements translation from an abstract irq_fwspec
-structure to hwirq numbers (Device Tree and ACPI GSI so far), and can
-be easily extended to support other IRQ topology data sources.
+irq_domain also implements a translation from an abstract struct
+irq_fwspec to hwirq numbers (Device Tree, non-DT firmware node, ACPI
+GSI, and software node so far), and can be easily extended to support
+other IRQ topology data sources. The implementation is performed
+without any extra platform support code.
 
 irq_domain Usage
 ================
 
-An interrupt controller driver creates and registers an irq_domain by
-calling one of the irq_domain_add_*() or irq_domain_create_*() functions
-(each mapping method has a different allocator function, more on that later).
-The function will return a pointer to the irq_domain on success. The caller
-must provide the allocator function with an irq_domain_ops structure.
+struct irq_domain could be defined as an irq domain controller. That
+is, it handles the mapping between hardware and virtual interrupt
+numbers for a given interrupt domain. The domain structure is
+generally created by the PIC code for a given PIC instance (though a
+domain can cover more than one PIC if they have a flat number model).
+It is the domain callbacks that are responsible for setting the
+irq_chip on a given irq_desc after it has been mapped.
+
+The host code and data structures use a fwnode_handle pointer to
+identify the domain. In some cases, and in order to preserve source
+code compatibility, this fwnode pointer is "upgraded" to a DT
+device_node. For those firmware infrastructures that do not provide a
+unique identifier for an interrupt controller, the irq_domain code
+offers a fwnode allocator.
+
+An interrupt controller driver creates and registers a struct irq_domain
+by calling one of the irq_domain_create_*() functions (each mapping
+method has a different allocator function, more on that later). The
+function will return a pointer to the struct irq_domain on success. The
+caller must provide the allocator function with a struct irq_domain_ops
+pointer.
 
 In most cases, the irq_domain will begin empty without any mappings
 between hwirq and IRQ numbers.  Mappings are added to the irq_domain
 by calling irq_create_mapping() which accepts the irq_domain and a
-hwirq number as arguments.  If a mapping for the hwirq doesn't already
-exist then it will allocate a new Linux irq_desc, associate it with
-the hwirq, and call the .map() callback so the driver can perform any
-required hardware setup.
+hwirq number as arguments. If a mapping for the hwirq doesn't already
+exist, irq_create_mapping() allocates a new Linux irq_desc, associates
+it with the hwirq, and calls the :c:member:`irq_domain_ops.map()`
+callback. In there, the driver can perform any required hardware
+setup.
 
 Once a mapping has been established, it can be retrieved or used via a
 variety of methods:
@@ -75,7 +94,8 @@ be allocated.
 
 If the driver has the Linux IRQ number or the irq_data pointer, and
 needs to know the associated hwirq number (such as in the irq_chip
-callbacks) then it can be directly obtained from irq_data->hwirq.
+callbacks) then it can be directly obtained from
+:c:member:`irq_data.hwirq`.
 
 Types of irq_domain Mappings
 ============================
@@ -231,20 +251,40 @@ There are four major interfaces to use hierarchy irq_domain:
 4) irq_domain_deactivate_irq(): deactivate interrupt controller hardware
    to stop delivering the interrupt.
 
-Following changes are needed to support hierarchy irq_domain:
+The following is needed to support hierarchy irq_domain:
 
-1) a new field 'parent' is added to struct irq_domain; it's used to
+1) The :c:member:`parent` field in struct irq_domain is used to
    maintain irq_domain hierarchy information.
-2) a new field 'parent_data' is added to struct irq_data; it's used to
-   build hierarchy irq_data to match hierarchy irq_domains. The irq_data
-   is used to store irq_domain pointer and hardware irq number.
-3) new callbacks are added to struct irq_domain_ops to support hierarchy
-   irq_domain operations.
-
-With support of hierarchy irq_domain and hierarchy irq_data ready, an
-irq_domain structure is built for each interrupt controller, and an
+2) The :c:member:`parent_data` field in struct irq_data is used to
+   build hierarchy irq_data to match hierarchy irq_domains. The
+   irq_data is used to store irq_domain pointer and hardware irq
+   number.
+3) The :c:member:`alloc()`, :c:member:`free()`, and other callbacks in
+   struct irq_domain_ops to support hierarchy irq_domain operations.
+
+With the support of hierarchy irq_domain and hierarchy irq_data ready,
+an irq_domain structure is built for each interrupt controller, and an
 irq_data structure is allocated for each irq_domain associated with an
-IRQ. Now we could go one step further to support stacked(hierarchy)
+IRQ.
+
+For an interrupt controller driver to support hierarchy irq_domain, it
+needs to:
+
+1) Implement irq_domain_ops.alloc() and irq_domain_ops.free()
+2) Optionally, implement irq_domain_ops.activate() and
+   irq_domain_ops.deactivate().
+3) Optionally, implement an irq_chip to manage the interrupt controller
+   hardware.
+4) There is no need to implement irq_domain_ops.map() and
+   irq_domain_ops.unmap(). They are unused with hierarchy irq_domain.
+
+Note the hierarchy irq_domain is in no way x86-specific, and is
+heavily used to support other architectures, such as ARM, ARM64 etc.
+
+Stacked irq_chip
+~~~~~~~~~~~~~~~~
+
+Now, we could go one step further to support stacked (hierarchy)
 irq_chip. That is, an irq_chip is associated with each irq_data along
 the hierarchy. A child irq_chip may implement a required action by
 itself or by cooperating with its parent irq_chip.
@@ -254,20 +294,6 @@ with the hardware managed by itself and may ask for services from its
 parent irq_chip when needed. So we could achieve a much cleaner
 software architecture.
 
-For an interrupt controller driver to support hierarchy irq_domain, it
-needs to:
-
-1) Implement irq_domain_ops.alloc and irq_domain_ops.free
-2) Optionally implement irq_domain_ops.activate and
-   irq_domain_ops.deactivate.
-3) Optionally implement an irq_chip to manage the interrupt controller
-   hardware.
-4) No need to implement irq_domain_ops.map and irq_domain_ops.unmap,
-   they are unused with hierarchy irq_domain.
-
-Hierarchy irq_domain is in no way x86 specific, and is heavily used to
-support other architectures, such as ARM, ARM64 etc.
-
 Debugging
 =========
 
include/linux/irqdomain.h +2 -24
index 3e7103645c63..b8bb37cfcee2 100644
@@ -1,30 +1,8 @@
 /* SPDX-License-Identifier: GPL-2.0 */
 /*
- * irq_domain - IRQ translation domains
+ * irq_domain - IRQ Translation Domains
  *
- * Translation infrastructure between hw and linux irq numbers.  This is
- * helpful for interrupt controllers to implement mapping between hardware
- * irq numbers and the Linux irq number space.
- *
- * irq_domains also have hooks for translating device tree or other
- * firmware interrupt representations into a hardware irq number that
- * can be mapped back to a Linux irq number without any extra platform
- * support code.
- *
- * Interrupt controller "domain" data structure. This could be defined as a
- * irq domain controller. That is, it handles the mapping between hardware
- * and virtual interrupt numbers for a given interrupt domain. The domain
- * structure is generally created by the PIC code for a given PIC instance
- * (though a domain can cover more than one PIC if they have a flat number
- * model). It's the domain callbacks that are responsible for setting the
- * irq_chip on a given irq_desc after it's been mapped.
- *
- * The host code and data structures use a fwnode_handle pointer to
- * identify the domain. In some cases, and in order to preserve source
- * code compatibility, this fwnode pointer is "upgraded" to a DT
- * device_node. For those firmware infrastructures that do not provide
- * a unique identifier for an interrupt controller, the irq_domain
- * code offers a fwnode allocator.
+ * See Documentation/core-api/irq/irq-domain.rst for the details.
  */
 
 #ifndef _LINUX_IRQDOMAIN_H
Signature · 1 line
2.49.0
reviewer
#256 lore raw

Re: [PATCH v2 56/57] docs: irqdomain: Update

Quoted 39 lines · Jiri Slaby (SUSE)

The irqdomain documentaion became obsolete over time. Update and extend it a bit with respect to the current code and HW.

Most notably the doubled documentation of irq_domain (from .rst and .h) was unified and let only in .rst. A reference link was added to .h.

Furthermore:
* Some 'struct' keywords added, so that the respective structs are hyperlinked.
* :c:member: used where appropriate to mark a member of a struct.
* Some wording rephrased to improve readability/understanding.

---
 Documentation/core-api/irq/irq-domain.rst | 122 +++++++++++++---------
 include/linux/irqdomain.h                 |  26 +----
 2 files changed, 76 insertions(+), 72 deletions(-)
Documentation/core-api/irq/irq-domain.rst +2 -2
index c2f2728b1a35..7a418b3135de 100644
@@ -3,8 +3,8 @@ The irq_domain Interrupt Number Mapping Library
 ===============================================
 
 The current design of the Linux kernel uses a single large number
-space where each separate IRQ source is assigned a different number.
-This is simple when there is only one interrupt controller, but in
+space where each separate IRQ source is assigned a unique number.
+This is simple when there is only one interrupt controller. But in
 systems with multiple interrupt controllers, the kernel must ensure
 that each one gets assigned non-overlapping allocations of Linux
 IRQ numbers.
@@ -15,45 +15,64 @@ such as GPIO controllers avoid reimplementing identical callback
 mechanisms as the IRQ core system by modelling their interrupt
 handlers as irqchips. I.e. in effect cascading interrupt controllers.

Documentation/core-api/irq/irq-domain.rst such as GPIO controllers avoid reimplementing identical callback · line 21

Quoted 10 lines
Documentation/core-api/irq/irq-domain.rst +4 -5
 
-Here the interrupt number loose all kind of correspondence to
-hardware interrupt numbers: whereas in the past, IRQ numbers could
-be chosen so they matched the hardware IRQ line into the root
-interrupt controller (i.e. the component actually fireing the
-interrupt line to the CPU) nowadays this number is just a number.
+So in the past, IRQ numbers could be chosen so that they match the
+hardware IRQ line into the root interrupt controller (i.e. the
+component actually firing the interrupt line to the CPU). Nowadays,
+this number is just a number and the number loose all kind of

loses

Quoted 2 lines
Documentation/core-api/irq/irq-domain.rst +1 -0
+correspondence to hardware interrupt numbers.
 

[snip]

Signature · 1 line
~Randy
author
#257 lore raw

Re: [PATCH v2 56/57] docs: irqdomain: Update

Quoted 4 lines · Randy Dunlap
Quoted 4 lines
Documentation/core-api/irq/irq-domain.rst +0 -0
@@ -15,45 +15,64 @@ such as GPIO controllers avoid reimplementing identical callback
  mechanisms as the IRQ core system by modelling their interrupt
  handlers as irqchips. I.e. in effect cascading interrupt controllers.
 
Quoted 11 lines

Documentation/core-api/irq/irq-domain.rst such as GPIO controllers avoid reimplementing identical callback · line 21

Quoted 9 lines
Documentation/core-api/irq/irq-domain.rst +4 -5
-Here the interrupt number loose all kind of correspondence to
-hardware interrupt numbers: whereas in the past, IRQ numbers could
-be chosen so they matched the hardware IRQ line into the root
-interrupt controller (i.e. the component actually fireing the
-interrupt line to the CPU) nowadays this number is just a number.
+So in the past, IRQ numbers could be chosen so that they match the
+hardware IRQ line into the root interrupt controller (i.e. the
+component actually firing the interrupt line to the CPU). Nowadays,
+this number is just a number and the number loose all kind of

loses

Thanks, fixed in 55/57 where I explicitly do "3rd person -> add 's' to verbs.". Even though this was "loose" and not "lose" ;).

Signature · 2 lines
js
suse labs
#258 lore raw

[tip: irq/cleanups] Documentation: irqdomain: Update it

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     1213b222c7b62d6aa775f945ae7a825b174a3133
Gitweb:        https://git.kernel.org/tip/1213b222c7b62d6aa775f945ae7a825b174a3133
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:49 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Tue, 06 May 2025 14:59:09 +02:00

Documentation: irqdomain: Update it

The irqdomain documentaion became obsolete over time. Update and extend it a bit with respect to the current code and HW.

Most notably the doubled documentation of irq_domain (from .rst and .h) was unified and let only in .rst. A reference link was added to .h.

Furthermore:
* Add some 'struct' keywords, so that the respective structs are hyperlinked
* :c:member: use where appropriate to mark a member of a struct
* Rephrase some wording to improve readability/understanding

---
 Documentation/core-api/irq/irq-domain.rst | 122 ++++++++++++---------
 include/linux/irqdomain.h                 |  26 +----
 2 files changed, 76 insertions(+), 72 deletions(-)
Documentation/core-api/irq/irq-domain.rst +74 -48
index cb25649..67d45b3 100644
@@ -3,8 +3,8 @@ The irq_domain Interrupt Number Mapping Library
 ===============================================
 
 The current design of the Linux kernel uses a single large number
-space where each separate IRQ source is assigned a different number.
-This is simple when there is only one interrupt controller, but in
+space where each separate IRQ source is assigned a unique number.
+This is simple when there is only one interrupt controller. But in
 systems with multiple interrupt controllers, the kernel must ensure
 that each one gets assigned non-overlapping allocations of Linux
 IRQ numbers.
@@ -15,44 +15,63 @@ such as GPIO controllers avoid reimplementing identical callback
 mechanisms as the IRQ core system by modelling their interrupt
 handlers as irqchips. I.e. in effect cascading interrupt controllers.
 
-Here the interrupt number loose all kind of correspondence to
-hardware interrupt numbers: whereas in the past, IRQ numbers could
-be chosen so they matched the hardware IRQ line into the root
-interrupt controller (i.e. the component actually fireing the
-interrupt line to the CPU) nowadays this number is just a number.
+So in the past, IRQ numbers could be chosen so that they match the
+hardware IRQ line into the root interrupt controller (i.e. the
+component actually firing the interrupt line to the CPU). Nowadays,
+this number is just a number and the number loose all kind of
+correspondence to hardware interrupt numbers.
 
 For this reason, we need a mechanism to separate controller-local
 interrupt numbers, called hardware IRQs, from Linux IRQ numbers.
 
 The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of
-irq numbers, but they don't provide any support for reverse mapping of
+IRQ numbers, but they don't provide any support for reverse mapping of
 the controller-local IRQ (hwirq) number into the Linux IRQ number
 space.
 
 The irq_domain library adds a mapping between hwirq and IRQ numbers on
-top of the irq_alloc_desc*() API.  An irq_domain to manage mapping is
-preferred over interrupt controller drivers open coding their own
+top of the irq_alloc_desc*() API. An irq_domain to manage the mapping
+is preferred over interrupt controller drivers open coding their own
 reverse mapping scheme.
 
-irq_domain also implements translation from an abstract irq_fwspec
-structure to hwirq numbers (Device Tree and ACPI GSI so far), and can
-be easily extended to support other IRQ topology data sources.
+irq_domain also implements a translation from an abstract struct
+irq_fwspec to hwirq numbers (Device Tree, non-DT firmware node, ACPI
+GSI, and software node so far), and can be easily extended to support
+other IRQ topology data sources. The implementation is performed
+without any extra platform support code.
 
 irq_domain Usage
 ================
-
-An interrupt controller driver creates and registers an irq_domain by
-calling one of the irq_domain_create_*() functions.  The function will
-return a pointer to the irq_domain on success. The caller must provide the
-allocator function with an irq_domain_ops structure.
+struct irq_domain could be defined as an irq domain controller. That
+is, it handles the mapping between hardware and virtual interrupt
+numbers for a given interrupt domain. The domain structure is
+generally created by the PIC code for a given PIC instance (though a
+domain can cover more than one PIC if they have a flat number model).
+It is the domain callbacks that are responsible for setting the
+irq_chip on a given irq_desc after it has been mapped.
+
+The host code and data structures use a fwnode_handle pointer to
+identify the domain. In some cases, and in order to preserve source
+code compatibility, this fwnode pointer is "upgraded" to a DT
+device_node. For those firmware infrastructures that do not provide a
+unique identifier for an interrupt controller, the irq_domain code
+offers a fwnode allocator.
+
+An interrupt controller driver creates and registers a struct irq_domain
+by calling one of the irq_domain_create_*() functions (each mapping
+method has a different allocator function, more on that later). The
+function will return a pointer to the struct irq_domain on success. The
+caller must provide the allocator function with a struct irq_domain_ops
+pointer.
 
 In most cases, the irq_domain will begin empty without any mappings
 between hwirq and IRQ numbers.  Mappings are added to the irq_domain
 by calling irq_create_mapping() which accepts the irq_domain and a
-hwirq number as arguments.  If a mapping for the hwirq doesn't already
-exist then it will allocate a new Linux irq_desc, associate it with
-the hwirq, and call the .map() callback so the driver can perform any
-required hardware setup.
+hwirq number as arguments. If a mapping for the hwirq doesn't already
+exist, irq_create_mapping() allocates a new Linux irq_desc, associates
+it with the hwirq, and calls the :c:member:`irq_domain_ops.map()`
+callback. In there, the driver can perform any required hardware
+setup.
 
 Once a mapping has been established, it can be retrieved or used via a
 variety of methods:
@@ -74,7 +93,8 @@ be allocated.
 
 If the driver has the Linux IRQ number or the irq_data pointer, and
 needs to know the associated hwirq number (such as in the irq_chip
-callbacks) then it can be directly obtained from irq_data->hwirq.
+callbacks) then it can be directly obtained from
+:c:member:`irq_data.hwirq`.
 
 Types of irq_domain Mappings
 ============================
@@ -230,20 +250,40 @@ There are four major interfaces to use hierarchy irq_domain:
 4) irq_domain_deactivate_irq(): deactivate interrupt controller hardware
    to stop delivering the interrupt.
 
-Following changes are needed to support hierarchy irq_domain:
+The following is needed to support hierarchy irq_domain:
 
-1) a new field 'parent' is added to struct irq_domain; it's used to
+1) The :c:member:`parent` field in struct irq_domain is used to
    maintain irq_domain hierarchy information.
-2) a new field 'parent_data' is added to struct irq_data; it's used to
-   build hierarchy irq_data to match hierarchy irq_domains. The irq_data
-   is used to store irq_domain pointer and hardware irq number.
-3) new callbacks are added to struct irq_domain_ops to support hierarchy
-   irq_domain operations.
-
-With support of hierarchy irq_domain and hierarchy irq_data ready, an
-irq_domain structure is built for each interrupt controller, and an
+2) The :c:member:`parent_data` field in struct irq_data is used to
+   build hierarchy irq_data to match hierarchy irq_domains. The
+   irq_data is used to store irq_domain pointer and hardware irq
+   number.
+3) The :c:member:`alloc()`, :c:member:`free()`, and other callbacks in
+   struct irq_domain_ops to support hierarchy irq_domain operations.
+
+With the support of hierarchy irq_domain and hierarchy irq_data ready,
+an irq_domain structure is built for each interrupt controller, and an
 irq_data structure is allocated for each irq_domain associated with an
-IRQ. Now we could go one step further to support stacked(hierarchy)
+IRQ.
+
+For an interrupt controller driver to support hierarchy irq_domain, it
+needs to:
+
+1) Implement irq_domain_ops.alloc() and irq_domain_ops.free()
+2) Optionally, implement irq_domain_ops.activate() and
+   irq_domain_ops.deactivate().
+3) Optionally, implement an irq_chip to manage the interrupt controller
+   hardware.
+4) There is no need to implement irq_domain_ops.map() and
+   irq_domain_ops.unmap(). They are unused with hierarchy irq_domain.
+
+Note the hierarchy irq_domain is in no way x86-specific, and is
+heavily used to support other architectures, such as ARM, ARM64 etc.
+
+Stacked irq_chip
+~~~~~~~~~~~~~~~~
+
+Now, we could go one step further to support stacked (hierarchy)
 irq_chip. That is, an irq_chip is associated with each irq_data along
 the hierarchy. A child irq_chip may implement a required action by
 itself or by cooperating with its parent irq_chip.
@@ -253,20 +293,6 @@ with the hardware managed by itself and may ask for services from its
 parent irq_chip when needed. So we could achieve a much cleaner
 software architecture.
 
-For an interrupt controller driver to support hierarchy irq_domain, it
-needs to:
-
-1) Implement irq_domain_ops.alloc and irq_domain_ops.free
-2) Optionally implement irq_domain_ops.activate and
-   irq_domain_ops.deactivate.
-3) Optionally implement an irq_chip to manage the interrupt controller
-   hardware.
-4) No need to implement irq_domain_ops.map and irq_domain_ops.unmap,
-   they are unused with hierarchy irq_domain.
-
-Hierarchy irq_domain is in no way x86 specific, and is heavily used to
-support other architectures, such as ARM, ARM64 etc.
-
 Debugging
 =========
 
include/linux/irqdomain.h +2 -24
index a70e2ba..1a1786d 100644
@@ -1,30 +1,8 @@
 /* SPDX-License-Identifier: GPL-2.0 */
 /*
- * irq_domain - IRQ translation domains
+ * irq_domain - IRQ Translation Domains
  *
- * Translation infrastructure between hw and linux irq numbers.  This is
- * helpful for interrupt controllers to implement mapping between hardware
- * irq numbers and the Linux irq number space.
- *
- * irq_domains also have hooks for translating device tree or other
- * firmware interrupt representations into a hardware irq number that
- * can be mapped back to a Linux irq number without any extra platform
- * support code.
- *
- * Interrupt controller "domain" data structure. This could be defined as a
- * irq domain controller. That is, it handles the mapping between hardware
- * and virtual interrupt numbers for a given interrupt domain. The domain
- * structure is generally created by the PIC code for a given PIC instance
- * (though a domain can cover more than one PIC if they have a flat number
- * model). It's the domain callbacks that are responsible for setting the
- * irq_chip on a given irq_desc after it's been mapped.
- *
- * The host code and data structures use a fwnode_handle pointer to
- * identify the domain. In some cases, and in order to preserve source
- * code compatibility, this fwnode pointer is "upgraded" to a DT
- * device_node. For those firmware infrastructures that do not provide
- * a unique identifier for an interrupt controller, the irq_domain
- * code offers a fwnode allocator.
+ * See Documentation/core-api/irq/irq-domain.rst for the details.
  */
 
 #ifndef _LINUX_IRQDOMAIN_H
#259 lore raw

[tip: irq/cleanups] Documentation: irqdomain: Update it

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     6b94eb3e855390d90bd7a1bb02ecc47b38cbd0a5
Gitweb:        https://git.kernel.org/tip/6b94eb3e855390d90bd7a1bb02ecc47b38cbd0a5
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:49 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 09:53:25 +02:00

Documentation: irqdomain: Update it

The irqdomain documentaion became obsolete over time. Update and extend it a bit with respect to the current code and HW.

Most notably the doubled documentation of irq_domain (from .rst and .h) was unified and let only in .rst. A reference link was added to .h.

Furthermore:
* Add some 'struct' keywords, so that the respective structs are hyperlinked
* :c:member: use where appropriate to mark a member of a struct
* Rephrase some wording to improve readability/understanding

---
 Documentation/core-api/irq/irq-domain.rst | 122 ++++++++++++---------
 include/linux/irqdomain.h                 |  26 +----
 2 files changed, 76 insertions(+), 72 deletions(-)
Documentation/core-api/irq/irq-domain.rst +74 -48
index cb25649..67d45b3 100644
@@ -3,8 +3,8 @@ The irq_domain Interrupt Number Mapping Library
 ===============================================
 
 The current design of the Linux kernel uses a single large number
-space where each separate IRQ source is assigned a different number.
-This is simple when there is only one interrupt controller, but in
+space where each separate IRQ source is assigned a unique number.
+This is simple when there is only one interrupt controller. But in
 systems with multiple interrupt controllers, the kernel must ensure
 that each one gets assigned non-overlapping allocations of Linux
 IRQ numbers.
@@ -15,44 +15,63 @@ such as GPIO controllers avoid reimplementing identical callback
 mechanisms as the IRQ core system by modelling their interrupt
 handlers as irqchips. I.e. in effect cascading interrupt controllers.
 
-Here the interrupt number loose all kind of correspondence to
-hardware interrupt numbers: whereas in the past, IRQ numbers could
-be chosen so they matched the hardware IRQ line into the root
-interrupt controller (i.e. the component actually fireing the
-interrupt line to the CPU) nowadays this number is just a number.
+So in the past, IRQ numbers could be chosen so that they match the
+hardware IRQ line into the root interrupt controller (i.e. the
+component actually firing the interrupt line to the CPU). Nowadays,
+this number is just a number and the number loose all kind of
+correspondence to hardware interrupt numbers.
 
 For this reason, we need a mechanism to separate controller-local
 interrupt numbers, called hardware IRQs, from Linux IRQ numbers.
 
 The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of
-irq numbers, but they don't provide any support for reverse mapping of
+IRQ numbers, but they don't provide any support for reverse mapping of
 the controller-local IRQ (hwirq) number into the Linux IRQ number
 space.
 
 The irq_domain library adds a mapping between hwirq and IRQ numbers on
-top of the irq_alloc_desc*() API.  An irq_domain to manage mapping is
-preferred over interrupt controller drivers open coding their own
+top of the irq_alloc_desc*() API. An irq_domain to manage the mapping
+is preferred over interrupt controller drivers open coding their own
 reverse mapping scheme.
 
-irq_domain also implements translation from an abstract irq_fwspec
-structure to hwirq numbers (Device Tree and ACPI GSI so far), and can
-be easily extended to support other IRQ topology data sources.
+irq_domain also implements a translation from an abstract struct
+irq_fwspec to hwirq numbers (Device Tree, non-DT firmware node, ACPI
+GSI, and software node so far), and can be easily extended to support
+other IRQ topology data sources. The implementation is performed
+without any extra platform support code.
 
 irq_domain Usage
 ================
-
-An interrupt controller driver creates and registers an irq_domain by
-calling one of the irq_domain_create_*() functions.  The function will
-return a pointer to the irq_domain on success. The caller must provide the
-allocator function with an irq_domain_ops structure.
+struct irq_domain could be defined as an irq domain controller. That
+is, it handles the mapping between hardware and virtual interrupt
+numbers for a given interrupt domain. The domain structure is
+generally created by the PIC code for a given PIC instance (though a
+domain can cover more than one PIC if they have a flat number model).
+It is the domain callbacks that are responsible for setting the
+irq_chip on a given irq_desc after it has been mapped.
+
+The host code and data structures use a fwnode_handle pointer to
+identify the domain. In some cases, and in order to preserve source
+code compatibility, this fwnode pointer is "upgraded" to a DT
+device_node. For those firmware infrastructures that do not provide a
+unique identifier for an interrupt controller, the irq_domain code
+offers a fwnode allocator.
+
+An interrupt controller driver creates and registers a struct irq_domain
+by calling one of the irq_domain_create_*() functions (each mapping
+method has a different allocator function, more on that later). The
+function will return a pointer to the struct irq_domain on success. The
+caller must provide the allocator function with a struct irq_domain_ops
+pointer.
 
 In most cases, the irq_domain will begin empty without any mappings
 between hwirq and IRQ numbers.  Mappings are added to the irq_domain
 by calling irq_create_mapping() which accepts the irq_domain and a
-hwirq number as arguments.  If a mapping for the hwirq doesn't already
-exist then it will allocate a new Linux irq_desc, associate it with
-the hwirq, and call the .map() callback so the driver can perform any
-required hardware setup.
+hwirq number as arguments. If a mapping for the hwirq doesn't already
+exist, irq_create_mapping() allocates a new Linux irq_desc, associates
+it with the hwirq, and calls the :c:member:`irq_domain_ops.map()`
+callback. In there, the driver can perform any required hardware
+setup.
 
 Once a mapping has been established, it can be retrieved or used via a
 variety of methods:
@@ -74,7 +93,8 @@ be allocated.
 
 If the driver has the Linux IRQ number or the irq_data pointer, and
 needs to know the associated hwirq number (such as in the irq_chip
-callbacks) then it can be directly obtained from irq_data->hwirq.
+callbacks) then it can be directly obtained from
+:c:member:`irq_data.hwirq`.
 
 Types of irq_domain Mappings
 ============================
@@ -230,20 +250,40 @@ There are four major interfaces to use hierarchy irq_domain:
 4) irq_domain_deactivate_irq(): deactivate interrupt controller hardware
    to stop delivering the interrupt.
 
-Following changes are needed to support hierarchy irq_domain:
+The following is needed to support hierarchy irq_domain:
 
-1) a new field 'parent' is added to struct irq_domain; it's used to
+1) The :c:member:`parent` field in struct irq_domain is used to
    maintain irq_domain hierarchy information.
-2) a new field 'parent_data' is added to struct irq_data; it's used to
-   build hierarchy irq_data to match hierarchy irq_domains. The irq_data
-   is used to store irq_domain pointer and hardware irq number.
-3) new callbacks are added to struct irq_domain_ops to support hierarchy
-   irq_domain operations.
-
-With support of hierarchy irq_domain and hierarchy irq_data ready, an
-irq_domain structure is built for each interrupt controller, and an
+2) The :c:member:`parent_data` field in struct irq_data is used to
+   build hierarchy irq_data to match hierarchy irq_domains. The
+   irq_data is used to store irq_domain pointer and hardware irq
+   number.
+3) The :c:member:`alloc()`, :c:member:`free()`, and other callbacks in
+   struct irq_domain_ops to support hierarchy irq_domain operations.
+
+With the support of hierarchy irq_domain and hierarchy irq_data ready,
+an irq_domain structure is built for each interrupt controller, and an
 irq_data structure is allocated for each irq_domain associated with an
-IRQ. Now we could go one step further to support stacked(hierarchy)
+IRQ.
+
+For an interrupt controller driver to support hierarchy irq_domain, it
+needs to:
+
+1) Implement irq_domain_ops.alloc() and irq_domain_ops.free()
+2) Optionally, implement irq_domain_ops.activate() and
+   irq_domain_ops.deactivate().
+3) Optionally, implement an irq_chip to manage the interrupt controller
+   hardware.
+4) There is no need to implement irq_domain_ops.map() and
+   irq_domain_ops.unmap(). They are unused with hierarchy irq_domain.
+
+Note the hierarchy irq_domain is in no way x86-specific, and is
+heavily used to support other architectures, such as ARM, ARM64 etc.
+
+Stacked irq_chip
+~~~~~~~~~~~~~~~~
+
+Now, we could go one step further to support stacked (hierarchy)
 irq_chip. That is, an irq_chip is associated with each irq_data along
 the hierarchy. A child irq_chip may implement a required action by
 itself or by cooperating with its parent irq_chip.
@@ -253,20 +293,6 @@ with the hardware managed by itself and may ask for services from its
 parent irq_chip when needed. So we could achieve a much cleaner
 software architecture.
 
-For an interrupt controller driver to support hierarchy irq_domain, it
-needs to:
-
-1) Implement irq_domain_ops.alloc and irq_domain_ops.free
-2) Optionally implement irq_domain_ops.activate and
-   irq_domain_ops.deactivate.
-3) Optionally implement an irq_chip to manage the interrupt controller
-   hardware.
-4) No need to implement irq_domain_ops.map and irq_domain_ops.unmap,
-   they are unused with hierarchy irq_domain.
-
-Hierarchy irq_domain is in no way x86 specific, and is heavily used to
-support other architectures, such as ARM, ARM64 etc.
-
 Debugging
 =========
 
include/linux/irqdomain.h +2 -24
index a70e2ba..1a1786d 100644
@@ -1,30 +1,8 @@
 /* SPDX-License-Identifier: GPL-2.0 */
 /*
- * irq_domain - IRQ translation domains
+ * irq_domain - IRQ Translation Domains
  *
- * Translation infrastructure between hw and linux irq numbers.  This is
- * helpful for interrupt controllers to implement mapping between hardware
- * irq numbers and the Linux irq number space.
- *
- * irq_domains also have hooks for translating device tree or other
- * firmware interrupt representations into a hardware irq number that
- * can be mapped back to a Linux irq number without any extra platform
- * support code.
- *
- * Interrupt controller "domain" data structure. This could be defined as a
- * irq domain controller. That is, it handles the mapping between hardware
- * and virtual interrupt numbers for a given interrupt domain. The domain
- * structure is generally created by the PIC code for a given PIC instance
- * (though a domain can cover more than one PIC if they have a flat number
- * model). It's the domain callbacks that are responsible for setting the
- * irq_chip on a given irq_desc after it's been mapped.
- *
- * The host code and data structures use a fwnode_handle pointer to
- * identify the domain. In some cases, and in order to preserve source
- * code compatibility, this fwnode pointer is "upgraded" to a DT
- * device_node. For those firmware infrastructures that do not provide
- * a unique identifier for an interrupt controller, the irq_domain
- * code offers a fwnode allocator.
+ * See Documentation/core-api/irq/irq-domain.rst for the details.
  */
 
 #ifndef _LINUX_IRQDOMAIN_H
#260 lore raw

[tip: irq/cleanups] Documentation: irqdomain: Update it

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     6fd30ec3e6c4c7b038bb795d18cba59c260248ff
Gitweb:        https://git.kernel.org/tip/6fd30ec3e6c4c7b038bb795d18cba59c260248ff
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:49 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 15:39:43 +02:00

Documentation: irqdomain: Update it

The irqdomain documentaion became obsolete over time. Update and extend it a bit with respect to the current code and HW.

Most notably the doubled documentation of irq_domain (from .rst and .h) was unified and let only in .rst. A reference link was added to .h.

Furthermore:
* Add some 'struct' keywords, so that the respective structs are hyperlinked
* :c:member: use where appropriate to mark a member of a struct
* Rephrase some wording to improve readability/understanding

---
 Documentation/core-api/irq/irq-domain.rst | 122 ++++++++++++---------
 include/linux/irqdomain.h                 |  26 +----
 2 files changed, 76 insertions(+), 72 deletions(-)
Documentation/core-api/irq/irq-domain.rst +74 -48
index cb25649..67d45b3 100644
@@ -3,8 +3,8 @@ The irq_domain Interrupt Number Mapping Library
 ===============================================
 
 The current design of the Linux kernel uses a single large number
-space where each separate IRQ source is assigned a different number.
-This is simple when there is only one interrupt controller, but in
+space where each separate IRQ source is assigned a unique number.
+This is simple when there is only one interrupt controller. But in
 systems with multiple interrupt controllers, the kernel must ensure
 that each one gets assigned non-overlapping allocations of Linux
 IRQ numbers.
@@ -15,44 +15,63 @@ such as GPIO controllers avoid reimplementing identical callback
 mechanisms as the IRQ core system by modelling their interrupt
 handlers as irqchips. I.e. in effect cascading interrupt controllers.
 
-Here the interrupt number loose all kind of correspondence to
-hardware interrupt numbers: whereas in the past, IRQ numbers could
-be chosen so they matched the hardware IRQ line into the root
-interrupt controller (i.e. the component actually fireing the
-interrupt line to the CPU) nowadays this number is just a number.
+So in the past, IRQ numbers could be chosen so that they match the
+hardware IRQ line into the root interrupt controller (i.e. the
+component actually firing the interrupt line to the CPU). Nowadays,
+this number is just a number and the number loose all kind of
+correspondence to hardware interrupt numbers.
 
 For this reason, we need a mechanism to separate controller-local
 interrupt numbers, called hardware IRQs, from Linux IRQ numbers.
 
 The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of
-irq numbers, but they don't provide any support for reverse mapping of
+IRQ numbers, but they don't provide any support for reverse mapping of
 the controller-local IRQ (hwirq) number into the Linux IRQ number
 space.
 
 The irq_domain library adds a mapping between hwirq and IRQ numbers on
-top of the irq_alloc_desc*() API.  An irq_domain to manage mapping is
-preferred over interrupt controller drivers open coding their own
+top of the irq_alloc_desc*() API. An irq_domain to manage the mapping
+is preferred over interrupt controller drivers open coding their own
 reverse mapping scheme.
 
-irq_domain also implements translation from an abstract irq_fwspec
-structure to hwirq numbers (Device Tree and ACPI GSI so far), and can
-be easily extended to support other IRQ topology data sources.
+irq_domain also implements a translation from an abstract struct
+irq_fwspec to hwirq numbers (Device Tree, non-DT firmware node, ACPI
+GSI, and software node so far), and can be easily extended to support
+other IRQ topology data sources. The implementation is performed
+without any extra platform support code.
 
 irq_domain Usage
 ================
-
-An interrupt controller driver creates and registers an irq_domain by
-calling one of the irq_domain_create_*() functions.  The function will
-return a pointer to the irq_domain on success. The caller must provide the
-allocator function with an irq_domain_ops structure.
+struct irq_domain could be defined as an irq domain controller. That
+is, it handles the mapping between hardware and virtual interrupt
+numbers for a given interrupt domain. The domain structure is
+generally created by the PIC code for a given PIC instance (though a
+domain can cover more than one PIC if they have a flat number model).
+It is the domain callbacks that are responsible for setting the
+irq_chip on a given irq_desc after it has been mapped.
+
+The host code and data structures use a fwnode_handle pointer to
+identify the domain. In some cases, and in order to preserve source
+code compatibility, this fwnode pointer is "upgraded" to a DT
+device_node. For those firmware infrastructures that do not provide a
+unique identifier for an interrupt controller, the irq_domain code
+offers a fwnode allocator.
+
+An interrupt controller driver creates and registers a struct irq_domain
+by calling one of the irq_domain_create_*() functions (each mapping
+method has a different allocator function, more on that later). The
+function will return a pointer to the struct irq_domain on success. The
+caller must provide the allocator function with a struct irq_domain_ops
+pointer.
 
 In most cases, the irq_domain will begin empty without any mappings
 between hwirq and IRQ numbers.  Mappings are added to the irq_domain
 by calling irq_create_mapping() which accepts the irq_domain and a
-hwirq number as arguments.  If a mapping for the hwirq doesn't already
-exist then it will allocate a new Linux irq_desc, associate it with
-the hwirq, and call the .map() callback so the driver can perform any
-required hardware setup.
+hwirq number as arguments. If a mapping for the hwirq doesn't already
+exist, irq_create_mapping() allocates a new Linux irq_desc, associates
+it with the hwirq, and calls the :c:member:`irq_domain_ops.map()`
+callback. In there, the driver can perform any required hardware
+setup.
 
 Once a mapping has been established, it can be retrieved or used via a
 variety of methods:
@@ -74,7 +93,8 @@ be allocated.
 
 If the driver has the Linux IRQ number or the irq_data pointer, and
 needs to know the associated hwirq number (such as in the irq_chip
-callbacks) then it can be directly obtained from irq_data->hwirq.
+callbacks) then it can be directly obtained from
+:c:member:`irq_data.hwirq`.
 
 Types of irq_domain Mappings
 ============================
@@ -230,20 +250,40 @@ There are four major interfaces to use hierarchy irq_domain:
 4) irq_domain_deactivate_irq(): deactivate interrupt controller hardware
    to stop delivering the interrupt.
 
-Following changes are needed to support hierarchy irq_domain:
+The following is needed to support hierarchy irq_domain:
 
-1) a new field 'parent' is added to struct irq_domain; it's used to
+1) The :c:member:`parent` field in struct irq_domain is used to
    maintain irq_domain hierarchy information.
-2) a new field 'parent_data' is added to struct irq_data; it's used to
-   build hierarchy irq_data to match hierarchy irq_domains. The irq_data
-   is used to store irq_domain pointer and hardware irq number.
-3) new callbacks are added to struct irq_domain_ops to support hierarchy
-   irq_domain operations.
-
-With support of hierarchy irq_domain and hierarchy irq_data ready, an
-irq_domain structure is built for each interrupt controller, and an
+2) The :c:member:`parent_data` field in struct irq_data is used to
+   build hierarchy irq_data to match hierarchy irq_domains. The
+   irq_data is used to store irq_domain pointer and hardware irq
+   number.
+3) The :c:member:`alloc()`, :c:member:`free()`, and other callbacks in
+   struct irq_domain_ops to support hierarchy irq_domain operations.
+
+With the support of hierarchy irq_domain and hierarchy irq_data ready,
+an irq_domain structure is built for each interrupt controller, and an
 irq_data structure is allocated for each irq_domain associated with an
-IRQ. Now we could go one step further to support stacked(hierarchy)
+IRQ.
+
+For an interrupt controller driver to support hierarchy irq_domain, it
+needs to:
+
+1) Implement irq_domain_ops.alloc() and irq_domain_ops.free()
+2) Optionally, implement irq_domain_ops.activate() and
+   irq_domain_ops.deactivate().
+3) Optionally, implement an irq_chip to manage the interrupt controller
+   hardware.
+4) There is no need to implement irq_domain_ops.map() and
+   irq_domain_ops.unmap(). They are unused with hierarchy irq_domain.
+
+Note the hierarchy irq_domain is in no way x86-specific, and is
+heavily used to support other architectures, such as ARM, ARM64 etc.
+
+Stacked irq_chip
+~~~~~~~~~~~~~~~~
+
+Now, we could go one step further to support stacked (hierarchy)
 irq_chip. That is, an irq_chip is associated with each irq_data along
 the hierarchy. A child irq_chip may implement a required action by
 itself or by cooperating with its parent irq_chip.
@@ -253,20 +293,6 @@ with the hardware managed by itself and may ask for services from its
 parent irq_chip when needed. So we could achieve a much cleaner
 software architecture.
 
-For an interrupt controller driver to support hierarchy irq_domain, it
-needs to:
-
-1) Implement irq_domain_ops.alloc and irq_domain_ops.free
-2) Optionally implement irq_domain_ops.activate and
-   irq_domain_ops.deactivate.
-3) Optionally implement an irq_chip to manage the interrupt controller
-   hardware.
-4) No need to implement irq_domain_ops.map and irq_domain_ops.unmap,
-   they are unused with hierarchy irq_domain.
-
-Hierarchy irq_domain is in no way x86 specific, and is heavily used to
-support other architectures, such as ARM, ARM64 etc.
-
 Debugging
 =========
 
include/linux/irqdomain.h +2 -24
index a70e2ba..1a1786d 100644
@@ -1,30 +1,8 @@
 /* SPDX-License-Identifier: GPL-2.0 */
 /*
- * irq_domain - IRQ translation domains
+ * irq_domain - IRQ Translation Domains
  *
- * Translation infrastructure between hw and linux irq numbers.  This is
- * helpful for interrupt controllers to implement mapping between hardware
- * irq numbers and the Linux irq number space.
- *
- * irq_domains also have hooks for translating device tree or other
- * firmware interrupt representations into a hardware irq number that
- * can be mapped back to a Linux irq number without any extra platform
- * support code.
- *
- * Interrupt controller "domain" data structure. This could be defined as a
- * irq domain controller. That is, it handles the mapping between hardware
- * and virtual interrupt numbers for a given interrupt domain. The domain
- * structure is generally created by the PIC code for a given PIC instance
- * (though a domain can cover more than one PIC if they have a flat number
- * model). It's the domain callbacks that are responsible for setting the
- * irq_chip on a given irq_desc after it's been mapped.
- *
- * The host code and data structures use a fwnode_handle pointer to
- * identify the domain. In some cases, and in order to preserve source
- * code compatibility, this fwnode pointer is "upgraded" to a DT
- * device_node. For those firmware infrastructures that do not provide
- * a unique identifier for an interrupt controller, the irq_domain
- * code offers a fwnode allocator.
+ * See Documentation/core-api/irq/irq-domain.rst for the details.
  */
 
 #ifndef _LINUX_IRQDOMAIN_H
#261 lore raw

[tip: irq/cleanups] Documentation: irqdomain: Update it

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     a4efe303e50e3222591ab6ec5eb0ea92b7260d96
Gitweb:        https://git.kernel.org/tip/a4efe303e50e3222591ab6ec5eb0ea92b7260d96
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:49 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Fri, 16 May 2025 21:06:13 +02:00

Documentation: irqdomain: Update it

The irqdomain documentaion became obsolete over time. Update and extend it a bit with respect to the current code and HW.

Most notably the doubled documentation of irq_domain (from .rst and .h) was unified and let only in .rst. A reference link was added to .h.

Furthermore:
* Add some 'struct' keywords, so that the respective structs are hyperlinked
* :c:member: use where appropriate to mark a member of a struct
* Rephrase some wording to improve readability/understanding

---
 Documentation/core-api/irq/irq-domain.rst | 122 ++++++++++++---------
 include/linux/irqdomain.h                 |  26 +----
 2 files changed, 76 insertions(+), 72 deletions(-)
Documentation/core-api/irq/irq-domain.rst +74 -48
index cb25649..67d45b3 100644
@@ -3,8 +3,8 @@ The irq_domain Interrupt Number Mapping Library
 ===============================================
 
 The current design of the Linux kernel uses a single large number
-space where each separate IRQ source is assigned a different number.
-This is simple when there is only one interrupt controller, but in
+space where each separate IRQ source is assigned a unique number.
+This is simple when there is only one interrupt controller. But in
 systems with multiple interrupt controllers, the kernel must ensure
 that each one gets assigned non-overlapping allocations of Linux
 IRQ numbers.
@@ -15,44 +15,63 @@ such as GPIO controllers avoid reimplementing identical callback
 mechanisms as the IRQ core system by modelling their interrupt
 handlers as irqchips. I.e. in effect cascading interrupt controllers.
 
-Here the interrupt number loose all kind of correspondence to
-hardware interrupt numbers: whereas in the past, IRQ numbers could
-be chosen so they matched the hardware IRQ line into the root
-interrupt controller (i.e. the component actually fireing the
-interrupt line to the CPU) nowadays this number is just a number.
+So in the past, IRQ numbers could be chosen so that they match the
+hardware IRQ line into the root interrupt controller (i.e. the
+component actually firing the interrupt line to the CPU). Nowadays,
+this number is just a number and the number loose all kind of
+correspondence to hardware interrupt numbers.
 
 For this reason, we need a mechanism to separate controller-local
 interrupt numbers, called hardware IRQs, from Linux IRQ numbers.
 
 The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of
-irq numbers, but they don't provide any support for reverse mapping of
+IRQ numbers, but they don't provide any support for reverse mapping of
 the controller-local IRQ (hwirq) number into the Linux IRQ number
 space.
 
 The irq_domain library adds a mapping between hwirq and IRQ numbers on
-top of the irq_alloc_desc*() API.  An irq_domain to manage mapping is
-preferred over interrupt controller drivers open coding their own
+top of the irq_alloc_desc*() API. An irq_domain to manage the mapping
+is preferred over interrupt controller drivers open coding their own
 reverse mapping scheme.
 
-irq_domain also implements translation from an abstract irq_fwspec
-structure to hwirq numbers (Device Tree and ACPI GSI so far), and can
-be easily extended to support other IRQ topology data sources.
+irq_domain also implements a translation from an abstract struct
+irq_fwspec to hwirq numbers (Device Tree, non-DT firmware node, ACPI
+GSI, and software node so far), and can be easily extended to support
+other IRQ topology data sources. The implementation is performed
+without any extra platform support code.
 
 irq_domain Usage
 ================
-
-An interrupt controller driver creates and registers an irq_domain by
-calling one of the irq_domain_create_*() functions.  The function will
-return a pointer to the irq_domain on success. The caller must provide the
-allocator function with an irq_domain_ops structure.
+struct irq_domain could be defined as an irq domain controller. That
+is, it handles the mapping between hardware and virtual interrupt
+numbers for a given interrupt domain. The domain structure is
+generally created by the PIC code for a given PIC instance (though a
+domain can cover more than one PIC if they have a flat number model).
+It is the domain callbacks that are responsible for setting the
+irq_chip on a given irq_desc after it has been mapped.
+
+The host code and data structures use a fwnode_handle pointer to
+identify the domain. In some cases, and in order to preserve source
+code compatibility, this fwnode pointer is "upgraded" to a DT
+device_node. For those firmware infrastructures that do not provide a
+unique identifier for an interrupt controller, the irq_domain code
+offers a fwnode allocator.
+
+An interrupt controller driver creates and registers a struct irq_domain
+by calling one of the irq_domain_create_*() functions (each mapping
+method has a different allocator function, more on that later). The
+function will return a pointer to the struct irq_domain on success. The
+caller must provide the allocator function with a struct irq_domain_ops
+pointer.
 
 In most cases, the irq_domain will begin empty without any mappings
 between hwirq and IRQ numbers.  Mappings are added to the irq_domain
 by calling irq_create_mapping() which accepts the irq_domain and a
-hwirq number as arguments.  If a mapping for the hwirq doesn't already
-exist then it will allocate a new Linux irq_desc, associate it with
-the hwirq, and call the .map() callback so the driver can perform any
-required hardware setup.
+hwirq number as arguments. If a mapping for the hwirq doesn't already
+exist, irq_create_mapping() allocates a new Linux irq_desc, associates
+it with the hwirq, and calls the :c:member:`irq_domain_ops.map()`
+callback. In there, the driver can perform any required hardware
+setup.
 
 Once a mapping has been established, it can be retrieved or used via a
 variety of methods:
@@ -74,7 +93,8 @@ be allocated.
 
 If the driver has the Linux IRQ number or the irq_data pointer, and
 needs to know the associated hwirq number (such as in the irq_chip
-callbacks) then it can be directly obtained from irq_data->hwirq.
+callbacks) then it can be directly obtained from
+:c:member:`irq_data.hwirq`.
 
 Types of irq_domain Mappings
 ============================
@@ -230,20 +250,40 @@ There are four major interfaces to use hierarchy irq_domain:
 4) irq_domain_deactivate_irq(): deactivate interrupt controller hardware
    to stop delivering the interrupt.
 
-Following changes are needed to support hierarchy irq_domain:
+The following is needed to support hierarchy irq_domain:
 
-1) a new field 'parent' is added to struct irq_domain; it's used to
+1) The :c:member:`parent` field in struct irq_domain is used to
    maintain irq_domain hierarchy information.
-2) a new field 'parent_data' is added to struct irq_data; it's used to
-   build hierarchy irq_data to match hierarchy irq_domains. The irq_data
-   is used to store irq_domain pointer and hardware irq number.
-3) new callbacks are added to struct irq_domain_ops to support hierarchy
-   irq_domain operations.
-
-With support of hierarchy irq_domain and hierarchy irq_data ready, an
-irq_domain structure is built for each interrupt controller, and an
+2) The :c:member:`parent_data` field in struct irq_data is used to
+   build hierarchy irq_data to match hierarchy irq_domains. The
+   irq_data is used to store irq_domain pointer and hardware irq
+   number.
+3) The :c:member:`alloc()`, :c:member:`free()`, and other callbacks in
+   struct irq_domain_ops to support hierarchy irq_domain operations.
+
+With the support of hierarchy irq_domain and hierarchy irq_data ready,
+an irq_domain structure is built for each interrupt controller, and an
 irq_data structure is allocated for each irq_domain associated with an
-IRQ. Now we could go one step further to support stacked(hierarchy)
+IRQ.
+
+For an interrupt controller driver to support hierarchy irq_domain, it
+needs to:
+
+1) Implement irq_domain_ops.alloc() and irq_domain_ops.free()
+2) Optionally, implement irq_domain_ops.activate() and
+   irq_domain_ops.deactivate().
+3) Optionally, implement an irq_chip to manage the interrupt controller
+   hardware.
+4) There is no need to implement irq_domain_ops.map() and
+   irq_domain_ops.unmap(). They are unused with hierarchy irq_domain.
+
+Note the hierarchy irq_domain is in no way x86-specific, and is
+heavily used to support other architectures, such as ARM, ARM64 etc.
+
+Stacked irq_chip
+~~~~~~~~~~~~~~~~
+
+Now, we could go one step further to support stacked (hierarchy)
 irq_chip. That is, an irq_chip is associated with each irq_data along
 the hierarchy. A child irq_chip may implement a required action by
 itself or by cooperating with its parent irq_chip.
@@ -253,20 +293,6 @@ with the hardware managed by itself and may ask for services from its
 parent irq_chip when needed. So we could achieve a much cleaner
 software architecture.
 
-For an interrupt controller driver to support hierarchy irq_domain, it
-needs to:
-
-1) Implement irq_domain_ops.alloc and irq_domain_ops.free
-2) Optionally implement irq_domain_ops.activate and
-   irq_domain_ops.deactivate.
-3) Optionally implement an irq_chip to manage the interrupt controller
-   hardware.
-4) No need to implement irq_domain_ops.map and irq_domain_ops.unmap,
-   they are unused with hierarchy irq_domain.
-
-Hierarchy irq_domain is in no way x86 specific, and is heavily used to
-support other architectures, such as ARM, ARM64 etc.
-
 Debugging
 =========
 
include/linux/irqdomain.h +2 -24
index a70e2ba..1a1786d 100644
@@ -1,30 +1,8 @@
 /* SPDX-License-Identifier: GPL-2.0 */
 /*
- * irq_domain - IRQ translation domains
+ * irq_domain - IRQ Translation Domains
  *
- * Translation infrastructure between hw and linux irq numbers.  This is
- * helpful for interrupt controllers to implement mapping between hardware
- * irq numbers and the Linux irq number space.
- *
- * irq_domains also have hooks for translating device tree or other
- * firmware interrupt representations into a hardware irq number that
- * can be mapped back to a Linux irq number without any extra platform
- * support code.
- *
- * Interrupt controller "domain" data structure. This could be defined as a
- * irq domain controller. That is, it handles the mapping between hardware
- * and virtual interrupt numbers for a given interrupt domain. The domain
- * structure is generally created by the PIC code for a given PIC instance
- * (though a domain can cover more than one PIC if they have a flat number
- * model). It's the domain callbacks that are responsible for setting the
- * irq_chip on a given irq_desc after it's been mapped.
- *
- * The host code and data structures use a fwnode_handle pointer to
- * identify the domain. In some cases, and in order to preserve source
- * code compatibility, this fwnode pointer is "upgraded" to a DT
- * device_node. For those firmware infrastructures that do not provide
- * a unique identifier for an interrupt controller, the irq_domain
- * code offers a fwnode allocator.
+ * See Documentation/core-api/irq/irq-domain.rst for the details.
  */
 
 #ifndef _LINUX_IRQDOMAIN_H
#262 lore raw

PATCH v2 57/57 irqdomain.c: Fix kernel-doc and add it to Documentation

In reply to Jiri Slaby (SUSE)

irqdomain.c's kernel-doc exists in that file, but is not plugged into Documentation/ yet.

Before plugging it in, fix it first: irq_domain_get_irq_data() and irq_domain_set_info() were documented twice. Identically, by both definitions for CONFIG_IRQ_DOMAIN_HIERARCHY and !CONFIG_IRQ_DOMAIN_HIERARCHY. Therefore, switch the second kernel-doc into an ordinary comment -- change "/**" to simple "/*". This avoids sphinx's:
WARNING: Duplicate C declaration

Next, in commit b7b377332b96 ("irqdomain: Fix the kernel-doc and plug it into Documentation"), I added irqdomain.h's (header) kernel-doc into core-api/genericirq.rst. But given the amount of irqdomain functions and structures, move all these to core-api/irq/irq-domain.rst now.

Finally, add these newly fixed irqdomain.c's (source) docs there as well.

---
 Documentation/core-api/genericirq.rst     |  2 --
 Documentation/core-api/irq/irq-domain.rst | 20 ++++++++++++++++++++
 kernel/irq/irqdomain.c                    |  4 ++--
 3 files changed, 22 insertions(+), 4 deletions(-)
Documentation/core-api/genericirq.rst +0 -2
index 25f94dfd66fa..582bde9bf5a9 100644
@@ -410,8 +410,6 @@ which are used in the generic IRQ layer.
 .. kernel-doc:: include/linux/interrupt.h
    :internal:
 
-.. kernel-doc:: include/linux/irqdomain.h
-
 Public Functions Provided
 =========================
 
Documentation/core-api/irq/irq-domain.rst +20 -0
index 7a418b3135de..4226e0bac4f0 100644
@@ -299,3 +299,23 @@ Debugging
 
 Most of the internals of the IRQ subsystem are exposed in debugfs by
 turning CONFIG_GENERIC_IRQ_DEBUGFS on.
+
+Structures and Public Functions Provided
+========================================
+
+This chapter contains the autogenerated documentation of the structures
+and exported kernel API functions which are used for IRQ domains.
+
+.. kernel-doc:: include/linux/irqdomain.h
+
+.. kernel-doc:: kernel/irq/irqdomain.c
+   :export:
+
+Internal Functions Provided
+===========================
+
+This chapter contains the autogenerated documentation of the internal
+functions.
+
+.. kernel-doc:: kernel/irq/irqdomain.c
+   :internal:
kernel/irq/irqdomain.c +2 -2
index 5bb3d2bbe229..5b21b568155b 100644
@@ -1940,7 +1940,7 @@ static void irq_domain_check_hierarchy(struct irq_domain *domain)
 		domain->flags |= IRQ_DOMAIN_FLAG_HIERARCHY;
 }
 #else	/* CONFIG_IRQ_DOMAIN_HIERARCHY */
-/**
+/*
  * irq_domain_get_irq_data - Get irq_data associated with @virq and @domain
  * @domain:	domain to match
  * @virq:	IRQ number to get irq_data
@@ -1954,7 +1954,7 @@ struct irq_data *irq_domain_get_irq_data(struct irq_domain *domain,
 }
 EXPORT_SYMBOL_GPL(irq_domain_get_irq_data);
 
-/**
+/*
  * irq_domain_set_info - Set the complete data for a @virq in @domain
  * @domain:		Interrupt domain to match
  * @virq:		IRQ number
Signature · 1 line
2.49.0
#263 lore raw

[tip: irq/cleanups] irqdomain: Fix kernel-doc and add it to Documentation

The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     b0daad295c4eec75228cf91246cf25d1c8eead5d
Gitweb:        https://git.kernel.org/tip/b0daad295c4eec75228cf91246cf25d1c8eead5d
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:50 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Tue, 06 May 2025 14:59:09 +02:00

irqdomain: Fix kernel-doc and add it to Documentation

irqdomain.c's kernel-doc exists, but is not plugged into Documentation/ yet.

Before plugging it in, fix it first: irq_domain_get_irq_data() and irq_domain_set_info() were documented twice. Identically, by both definitions for CONFIG_IRQ_DOMAIN_HIERARCHY and !CONFIG_IRQ_DOMAIN_HIERARCHY.

Therefore, switch the second kernel-doc into an ordinary comment -- change "/**" to simple "/*". This avoids sphinx's: WARNING: Duplicate C declaration

Next, in commit b7b377332b96 ("irqdomain: Fix the kernel-doc and plug it into Documentation"), irqdomain.h's (header) kernel-doc was added into core-api/genericirq.rst. But given the amount of irqdomain functions and structures, move all these to core-api/irq/irq-domain.rst now.

Finally, add these newly fixed irqdomain.c's (source) docs there as well.

---
 Documentation/core-api/genericirq.rst     |  2 --
 Documentation/core-api/irq/irq-domain.rst | 20 ++++++++++++++++++++
 kernel/irq/irqdomain.c                    |  4 ++--
 3 files changed, 22 insertions(+), 4 deletions(-)
Documentation/core-api/genericirq.rst +0 -2
index 25f94df..582bde9 100644
@@ -410,8 +410,6 @@ which are used in the generic IRQ layer.
 .. kernel-doc:: include/linux/interrupt.h
    :internal:
 
-.. kernel-doc:: include/linux/irqdomain.h
-
 Public Functions Provided
 =========================
 
Documentation/core-api/irq/irq-domain.rst +20 -0
index 67d45b3..a01c6ea 100644
@@ -298,3 +298,23 @@ Debugging
 
 Most of the internals of the IRQ subsystem are exposed in debugfs by
 turning CONFIG_GENERIC_IRQ_DEBUGFS on.
+
+Structures and Public Functions Provided
+========================================
+
+This chapter contains the autogenerated documentation of the structures
+and exported kernel API functions which are used for IRQ domains.
+
+.. kernel-doc:: include/linux/irqdomain.h
+
+.. kernel-doc:: kernel/irq/irqdomain.c
+   :export:
+
+Internal Functions Provided
+===========================
+
+This chapter contains the autogenerated documentation of the internal
+functions.
+
+.. kernel-doc:: kernel/irq/irqdomain.c
+   :internal:
kernel/irq/irqdomain.c +2 -2
index 57098c7..c8b6de0 100644
@@ -1996,7 +1996,7 @@ static void irq_domain_check_hierarchy(struct irq_domain *domain)
 		domain->flags |= IRQ_DOMAIN_FLAG_HIERARCHY;
 }
 #else	/* CONFIG_IRQ_DOMAIN_HIERARCHY */
-/**
+/*
  * irq_domain_get_irq_data - Get irq_data associated with @virq and @domain
  * @domain:	domain to match
  * @virq:	IRQ number to get irq_data
@@ -2010,7 +2010,7 @@ struct irq_data *irq_domain_get_irq_data(struct irq_domain *domain,
 }
 EXPORT_SYMBOL_GPL(irq_domain_get_irq_data);
 
-/**
+/*
  * irq_domain_set_info - Set the complete data for a @virq in @domain
  * @domain:		Interrupt domain to match
  * @virq:		IRQ number
#264 lore raw

[tip: irq/cleanups] irqdomain: Fix kernel-doc and add it to Documentation

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     6b67de3a2db90987b5d0845b9c6a3ed7eb94dcf4
Gitweb:        https://git.kernel.org/tip/6b67de3a2db90987b5d0845b9c6a3ed7eb94dcf4
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:50 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 09:53:25 +02:00

irqdomain: Fix kernel-doc and add it to Documentation

irqdomain.c's kernel-doc exists, but is not plugged into Documentation/ yet.

Before plugging it in, fix it first: irq_domain_get_irq_data() and irq_domain_set_info() were documented twice. Identically, by both definitions for CONFIG_IRQ_DOMAIN_HIERARCHY and !CONFIG_IRQ_DOMAIN_HIERARCHY.

Therefore, switch the second kernel-doc into an ordinary comment -- change "/**" to simple "/*". This avoids sphinx's: WARNING: Duplicate C declaration

Next, in commit b7b377332b96 ("irqdomain: Fix the kernel-doc and plug it into Documentation"), irqdomain.h's (header) kernel-doc was added into core-api/genericirq.rst. But given the amount of irqdomain functions and structures, move all these to core-api/irq/irq-domain.rst now.

Finally, add these newly fixed irqdomain.c's (source) docs there as well.

---
 Documentation/core-api/genericirq.rst     |  2 --
 Documentation/core-api/irq/irq-domain.rst | 20 ++++++++++++++++++++
 kernel/irq/irqdomain.c                    |  4 ++--
 3 files changed, 22 insertions(+), 4 deletions(-)
Documentation/core-api/genericirq.rst +0 -2
index 25f94df..582bde9 100644
@@ -410,8 +410,6 @@ which are used in the generic IRQ layer.
 .. kernel-doc:: include/linux/interrupt.h
    :internal:
 
-.. kernel-doc:: include/linux/irqdomain.h
-
 Public Functions Provided
 =========================
 
Documentation/core-api/irq/irq-domain.rst +20 -0
index 67d45b3..a01c6ea 100644
@@ -298,3 +298,23 @@ Debugging
 
 Most of the internals of the IRQ subsystem are exposed in debugfs by
 turning CONFIG_GENERIC_IRQ_DEBUGFS on.
+
+Structures and Public Functions Provided
+========================================
+
+This chapter contains the autogenerated documentation of the structures
+and exported kernel API functions which are used for IRQ domains.
+
+.. kernel-doc:: include/linux/irqdomain.h
+
+.. kernel-doc:: kernel/irq/irqdomain.c
+   :export:
+
+Internal Functions Provided
+===========================
+
+This chapter contains the autogenerated documentation of the internal
+functions.
+
+.. kernel-doc:: kernel/irq/irqdomain.c
+   :internal:
kernel/irq/irqdomain.c +2 -2
index 57098c7..c8b6de0 100644
@@ -1996,7 +1996,7 @@ static void irq_domain_check_hierarchy(struct irq_domain *domain)
 		domain->flags |= IRQ_DOMAIN_FLAG_HIERARCHY;
 }
 #else	/* CONFIG_IRQ_DOMAIN_HIERARCHY */
-/**
+/*
  * irq_domain_get_irq_data - Get irq_data associated with @virq and @domain
  * @domain:	domain to match
  * @virq:	IRQ number to get irq_data
@@ -2010,7 +2010,7 @@ struct irq_data *irq_domain_get_irq_data(struct irq_domain *domain,
 }
 EXPORT_SYMBOL_GPL(irq_domain_get_irq_data);
 
-/**
+/*
  * irq_domain_set_info - Set the complete data for a @virq in @domain
  * @domain:		Interrupt domain to match
  * @virq:		IRQ number
#265 lore raw

[tip: irq/cleanups] irqdomain: Fix kernel-doc and add it to Documentation

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     e0de777349a3a1f97acedc876cba1ceb589fb9be
Gitweb:        https://git.kernel.org/tip/e0de777349a3a1f97acedc876cba1ceb589fb9be
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:50 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Wed, 07 May 2025 15:39:43 +02:00

irqdomain: Fix kernel-doc and add it to Documentation

irqdomain.c's kernel-doc exists, but is not plugged into Documentation/ yet.

Before plugging it in, fix it first: irq_domain_get_irq_data() and irq_domain_set_info() were documented twice. Identically, by both definitions for CONFIG_IRQ_DOMAIN_HIERARCHY and !CONFIG_IRQ_DOMAIN_HIERARCHY.

Therefore, switch the second kernel-doc into an ordinary comment -- change "/**" to simple "/*". This avoids sphinx's: WARNING: Duplicate C declaration

Next, in commit b7b377332b96 ("irqdomain: Fix the kernel-doc and plug it into Documentation"), irqdomain.h's (header) kernel-doc was added into core-api/genericirq.rst. But given the amount of irqdomain functions and structures, move all these to core-api/irq/irq-domain.rst now.

Finally, add these newly fixed irqdomain.c's (source) docs there as well.

---
 Documentation/core-api/genericirq.rst     |  2 --
 Documentation/core-api/irq/irq-domain.rst | 20 ++++++++++++++++++++
 kernel/irq/irqdomain.c                    |  4 ++--
 3 files changed, 22 insertions(+), 4 deletions(-)
Documentation/core-api/genericirq.rst +0 -2
index 25f94df..582bde9 100644
@@ -410,8 +410,6 @@ which are used in the generic IRQ layer.
 .. kernel-doc:: include/linux/interrupt.h
    :internal:
 
-.. kernel-doc:: include/linux/irqdomain.h
-
 Public Functions Provided
 =========================
 
Documentation/core-api/irq/irq-domain.rst +20 -0
index 67d45b3..a01c6ea 100644
@@ -298,3 +298,23 @@ Debugging
 
 Most of the internals of the IRQ subsystem are exposed in debugfs by
 turning CONFIG_GENERIC_IRQ_DEBUGFS on.
+
+Structures and Public Functions Provided
+========================================
+
+This chapter contains the autogenerated documentation of the structures
+and exported kernel API functions which are used for IRQ domains.
+
+.. kernel-doc:: include/linux/irqdomain.h
+
+.. kernel-doc:: kernel/irq/irqdomain.c
+   :export:
+
+Internal Functions Provided
+===========================
+
+This chapter contains the autogenerated documentation of the internal
+functions.
+
+.. kernel-doc:: kernel/irq/irqdomain.c
+   :internal:
kernel/irq/irqdomain.c +2 -2
index 57098c7..c8b6de0 100644
@@ -1996,7 +1996,7 @@ static void irq_domain_check_hierarchy(struct irq_domain *domain)
 		domain->flags |= IRQ_DOMAIN_FLAG_HIERARCHY;
 }
 #else	/* CONFIG_IRQ_DOMAIN_HIERARCHY */
-/**
+/*
  * irq_domain_get_irq_data - Get irq_data associated with @virq and @domain
  * @domain:	domain to match
  * @virq:	IRQ number to get irq_data
@@ -2010,7 +2010,7 @@ struct irq_data *irq_domain_get_irq_data(struct irq_domain *domain,
 }
 EXPORT_SYMBOL_GPL(irq_domain_get_irq_data);
 
-/**
+/*
  * irq_domain_set_info - Set the complete data for a @virq in @domain
  * @domain:		Interrupt domain to match
  * @virq:		IRQ number
#266 lore raw

[tip: irq/cleanups] irqdomain: Fix kernel-doc and add it to Documentation

In reply to Jiri Slaby (SUSE)
The following commit has been merged into the irq/cleanups branch of tip:

The following commit has been merged into the irq/cleanups branch of tip:

Commit-ID:     a10024e671d12c8125a8f31d08c67245f6dee16d
Gitweb:        https://git.kernel.org/tip/a10024e671d12c8125a8f31d08c67245f6dee16d
Author:        Jiri Slaby (SUSE) <[email protected]>
AuthorDate:    Wed, 19 Mar 2025 10:29:50 +01:00
Committer:     Thomas Gleixner <[email protected]>
CommitterDate: Fri, 16 May 2025 21:06:13 +02:00

irqdomain: Fix kernel-doc and add it to Documentation

irqdomain.c's kernel-doc exists, but is not plugged into Documentation/ yet.

Before plugging it in, fix it first: irq_domain_get_irq_data() and irq_domain_set_info() were documented twice. Identically, by both definitions for CONFIG_IRQ_DOMAIN_HIERARCHY and !CONFIG_IRQ_DOMAIN_HIERARCHY.

Therefore, switch the second kernel-doc into an ordinary comment -- change "/**" to simple "/*". This avoids sphinx's: WARNING: Duplicate C declaration

Next, in commit b7b377332b96 ("irqdomain: Fix the kernel-doc and plug it into Documentation"), irqdomain.h's (header) kernel-doc was added into core-api/genericirq.rst. But given the amount of irqdomain functions and structures, move all these to core-api/irq/irq-domain.rst now.

Finally, add these newly fixed irqdomain.c's (source) docs there as well.

---
 Documentation/core-api/genericirq.rst     |  2 --
 Documentation/core-api/irq/irq-domain.rst | 20 ++++++++++++++++++++
 kernel/irq/irqdomain.c                    |  4 ++--
 3 files changed, 22 insertions(+), 4 deletions(-)
Documentation/core-api/genericirq.rst +0 -2
index 25f94df..582bde9 100644
@@ -410,8 +410,6 @@ which are used in the generic IRQ layer.
 .. kernel-doc:: include/linux/interrupt.h
    :internal:
 
-.. kernel-doc:: include/linux/irqdomain.h
-
 Public Functions Provided
 =========================
 
Documentation/core-api/irq/irq-domain.rst +20 -0
index 67d45b3..a01c6ea 100644
@@ -298,3 +298,23 @@ Debugging
 
 Most of the internals of the IRQ subsystem are exposed in debugfs by
 turning CONFIG_GENERIC_IRQ_DEBUGFS on.
+
+Structures and Public Functions Provided
+========================================
+
+This chapter contains the autogenerated documentation of the structures
+and exported kernel API functions which are used for IRQ domains.
+
+.. kernel-doc:: include/linux/irqdomain.h
+
+.. kernel-doc:: kernel/irq/irqdomain.c
+   :export:
+
+Internal Functions Provided
+===========================
+
+This chapter contains the autogenerated documentation of the internal
+functions.
+
+.. kernel-doc:: kernel/irq/irqdomain.c
+   :internal:
kernel/irq/irqdomain.c +2 -2
index 57098c7..c8b6de0 100644
@@ -1996,7 +1996,7 @@ static void irq_domain_check_hierarchy(struct irq_domain *domain)
 		domain->flags |= IRQ_DOMAIN_FLAG_HIERARCHY;
 }
 #else	/* CONFIG_IRQ_DOMAIN_HIERARCHY */
-/**
+/*
  * irq_domain_get_irq_data - Get irq_data associated with @virq and @domain
  * @domain:	domain to match
  * @virq:	IRQ number to get irq_data
@@ -2010,7 +2010,7 @@ struct irq_data *irq_domain_get_irq_data(struct irq_domain *domain,
 }
 EXPORT_SYMBOL_GPL(irq_domain_get_irq_data);
 
-/**
+/*
  * irq_domain_set_info - Set the complete data for a @virq in @domain
  * @domain:		Interrupt domain to match
  * @virq:		IRQ number
#267 lore raw
In reply to Jiri Slaby (SUSE)
Quoted 14 lines · Jiri Slaby (SUSE)

Hi,

tl;dr if patches are agreed upon, I ask subsys maintainers to take the respective ones via their trees (as they are split per subsys), so that the IRQ tree can take only the rest. That would minimize churn/conflicts during merges.

===

While I was reading through the irqdomain code and headers, I found some naming and documentation hard to follow or incomplete. Especially the naming of _add/_create/_instantiate functions.

Quoted 7 lines

I tried to come up with a better state with this patchset:
* only irq _domain_ (not host),
* only irq_domain_create*() functions, all taking fwnode uniformly,

Finally, all the irqdomain stuff is now plugged (and generated) into Documentation. So that everyone can walk through it at
https://www.kernel.org/doc/ (once applied, of course).

I am all to support the idea, but in some cases I would think of a bit more work to be done to get rid of the of_fwnode_handle(np) in favour of dev_fwnode(dev). Note, this is based on a brief look, I haven't any example at hand right now.

Signature · 2 lines
With Best Regards,
Andy Shevchenko
author
#268 lore raw
Quoted 4 lines · Andy Shevchenko

I am all to support the idea, but in some cases I would think of a bit more work to be done to get rid of the of_fwnode_handle(np) in favour of dev_fwnode(dev). Note, this is based on a brief look, I haven't any example at hand right now.

Aah, that's the helper I was looking for!

I was about to use dev->fwnode directly (see the commit log for the Switch to irq_domain_create_*()), but that is not guaranteed to be always properly set.

Will use this instead in v3.

thanks,

Signature · 2 lines
js
suse labs
maintainer
#269 lore raw

Re: (subset) [PATCH v2 00/57] irqdomain: Cleanups and Documentation

In reply to Jiri Slaby (SUSE)
Quoted 8 lines · Jiri Slaby (SUSE)

tl;dr if patches are agreed upon, I ask subsys maintainers to take the respective ones via their trees (as they are split per subsys), so that the IRQ tree can take only the rest. That would minimize churn/conflicts during merges.

===

[...]

Applied to

https://git.kernel.org/pub/scm/linux/kernel/git/broonie/sound.git for-next

Thanks!

[35/57] irqdomain: sound: Switch to irq_domain_create_linear()

        commit: 83eddf0116b09186f909bc643f2093f266f204ea

All being well this means that it will be integrated into the linux-next tree (usually sometime in the next 24 hours) and sent to Linus during the next merge window (or sooner if it is a bug fix), however if problems are discovered then the patch may be dropped or reverted.

You may get further e-mails resulting from automated or manual testing and review of the tree, please engage with people reporting problems and send followup patches addressing any issues that are reported if needed.

If any updates are required or you are submitting further changes they should be sent as incremental updates against current git, existing patches will not be replaced.

Please add any relevant lists and maintainers to the CCs when replying to this mail.

Thanks,
Mark

#270 lore raw

Re: (subset) [PATCH v2 00/57] irqdomain: Cleanups and Documentation

In reply to Jiri Slaby (SUSE)
Quoted 8 lines · Jiri Slaby (SUSE)

tl;dr if patches are agreed upon, I ask subsys maintainers to take the respective ones via their trees (as they are split per subsys), so that the IRQ tree can take only the rest. That would minimize churn/conflicts during merges.

===

[...]

Applied, thanks!

[48/57] irqdomain: soc: Switch to irq_find_mapping()

        commit: a70a3a6322131632cc6cf71e9d2fa6409a029fd7

Best regards,

Signature · 1 line
Christophe Leroy <[email protected]>
#271 lore raw
In reply to Jiri Slaby (SUSE)
Quoted 6 lines · Jiri Slaby

Hi,

tl;dr if patches are agreed upon, I ask subsys maintainers to take the respective ones via their trees (as they are split per subsys), so that the IRQ tree can take only the rest. That would minimize churn/conflicts during merges.

So. It's rc5 by now and I picked up everything which did not show up in next yet. As there are some patches in next, I delayed the removal of functions for the merge window so that we don't end up with merge dependencies.

To reducde conflicts, I grabbed the irq branch from the PCI tree under the assumption that this branch is stable.

The series sits now in

git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git irq/cleanups

and will be in next soon. If there are duplicates showing up in next, I'm going to remove them from my branch, so the branch is not for basing development on.

@Jiri, I fixed up all your subject prefixes as

'irqdomain: subsys: Switch to foo()'

does not make any sense at all. These subsystems have their regular prefixes and these changes do not justify made up irqdomain special prefixes at all.

Thanks,

tglx

author
#272 lore raw
Quoted 10 lines · Thomas Gleixner
Quoted 6 lines · Jiri Slaby

Hi,

tl;dr if patches are agreed upon, I ask subsys maintainers to take the respective ones via their trees (as they are split per subsys), so that the IRQ tree can take only the rest. That would minimize churn/conflicts during merges.

So. It's rc5 by now and I picked up everything

Good, thanks.

Quoted 1 line

which did not show up in next yet.

Which is the majority -- routing through subsystems didn't work as well as I anticipated.

I planned to retry with v3 after the next merge window, but you were faster.

V3 contains a switch from nodes to dev_fwnode() in some cases. It simplifies the code there. This did not get lost, I will send this separately to maintainers once everything from this series settles in the tree. I.e. likely after the next merge window.

Quoted 7 lines

@Jiri, I fixed up all your subject prefixes as

'irqdomain: subsys: Switch to foo()'

does not make any sense at all. These subsystems have their regular prefixes and these changes do not justify made up irqdomain special prefixes at all.

Yes.

thanks,

Signature · 2 lines
js
suse labs