Message-ID: <4c71b7bd-5264-4a64-81bc-297dcf1c81a1@infradead.org>
Date: Wed, 19 Mar 2025 10:54:13 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: "Jiri Slaby (SUSE)" <jirislaby@...nel.org>, tglx@...utronix.de
Cc: maz@...nel.org, linux-kernel@...r.kernel.org,
 Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org
Subject: Re: [PATCH v2 55/57] docs: irq-domain.rst: Simple improvements

Hi,

On 3/19/25 2:29 AM, Jiri Slaby (SUSE) wrote:
> 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.
> 
> Signed-off-by: Jiri Slaby (SUSE) <jirislaby@...nel.org>
> Cc: Jonathan Corbet <corbet@....net>
> Cc: linux-doc@...r.kernel.org
> Cc: Randy Dunlap <rdunlap@...radead.org>
> ---
>  Documentation/core-api/irq/irq-domain.rst | 22 +++++++++++-----------
>  1 file changed, 11 insertions(+), 11 deletions(-)
> 
> diff --git a/Documentation/core-api/irq/irq-domain.rst b/Documentation/core-api/irq/irq-domain.rst
> index 775dd43b3340..c2f2728b1a35 100644
> --- a/Documentation/core-api/irq/irq-domain.rst
> +++ b/Documentation/core-api/irq/irq-domain.rst
> @@ -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.
>  

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

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

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

thanks.
-- 
~Randy

Powered by blists - more mailing lists