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

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

[Aaron Tomlin]

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

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

[kernel test robot]

Hi Aaron,

kernel test robot noticed the following build warnings:

[auto build test WARNING on lwn/docs-next]
[also build test WARNING on linus/master v7.1-rc1 next-20260429]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Aaron-Tomlin/docs-kernel-parameters-document-scope-of-irqaffinity-parameter/20260423-221944
base:   git://git.lwn.net/linux.git docs-next
patch link:    https://lore.kernel.org/r/20260421150911.42404-1-atomlin%40atomlin.com
patch subject: [PATCH v2] docs: kernel-parameters: document scope of irqaffinity= parameter
compiler: clang version 20.1.8 (https://github.com/llvm/llvm-project 87f0227cb60147a26a1eeb4fb06e3b505e9c7261)
docutils: docutils (Docutils 0.21.2, Python 3.13.5, on linux)
reproduce: (https://download.01.org/0day-ci/archive/20260430/202604300215.1Alrqyxi-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202604300215.1Alrqyxi-lkp@intel.com/

All warnings (new ones prefixed by >>):

   Warning: tools/docs/documentation-file-ref-check references a file that doesn't exist: Documentation/devicetree/dt-object-internal.txt
   Warning: tools/docs/documentation-file-ref-check references a file that doesn't exist: m,^Documentation/scheduler/sched-pelt
   Warning: tools/docs/documentation-file-ref-check references a file that doesn't exist: m,(Documentation/translations/[
   Using alabaster theme
   Documentation/core-api/irq/managed_irq.rst:97: ERROR: Unexpected indentation. [docutils]
>> Documentation/core-api/irq/managed_irq.rst:104: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
   Documentation/core-api/irq/managed_irq.rst:109: ERROR: Unexpected indentation. [docutils]
   Documentation/core-api/irq/managed_irq.rst:111: ERROR: Unexpected indentation. [docutils]
   Documentation/core-api/irq/managed_irq.rst:118: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
   Documentation/core-api/irq/managed_irq.rst:122: ERROR: Unexpected indentation. [docutils]
   Documentation/core-api/irq/managed_irq.rst:123: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]


vim +104 Documentation/core-api/irq/managed_irq.rst

    65	
    66	- A QEMU instance is booted with "-device virtio-scsi-pci".
    67	  The MSI‑X device exposes 11 interrupts: 3 "management" interrupts and 8
    68	  "queue" interrupts. The driver requests the 8 queue interrupts, each of which
    69	  is affine to exactly one CPU. If that CPU goes offline, the interrupt is shut
    70	  down.
    71	
    72	  Assuming interrupt 48 is one of the queue interrupts, the following appears::
    73	
    74	    /proc/irq/48/effective_affinity_list:7
    75	    /proc/irq/48/smp_affinity_list:7
    76	
    77	  This indicates that the interrupt is served only by CPU7. Shutting down CPU7
    78	  does not migrate the interrupt to another CPU::
    79	
    80	    /proc/irq/48/effective_affinity_list:0
    81	    /proc/irq/48/smp_affinity_list:7
    82	
    83	  If the Linux kernel was built with Kconfig CONFIG_GENERIC_IRQ_DEBUGFS
    84	  enabled, this can be verified via the debugfs interface (e.g.,
    85	  /sys/kernel/debug/irq/irqs/48). The dstate field will include
    86	  IRQD_IRQ_DISABLED, IRQD_IRQ_MASKED and IRQD_MANAGED_SHUTDOWN.
    87	  A managed IRQ will also include IRQD_AFFINITY_MANAGED. For example:
    88	
    89	    # cat /sys/kernel/debug/irq/irqs/87
    90	    handler:  handle_edge_irq
    91	    device:   0000:41:00.0
    92	    status:   0x00000000
    93	    istate:   0x00004000
    94	    ddepth:   0
    95	    wdepth:   0
    96	    dstate:   0x19601200
    97			IRQD_ACTIVATED
    98			IRQD_IRQ_STARTED
    99			IRQD_SINGLE_TARGET
   100			IRQD_AFFINITY_SET
   101			IRQD_AFFINITY_MANAGED
   102			IRQD_AFFINITY_ON_ACTIVATE
   103			IRQD_HANDLE_ENFORCE_IRQCTX
 > 104	    node:     0
   105	    affinity: 9
   106	    effectiv: 9
   107	    pending:
   108	    domain:  IR-PCI-MSIX-0000:41:00.0-12
   109	     hwirq:   0x8
   110	     chip:    IR-PCI-MSIX-0000:41:00.0
   111	      flags:   0x430
   112			 IRQCHIP_SKIP_SET_WAKE
   113			 IRQCHIP_ONESHOT_SAFE
   114	
   115	      address_hi: 0x00000000
   116	      address_lo: 0xfee00000
   117	      msg_data:   0x00000008
   118	     parent:
   119		domain:  AMD-IR-3-14
   120		 hwirq:   0x41000000
   121		 chip:    AMD-IR
   122		  flags:   0x0
   123		 parent:
   124		    domain:  VECTOR
   125		     hwirq:   0x57
   126		     chip:    APIC
   127		      flags:   0x0
   128		     Vector:    33
   129		     Target:     9
   130		     move_in_progress: 0
   131		     is_managed:       1
   132		     can_reserve:      0
   133		     has_reserved:     0
   134		     cleanup_pending:  0
   135	

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

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

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 747 bytes --]

On Tue, Apr 21, 2026 at 11:09:11AM -0400, Aaron Tomlin wrote:
> -  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:

Use double-colon syntax (i.e. ``For example::``) for literal code block
below.

> +
> +    # cat /sys/kernel/debug/irq/irqs/87

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

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

[Jonathan Corbet]

Aaron Tomlin <atomlin@atomlin.com> writes:

> 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/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

This will not render the way you seem to expect, it should be a literal
block.  Please do build the docs and look at the results before sending
documentation patches.

Thanks,

jon

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

[Aaron Tomlin]

[-- Attachment #1: Type: text/plain, Size: 1407 bytes --]

On Sun, May 03, 2026 at 09:16:01AM -0600, Jonathan Corbet wrote:
> > 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
> 
> This will not render the way you seem to expect, it should be a literal
> block.  Please do build the docs and look at the results before sending
> documentation patches.
> 
Hi Jon,

Acknowledged. I'll resolve the above in the next iteration.


Kind regards,
-- 
Aaron Tomlin

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]