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..6ca58c8249e5 --- /dev/null +++ b/Documentation/driver-api/wmi.rst @@ -0,0 +1,21 @@ +.. 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 latter interface is +considered to be deprecated, so new 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 `, so it supports +WMI devices sharing GUIDs and/or notification IDs. Drivers can then register +a :c:type:`struct wmi_driver `, which will be bound to compatible +WMI devices by the driver core. + +.. 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..d31af0ed9c08 --- /dev/null +++ b/Documentation/wmi/acpi-interface.rst @@ -0,0 +1,96 @@ +.. 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 method. The last two characters of the ACPI method name +are the method ID of the data block to query. Their single parameter is an +integer describing the instance which should be queried. This 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 describing the +instance which methods should be executed. The second parameter is an 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 +an ASCIZ string, then this buffer should contain 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 7e0b87d5aa2e..46ad203dad12 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -449,6 +449,8 @@ F: include/linux/acpi_viot.h ACPI WMI DRIVER L: platform-driver-x86@vger.kernel.org S: Orphan +F: Documentation/driver-api/wmi.rst +F: Documentation/wmi/ F: drivers/platform/x86/wmi.c F: include/uapi/linux/wmi.h