Am 25.04.23 um 18:30 schrieb Hans de Goede:
Hi All,
Armin thank you very mich for the WMI documentation work,
this is much appreciated!
On 4/25/23 05:07, Randy Dunlap wrote:
Hi--
On 4/24/23 15:29, Armin Wolf wrote:
Add documentation for the WMI subsystem. The documentation describes
both the ACPI WMI interface and the driver API for interacting with
the WMI driver core. The information regarding the ACPI interface
was retrieved from the Ubuntu kernel references and the Windows driver
samples available on GitHub. The documentation is supposed to help
driver developers writing WMI drivers, as many modern machines designed
to run Windows provide an ACPI WMI interface.
Signed-off-by: Armin Wolf <W_Armin@xxxxxx>
---
Documentation/driver-api/index.rst | 1 +
Documentation/driver-api/wmi.rst | 21 ++++++
Documentation/subsystem-apis.rst | 1 +
Documentation/wmi/acpi-interface.rst | 96 ++++++++++++++++++++++++++++
Documentation/wmi/index.rst | 18 ++++++
MAINTAINERS | 2 +
6 files changed, 139 insertions(+)
create mode 100644 Documentation/driver-api/wmi.rst
create mode 100644 Documentation/wmi/acpi-interface.rst
create mode 100644 Documentation/wmi/index.rst
diff --git a/Documentation/driver-api/wmi.rst b/Documentation/driver-api/wmi.rst
new file mode 100644
index 000000000000..6ca58c8249e5
--- /dev/null
+++ b/Documentation/driver-api/wmi.rst
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+==============
+WMI Driver API
+==============
+
+The WMI driver core supports a more modern bus-based interface for interacting
+with WMI devices, and an older GUID-based interface. The latter interface is
+considered to be deprecated, so new WMI drivers should generally avoid it since
+it has some issues with multiple WMI devices and events sharing the same GUIDs
+and/or notification IDs. The modern bus-based interface instead maps each
+WMI device to a :c:type:`struct wmi_device <wmi_device>`, so it supports
+WMI devices sharing GUIDs and/or notification IDs. Drivers can then register
+a :c:type:`struct wmi_driver <wmi_driver>`, which will be bound to compatible
+WMI devices by the driver core.
+
+.. kernel-doc:: include/linux/wmi.h
+ :internal:
There are no kernel-doc comments in include/linux/wmi.h, so this
causes a kernel-doc warning:
../include/linux/wmi.h:1: warning: no structured comments found
Otherwise this all looks good.
So what is the plan here, is there something we can do to fix this
new warning and should I expect a v3? Or shall I merge this as is ?
Regards,
Hans
I did a complete rebuild of the documentation on my machine, and this
error message did not appear. Also include/linux/wmi.h does include
kernel-doc comments for macros like wmi_driver_register(), so i do not
know why this warning is issued by sphinx.
Armin Wolf
Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Acked-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
thanks.
