€•©s      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ0/translations/zh_CN/wmi/driver-development-guide”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ0/translations/zh_TW/wmi/driver-development-guide”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ0/translations/it_IT/wmi/driver-development-guide”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ0/translations/ja_JP/wmi/driver-development-guide”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ0/translations/ko_KR/wmi/driver-development-guide”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ0/translations/sp_SP/wmi/driver-development-guide”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ)SPDX-License-Identifier: GPL-2.0-or-later”h]”hŒ)SPDX-License-Identifier: GPL-2.0-or-later”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒJ/var/lib/git/docbuild/linux/Documentation/wmi/driver-development-guide.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒWMI driver development guide”h]”hŒWMI driver development guide”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h KubhŒ	paragraph”“”)”}”(hXa  The WMI subsystem provides a rich driver API for implementing WMI drivers,
documented at Documentation/driver-api/wmi.rst. This document will serve
as an introductory guide for WMI driver writers using this API. It is supposed
to be a successor to the original LWN article [1]_ which deals with WMI drivers
using the deprecated GUID-based WMI interface.”h]”(hX  The WMI subsystem provides a rich driver API for implementing WMI drivers,
documented at Documentation/driver-api/wmi.rst. This document will serve
as an introductory guide for WMI driver writers using this API. It is supposed
to be a successor to the original LWN article ”…””}”(hhËhžhhŸNh NubhŒfootnote_reference”“”)”}”(hŒ[1]_”h]”hŒ1”…””}”(hhÕhžhhŸNh Nubah}”(h]”Œid1”ah ]”h"]”h$]”h&]”Œrefid”Œid2”Œdocname”Œwmi/driver-development-guide”uh1hÓhhËŒresolved”KubhŒL which deals with WMI drivers
using the deprecated GUID-based WMI interface.”…””}”(hhËhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhµ)”}”(hhh]”(hº)”}”(hŒ Obtaining WMI device information”h]”hŒ Obtaining WMI device information”…””}”(hhöhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hhóhžhhŸh³h KubhÊ)”}”(hŒéBefore developing an WMI driver, information about the WMI device in question
must be obtained. The `lswmi <https://pypi.org/project/lswmi>`_ utility can be
used to extract detailed WMI device information using the following command:”h]”(hŒdBefore developing an WMI driver, information about the WMI device in question
must be obtained. The ”…””}”(hj  hžhhŸNh NubhŒ	reference”“”)”}”(hŒ)`lswmi <https://pypi.org/project/lswmi>`_”h]”hŒlswmi”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œname”Œlswmi”Œrefuri”Œhttps://pypi.org/project/lswmi”uh1j  hj  ubhŒtarget”“”)”}”(hŒ! <https://pypi.org/project/lswmi>”h]”h}”(h]”Œlswmi”ah ]”h"]”Œlswmi”ah$]”h&]”Œrefuri”j  uh1j   Œ
referenced”Khj  ubhŒ\ utility can be
used to extract detailed WMI device information using the following command:”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KhhóhžhubhŒliteral_block”“”)”}”(hŒlswmi -V”h]”hŒlswmi -V”…””}”hj<  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j:  hŸh³h KhhóhžhubhÊ)”}”(hŒ~The resulting output will contain information about all WMI devices available on
a given machine, plus some extra information.”h]”hŒ~The resulting output will contain information about all WMI devices available on
a given machine, plus some extra information.”…””}”(hjJ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KhhóhžhubhÊ)”}”(hX_  In order to find out more about the interface used to communicate with a WMI device,
the `bmfdec <https://github.com/pali/bmfdec>`_ utilities can be used to decode
the Binary MOF (Managed Object Format) information used to describe WMI devices.
The ``wmi-bmof`` driver exposes this information to userspace, see
Documentation/wmi/devices/wmi-bmof.rst.”h]”(hŒYIn order to find out more about the interface used to communicate with a WMI device,
the ”…””}”(hjX  hžhhŸNh Nubj  )”}”(hŒ*`bmfdec <https://github.com/pali/bmfdec>`_”h]”hŒbmfdec”…””}”(hj`  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œname”Œbmfdec”j  Œhttps://github.com/pali/bmfdec”uh1j  hjX  ubj!  )”}”(hŒ! <https://github.com/pali/bmfdec>”h]”h}”(h]”Œbmfdec”ah ]”h"]”Œbmfdec”ah$]”h&]”Œrefuri”jp  uh1j   j/  KhjX  ubhŒv utilities can be used to decode
the Binary MOF (Managed Object Format) information used to describe WMI devices.
The ”…””}”(hjX  hžhhŸNh NubhŒliteral”“”)”}”(hŒ``wmi-bmof``”h]”hŒwmi-bmof”…””}”(hj„  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j‚  hjX  ubhŒZ driver exposes this information to userspace, see
Documentation/wmi/devices/wmi-bmof.rst.”…””}”(hjX  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KhhóhžhubhÊ)”}”(hŒcIn order to retrieve the decoded Binary MOF information, use the following command (requires root):”h]”hŒcIn order to retrieve the decoded Binary MOF information, use the following command (requires root):”…””}”(hjœ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K!hhóhžhubj;  )”}”(hŒL./bmf2mof /sys/bus/wmi/devices/05901221-D566-11D1-B2F0-00A0C9062910[-X]/bmof”h]”hŒL./bmf2mof /sys/bus/wmi/devices/05901221-D566-11D1-B2F0-00A0C9062910[-X]/bmof”…””}”hjª  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j:  hŸh³h K%hhóhžhubhÊ)”}”(hX  Sometimes, looking at the disassembled ACPI tables used to describe the WMI device
helps in understanding how the WMI device is supposed to work. The path of the ACPI
method associated with a given WMI device can be retrieved using the ``lswmi`` utility
as mentioned above.”h]”(hŒìSometimes, looking at the disassembled ACPI tables used to describe the WMI device
helps in understanding how the WMI device is supposed to work. The path of the ACPI
method associated with a given WMI device can be retrieved using the ”…””}”(hj¸  hžhhŸNh Nubjƒ  )”}”(hŒ	``lswmi``”h]”hŒlswmi”…””}”(hjÀ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j‚  hj¸  ubhŒ utility
as mentioned above.”…””}”(hj¸  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K'hhóhžhubhÊ)”}”(hŒÚ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.”h]”(hŒUIf you are attempting to port a driver to Linux and are working on a Windows
system, ”…””}”(hjØ  hžhhŸNh Nubj  )”}”(hŒ6`WMIExplorer <https://github.com/vinaypamnani/wmie2>`_”h]”hŒWMIExplorer”…””}”(hjà  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œname”ŒWMIExplorer”j  Œ%https://github.com/vinaypamnani/wmie2”uh1j  hjØ  ubj!  )”}”(hŒ( <https://github.com/vinaypamnani/wmie2>”h]”h}”(h]”Œwmiexplorer”ah ]”h"]”Œwmiexplorer”ah$]”h&]”Œrefuri”jð  uh1j   j/  KhjØ  ubhŒO can be useful
for inspecting available WMI methods and invoking them directly.”…””}”(hjØ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K,hhóhžhubeh}”(h]”Œ obtaining-wmi-device-information”ah ]”h"]”Œ obtaining wmi device information”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒBasic WMI driver structure”h]”hŒBasic WMI driver structure”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h K1ubhÊ)”}”(hŒ‹The basic WMI driver is build around the struct wmi_driver, which is then bound
to matching WMI devices using a struct wmi_device_id table:”h]”hŒ‹The basic WMI driver is build around the struct wmi_driver, which is then bound
to matching WMI devices using a struct wmi_device_id table:”…””}”(hj!  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K3hj  hžhubj;  )”}”(hX  static const struct wmi_device_id foo_id_table[] = {
       { "936DA01F-9ABD-4D9D-80C7-02AF85C822A8", NULL },
       { }
};
MODULE_DEVICE_TABLE(wmi, foo_id_table);

static struct wmi_driver foo_driver = {
      .driver = {
              .name = "foo",
              .probe_type = PROBE_PREFER_ASYNCHRONOUS,        /* recommended */
              .pm = pm_sleep_ptr(&foo_dev_pm_ops),            /* optional */
      },
      .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 */
};
module_wmi_driver(foo_driver);”h]”hX  static const struct wmi_device_id foo_id_table[] = {
       { "936DA01F-9ABD-4D9D-80C7-02AF85C822A8", NULL },
       { }
};
MODULE_DEVICE_TABLE(wmi, foo_id_table);

