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