| Message ID | 20240620194214.3071-3-W_Armin@gmx.de (mailing list archive) |
|---|---|
| State | Changes Requested, archived |
| Headers | show |
| Series | platform/x86: wmi: Add driver_override support | expand |
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@gmx.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@gmx.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@kernel.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@kernel.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@kernel.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@kernel.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@kernel.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@kernel.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@infradead.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@gmx.de> > L: platform-driver-x86@vger.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@linux.intel.com>
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@gmx.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 + (echo > driver_override). This returns the device to standard + 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@kernel.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@kernel.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@kernel.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@kernel.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@kernel.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@kernel.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@infradead.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@gmx.de> L: platform-driver-x86@vger.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
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@gmx.de> --- Documentation/ABI/testing/sysfs-bus-wmi | 79 +++++++++++++++++++++++++ MAINTAINERS | 1 + 2 files changed, 80 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-bus-wmi -- 2.39.2