Hi--
On 4/20/23 16:32, Armin Wolf wrote:
> Add documentation for the WMI subsystem. The documentation describes
> both the ACPI WMI interface and the driver API for interacting with
> the WMI driver core. The information regarding the ACPI interface
> where retrieved from the Ubuntu kernel references and the
were? I would say "was".
> Windows driver samples available on GitHub. The documentation is
> supposed to help driver developers writing WMI drivers, as many
> modern machines designed to run Windows provide a ACPI WMI interface.
an ACPI
For the Documentation/ files, AFAIK, we still have an 80-column preferred
limit. coding-style.rst does not say anything about Documentation/ being
exempt from that limit.
>
> Signed-off-by: Armin Wolf <W_Armin@xxxxxx>
> ---
> Documentation/driver-api/index.rst | 1 +
> Documentation/driver-api/wmi.rst | 19 ++++++
> Documentation/subsystem-apis.rst | 1 +
> Documentation/wmi/acpi-interface.rst | 86 ++++++++++++++++++++++++++++
> Documentation/wmi/index.rst | 18 ++++++
> MAINTAINERS | 2 +
> include/linux/wmi.h | 2 +-
> 7 files changed, 128 insertions(+), 1 deletion(-)
> create mode 100644 Documentation/driver-api/wmi.rst
> create mode 100644 Documentation/wmi/acpi-interface.rst
> create mode 100644 Documentation/wmi/index.rst
>
> diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
> index ff9aa1afdc62..1e16a40da3ba 100644
> --- a/Documentation/driver-api/index.rst
> +++ b/Documentation/driver-api/index.rst
> @@ -113,6 +113,7 @@ available subsections can be seen below.
> xillybus
> zorro
> hte/index
> + wmi
>
> .. only:: subproject and html
>
> diff --git a/Documentation/driver-api/wmi.rst b/Documentation/driver-api/wmi.rst
> new file mode 100644
> index 000000000000..06cecbe36afd
> --- /dev/null
> +++ b/Documentation/driver-api/wmi.rst
> @@ -0,0 +1,19 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
> +==============
> +WMI Driver API
> +==============
> +
> +The WMI driver core supports a more modern bus-based interface for interacting with WMI devices,
> +and an older GUID-based interface. The later interface is considered to be deprecated, so new
ITYM latter
> +WMI drivers should generally avoid it since it has some issues with multiple WMI devices and
> +events sharing the same GUIDs and/or notification IDs. The modern bus-based interface instead
> +maps each WMI device to a :c:type:`struct wmi_device <wmi_device>`, so it supports WMI devices
> +sharing GUIDs and/or notification IDs. Drivers can then register a :c:type:`struct wmi_driver <wmi_driver>`,
> +which will get bound to compatible WMI devices by the driver core.
s/get/be/ preferably.
> +
> +.. kernel-doc:: include/linux/wmi.h
> + :internal:
> +
> +.. kernel-doc:: drivers/platform/x86/wmi.c
> + :export:
> diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst
> index b51f38527e14..69f5e4d53bad 100644
> --- a/Documentation/subsystem-apis.rst
> +++ b/Documentation/subsystem-apis.rst
> @@ -57,3 +57,4 @@ needed).
> scheduler/index
> mhi/index
> peci/index
> + wmi/index
> diff --git a/Documentation/wmi/acpi-interface.rst b/Documentation/wmi/acpi-interface.rst
> new file mode 100644
> index 000000000000..c0afdb6c5885
> --- /dev/null
> +++ b/Documentation/wmi/acpi-interface.rst
> @@ -0,0 +1,86 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
> +==================
> +ACPI WMI interface
> +==================
> +
> +The ACPI WMI interface is a proprietary extension of the ACPI specification made by Microsoft
> +to allow hardware vendors to embed WMI (Windows Management Instrumentation) objects inside
> +their ACPI firmware. Typical functions implemented over ACPI WMI are hotkey events on modern
> +notebooks and configuration of BIOS options.
> +
> +PNP0C14 ACPI device
> +-------------------
> +
> +Discovery of WMI objects is handled by defining ACPI devices with a PNP ID of ``PNP0C14``.
> +These devices will contain a set of ACPI buffers and methods used for mapping and execution
> +of WMI methods and/or queries. If there exist multiple of such devices, then each device is
> +required to have a unique ACPI UID.
> +
> +_WDG buffer
> +-----------
> +
> +The ``_WDG`` buffer is used to discover WMI objects and is required to be static. Its internal
> +structure consists of data blocks with a size of 20 bytes, containing the following data:
> +
> +======= =============== =====================================================
> +Offset Size (in bytes) Content
> +======= =============== =====================================================
> +0x00 16 128 bit Variant 2 object GUID.
> +0x10 2 2 character method ID or single byte notification ID.
> +0x12 1 Object instance count.
> +0x13 1 Object flags.
> +======= =============== =====================================================
> +
> +The WMI object flags control whether the method or notification ID is used:
> +
> +- 0x1: Data block usage is expensive and must be explicitly enabled/disabled.
> +- 0x2: Data block contains WMI methods.
> +- 0x4: Data block contains ASCIZ string.
> +- 0x8: Data block describes a WMI event, use notification ID instead of method ID.
> +
> +Each WMI object GUID can appear multiple times inside a system. The method/notification ID
> +is used to construct the ACPI method names used for interacting with the WMI object.
> +
> +WQxx ACPI methods
> +-----------------
> +
> +If a data block does not contain WMI methods, then its content can be retrieved by this required
> +ACPI methods. The last two characters of the ACPI method name are the method ID of the data block
ACPI method.
> +to query. Their single parameter is a integer describing the instance which should be queried. This
an integer
> +parameter can be omitted if the data block contains only a single instance.
> +
> +WSxx ACPI methods
> +-----------------
> +
> +Similar to the ``WQxx`` ACPI methods, except that it is optional and takes an additional buffer
> +as its second argument. The instance argument also cannot be omitted.
> +
> +WMxx ACPI methods
> +-----------------
> +
> +Used for executing WMI methods associated with a data block. The last two characters of the ACPI method
> +name are the method ID of the data block containing the WMI methods. Their first parameter is a integer
an integer
> +describing the instance which methods should be executed. The second parameter is a integer describing
> +the WMI method ID to execute, and the third parameter is a buffer containing the WMI method parameters.
> +If the data block is marked as containing a ASCIZ string, then this buffer should contain a ASCIZ string.
an ASCIZ string, an ASCIZ string.
> +The ACPI method will return the result of the executed WMI method.
> +
> +WExx ACPI methods
> +-----------------
> +
> +Used for optionally enabling/disabling WMI events, the last two characters of the ACPI method are the
> +notification ID of the data block describing the WMI event as hexadecimal value. Their first parameter
> +is an integer with a value of 0 if the WMI event should be disabled, other values will enable the WMI event.
> +
> +WCxx ACPI methods
> +-----------------
> +Similar to the ``WExx`` ACPI methods, except that it controls data collection instead of events
> +and thus the last two characters of the ACPI method name are the method ID of the data block
> +to enable/disable.
> +
> +_WED ACPI method
> +----------------
> +
> +Used to retrieve additional WMI event data, its single parameter is a integer holding the
> +notification ID of the event.
> diff --git a/Documentation/wmi/index.rst b/Documentation/wmi/index.rst
> new file mode 100644
> index 000000000000..b29933a86380
> --- /dev/null
> +++ b/Documentation/wmi/index.rst
> @@ -0,0 +1,18 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
> +=============
> +WMI Subsystem
> +=============
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + acpi-interface
> +
> +.. only:: subproject and html
> +
> +
> + Indices
> + =======
> +
> + * :ref:`genindex`
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 0c9011f5fc17..979d37176429 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -449,6 +449,8 @@ F: include/linux/acpi_viot.h
> ACPI WMI DRIVER
> L: platform-driver-x86@xxxxxxxxxxxxxxx
> S: Orphan
> +F: Documentation/driver-api/wmi.rst
> +F: Documentation/wmi/
> F: drivers/platform/x86/wmi.c
> F: include/uapi/linux/wmi.h
>
> diff --git a/include/linux/wmi.h b/include/linux/wmi.h
> index 88f66b12eef9..87822effdf3c 100644
> --- a/include/linux/wmi.h
> +++ b/include/linux/wmi.h
> @@ -49,7 +49,7 @@ extern int set_required_buffer_size(struct wmi_device *wdev, u64 length);
> *
> * This represents WMI drivers which handle WMI devices.
> * @filter_callback is only necessary for drivers which
> - * want to set up a WMI IOCTL interface.
> + * want to set up a WMI IOCTL interface
Nothing wrong with the ending '.' there.
> */
> struct wmi_driver {
> struct device_driver driver;
> --
> 2.30.2
>
--
~Randy
