linux-kernel - Re: [PATCH 2/2] platform/x86: wmi: Add bus ABI documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Date: Mon, 24 Jun 2024 17:07:48 +0300 (EEST)
From: Ilpo Järvinen <ilpo.jarvinen@...ux.intel.com>
To: Armin Wolf <W_Armin@....de>
cc: Hans de Goede <hdegoede@...hat.com>, corbet@....net, 
    platform-driver-x86@...r.kernel.org, linux-doc@...r.kernel.org, 
    LKML <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH 2/2] platform/x86: wmi: Add bus ABI documentation

On Thu, 20 Jun 2024, Armin Wolf wrote:

> Add documentation for the WMI bus sysfs interface so userspace
> applications can use it to access additional data about WMI devices.
> 
> Signed-off-by: Armin Wolf <W_Armin@....de>
> ---
>  Documentation/ABI/testing/sysfs-bus-wmi | 79 +++++++++++++++++++++++++
>  MAINTAINERS                             |  1 +
>  2 files changed, 80 insertions(+)
>  create mode 100644 Documentation/ABI/testing/sysfs-bus-wmi
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-wmi b/Documentation/ABI/testing/sysfs-bus-wmi
> new file mode 100644
> index 000000000000..496d602b67c6
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-bus-wmi
> @@ -0,0 +1,79 @@
> +What:		/sys/bus/wmi/devices/.../driver_override
> +Date:		February 2024
> +Contact:	Armin Wolf <W_Armin@....de>
> +Description:
> +		This file allows the driver for a device to be specified which
> +		will override standard ID table matching.
> +		When specified, only a driver with a name matching the value
> +		written to driver_override will have an opportunity to bind
> +		to the device. The override is specified by writing a string
> +		to the driver_override file (echo wmi-event-dummy > \
> +		driver_override) and may be cleared with an empty string

I suggest replacing:

"and" -> ". The override"

> +		(echo > driver_override). This returns the device to standard

". This" -> which

to make the internal referencing crystal clear.

> +		matching rules binding. Writing to driver_override does not
> +		automatically unbind the device from its current driver or make
> +		any attempt to automatically load the specified driver. If no
> +		driver with a matching name is currently loaded in the kernel,
> +		the device will not bind to any driver. This also allows
> +		devices to opt-out of driver binding using a driver_override
> +		name such as "none". Only a single driver may be specified in
> +		the override, there is no support for parsing delimiters.
> +
> +What:		/sys/bus/wmi/devices/.../modalias
> +Date:		November 2015
> +Contact:	Andy Lutomirski <luto@...nel.org>
> +Description:
> +		This file contains the MODALIAS value emitted by uevent for a
> +		given WMI device.
> +
> +		Format: wmi:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.
> +
> +What:		/sys/bus/wmi/devices/.../guid
> +Date:		November 2015
> +Contact:	Andy Lutomirski <luto@...nel.org>
> +Description:
> +		This file contains the GUID used to match WMI devices to
> +		compatible WMI drivers. This GUID is not necessarily unique
> +		inside a given machine, it is solely used to identify the
> +		interface exposed by a given WMI device.
> +
> +What:		/sys/bus/wmi/devices/.../object_id
> +Date:		November 2015
> +Contact:	Andy Lutomirski <luto@...nel.org>
> +Description:
> +		This file contains the WMI object ID used internally to construct
> +		the ACPI method names used by non-event WMI devices. It contains
> +		two ASCII letters.
> +
> +What:		/sys/bus/wmi/devices/.../notify_id
> +Date:		November 2015
> +Contact:	Andy Lutomirski <luto@...nel.org>
> +Description:
> +		This file contains the WMI notify ID used internally to map ACPI
> +		events to WMI event devices. It contains two ASCII letters.
> +
> +What:		/sys/bus/wmi/devices/.../instance_count
> +Date:		November 2015
> +Contact:	Andy Lutomirski <luto@...nel.org>
> +Description:
> +		This file contains the number of WMI object instances being
> +		present on a given WMI device. It contains a non-negative
> +		number.
> +
> +What:		/sys/bus/wmi/devices/.../expensive
> +Date:		November 2015
> +Contact:	Andy Lutomirski <luto@...nel.org>
> +Description:
> +		This file contains a boolean flag signaling if interacting with
> +		the given WMI device will consume significant CPU resources.
> +		The WMI driver core will take care of enabling/disabling such
> +		WMI devices.
> +
> +What:		/sys/bus/wmi/devices/.../setable
> +Date:		May 2017
> +Contact:	Darren Hart (VMware) <dvhart@...radead.org>
> +Description:
> +		This file contains a boolean flags signaling the data block
> +		aassociated with the given WMI device is writable. If the
> +		given WMI device is not associated with a data block, then
> +		this file will not exist.
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 09ff0dfd65cb..4f76d6a5d348 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -392,6 +392,7 @@ ACPI WMI DRIVER
>  M:	Armin Wolf <W_Armin@....de>
>  L:	platform-driver-x86@...r.kernel.org
>  S:	Maintained
> +F:	Documentation/ABI/testing/sysfs-bus-wmi
>  F:	Documentation/driver-api/wmi.rst
>  F:	Documentation/wmi/
>  F:	drivers/platform/x86/wmi.c

Other than the this issue above, this looked fine,

Reviewed-by: Ilpo Järvinen <ilpo.jarvinen@...ux.intel.com>

-- 
 i.