diff options
Diffstat (limited to 'Documentation/wmi/driver-development-guide.rst')
| -rw-r--r-- | Documentation/wmi/driver-development-guide.rst | 15 |
1 files changed, 14 insertions, 1 deletions
diff --git a/Documentation/wmi/driver-development-guide.rst b/Documentation/wmi/driver-development-guide.rst index 429137b2f632..99ef21fc1c1e 100644 --- a/Documentation/wmi/driver-development-guide.rst +++ b/Documentation/wmi/driver-development-guide.rst @@ -41,6 +41,10 @@ helps in understanding how the WMI device is supposed to work. The path of the A method associated with a given WMI device can be retrieved using the ``lswmi`` utility as mentioned above. +If you are attempting to port a driver to Linux and are working on a Windows +system, `WMIExplorer <https://github.com/vinaypamnani/wmie2>`_ can be useful +for inspecting available WMI methods and invoking them directly. + Basic WMI driver structure -------------------------- @@ -64,6 +68,7 @@ to matching WMI devices using a struct wmi_device_id table: .id_table = foo_id_table, .probe = foo_probe, .remove = foo_remove, /* optional, devres is preferred */ + .shutdown = foo_shutdown, /* optional, called during shutdown */ .notify = foo_notify, /* optional, for event handling */ .no_notify_data = true, /* optional, enables events containing no additional data */ .no_singleton = true, /* required for new WMI drivers */ @@ -79,6 +84,10 @@ to unregister interfaces to other kernel subsystems and release resources, devre This simplifies error handling during probe and often allows to omit this callback entirely, see Documentation/driver-api/driver-model/devres.rst for details. +The shutdown() callback is called during shutdown, reboot or kexec. Its sole purpose is to disable +the WMI device and put it in a well-known state for the WMI driver to pick up later after reboot +or kexec. Most WMI drivers need no special shutdown handling and can thus omit this callback. + Please note that new WMI drivers are required to be able to be instantiated multiple times, and are forbidden from using any deprecated GUID-based WMI functions. This means that the WMI driver should be prepared for the scenario that multiple matching WMI devices are present @@ -87,6 +96,10 @@ on a given machine. Because of this, WMI drivers should use the state container design pattern as described in Documentation/driver-api/driver-model/design-patterns.rst. +.. warning:: Using both GUID-based and non-GUID-based functions for querying WMI data blocks and + handling WMI events simultaneously on the same device is guaranteed to corrupt the + WMI device state and might lead to erratic behaviour. + WMI method drivers ------------------ @@ -123,7 +136,7 @@ ACPI object is being done by the WMI subsystem, not the driver. The WMI driver core will take care that the notify() callback will only be called after the probe() callback has been called, and that no events are being received by the driver -right before and after calling its remove() callback. +right before and after calling its remove() or shutdown() callback. However WMI driver developers should be aware that multiple WMI events can be received concurrently, so any locking (if necessary) needs to be provided by the WMI driver itself. |