diff mbox series

[4/4] platform/x86: wmi: Add device specific documentation

Message ID 20230420233226.14561-5-W_Armin@gmx.de
State New
Headers
Series platform/x86: wmi: Add subsystem documentation |

Commit Message

Armin Wolf April 20, 2023, 11:32 p.m. UTC 
  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>
---
 .../ABI/stable/sysfs-platform-wmi-bmof        |  7 ++++++
 Documentation/wmi/devices/index.rst           | 22 +++++++++++++++++++
 Documentation/wmi/devices/wmi-bmof.rst        | 22 +++++++++++++++++++
 Documentation/wmi/index.rst                   |  1 +
 MAINTAINERS                                   |  7 ++++++
 5 files changed, 59 insertions(+)
 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

--
2.30.2

Comments

Randy Dunlap April 22, 2023, 2:28 a.m. UTC | #1 
Hi,

On 4/20/23 16:32, Armin Wolf wrote:
> diff --git a/Documentation/wmi/devices/wmi-bmof.rst b/Documentation/wmi/devices/wmi-bmof.rst
> new file mode 100644
> index 000000000000..b558fa46190c
> --- /dev/null
> +++ b/Documentation/wmi/devices/wmi-bmof.rst
> @@ -0,0 +1,22 @@
> +.. SPDX-License-Identifier: GPL-2.0-only
> +
> +==============================
> +WMI embedded Binary MOF driver
> +==============================
> +

Please tell the reader what MOF means.

It would be good in drivers/platform/x86/Kconfig also did that.

> +Introduction
> +============
> +
> +Many machines embed WMI Binary MOF 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 mbox series

Patch

diff --git a/Documentation/ABI/stable/sysfs-platform-wmi-bmof b/Documentation/ABI/stable/sysfs-platform-wmi-bmof
new file mode 100644
index 000000000000..a786504b6027
--- /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 000000000000..c08735a9d7df
--- /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 000000000000..b558fa46190c
--- /dev/null
+++ b/Documentation/wmi/devices/wmi-bmof.rst
@@ -0,0 +1,22 @@ 
+.. SPDX-License-Identifier: GPL-2.0-only
+
+==============================
+WMI embedded Binary MOF driver
+==============================
+
+Introduction
+============
+
+Many machines embed WMI Binary MOF 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 b29933a86380..537cff188e14 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 979d37176429..4d5b1f6d77f6 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -22556,6 +22556,13 @@  L:	linux-wireless@vger.kernel.org
 S:	Odd fixes
 F:	drivers/net/wireless/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