static struct wmi_driver foo_driver = {
      .driver = {
              .name = "foo",
              .probe_type = PROBE_PREFER_ASYNCHRONOUS,        /* recommended */
              .pm = pm_sleep_ptr(&foo_dev_pm_ops),            /* optional */
      },
      .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 */
};
module_wmi_driver(foo_driver);”…””}”hj/  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j:  hŸh³h K8hj  hžhubhÊ)”}”(hŒáThe probe() callback is called when the WMI driver is bound to a matching WMI device. Allocating
driver-specific data structures and initialising interfaces to other kernel subsystems should
normally be done in this function.”h]”hŒáThe probe() callback is called when the WMI driver is bound to a matching WMI device. Allocating
driver-specific data structures and initialising interfaces to other kernel subsystems should
normally be done in this function.”…””}”(hj=  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KNhj  hžhubhÊ)”}”(hX`  The remove() callback is then called when the WMI driver is unbound from a WMI device. In order
to unregister interfaces to other kernel subsystems and release resources, devres should be used.
This simplifies error handling during probe and often allows to omit this callback entirely, see
Documentation/driver-api/driver-model/devres.rst for details.”h]”hX`  The remove() callback is then called when the WMI driver is unbound from a WMI device. In order
to unregister interfaces to other kernel subsystems and release resources, devres should be used.
This simplifies error handling during probe and often allows to omit this callback entirely, see
Documentation/driver-api/driver-model/devres.rst for details.”…””}”(hjK  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KRhj  hžhubhÊ)”}”(hX!  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.”h]”hX!  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.”…””}”(hjY  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KWhj  hžhubhÊ)”}”(hX'  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
on a given machine.”h]”hX'  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
on a given machine.”…””}”(hjg  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K[hj  hžhubhÊ)”}”(hŒ•Because of this, WMI drivers should use the state container design pattern as described in
Documentation/driver-api/driver-model/design-patterns.rst.”h]”hŒ•Because of this, WMI drivers should use the state container design pattern as described in
Documentation/driver-api/driver-model/design-patterns.rst.”…””}”(hju  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K`hj  hžhubhŒwarning”“”)”}”(hŒÜ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.”h]”hÊ)”}”(hŒÜ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.”h]”hŒÜ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.”…””}”(hj‰  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kchj…  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jƒ  hj  hžhhŸh³h Nubeh}”(h]”Œbasic-wmi-driver-structure”ah ]”h"]”Œbasic wmi driver structure”ah$]”h&]”uh1h´hh¶hžhhŸh³h K1ubhµ)”}”(hhh]”(hº)”}”(hŒWMI method drivers”h]”hŒWMI method drivers”…””}”(hj¨  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj¥  hžhhŸh³h KhubhÊ)”}”(hX­  WMI drivers can call WMI device methods using wmidev_evaluate_method(), the
structure of the ACPI buffer passed to this function is device-specific and usually
needs some tinkering to get right. Looking at the ACPI tables containing the WMI
device usually helps here. The method id and instance number passed to this function
are also device-specific, looking at the decoded Binary MOF is usually enough to
find the right values.”h]”hX­  WMI drivers can call WMI device methods using wmidev_evaluate_method(), the
structure of the ACPI buffer passed to this function is device-specific and usually
needs some tinkering to get right. Looking at the ACPI tables containing the WMI
device usually helps here. The method id and instance number passed to this function
are also device-specific, looking at the decoded Binary MOF is usually enough to
find the right values.”…””}”(hj¶  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kjhj¥  hžhubhÊ)”}”(hŒZThe maximum instance number can be retrieved during runtime using wmidev_instance_count().”h]”hŒZThe maximum instance number can be retrieved during runtime using wmidev_instance_count().”…””}”(hjÄ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kqhj¥  hžhubhÊ)”}”(hŒ_Take a look at drivers/platform/x86/inspur_platform_profile.c for an example WMI method driver.”h]”hŒ_Take a look at drivers/platform/x86/inspur_platform_profile.c for an example WMI method driver.”…””}”(hjÒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kshj¥  hžhubeh}”(h]”Œwmi-method-drivers”ah ]”h"]”Œwmi method drivers”ah$]”h&]”uh1h´hh¶hžhhŸh³h Khubhµ)”}”(hhh]”(hº)”}”(hŒWMI data block drivers”h]”hŒWMI data block drivers”…””}”(hjë  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjè  hžhhŸh³h KvubhÊ)”}”(hŒÚWMI drivers can query WMI device data blocks using wmidev_block_query(), the
structure of the returned ACPI object is again device-specific. Some WMI devices
also allow for setting data blocks using wmidev_block_set().”h]”hŒÚWMI drivers can query WMI device data blocks using wmidev_block_query(), the
structure of the returned ACPI object is again device-specific. Some WMI devices
also allow for setting data blocks using wmidev_block_set().”…””}”(hjù  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kxhjè  hžhubhÊ)”}”(hŒPThe maximum instance number can also be retrieved using wmidev_instance_count().”h]”hŒPThe maximum instance number can also be retrieved using wmidev_instance_count().”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K|hjè  hžhubhÊ)”}”(hŒcTake a look at drivers/platform/x86/intel/wmi/sbl-fw-update.c for an example
WMI data block driver.”h]”hŒcTake a look at drivers/platform/x86/intel/wmi/sbl-fw-update.c for an example
WMI data block driver.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K~hjè  hžhubeh}”(h]”Œwmi-data-block-drivers”ah ]”h"]”Œwmi data block drivers”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kvubhµ)”}”(hhh]”(hº)”}”(hŒWMI event drivers”h]”hŒWMI event drivers”…””}”(hj.  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj+  hžhhŸh³h K‚ubhÊ)”}”(hXW  WMI drivers can receive WMI events via the notify() callback inside the struct wmi_driver.
The WMI subsystem will then take care of setting up the WMI event accordingly. Please note that
the structure of the ACPI object passed to this callback is device-specific, and freeing the
ACPI object is being done by the WMI subsystem, not the driver.”h]”hXW  WMI drivers can receive WMI events via the notify() callback inside the struct wmi_driver.
The WMI subsystem will then take care of setting up the WMI event accordingly. Please note that
the structure of the ACPI object passed to this callback is device-specific, and freeing the
ACPI object is being done by the WMI subsystem, not the driver.”…””}”(hj<  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K„hj+  hžhubhÊ)”}”(hŒõ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() or shutdown() callback.”h]”hŒõ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() or shutdown() callback.”…””}”(hjJ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K‰hj+  hžhubhÊ)”}”(hŒ±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.”h]”hŒ±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.”…””}”(hjX  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khj+  hžhubhÊ)”}”(hŒžIn order to be able to receive WMI events containing no additional event data,
the ``no_notify_data`` flag inside struct wmi_driver should be set to ``true``.”h]”(hŒSIn order to be able to receive WMI events containing no additional event data,
the ”…””}”(hjf  hžhhŸNh Nubjƒ  )”}”(hŒ``no_notify_data``”h]”hŒno_notify_data”…””}”(hjn  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j‚  hjf  ubhŒ0 flag inside struct wmi_driver should be set to ”…””}”(hjf  hžhhŸNh Nubjƒ  )”}”(hŒ``true``”h]”hŒtrue”…””}”(hj€  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j‚  hjf  ubhŒ.”…””}”(hjf  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khj+  hžhubhÊ)”}”(hŒQTake a look at drivers/platform/x86/xiaomi-wmi.c for an example WMI event driver.”h]”hŒQTake a look at drivers/platform/x86/xiaomi-wmi.c for an example WMI event driver.”…””}”(hj˜  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K“hj+  hžhubeh}”(h]”Œwmi-event-drivers”ah ]”h"]”Œwmi event drivers”ah$]”h&]”uh1h´hh¶hžhhŸh³h K‚ubhµ)”}”(hhh]”(hº)”}”(hŒ%Handling multiple WMI devices at once”h]”hŒ%Handling multiple WMI devices at once”…””}”(hj±  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj®  hžhhŸh³h K–ubhÊ)”}”(hX  There are many cases of firmware vendors using multiple WMI devices to control different aspects
of a single physical device. This can make developing WMI drivers complicated, as those drivers
might need to communicate with each other to present a unified interface to userspace.”h]”hX  There are many cases of firmware vendors using multiple WMI devices to control different aspects
of a single physical device. This can make developing WMI drivers complicated, as those drivers
might need to communicate with each other to present a unified interface to userspace.”…””}”(hj¿  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K˜hj®  hžhubhÊ)”}”(hŒýOn such case involves a WMI event device which needs to talk to a WMI data block device or WMI
method device upon receiving an WMI event. In such a case, two WMI drivers should be developed,
one for the WMI event device and one for the other WMI device.”h]”hŒýOn such case involves a WMI event device which needs to talk to a WMI data block device or WMI
method device upon receiving an WMI event. In such a case, two WMI drivers should be developed,
one for the WMI event device and one for the other WMI device.”…””}”(hjÍ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kœhj®  hžhubhÊ)”}”(hXe  The WMI event device driver has only one purpose: to receive WMI events, validate any additional
event data and invoke a notifier chain. The other WMI driver adds itself to this notifier chain
during probing and thus gets notified every time a WMI event is received. This WMI driver might
then process the event further for example by using an input device.”h]”hXe  The WMI event device driver has only one purpose: to receive WMI events, validate any additional
event data and invoke a notifier chain. The other WMI driver adds itself to this notifier chain
during probing and thus gets notified every time a WMI event is received. This WMI driver might
then process the event further for example by using an input device.”…””}”(hjÛ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K hj®  hžhubhÊ)”}”(hŒDFor other WMI device constellations, similar mechanisms can be used.”h]”hŒDFor other WMI device constellations, similar mechanisms can be used.”…””}”(hjé  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K¥hj®  hžhubeh}”(h]”Œ%handling-multiple-wmi-devices-at-once”ah ]”h"]”Œ%handling multiple wmi devices at once”ah$]”h&]”uh1h´hh¶hžhhŸh³h K–ubhµ)”}”(hhh]”(hº)”}”(hŒThings to avoid”h]”hŒThings to avoid”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjÿ  hžhhŸh³h K¨ubhÊ)”}”(hŒRWhen developing WMI drivers, there are a couple of things which should be avoided:”h]”hŒRWhen developing WMI drivers, there are a couple of things which should be avoided:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kªhjÿ  hžhubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒ_usage of the deprecated GUID-based WMI interface which uses GUIDs instead of WMI device structs”h]”hÊ)”}”(hj'  h]”hŒ_usage of the deprecated GUID-based WMI interface which uses GUIDs instead of WMI device structs”…””}”(hj)  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K¬hj%  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j#  hj   hžhhŸh³h Nubj$  )”}”(hŒ:bypassing of the WMI subsystem when talking to WMI devices”h]”hÊ)”}”(hj>  h]”hŒ:bypassing of the WMI subsystem when talking to WMI devices”…””}”(hj@  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K­hj<  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j#  hj   hžhhŸh³h Nubj$  )”}”(hŒ9WMI drivers which cannot be instantiated multiple times.
”h]”hÊ)”}”(hŒ8WMI drivers which cannot be instantiated multiple times.”h]”hŒ8WMI drivers which cannot be instantiated multiple times.”…””}”(hjW  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K®hjS  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j#  hj   hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1j  hŸh³h K¬hjÿ  hžhubhÊ)”}”(hŒÜMany older WMI drivers violate one or more points from this list. The reason for
this is that the WMI subsystem evolved significantly over the last two decades,
so there is a lot of legacy cruft inside older WMI drivers.”h]”hŒÜMany older WMI drivers violate one or more points from this list. The reason for
this is that the WMI subsystem evolved significantly over the last two decades,
so there is a lot of legacy cruft inside older WMI drivers.”…””}”(hjs  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K°hjÿ  hžhubhÊ)”}”(hŒùNew WMI drivers are also required to conform to the linux kernel coding style as specified in
Documentation/process/coding-style.rst. The checkpatch utility can catch many common coding style
violations, you can invoke it with the following command:”h]”hŒùNew WMI drivers are also required to conform to the linux kernel coding style as specified in
Documentation/process/coding-style.rst. The checkpatch utility can catch many common coding style
violations, you can invoke it with the following command:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K´hjÿ  hžhubj;  )”}”(hŒ6./scripts/checkpatch.pl --strict <path to driver file>”h]”hŒ6./scripts/checkpatch.pl --strict <path to driver file>”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j:  hŸh³h Kºhjÿ  hžhubhµ)”}”(hhh]”(hº)”}”(hŒ
References”h]”hŒ
References”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h K½ubhŒfootnote”“”)”}”(hŒ https://lwn.net/Articles/391230/”h]”(hŒlabel”“”)”}”(hŒ1”h]”hŒ1”…””}”(hj¶  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j´  hj°  ubhÊ)”}”(hj²  h]”j  )”}”(hj²  h]”hŒ https://lwn.net/Articles/391230/”…””}”(hjÇ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j²  uh1j  hjÄ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K¿hj°  ubeh}”(h]”håah ]”h"]”Œ1”ah$]”h&]”hßahæhçuh1j®  hŸh³h K¿hj  hžhhèKubeh}”(h]”Œ
references”ah ]”h"]”Œ
references”ah$]”h&]”uh1h´hjÿ  hžhhŸh³h K½ubeh}”(h]”Œthings-to-avoid”ah ]”h"]”Œthings to avoid”ah$]”h&]”uh1h´hh¶hžhhŸh³h K¨ubeh}”(h]”Œwmi-driver-development-guide”ah ]”h"]”Œwmi driver development guide”ah$]”h&]”uh1h´hhhžhhŸh³h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¹NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œ1”]”hÕasŒrefids”}”Œnameids”}”(j÷  jô  j  j
  j+  j(  jz  jw  jú  j÷  j¢  jŸ  jå  jâ  j(  j%  j«  j¨  jü  jù  jï  jì  jç  jä  jß  håuŒ	nametypes”}”(j÷  ‰j  ‰j+  ˆjz  ˆjú  ˆj¢  ‰jå  ‰j(  ‰j«  ‰jü  ‰jï  ‰jç  ‰jß  ˆuh}”(jô  h¶hßhÕj
  hój(  j"  jw  jq  j÷  jñ  jŸ  j  jâ  j¥  j%  jè  j¨  j+  jù  j®  jì  jÿ  jä  j  håj°  uŒfootnote_refs”}”j]  ]”hÕasŒcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”j°  aŒ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”j+  Ks…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.