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. Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx> Acked-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx> thanks. -- ~Randy
