From bf4f93c4ca4b6f41e81e83131cf9458d27cf62ee Mon Sep 17 00:00:00 2001
From: Armin Wolf <W_Armin@gmx.de>
Date: Tue, 25 Apr 2023 00:29:39 +0200
Subject: [PATCH] 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>
---
.../ABI/stable/sysfs-platform-wmi-bmof | 7 ++++++
Documentation/wmi/devices/index.rst | 22 ++++++++++++++++
Documentation/wmi/devices/wmi-bmof.rst | 25 +++++++++++++++++++
Documentation/wmi/index.rst | 1 +
MAINTAINERS | 7 ++++++
drivers/platform/x86/Kconfig | 4 +--
6 files changed, 64 insertions(+), 2 deletions(-)
create mode 100644 Documentation/ABI/stable/sysfs-platform-wmi-bmof
create mode 100644 Documentation/wmi/devices/index.rst
create mode 100644 Documentation/wmi/devices/wmi-bmof.rst
diff --git a/Documentation/ABI/stable/sysfs-platform-wmi-bmof b/Documentation/ABI/stable/sysfs-platform-wmi-bmof
new file mode 100644
index 0000000000000..a786504b6027e
--- /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
index 0000000000000..c08735a9d7df3
--- /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
index 0000000000000..ca1ee9a29be3b
--- /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 b29933a863807..537cff188e14c 100644
--- 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 46ad203dad12f..fcacf0038d118 100644
--- 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 22052031c7190..3d5dd9e997a68 100644
--- 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.
--
GitLab