[PATCH v2] docs: kernel-parameters: document scope of irqaffinity= parameter

Aaron Tomlin
2026-04-21T15:09:22Z

There is a common misconception that the "irqaffinity=" boot parameter
acts as a global override for all hardware interrupts. In reality, it
only sets the irq_default_affinity mask, which is explicitly ignored
by managed interrupts (e.g., modern multiqueue storage controllers).

This patch updates kernel-parameters.txt to document this limitation,
directs users to "isolcpus=managed_irq" and
Documentation/core-api/irq/managed_irq.rst for further details.
Additionally, it updates managed_irq.rst to provide a debugfs example
demonstrating the IRQD_AFFINITY_MANAGED state flag.

Signed-off-by: Aaron Tomlin <atomlin@atomlin.com>
---
Changes in v1 [1]:
- Provided an example of a managed IRQ using CONFIG_GENERIC_IRQ_DEBUGFS
- Referenced Documentation/core-api/irq/managed_irq.rst

[1]: https://lore.kernel.org/lkml/20260414200245.1153919-1-atomlin@atomlin.com/
---
.../admin-guide/kernel-parameters.txt | 11 ++++
Documentation/core-api/irq/managed_irq.rst | 53 ++++++++++++++++++-
2 files changed, 62 insertions(+), 2 deletions(-)

diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index cf3807641d89..365c4931700a 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -2726,6 +2726,17 @@ Kernel parameters
irqaffinity= [SMP] Set the default irq affinity mask
The argument is a cpu list, as described above.

+ Note: This parameter only sets the default affinity
+ for unmanaged interrupts (e.g., legacy single-queue
+ devices or unmanaged pre/post vectors). It is
+ explicitly ignored by managed interrupts, such as
+ those utilised by modern multiqueue storage
+ controllers. To isolate CPUs from managed
+ interrupts, see "isolcpus=managed_irq".
+
+ For further details see:
+ Documentation/core-api/irq/managed_irq.rst
+
irqchip.gicv2_force_probe=
[ARM,ARM64,EARLY]
Format: <bool>
diff --git a/Documentation/core-api/irq/managed_irq.rst b/Documentation/core-api/irq/managed_irq.rst
index 05e295f3c289..8e973a7d1bd1 100644
--- a/Documentation/core-api/irq/managed_irq.rst
+++ b/Documentation/core-api/irq/managed_irq.rst
@@ -80,9 +80,58 @@ The following examples assume a system with 8 CPUs.
/proc/irq/48/effective_affinity_list:0
/proc/irq/48/smp_affinity_list:7

- This can be verified via the debugfs interface
- (/sys/kernel/debug/irq/irqs/48). The dstate field will include
+ If the Linux kernel was built with Kconfig CONFIG_GENERIC_IRQ_DEBUGFS
+ enabled, this can be verified via the debugfs interface (e.g.,
+ /sys/kernel/debug/irq/irqs/48). The dstate field will include
IRQD_IRQ_DISABLED, IRQD_IRQ_MASKED and IRQD_MANAGED_SHUTDOWN.
+ A managed IRQ will also include IRQD_AFFINITY_MANAGED. For example:
+
+ # cat /sys/kernel/debug/irq/irqs/87
+ handler: handle_edge_irq
+ device: 0000:41:00.0
+ status: 0x00000000
+ istate: 0x00004000
+ ddepth: 0
+ wdepth: 0
+ dstate: 0x19601200
+ IRQD_ACTIVATED
+ IRQD_IRQ_STARTED
+ IRQD_SINGLE_TARGET
+ IRQD_AFFINITY_SET
+ IRQD_AFFINITY_MANAGED
+ IRQD_AFFINITY_ON_ACTIVATE
+ IRQD_HANDLE_ENFORCE_IRQCTX
+ node: 0
+ affinity: 9
+ effectiv: 9
+ pending:
+ domain: IR-PCI-MSIX-0000:41:00.0-12
+ hwirq: 0x8
+ chip: IR-PCI-MSIX-0000:41:00.0
+ flags: 0x430
+ IRQCHIP_SKIP_SET_WAKE
+ IRQCHIP_ONESHOT_SAFE
+
+ address_hi: 0x00000000
+ address_lo: 0xfee00000
+ msg_data: 0x00000008
+ parent:
+ domain: AMD-IR-3-14
+ hwirq: 0x41000000
+ chip: AMD-IR
+ flags: 0x0
+ parent:
+ domain: VECTOR
+ hwirq: 0x57
+ chip: APIC
+ flags: 0x0
+ Vector: 33
+ Target: 9
+ move_in_progress: 0
+ is_managed: 1
+ can_reserve: 0
+ has_reserved: 0
+ cleanup_pending: 0

- A QEMU instance is booted with "-device virtio-scsi-pci,num_queues=2"
and the kernel command line includes:
--
2.51.0