On 3/19/25 2:29 AM, Jiri Slaby (SUSE) wrote:
> 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.
>
> Signed-off-by: Jiri Slaby (SUSE) <jirislaby@xxxxxxxxxx>
> Cc: Jonathan Corbet <corbet@xxxxxxx>
> Cc: linux-doc@xxxxxxxxxxxxxxx
> Cc: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> ---
> Documentation/core-api/irq/irq-domain.rst | 122 +++++++++++++---------
> include/linux/irqdomain.h | 26 +----
> 2 files changed, 76 insertions(+), 72 deletions(-)
>
> diff --git a/Documentation/core-api/irq/irq-domain.rst b/Documentation/core-api/irq/irq-domain.rst
> index c2f2728b1a35..7a418b3135de 100644
> --- a/Documentation/core-api/irq/irq-domain.rst
> +++ b/Documentation/core-api/irq/irq-domain.rst
> @@ -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
loses
> +correspondence to hardware interrupt numbers.
>
[snip]
--
~Randy
