1.. SPDX-License-Identifier: GPL-2.0-or-later 2 3============================ 4WMI driver development guide 5============================ 6 7The WMI subsystem provides a rich driver API for implementing WMI drivers, 8documented at Documentation/driver-api/wmi.rst. This document will serve 9as an introductory guide for WMI driver writers using this API. It is supposed 10to be a successor to the original LWN article [1]_ which deals with WMI drivers 11using the deprecated GUID-based WMI interface. 12 13Obtaining WMI device information 14-------------------------------- 15 16Before developing an WMI driver, information about the WMI device in question 17must be obtained. The `lswmi <https://pypi.org/project/lswmi>`_ utility can be 18used to extract detailed WMI device information using the following command: 19 20:: 21 22 lswmi -V 23 24The resulting output will contain information about all WMI devices available on 25a given machine, plus some extra information. 26 27In order to find out more about the interface used to communicate with a WMI device, 28the `bmfdec <https://github.com/pali/bmfdec>`_ utilities can be used to decode 29the Binary MOF (Managed Object Format) information used to describe WMI devices. 30The ``wmi-bmof`` driver exposes this information to userspace, see 31Documentation/wmi/devices/wmi-bmof.rst. 32 33In order to retrieve the decoded Binary MOF information, use the following command (requires root): 34 35:: 36 37 ./bmf2mof /sys/bus/wmi/devices/05901221-D566-11D1-B2F0-00A0C9062910[-X]/bmof 38 39Sometimes, looking at the disassembled ACPI tables used to describe the WMI device 40helps in understanding how the WMI device is supposed to work. The path of the ACPI 41method associated with a given WMI device can be retrieved using the ``lswmi`` utility 42as mentioned above. 43 44If you are attempting to port a driver to Linux and are working on a Windows 45system, `WMIExplorer <https://github.com/vinaypamnani/wmie2>`_ can be useful 46for inspecting available WMI methods and invoking them directly. 47 48Basic WMI driver structure 49-------------------------- 50 51The basic WMI driver is build around the struct wmi_driver, which is then bound 52to matching WMI devices using a struct wmi_device_id table: 53 54:: 55 56 static const struct wmi_device_id foo_id_table[] = { 57 { "936DA01F-9ABD-4D9D-80C7-02AF85C822A8", NULL }, 58 { } 59 }; 60 MODULE_DEVICE_TABLE(wmi, foo_id_table); 61 62 static struct wmi_driver foo_driver = { 63 .driver = { 64 .name = "foo", 65 .probe_type = PROBE_PREFER_ASYNCHRONOUS, /* recommended */ 66 .pm = pm_sleep_ptr(&foo_dev_pm_ops), /* optional */ 67 }, 68 .id_table = foo_id_table, 69 .probe = foo_probe, 70 .remove = foo_remove, /* optional, devres is preferred */ 71 .shutdown = foo_shutdown, /* optional, called during shutdown */ 72 .notify = foo_notify, /* optional, for event handling */ 73 .no_notify_data = true, /* optional, enables events containing no additional data */ 74 .no_singleton = true, /* required for new WMI drivers */ 75 }; 76 module_wmi_driver(foo_driver); 77 78The probe() callback is called when the WMI driver is bound to a matching WMI device. Allocating 79driver-specific data structures and initialising interfaces to other kernel subsystems should 80normally be done in this function. 81 82The remove() callback is then called when the WMI driver is unbound from a WMI device. In order 83to unregister interfaces to other kernel subsystems and release resources, devres should be used. 84This simplifies error handling during probe and often allows to omit this callback entirely, see 85Documentation/driver-api/driver-model/devres.rst for details. 86 87The shutdown() callback is called during shutdown, reboot or kexec. Its sole purpose is to disable 88the WMI device and put it in a well-known state for the WMI driver to pick up later after reboot 89or kexec. Most WMI drivers need no special shutdown handling and can thus omit this callback. 90 91Please note that new WMI drivers are required to be able to be instantiated multiple times, 92and are forbidden from using any deprecated GUID-based WMI functions. This means that the 93WMI driver should be prepared for the scenario that multiple matching WMI devices are present 94on a given machine. 95 96Because of this, WMI drivers should use the state container design pattern as described in 97Documentation/driver-api/driver-model/design-patterns.rst. 98 99.. warning:: Using both GUID-based and non-GUID-based functions for querying WMI data blocks and 100 handling WMI events simultaneously on the same device is guaranteed to corrupt the 101 WMI device state and might lead to erratic behaviour. 102 103WMI method drivers 104------------------ 105 106WMI drivers can call WMI device methods using wmidev_evaluate_method(), the 107structure of the ACPI buffer passed to this function is device-specific and usually 108needs some tinkering to get right. Looking at the ACPI tables containing the WMI 109device usually helps here. The method id and instance number passed to this function 110are also device-specific, looking at the decoded Binary MOF is usually enough to 111find the right values. 112 113The maximum instance number can be retrieved during runtime using wmidev_instance_count(). 114 115Take a look at drivers/platform/x86/inspur_platform_profile.c for an example WMI method driver. 116 117WMI data block drivers 118---------------------- 119 120WMI drivers can query WMI device data blocks using wmidev_block_query(), the 121structure of the returned ACPI object is again device-specific. Some WMI devices 122also allow for setting data blocks using wmidev_block_set(). 123 124The maximum instance number can also be retrieved using wmidev_instance_count(). 125 126Take a look at drivers/platform/x86/intel/wmi/sbl-fw-update.c for an example 127WMI data block driver. 128 129WMI event drivers 130----------------- 131 132WMI drivers can receive WMI events via the notify() callback inside the struct wmi_driver. 133The WMI subsystem will then take care of setting up the WMI event accordingly. Please note that 134the structure of the ACPI object passed to this callback is device-specific, and freeing the 135ACPI object is being done by the WMI subsystem, not the driver. 136 137The WMI driver core will take care that the notify() callback will only be called after 138the probe() callback has been called, and that no events are being received by the driver 139right before and after calling its remove() or shutdown() callback. 140 141However WMI driver developers should be aware that multiple WMI events can be received concurrently, 142so any locking (if necessary) needs to be provided by the WMI driver itself. 143 144In order to be able to receive WMI events containing no additional event data, 145the ``no_notify_data`` flag inside struct wmi_driver should be set to ``true``. 146 147Take a look at drivers/platform/x86/xiaomi-wmi.c for an example WMI event driver. 148 149Handling multiple WMI devices at once 150------------------------------------- 151 152There are many cases of firmware vendors using multiple WMI devices to control different aspects 153of a single physical device. This can make developing WMI drivers complicated, as those drivers 154might need to communicate with each other to present a unified interface to userspace. 155 156On such case involves a WMI event device which needs to talk to a WMI data block device or WMI 157method device upon receiving an WMI event. In such a case, two WMI drivers should be developed, 158one for the WMI event device and one for the other WMI device. 159 160The WMI event device driver has only one purpose: to receive WMI events, validate any additional 161event data and invoke a notifier chain. The other WMI driver adds itself to this notifier chain 162during probing and thus gets notified every time a WMI event is received. This WMI driver might 163then process the event further for example by using an input device. 164 165For other WMI device constellations, similar mechanisms can be used. 166 167Things to avoid 168--------------- 169 170When developing WMI drivers, there are a couple of things which should be avoided: 171 172- usage of the deprecated GUID-based WMI interface which uses GUIDs instead of WMI device structs 173- bypassing of the WMI subsystem when talking to WMI devices 174- WMI drivers which cannot be instantiated multiple times. 175 176Many older WMI drivers violate one or more points from this list. The reason for 177this is that the WMI subsystem evolved significantly over the last two decades, 178so there is a lot of legacy cruft inside older WMI drivers. 179 180New WMI drivers are also required to conform to the linux kernel coding style as specified in 181Documentation/process/coding-style.rst. The checkpatch utility can catch many common coding style 182violations, you can invoke it with the following command: 183 184:: 185 186 ./scripts/checkpatch.pl --strict <path to driver file> 187 188References 189========== 190 191.. [1] https://lwn.net/Articles/391230/ 192