€•Œ      Œ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ŒPortuguese (Brazilian)”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ0/translations/pt_BR/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j
  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhj  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”j3  uh1j4  Œ
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j  h²hubhŒliteral_block”“”)”}”(hŒlswmi -V”h]”hŒlswmi -V”…””}”hjP  sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1jN  h³hÇh´Khj  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j^  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Khj  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jl  h²hh³Nh´Nubj!  )”}”(hŒ*`bmfdec <https://github.com/pali/bmfdec>`_”h]”hŒbmfdec”…””}”(hjt  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”Œname”Œbmfdec”j2  Œhttps://github.com/pali/bmfdec”uh1j   hjl  ubj5  )”}”(hŒ! <https://github.com/pali/bmfdec>”h]”h}”(h]”Œbmfdec”ah ]”h"]”Œbmfdec”ah$]”h&]”Œrefuri”j„  uh1j4  jC  Khjl  ubhŒv utilities can be used to decode
the Binary MOF (Managed Object Format) information used to describe WMI devices.
The ”…””}”(hjl  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jl  ubhŒZ driver exposes this information to userspace, see
Documentation/wmi/devices/wmi-bmof.rst.”…””}”(hjl  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Khj  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j  h²hubjO  )”}”(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Æuh1jN  h³hÇh´K%hj  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j  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”j2  Œ%https://github.com/vinaypamnani/wmie2”uh1j   hjì  ubj5  )”}”(hŒ( <https://github.com/vinaypamnani/wmie2>”h]”h}”(h]”Œwmiexplorer”ah ]”h"]”Œwmiexplorer”ah$]”h&]”Œrefuri”j  uh1j4  jC  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j  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j5  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K3hj$  h²hubjO  )”}”(hX¦  static const struct wmi_device_id foo_id_table[] = {
       /* Only use uppercase letters! */
       { "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_new = foo_notify,     /* optional, for event handling */
      .min_event_size = X,          /* optional, simplifies event payload size verification */
      .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[] = {
       /* Only use uppercase letters! */
       { "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_new = foo_notify,     /* optional, for event handling */
      .min_event_size = X,          /* optional, simplifies event payload size verification */
      .no_singleton = true,         /* required for new WMI drivers */
};
module_wmi_driver(foo_driver);”…””}”hjC  sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1jN  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jQ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KOh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j_  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KSh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jm  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KXhj$  h²hubhÞ)”}”(hX5  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 or ACPI-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X5  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 or ACPI-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j{  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j‰  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Kah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´Kdh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´KiubhÞ)”}”(hXl  WMI drivers can call WMI device methods using wmidev_invoke_method(). For each WMI method
invocation the WMI driver needs to provide the instance number and the method ID, as well as
a buffer with the method arguments and optionally a buffer for the results. When calling WMI
methods that do not return any values, wmidev_invoke_procedure() should be used instead.”h]”hXl  WMI drivers can call WMI device methods using wmidev_invoke_method(). For each WMI method
invocation the WMI driver needs to provide the instance number and the method ID, as well as
a buffer with the method arguments and optionally a buffer for the results. When calling WMI
methods that do not return any values, wmidev_invoke_procedure() should be used instead.”…””}”(hjÊ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Kkhj¹  h²hubhÞ)”}”(hXÊ  The layout of said buffers is device-specific and described by the Binary MOF data associated
with a given WMI device. Said Binary MOF data also describes the method ID of a given WMI method
with the ``WmiMethodId`` qualifier. WMI devices exposing WMI methods usually expose only a single
instance (instance number 0), but in theory can expose multiple instances as well. In such a case
the number of instances can be retrieved using wmidev_instance_count().”h]”(hŒÈThe layout of said buffers is device-specific and described by the Binary MOF data associated
with a given WMI device. Said Binary MOF data also describes the method ID of a given WMI method
with the ”…””}”(hjØ  h²hh³Nh´Nubj—  )”}”(hŒ``WmiMethodId``”h]”hŒWmiMethodId”…””}”(hjà  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j–  hjØ  ubhŒó qualifier. WMI devices exposing WMI methods usually expose only a single
instance (instance number 0), but in theory can expose multiple instances as well. In such a case
the number of instances can be retrieved using wmidev_instance_count().”…””}”(hjØ  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Kphj¹  h²hubhÞ)”}”(hŒ]Take a look at drivers/platform/x86/intel/wmi/thunderbolt.c for an example WMI method driver.”h]”hŒ]Take a look at drivers/platform/x86/intel/wmi/thunderbolt.c for an example WMI method driver.”…””}”(hjø  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Kvhj¹  h²hubeh}”(h]”Œwmi-method-drivers”ah ]”h"]”Œwmi method drivers”ah$]”h&]”uh1hÈhhÊh²hh³hÇh´KiubhÉ)”}”(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´KyubhÞ)”}”(hXL  WMI drivers can query WMI data blocks using wmidev_query_block(), the layout of the returned
buffer is again device-specific and described by the Binary MOF data. Some WMI data blocks are
also writeable and can be set using wmidev_set_block(). The number of data block instances can
again be retrieved using wmidev_instance_count().”h]”hXL  WMI drivers can query WMI data blocks using wmidev_query_block(), the layout of the returned
buffer is again device-specific and described by the Binary MOF data. Some WMI data blocks are
also writeable and can be set using wmidev_set_block(). The number of data block instances can
again 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´KyubhÉ)”}”(hhh]”(hÎ)”}”(hŒWMI event drivers”h]”hŒWMI event drivers”…””}”(hjF  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhjC  h²hh³hÇh´KƒubhÞ)”}”(hXR  WMI drivers can receive WMI events via the notify_new() callback inside the struct wmi_driver.
The WMI subsystem will then take care of setting up the WMI event accordingly. Please note that
the layout of the buffer passed to this callback is device-specific, and freeing of the buffer
is done by the WMI subsystem itself, not the driver.”h]”hXR  WMI drivers can receive WMI events via the notify_new() callback inside the struct wmi_driver.
The WMI subsystem will then take care of setting up the WMI event accordingly. Please note that
the layout of the buffer passed to this callback is device-specific, and freeing of the buffer
is done by the WMI subsystem itself, not the driver.”…””}”(hjT  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K…hjC  h²hubhÞ)”}”(hŒùThe WMI driver core will take care that the notify_new() 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_new() 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jb  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KŠhjC  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jp  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KŽhjC  h²hubhÞ)”}”(hX4  The WMI driver can furthermore instruct the WMI driver core to automatically reject WMI events
that contain a undersized event payload by populating the ``min_event_size`` field inside
struct wmi_driver. Setting this field to 0 will thus enable the WMI driver to receive WMI events
without any event payload.”h]”(hŒ™The WMI driver can furthermore instruct the WMI driver core to automatically reject WMI events
that contain a undersized event payload by populating the ”…””}”(hj~  h²hh³Nh´Nubj—  )”}”(hŒ``min_event_size``”h]”hŒmin_event_size”…””}”(hj†  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j–  hj~  ubhŒ‰ field inside
struct wmi_driver. Setting this field to 0 will thus enable the WMI driver to receive WMI events
without any event payload.”…””}”(hj~  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K‘hjC  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jC  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Œ(Exchanging data with the WMI driver core”h]”hŒ(Exchanging data with the WMI driver core”…””}”(hj·  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhj´  h²hh³hÇh´K™ubhÞ)”}”(hX#  WMI drivers can exchange data with the WMI driver core using struct wmi_buffer. The internal
structure of those buffers is device-specific and only known by the WMI driver. Because of this
the WMI driver itself is responsible for parsing and validating the data received from its
WMI device.”h]”hX#  WMI drivers can exchange data with the WMI driver core using struct wmi_buffer. The internal
structure of those buffers is device-specific and only known by the WMI driver. Because of this
the WMI driver itself is responsible for parsing and validating the data received from its
WMI device.”…””}”(hjÅ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K›hj´  h²hubhÞ)”}”(hX¬  The structure of said buffers is described by the MOF data associated with the WMI device in
question. When such a buffer contains multiple data items it usually makes sense to define a
C structure and use it during parsing. Since the WMI driver core guarantees that all buffers
received from a WMI device are aligned on an 8-byte boundary, WMI drivers can simply perform
a cast between the WMI buffer data and this C structure.”h]”hX¬  The structure of said buffers is described by the MOF data associated with the WMI device in
question. When such a buffer contains multiple data items it usually makes sense to define a
C structure and use it during parsing. Since the WMI driver core guarantees that all buffers
received from a WMI device are aligned on an 8-byte boundary, WMI drivers can simply perform
a cast between the WMI buffer data and this C structure.”…””}”(hjÓ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K hj´  h²hubhÞ)”}”(hXY  This however should only be done after the size of the buffer was verified to be large enough
to hold the whole C structure. WMI drivers should reject undersized buffers as they are usually
sent by the WMI device to signal an internal error. Oversized buffers however should be accepted
to emulate the behavior of the Windows WMI implementation.”h]”hXY  This however should only be done after the size of the buffer was verified to be large enough
to hold the whole C structure. WMI drivers should reject undersized buffers as they are usually
sent by the WMI device to signal an internal error. Oversized buffers however should be accepted
to emulate the behavior of the Windows WMI implementation.”…””}”(hjá  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K¦hj´  h²hubhÞ)”}”(hX}  When defining a C structure for parsing WMI buffers the alignment of the data items should be
respected. This is especially important for 64-bit integers as those have different alignments
on 64-bit (8-byte alignment) and 32-bit (4-byte alignment) architectures. It is thus a good idea
to manually specify the alignment of such data items or mark the whole structure as packed when
appropriate. Integer data items in general are little-endian integers and should be marked as
such using ``__le64`` and friends. When parsing WMI string data items the struct wmi_string should
be used as WMI strings have a different layout than C strings.”h]”(hXç  When defining a C structure for parsing WMI buffers the alignment of the data items should be
respected. This is especially important for 64-bit integers as those have different alignments
on 64-bit (8-byte alignment) and 32-bit (4-byte alignment) architectures. It is thus a good idea
to manually specify the alignment of such data items or mark the whole structure as packed when
appropriate. Integer data items in general are little-endian integers and should be marked as
such using ”…””}”(hjï  h²hh³Nh´Nubj—  )”}”(hŒ
``__le64``”h]”hŒ__le64”…””}”(hj÷  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j–  hjï  ubhŒŒ and friends. When parsing WMI string data items the struct wmi_string should
be used as WMI strings have a different layout than C strings.”…””}”(hjï  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K«hj´  h²hubhÞ)”}”(hŒlSee Documentation/wmi/acpi-interface.rst for more information regarding the binary format
of WMI data items.”h]”hŒlSee Documentation/wmi/acpi-interface.rst for more information regarding the binary format
of WMI data items.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K³hj´  h²hubeh}”(h]”Œ(exchanging-data-with-the-wmi-driver-core”ah ]”h"]”Œ(exchanging data with the wmi driver core”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j6  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jD  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jR  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jy  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhjv  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jv  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Œausage of the deprecated ACPI-based WMI interface which uses ACPI objects instead of plain buffers”h]”hÞ)”}”(hjµ  h]”hŒausage of the deprecated ACPI-based WMI interface which uses ACPI objects instead of plain buffers”…””}”(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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´Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1j•  h³hÇh´KÍhjv  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j  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KÒhjv  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jv  h²hubjO  )”}”(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Æuh1jN  h³hÇh´KÜhjv  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jD  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jB  hj>  ubhÞ)”}”(hj@  h]”j!  )”}”(hj@  h]”hŒ https://lwn.net/Articles/391230/”…””}”(hjU  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j@  uh1j   hjR  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jv  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<  jŽ  j‹  j  j  j¶  j³  j  j  j@  j=  j±  j®  j"  j  js  jp  j}  jz  ju  jr  jm  hùuŒ	nametypes”}”(j…  ‰j!  ‰j?  ˆjŽ  ˆj  ˆj¶  ‰j  ‰j@  ‰j±  ‰j"  ‰js  ‰j}  ‰ju  ‰jm  ˆuh}”(j‚  hÊhóhéj  j  j<  j6  j‹  j…  j  j  j³  j$  j  j¹  j=  j  j®  jC  j  j´  jp  j%  jz  jv  jr  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.