On 4/25/23 13:29, Armin Wolf wrote: > 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. OK, Hans, go ahead and merge it as is. Thanks. -- ~Randy
