Messages in this thread | | | Date | Mon, 24 Apr 2023 20:07:58 -0700 | Subject | Re: [PATCH v2 3/4] platform/x86: wmi: Add documentation | From | Randy Dunlap <> |
| |
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@gmx.de> > --- > 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.
Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org>
thanks. -- ~Randy
| |