[PATCH-for-4.2,v11,09/11] docs/specs: Add ACPI GED documentation

Commit Message

Shameerali Kolothum Thodi Sept. 18, 2019, 1:06 p.m. UTC

Documents basic concepts of ACPI Generic Event device(GED)
and interface between QEMU and the ACPI BIOS.

Signed-off-by: Shameer Kolothum <[e-mail]>
Reviewed-by: Eric Auger <[e-mail]>
---
Addressed Peter's comments,
 -changed to rst format.
 -typo/grammer corrections.
---
 docs/specs/acpi_hw_reduced_hotplug.rst | 70 ++++++++++++++++++++++++++
 docs/specs/index.rst                   |  1 +
 2 files changed, 71 insertions(+)
 create mode 100644 docs/specs/acpi_hw_reduced_hotplug.rst

Comments

Igor Mammedov Sept. 25, 2019, 3:09 p.m. UTC | #1

On Wed, 18 Sep 2019 14:06:31 +0100
Shameer Kolothum <[e-mail]> wrote:

> Documents basic concepts of ACPI Generic Event device(GED)
> and interface between QEMU and the ACPI BIOS.
> 
> Signed-off-by: Shameer Kolothum <[e-mail]>
> Reviewed-by: Eric Auger <[e-mail]>

Reviewed-by: Igor Mammedov <[e-mail]>

> ---
> Addressed Peter's comments,
>  -changed to rst format.
>  -typo/grammer corrections.
> ---
>  docs/specs/acpi_hw_reduced_hotplug.rst | 70 ++++++++++++++++++++++++++
>  docs/specs/index.rst                   |  1 +
>  2 files changed, 71 insertions(+)
>  create mode 100644 docs/specs/acpi_hw_reduced_hotplug.rst
> 
> diff --git a/docs/specs/acpi_hw_reduced_hotplug.rst b/docs/specs/acpi_hw_reduced_hotplug.rst
> new file mode 100644
> index 0000000000..911a98255b
> --- /dev/null
> +++ b/docs/specs/acpi_hw_reduced_hotplug.rst
> @@ -0,0 +1,70 @@
> +==================================================
> +QEMU and ACPI BIOS Generic Event Device interface
> +==================================================
> +
> +The ACPI *Generic Event Device* (GED) is a HW reduced platform
> +specific device introduced in ACPI v6.1 that handles all platform
> +events, including the hotplug ones. GED is modelled as a device
> +in the namespace with a _HID defined to be ACPI0013. This document
> +describes the interface between QEMU and the ACPI BIOS.
> +
> +GED allows HW reduced platforms to handle interrupts in ACPI ASL
> +statements. It follows a very similar approach to the _EVT method
> +from GPIO events. All interrupts are listed in  _CRS and the handler
> +is written in _EVT method. However, the QEMU implementation uses a
> +single interrupt for the GED device, relying on an IO memory region
> +to communicate the type of device affected by the interrupt. This way,
> +we can support up to 32 events with a unique interrupt.
> +
> +**Here is an example,**
> +
> +::
> +
> +   Device (\_SB.GED)
> +   {
> +       Name (_HID, "ACPI0013")
> +       Name (_UID, Zero)
> +       Name (_CRS, ResourceTemplate ()
> +       {
> +           Interrupt (ResourceConsumer, Edge, ActiveHigh, Exclusive, ,, )
> +           {
> +               0x00000029,
> +           }
> +       })
> +       OperationRegion (EREG, SystemMemory, 0x09080000, 0x04)
> +       Field (EREG, DWordAcc, NoLock, WriteAsZeros)
> +       {
> +           ESEL,   32
> +       }
> +       Method (_EVT, 1, Serialized)
> +       {
> +           Local0 = ESEL // ESEL = IO memory region which specifies the
> +                         // device type.
> +           If (((Local0 & One) == One))
> +           {
> +               MethodEvent1()
> +           }
> +           If ((Local0 & 0x2) == 0x2)
> +           {
> +               MethodEvent2()
> +           }
> +           ...
> +       }
> +   }
> +
> +GED IO interface (4 byte access)
> +--------------------------------
> +**read access:**
> +
> +::
> +
> +   [0x0-0x3] Event selector bit field (32 bit) set by QEMU.
> +
> +    bits:
> +       0: Memory hotplug event
> +       1: System power down event
> +    2-31: Reserved
> +
> +**write_access:**
> +
> +Nothing is expected to be written into GED IO memory
> diff --git a/docs/specs/index.rst b/docs/specs/index.rst
> index 40adb97c5e..984ba44029 100644
> --- a/docs/specs/index.rst
> +++ b/docs/specs/index.rst
> @@ -12,3 +12,4 @@ Contents:
>  
>     ppc-xive
>     ppc-spapr-xive
> +   acpi_hw_reduced_hotplug

Patch

diff --git a/docs/specs/acpi_hw_reduced_hotplug.rst b/docs/specs/acpi_hw_reduced_hotplug.rst
new file mode 100644
index 0000000000..911a98255b
--- /dev/null
+++ b/docs/specs/acpi_hw_reduced_hotplug.rst
@@ -0,0 +1,70 @@ 
+==================================================
+QEMU and ACPI BIOS Generic Event Device interface
+==================================================
+
+The ACPI *Generic Event Device* (GED) is a HW reduced platform
+specific device introduced in ACPI v6.1 that handles all platform
+events, including the hotplug ones. GED is modelled as a device
+in the namespace with a _HID defined to be ACPI0013. This document
+describes the interface between QEMU and the ACPI BIOS.
+
+GED allows HW reduced platforms to handle interrupts in ACPI ASL
+statements. It follows a very similar approach to the _EVT method
+from GPIO events. All interrupts are listed in  _CRS and the handler
+is written in _EVT method. However, the QEMU implementation uses a
+single interrupt for the GED device, relying on an IO memory region
+to communicate the type of device affected by the interrupt. This way,
+we can support up to 32 events with a unique interrupt.
+
+**Here is an example,**
+
+::
+
+   Device (\_SB.GED)
+   {
+       Name (_HID, "ACPI0013")
+       Name (_UID, Zero)
+       Name (_CRS, ResourceTemplate ()
+       {
+           Interrupt (ResourceConsumer, Edge, ActiveHigh, Exclusive, ,, )
+           {
+               0x00000029,
+           }
+       })
+       OperationRegion (EREG, SystemMemory, 0x09080000, 0x04)
+       Field (EREG, DWordAcc, NoLock, WriteAsZeros)
+       {
+           ESEL,   32
+       }
+       Method (_EVT, 1, Serialized)
+       {
+           Local0 = ESEL // ESEL = IO memory region which specifies the
+                         // device type.
+           If (((Local0 & One) == One))
+           {
+               MethodEvent1()
+           }
+           If ((Local0 & 0x2) == 0x2)
+           {
+               MethodEvent2()
+           }
+           ...
+       }
+   }
+
+GED IO interface (4 byte access)
+--------------------------------
+**read access:**
+
+::
+
+   [0x0-0x3] Event selector bit field (32 bit) set by QEMU.
+
+    bits:
+       0: Memory hotplug event
+       1: System power down event
+    2-31: Reserved
+
+**write_access:**
+
+Nothing is expected to be written into GED IO memory
diff --git a/docs/specs/index.rst b/docs/specs/index.rst
index 40adb97c5e..984ba44029 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -12,3 +12,4 @@  Contents:
 
    ppc-xive
    ppc-spapr-xive
+   acpi_hw_reduced_hotplug