Re: [PATCH v2 55/57] docs: irq-domain.rst: Simple improvements

Randy Dunlap
2025-03-19T17:54:23Z

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@kernel.org>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Randy Dunlap <rdunlap@infradead.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