diff mbox series

[v3,2/3] docs: firmware-guide: ACPI: Add named interrupt doc

Message ID 1642686255-25951-3-git-send-email-akhilrajeev@nvidia.com
State Superseded
Headers show
Series Enable named interrupt smbus-alert for ACPI | expand

Commit Message

Akhil R Jan. 20, 2022, 1:44 p.m. UTC
Added details and example for named interrupts in the ACPI table.

Signed-off-by: Akhil R <akhilrajeev@nvidia.com>
---
 Documentation/firmware-guide/acpi/enumeration.rst | 38 +++++++++++++++++++++++
 1 file changed, 38 insertions(+)

Comments

Akhil R Jan. 21, 2022, 12:50 p.m. UTC | #1
> > Added details and example for named interrupts in the ACPI table.
> 
> Added details and example for --> Add a detailed example of the
> 
> ...
> 
> > +            Interrupt (ResourceConsumer, Level, ActiveHigh, Exclusive) {
> > +                0x20,
> 
> I would think of splitting this to two separate entries in between of which the
> GpioInt() resource is provided. It will explicitly show that you describe the case
> only for Interrupt(). Something like
> 
>   Interrupt (...) { 0x20 }
>   GpioInt(...) { ... }
>   Interrupt (...) { 0x24 }
> 
> But it's up to you.
Instead, would it be good to add a statement mentioning this explicitly. Something 
like -

    The interrupt name 'default' will correspond to 0x20 in Interrupt()
    resource and 'alert' to 0x24. Note that only the Interrupt() resource
    is mapped and not GpioInt() or similar.

I feel mixing these in the example would add a bit of confusion to the reader.

Thanks,
Akhil
Andy Shevchenko Jan. 21, 2022, 2 p.m. UTC | #2
On Fri, Jan 21, 2022 at 2:50 PM Akhil R <akhilrajeev@nvidia.com> wrote:
>
> > > Added details and example for named interrupts in the ACPI table.
> >
> > Added details and example for --> Add a detailed example of the
> >
> > ...
> >
> > > +            Interrupt (ResourceConsumer, Level, ActiveHigh, Exclusive) {
> > > +                0x20,
> >
> > I would think of splitting this to two separate entries in between of which the
> > GpioInt() resource is provided. It will explicitly show that you describe the case
> > only for Interrupt(). Something like
> >
> >   Interrupt (...) { 0x20 }
> >   GpioInt(...) { ... }
> >   Interrupt (...) { 0x24 }
> >
> > But it's up to you.
> Instead, would it be good to add a statement mentioning this explicitly. Something
> like -
>
>     The interrupt name 'default' will correspond to 0x20 in Interrupt()
>     resource and 'alert' to 0x24. Note that only the Interrupt() resource
>     is mapped and not GpioInt() or similar.
>
> I feel mixing these in the example would add a bit of confusion to the reader.

That's why I added "up to you" in my previous reply. I also thought
about the example being a bit confusing for a reader who is
non-familiar with the ACPI.
diff mbox series

Patch

diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst
index 74b830b2..595deba 100644
--- a/Documentation/firmware-guide/acpi/enumeration.rst
+++ b/Documentation/firmware-guide/acpi/enumeration.rst
@@ -143,6 +143,44 @@  In robust cases the client unfortunately needs to call
 acpi_dma_request_slave_chan_by_index() directly and therefore choose the
 specific FixedDMA resource by its index.
 
+Named Interrupts
+================
+
+Drivers enumerated via ACPI can have names to interrupts in the ACPI table
+which can be used to get the IRQ number in the driver.
+
+The interrupt name can be listed in _DSD as 'interrupt-names'. The names
+should be listed as an array of strings which will map to the Interrupt()
+resource in the ACPI table corresponding to its index.
+
+The table below shows an example of its usage::
+
+    Device (DEV0) {
+        ...
+        Name (_CRS, ResourceTemplate() {
+            ...
+            Interrupt (ResourceConsumer, Level, ActiveHigh, Exclusive) {
+                0x20,
+                0x24
+            }
+        })
+
+        Name (_DSD, Package () {
+            ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+            Package () {
+                Package () {"interrupt-names",
+                Package (2) {"default", "alert"}},
+            }
+        ...
+        })
+    }
+
+The interrupt name 'default' will correspond to 0x20 in Interrupt()
+resource and 'alert' to 0x24.
+
+The driver can call the function - device_irq_get_byname() with the device
+and interrupt name as arguments to get the corresponding IRQ number.
+
 SPI serial bus support
 ======================