1e8f8b448SArmin Wolf.. SPDX-License-Identifier: GPL-2.0-or-later 2e8f8b448SArmin Wolf 3e8f8b448SArmin Wolf================== 4e8f8b448SArmin WolfACPI WMI interface 5e8f8b448SArmin Wolf================== 6e8f8b448SArmin Wolf 7e8f8b448SArmin WolfThe ACPI WMI interface is a proprietary extension of the ACPI specification made 8e8f8b448SArmin Wolfby Microsoft to allow hardware vendors to embed WMI (Windows Management Instrumentation) 9e8f8b448SArmin Wolfobjects inside their ACPI firmware. Typical functions implemented over ACPI WMI 10e8f8b448SArmin Wolfare hotkey events on modern notebooks and configuration of BIOS options. 11e8f8b448SArmin Wolf 12e8f8b448SArmin WolfPNP0C14 ACPI device 13e8f8b448SArmin Wolf------------------- 14e8f8b448SArmin Wolf 15e8f8b448SArmin WolfDiscovery of WMI objects is handled by defining ACPI devices with a PNP ID 16e8f8b448SArmin Wolfof ``PNP0C14``. These devices will contain a set of ACPI buffers and methods 17e8f8b448SArmin Wolfused for mapping and execution of WMI methods and/or queries. If there exist 18e8f8b448SArmin Wolfmultiple of such devices, then each device is required to have a 19e8f8b448SArmin Wolfunique ACPI UID. 20e8f8b448SArmin Wolf 21e8f8b448SArmin Wolf_WDG buffer 22e8f8b448SArmin Wolf----------- 23e8f8b448SArmin Wolf 24e8f8b448SArmin WolfThe ``_WDG`` buffer is used to discover WMI objects and is required to be 25e8f8b448SArmin Wolfstatic. Its internal structure consists of data blocks with a size of 20 bytes, 26e8f8b448SArmin Wolfcontaining the following data: 27e8f8b448SArmin Wolf 28e8f8b448SArmin Wolf======= =============== ===================================================== 29e8f8b448SArmin WolfOffset Size (in bytes) Content 30e8f8b448SArmin Wolf======= =============== ===================================================== 31e8f8b448SArmin Wolf0x00 16 128 bit Variant 2 object GUID. 32e8f8b448SArmin Wolf0x10 2 2 character method ID or single byte notification ID. 33e8f8b448SArmin Wolf0x12 1 Object instance count. 34e8f8b448SArmin Wolf0x13 1 Object flags. 35e8f8b448SArmin Wolf======= =============== ===================================================== 36e8f8b448SArmin Wolf 37e8f8b448SArmin WolfThe WMI object flags control whether the method or notification ID is used: 38e8f8b448SArmin Wolf 39e8f8b448SArmin Wolf- 0x1: Data block usage is expensive and must be explicitly enabled/disabled. 40e8f8b448SArmin Wolf- 0x2: Data block contains WMI methods. 41e8f8b448SArmin Wolf- 0x4: Data block contains ASCIZ string. 42e8f8b448SArmin Wolf- 0x8: Data block describes a WMI event, use notification ID instead 43e8f8b448SArmin Wolf of method ID. 44e8f8b448SArmin Wolf 45e8f8b448SArmin WolfEach WMI object GUID can appear multiple times inside a system. 46e8f8b448SArmin WolfThe method/notification ID is used to construct the ACPI method names used for 47e8f8b448SArmin Wolfinteracting with the WMI object. 48e8f8b448SArmin Wolf 49e8f8b448SArmin WolfWQxx ACPI methods 50e8f8b448SArmin Wolf----------------- 51e8f8b448SArmin Wolf 52e8f8b448SArmin WolfIf a data block does not contain WMI methods, then its content can be retrieved 53e8f8b448SArmin Wolfby this required ACPI method. The last two characters of the ACPI method name 54e8f8b448SArmin Wolfare the method ID of the data block to query. Their single parameter is an 55e8f8b448SArmin Wolfinteger describing the instance which should be queried. This parameter can be 56e8f8b448SArmin Wolfomitted if the data block contains only a single instance. 57e8f8b448SArmin Wolf 58e8f8b448SArmin WolfWSxx ACPI methods 59e8f8b448SArmin Wolf----------------- 60e8f8b448SArmin Wolf 61e8f8b448SArmin WolfSimilar to the ``WQxx`` ACPI methods, except that it is optional and takes an 62e8f8b448SArmin Wolfadditional buffer as its second argument. The instance argument also cannot 63e8f8b448SArmin Wolfbe omitted. 64e8f8b448SArmin Wolf 65e8f8b448SArmin WolfWMxx ACPI methods 66e8f8b448SArmin Wolf----------------- 67e8f8b448SArmin Wolf 68e8f8b448SArmin WolfUsed for executing WMI methods associated with a data block. The last two 69e8f8b448SArmin Wolfcharacters of the ACPI method name are the method ID of the data block 70e8f8b448SArmin Wolfcontaining the WMI methods. Their first parameter is a integer describing the 71e8f8b448SArmin Wolfinstance which methods should be executed. The second parameter is an integer 72e8f8b448SArmin Wolfdescribing the WMI method ID to execute, and the third parameter is a buffer 73e8f8b448SArmin Wolfcontaining the WMI method parameters. If the data block is marked as containing 74e8f8b448SArmin Wolfan ASCIZ string, then this buffer should contain an ASCIZ string. The ACPI 75e8f8b448SArmin Wolfmethod will return the result of the executed WMI method. 76e8f8b448SArmin Wolf 77e8f8b448SArmin WolfWExx ACPI methods 78e8f8b448SArmin Wolf----------------- 79e8f8b448SArmin Wolf 80e8f8b448SArmin WolfUsed for optionally enabling/disabling WMI events, the last two characters of 81e8f8b448SArmin Wolfthe ACPI method are the notification ID of the data block describing the WMI 82e8f8b448SArmin Wolfevent as hexadecimal value. Their first parameter is an integer with a value 83e8f8b448SArmin Wolfof 0 if the WMI event should be disabled, other values will enable 84e8f8b448SArmin Wolfthe WMI event. 85e8f8b448SArmin Wolf 86e8f8b448SArmin WolfWCxx ACPI methods 87e8f8b448SArmin Wolf----------------- 88e8f8b448SArmin WolfSimilar to the ``WExx`` ACPI methods, except that it controls data collection 89e8f8b448SArmin Wolfinstead of events and thus the last two characters of the ACPI method name are 90e8f8b448SArmin Wolfthe method ID of the data block to enable/disable. 91e8f8b448SArmin Wolf 92e8f8b448SArmin Wolf_WED ACPI method 93e8f8b448SArmin Wolf---------------- 94e8f8b448SArmin Wolf 95e8f8b448SArmin WolfUsed to retrieve additional WMI event data, its single parameter is a integer 96*3c430351SArmin Wolfholding the notification ID of the event. This method should be evaluated every 97*3c430351SArmin Wolftime an ACPI notification is received, since some ACPI implementations use a 98*3c430351SArmin Wolfqueue to store WMI event data items. This queue will overflow after a couple 99*3c430351SArmin Wolfof WMI events are received without retrieving the associated WMI event data. 100