| 1 | |
| 2 |
|
| 3 | ============================
|
| 4 | WMI driver development guide
|
| 5 | ============================
|
| 6 |
|
| 7 | The WMI subsystem provides a rich driver API for implementing WMI drivers,
|
| 8 | documented at Documentation/driver-api/wmi.rst. This document will serve
|
| 9 | as an introductory guide for WMI driver writers using this API. It is supposed
|
| 10 | to be a successor to the original LWN article which deals with WMI drivers
|
| 11 | using the deprecated GUID-based WMI interface.
|
| 12 |
|
| 13 | Obtaining WMI device information
|
| 14 | --------------------------------
|
| 15 |
|
| 16 | Before developing an WMI driver, information about the WMI device in question
|
| 17 | must be obtained. The `lswmi <https://pypi.org/project/lswmi>`_ utility can be
|
| 18 | used to extract detailed WMI device information using the following command:
|
| 19 |
|
| 20 | ::
|
| 21 |
|
| 22 | lswmi -V
|
| 23 |
|
| 24 | The resulting output will contain information about all WMI devices available on
|
| 25 | a given machine, plus some extra information.
|
| 26 |
|
| 27 | In order to find out more about the interface used to communicate with a WMI device,
|
| 28 | the `bmfdec <https://github.com/pali/bmfdec>`_ utilities can be used to decode
|
| 29 | the Binary MOF (Managed Object Format) information used to describe WMI devices.
|
| 30 | The ``wmi-bmof`` driver exposes this information to userspace, see
|
| 31 | Documentation/wmi/devices/wmi-bmof.rst.
|
| 32 |
|
| 33 | In 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 |
|
| 39 | Sometimes, looking at the disassembled ACPI tables used to describe the WMI device
|
| 40 | helps in understanding how the WMI device is supposed to work. The path of the ACPI
|
| 41 | method associated with a given WMI device can be retrieved using the ``lswmi`` utility
|
| 42 | as mentioned above.
|
| 43 |
|
| 44 | If you are attempting to port a driver to Linux and are working on a Windows
|
| 45 | system, `WMIExplorer <https://github.com/vinaypamnani/wmie2>`_ can be useful
|
| 46 | for inspecting available WMI methods and invoking them directly.
|
| 47 |
|
| 48 | Basic WMI driver structure
|
| 49 | --------------------------
|
| 50 |
|
| 51 | The basic WMI driver is build around the struct wmi_driver, which is then bound
|
| 52 | to matching WMI devices using a struct wmi_device_id table:
|
| 53 |
|
| 54 | ::
|
| 55 |
|
| 56 | static const struct wmi_device_id foo_id_table[] = {
|
| 57 | /* Using only uppercase letters is recommended */
|
| 58 | { "936DA01F-9ABD-4D9D-80C7-02AF85C822A8", NULL },
|
| 59 | { }
|
| 60 | };
|
| 61 | MODULE_DEVICE_TABLE(wmi, foo_id_table);
|
| 62 |
|
| 63 | static struct wmi_driver foo_driver = {
|
| 64 | .driver = {
|
| 65 | .name = "foo",
|
| 66 | .probe_type = PROBE_PREFER_ASYNCHRONOUS, /* recommended */
|
| 67 | .pm = pm_sleep_ptr(&foo_dev_pm_ops), /* optional */
|
| 68 | },
|
| 69 | .id_table = foo_id_table,
|
| 70 | .probe = foo_probe,
|
| 71 | .remove = foo_remove, /* optional, devres is preferred */
|
| 72 | .shutdown = foo_shutdown, /* optional, called during shutdown */
|
| 73 | .notify_new = foo_notify, /* optional, for event handling */
|
| 74 | .min_event_size = X, /* optional, simplifies event payload size verification */
|
| 75 | .no_singleton = true, /* required for new WMI drivers */
|
| 76 | };
|
| 77 | module_wmi_driver(foo_driver);
|
| 78 |
|
| 79 | The probe() callback is called when the WMI driver is bound to a matching WMI device. Allocating
|
| 80 | driver-specific data structures and initialising interfaces to other kernel subsystems should
|
| 81 | normally be done in this function.
|
| 82 |
|
| 83 | The remove() callback is then called when the WMI driver is unbound from a WMI device. In order
|
| 84 | to unregister interfaces to other kernel subsystems and release resources, devres should be used.
|
| 85 | This simplifies error handling during probe and often allows to omit this callback entirely, see
|
| 86 | Documentation/driver-api/driver-model/devres.rst for details.
|
| 87 |
|
| 88 | The shutdown() callback is called during shutdown, reboot or kexec. Its sole purpose is to disable
|
| 89 | the WMI device and put it in a well-known state for the WMI driver to pick up later after reboot
|
| 90 | or kexec. Most WMI drivers need no special shutdown handling and can thus omit this callback.
|
| 91 |
|
| 92 | Please note that new WMI drivers are required to be able to be instantiated multiple times,
|
| 93 | and are forbidden from using any deprecated GUID-based or ACPI-based WMI functions. This means
|
| 94 | that the WMI driver should be prepared for the scenario that multiple matching WMI devices are
|
| 95 | present on a given machine.
|
| 96 |
|
| 97 | Because of this, WMI drivers should use the state container design pattern as described in
|
| 98 | Documentation/driver-api/driver-model/design-patterns.rst.
|
| 99 |
|
| 100 | .. warning:: Using both GUID-based and non-GUID-based functions for querying WMI data blocks and
|
| 101 | handling WMI events simultaneously on the same device is guaranteed to corrupt the
|
| 102 | WMI device state and might lead to erratic behaviour.
|
| 103 |
|
| 104 | WMI method drivers
|
| 105 | ------------------
|
| 106 |
|
| 107 | WMI drivers can call WMI device methods using wmidev_invoke_method(). For each WMI method
|
| 108 | invocation the WMI driver needs to provide the instance number and the method ID, as well as
|
| 109 | a buffer with the method arguments and optionally a buffer for the results. When calling WMI
|
| 110 | methods that do not return any values, wmidev_invoke_procedure() should be used instead.
|
| 111 |
|
| 112 | The layout of said buffers is device-specific and described by the Binary MOF data associated
|
| 113 | with a given WMI device. Said Binary MOF data also describes the method ID of a given WMI method
|
| 114 | with the ``WmiMethodId`` qualifier. WMI devices exposing WMI methods usually expose only a single
|
| 115 | instance (instance number 0), but in theory can expose multiple instances as well. In such a case
|
| 116 | the number of instances can be retrieved using wmidev_instance_count().
|
| 117 |
|
| 118 | Take a look at drivers/platform/x86/intel/wmi/thunderbolt.c for an example WMI method driver.
|
| 119 |
|
| 120 | WMI data block drivers
|
| 121 | ----------------------
|
| 122 |
|
| 123 | WMI drivers can query WMI data blocks using wmidev_query_block(), the layout of the returned
|
| 124 | buffer is again device-specific and described by the Binary MOF data. Some WMI data blocks are
|
| 125 | also writeable and can be set using wmidev_set_block(). The number of data block instances can
|
| 126 | again be retrieved using wmidev_instance_count().
|
| 127 |
|
| 128 | Take a look at drivers/platform/x86/intel/wmi/sbl-fw-update.c for an example WMI data block driver.
|
| 129 |
|
| 130 | WMI event drivers
|
| 131 | -----------------
|
| 132 |
|
| 133 | WMI drivers can receive WMI events via the notify_new() callback inside the struct wmi_driver.
|
| 134 | The WMI subsystem will then take care of setting up the WMI event accordingly. Please note that
|
| 135 | the layout of the buffer passed to this callback is device-specific, and freeing of the buffer
|
| 136 | is done by the WMI subsystem itself, not the driver.
|
| 137 |
|
| 138 | The WMI driver core will take care that the notify_new() callback will only be called after
|
| 139 | the probe() callback has been called, and that no events are being received by the driver
|
| 140 | right before and after calling its remove() or shutdown() callback.
|
| 141 |
|
| 142 | However WMI driver developers should be aware that multiple WMI events can be received concurrently,
|
| 143 | so any locking (if necessary) needs to be provided by the WMI driver itself.
|
| 144 |
|
| 145 | The WMI driver can furthermore instruct the WMI driver core to automatically reject WMI events
|
| 146 | that contain a undersized event payload by populating the ``min_event_size`` field inside
|
| 147 | struct wmi_driver. Setting this field to 0 will thus enable the WMI driver to receive WMI events
|
| 148 | without any event payload.
|
| 149 |
|
| 150 | Take a look at drivers/platform/x86/xiaomi-wmi.c for an example WMI event driver.
|
| 151 |
|
| 152 | Exchanging data with the WMI driver core
|
| 153 | ----------------------------------------
|
| 154 |
|
| 155 | WMI drivers can exchange data with the WMI driver core using struct wmi_buffer. The internal
|
| 156 | structure of those buffers is device-specific and only known by the WMI driver. Because of this
|
| 157 | the WMI driver itself is responsible for parsing and validating the data received from its
|
| 158 | WMI device.
|
| 159 |
|
| 160 | The structure of said buffers is described by the MOF data associated with the WMI device in
|
| 161 | question. When such a buffer contains multiple data items it usually makes sense to define a
|
| 162 | C structure and use it during parsing. Since the WMI driver core guarantees that all buffers
|
| 163 | received from a WMI device are aligned on an 8-byte boundary, WMI drivers can simply perform
|
| 164 | a cast between the WMI buffer data and this C structure.
|
| 165 |
|
| 166 | This however should only be done after the size of the buffer was verified to be large enough
|
| 167 | to hold the whole C structure. WMI drivers should reject undersized buffers as they are usually
|
| 168 | sent by the WMI device to signal an internal error. Oversized buffers however should be accepted
|
| 169 | to emulate the behavior of the Windows WMI implementation.
|
| 170 |
|
| 171 | When defining a C structure for parsing WMI buffers the alignment of the data items should be
|
| 172 | respected. This is especially important for 64-bit integers as those have different alignments
|
| 173 | on 64-bit (8-byte alignment) and 32-bit (4-byte alignment) architectures. It is thus a good idea
|
| 174 | to manually specify the alignment of such data items or mark the whole structure as packed when
|
| 175 | appropriate. Integer data items in general are little-endian integers and should be marked as
|
| 176 | such using ``__le64`` and friends. When parsing WMI string data items the struct wmi_string should
|
| 177 | be used as WMI strings have a different layout than C strings.
|
| 178 |
|
| 179 | See Documentation/wmi/acpi-interface.rst for more information regarding the binary format
|
| 180 | of WMI data items.
|
| 181 |
|
| 182 | Handling multiple WMI devices at once
|
| 183 | -------------------------------------
|
| 184 |
|
| 185 | There are many cases of firmware vendors using multiple WMI devices to control different aspects
|
| 186 | of a single physical device. This can make developing WMI drivers complicated, as those drivers
|
| 187 | might need to communicate with each other to present a unified interface to userspace.
|
| 188 |
|
| 189 | On such case involves a WMI event device which needs to talk to a WMI data block device or WMI
|
| 190 | method device upon receiving an WMI event. In such a case, two WMI drivers should be developed,
|
| 191 | one for the WMI event device and one for the other WMI device.
|
| 192 |
|
| 193 | The WMI event device driver has only one purpose: to receive WMI events, validate any additional
|
| 194 | event data and invoke a notifier chain. The other WMI driver adds itself to this notifier chain
|
| 195 | during probing and thus gets notified every time a WMI event is received. This WMI driver might
|
| 196 | then process the event further for example by using an input device.
|
| 197 |
|
| 198 | For other WMI device constellations, similar mechanisms can be used.
|
| 199 |
|
| 200 | Things to avoid
|
| 201 | ---------------
|
| 202 |
|
| 203 | When developing WMI drivers, there are a couple of things which should be avoided:
|
| 204 |
|
| 205 | - usage of the deprecated GUID-based WMI interface which uses GUIDs instead of WMI device structs
|
| 206 | - usage of the deprecated ACPI-based WMI interface which uses ACPI objects instead of plain buffers
|
| 207 | - bypassing of the WMI subsystem when talking to WMI devices
|
| 208 | - WMI drivers which cannot be instantiated multiple times.
|
| 209 |
|
| 210 | Many older WMI drivers violate one or more points from this list. The reason for
|
| 211 | this is that the WMI subsystem evolved significantly over the last two decades,
|
| 212 | so there is a lot of legacy cruft inside older WMI drivers.
|
| 213 |
|
| 214 | New WMI drivers are also required to conform to the linux kernel coding style as specified in
|
| 215 | Documentation/process/coding-style.rst. The checkpatch utility can catch many common coding style
|
| 216 | violations, you can invoke it with the following command:
|
| 217 |
|
| 218 | ::
|
| 219 |
|
| 220 | ./scripts/checkpatch.pl --strict <path to driver file>
|
| 221 |
|
| 222 | References
|
| 223 | ==========
|
| 224 |
|
| 225 |
|