platform/x86: wmi: Add device specific documentation

Add a place for device-specific documentation of WMI drivers.
The first entry is documentation for the wmi-bmof driver, with
additional documentation being expected to follow.

Signed-off-by: Armin Wolf <W_Armin@gmx.de>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20230424222939.208137-5-W_Armin@gmx.de
Signed-off-by: Hans de Goede <hdegoede@redhat.com>

diff --git a/Documentation/ABI/stable/sysfs-platform-wmi-bmof b/Documentation/ABI/stable/sysfs-platform-wmi-bmof
new file mode 100644 (file)
index 0000000..a786504
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-platform-wmi-bmof
@@ -0,0 +1,7 @@
+What:          /sys/bus/wmi/devices/05901221-D566-11D1-B2F0-00A0C9062910[-X]/bmof
+Date:          Jun 2017
+KernelVersion: 4.13
+Description:
+               Binary MOF metadata used to decribe the details of available ACPI WMI interfaces.
+
+               See Documentation/wmi/devices/wmi-bmof.rst for details.

diff --git a/Documentation/wmi/devices/index.rst b/Documentation/wmi/devices/index.rst
new file mode 100644 (file)
index 0000000..c08735a
--- /dev/null
+++ b/Documentation/wmi/devices/index.rst
@@ -0,0 +1,22 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+=============================
+Driver-specific Documentation
+=============================
+
+This section provides information about various devices supported by
+the Linux kernel, their protocols and driver details.
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+   :glob:
+
+   *
+
+.. only:: subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`

diff --git a/Documentation/wmi/devices/wmi-bmof.rst b/Documentation/wmi/devices/wmi-bmof.rst
new file mode 100644 (file)
index 0000000..ca1ee9a
--- /dev/null
+++ b/Documentation/wmi/devices/wmi-bmof.rst
@@ -0,0 +1,25 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+==============================
+WMI embedded Binary MOF driver
+==============================
+
+Introduction
+============
+
+Many machines embed WMI Binary MOF (Managed Object Format) metadata used to
+describe the details of their ACPI WMI interfaces. The data can be decoded
+with tools like `bmfdec <https://github.com/pali/bmfdec>`_ to obtain a
+human readable WMI interface description, which is useful for developing
+new WMI drivers.
+
+The Binary MOF data can be retrieved from the ``bmof`` sysfs attribute of the
+associated WMI device. Please note that multiple WMI devices containing Binary
+MOF data can exist on a given system.
+
+WMI interface
+=============
+
+The Binary MOF WMI device is identified by the WMI GUID ``05901221-D566-11D1-B2F0-00A0C9062910``.
+The Binary MOF can be obtained by doing a WMI data block query. The result is
+then returned as an ACPI buffer with a variable size.

diff --git a/Documentation/wmi/index.rst b/Documentation/wmi/index.rst
index b29933a863807b32fb0a3a5afe2af76f37b6074a..537cff188e14ceda7380559ebe478a6c00c88e68 100644 (file)
--- a/Documentation/wmi/index.rst
+++ b/Documentation/wmi/index.rst
@@ -8,6 +8,7 @@ WMI Subsystem
    :maxdepth: 1
 
    acpi-interface
+   devices/index
 
 .. only::  subproject and html
 

diff --git a/MAINTAINERS b/MAINTAINERS
index 46ad203dad12f3f2dca6c4e1e326d00aaeaab1c3..fcacf0038d11873184ac0d10b894774423ecbe8e 100644 (file)
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -22739,6 +22739,13 @@ L:     linux-wireless@vger.kernel.org
 S:     Odd fixes
 F:     drivers/net/wireless/legacy/wl3501*
 
+WMI BINARY MOF DRIVER
+L:     platform-drivers-x86@vger.kernel.org
+S:     Orphan
+F:     Documentation/ABI/stable/sysfs-platform-wmi-bmof
+F:     Documentation/wmi/devices/wmi-bmof.rst
+F:     drivers/platform/x86/wmi-bmof.c
+
 WOLFSON MICROELECTRONICS DRIVERS
 L:     patches@opensource.cirrus.com
 S:     Supported

diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
index 22052031c7190097996f778197733a4bf9ad7165..3d5dd9e997a68554277ec2fd637ead63b7eadf55 100644 (file)
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -43,8 +43,8 @@ config WMI_BMOF
        default ACPI_WMI
        help
          Say Y here if you want to be able to read a firmware-embedded
-         WMI Binary MOF data. Using this requires userspace tools and may be
-         rather tedious.
+         WMI Binary MOF (Managed Object Format) data. Using this requires
+         userspace tools and may be rather tedious.
 
          To compile this driver as a module, choose M here: the module will
          be called wmi-bmof.