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

[Randy Dunlap]

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