Skip to contentSkip to conversation

platform/wmi: Introduce marshalling support

PATCH Superseded Armin Wolf 3 participants 17 messages Jan 9 – Jan 23

Subsystems (6)

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore

Armin Wolf

author maintainer
#0 lore raw

v3 cover platform/wmi: Introduce marshalling support

The Windows WMI-ACPI driver likely uses wmilib [1] to interact with the WMI service in userspace. Said library uses plain byte buffers for exchanging data, so the WMI-ACPI driver has to convert between those byte buffers and ACPI objects returned by the ACPI firmware.

The format of the byte buffer is publicly documented [2], and after some reverse eingineering of the WMI-ACPI driver using a set of custom ACPI tables, the following conversion rules have been discovered:

- ACPI integers are always converted into a uint32
- ACPI strings are converted into special WMI strings
- ACPI buffers are copied as-is
- ACPI packages are unpacked

Extending the ACPI-WMI to perform this kind of marshalling for WMI data blocks, methods and events would give us a number of benefits:

- WMI drivers are not restricted to a fixed set of supported ACPI data types anymore, see dell-wmi-aio (integer vs buffer) and hp-wmi-sensors (string vs buffer)

- correct marshalling of WMI strings when data blocks are marked as requiring ACPI strings instead of ACPI buffers

- development of WMI drivers without having to understand ACPI

This eventually should result in better compatibility with some ACPI firmware implementations and in simpler WMI drivers.

The first patch extends the WMI driver core to perform said marshalling as well as a new API not based on ACPI objects. The next patch adds a KUnit test for testing the marshalling code. The following two patches then add a set of helper functions for dealing with WMI string data together with another KUnit test.

The remaining patches then convert some simple WMI drivers to use the new WMI API and update the driver development guide so that new WMI drivers stop using the ACPI-based API.

The series has been tested on multiple machines, with the xiaomi-wmi and intel-wmi-sbl-fw-update being tested using a set of custom ACPI tables loaded over configFS.

[1] https://learn.microsoft.com/de-de/windows-hardware/drivers/ddi/wmilib/

Changes since v2:
- assert that kmallloc aligns buffer on a 8 byte boundary
- add missing includes
- fix some code style issues

Changes since v1:
- fix spelling issues inside the documentation
- add Reviewed-by tag for the documentation

Armin Wolf (9):
platform/wmi: Introduce marshalling support platform/wmi: Add kunit test for the marshalling code platform/wmi: Add helper functions for WMI string conversions platform/wmi: Add kunit test for the string conversion code platform/x86: intel-wmi-sbl-fw-update: Use new buffer-based WMI API platform/x86/intel/wmi: thunderbolt: Use new buffer-based WMI API platform/x86: xiaomi-wmi: Use new buffer-based WMI API platform/x86: wmi-bmof: Use new buffer-based WMI API platform/wmi: Update driver development guide

 Documentation/driver-api/wmi.rst              |   3 +
 Documentation/wmi/acpi-interface.rst          |  68 +++
 .../wmi/driver-development-guide.rst          |  76 ++-
 drivers/platform/wmi/Kconfig                  |   3 +
 drivers/platform/wmi/Makefile                 |   5 +-
 drivers/platform/wmi/core.c                   | 160 ++++++-
 drivers/platform/wmi/internal.h               |  17 +
 drivers/platform/wmi/marshalling.c            | 241 ++++++++++
 drivers/platform/wmi/string.c                 |  92 ++++
 drivers/platform/wmi/tests/Kconfig            |  27 ++
 drivers/platform/wmi/tests/Makefile           |  11 +
 .../platform/wmi/tests/marshalling_kunit.c    | 449 ++++++++++++++++++
 drivers/platform/wmi/tests/string_kunit.c     | 278 +++++++++++
 .../platform/x86/intel/wmi/sbl-fw-update.c    |  43 +-
 drivers/platform/x86/intel/wmi/thunderbolt.c  |  26 +-
 drivers/platform/x86/wmi-bmof.c               |  34 +-
 drivers/platform/x86/xiaomi-wmi.c             |   5 +-
 include/linux/wmi.h                           |  45 +-
 18 files changed, 1491 insertions(+), 92 deletions(-)
 create mode 100644 drivers/platform/wmi/internal.h
 create mode 100644 drivers/platform/wmi/marshalling.c
 create mode 100644 drivers/platform/wmi/string.c
 create mode 100644 drivers/platform/wmi/tests/Kconfig
 create mode 100644 drivers/platform/wmi/tests/Makefile
 create mode 100644 drivers/platform/wmi/tests/marshalling_kunit.c
 create mode 100644 drivers/platform/wmi/tests/string_kunit.c
Signature · 1 line
2.39.5
author maintainer
#1 lore raw

PATCH v3 1/9 platform/wmi: Introduce marshalling support

The Windows WMI-ACPI driver likely uses wmilib [1] to interact with the WMI service in userspace. Said library uses plain byte buffers for exchanging data, so the WMI-ACPI driver has to convert between those byte buffers and ACPI objects returned by the ACPI firmware.

The format of the byte buffer is publicly documented [2], and after some reverse eingineering of the WMI-ACPI driver using a set of custom ACPI tables, the following conversion rules have been discovered:

- ACPI integers are always converted into a uint32
- ACPI strings are converted into special WMI strings
- ACPI buffers are copied as-is
- ACPI packages are unpacked

Extend the ACPI-WMI driver to also perform this kind of marshalling for WMI data blocks, methods and events. Doing so gives us a number of benefits:

- WMI drivers are not restricted to a fixed set of supported ACPI data types anymore, see dell-wmi-aio (integer vs buffer) and hp-wmi-sensors (string vs buffer)

- correct marshalling of WMI strings when data blocks are marked as requiring ACPI strings instead of ACPI buffers

- development of WMI drivers without having to understand ACPI

This eventually should result in better compatibility with some ACPI firmware implementations and in simpler WMI drivers. There are however some differences between the original Windows driver and the ACPI-WMI driver when it comes to ACPI object conversions:

- the Windows driver copies internal _ACPI_METHOD_ARGUMENT_V1 data structures into the output buffer when encountering nested ACPI packages. This is very likely an error inside the driver itself, so we do not support nested ACPI packages.

- when converting WMI strings (UTF-16LE) into ACPI strings (ASCII), the Windows driver replaces non-ascii characters (ä -> a, & -> ?) instead of returning an error. This behavior is not documented anywhere and might lead to severe errors in some cases (like setting BIOS passwords over WMI), so we simply return an error.

As the current bus-based WMI API is based on ACPI buffers, a new API is necessary. The legacy GUID-based WMI API is not extended to support marshalling, as WMI drivers using said API are expected to move to the bus-based WMI API in the future.

[1] https://learn.microsoft.com/de-de/windows-hardware/drivers/ddi/wmilib/
[2] https://learn.microsoft.com/en-us/windows-hardware/drivers/kernel/
driver-defined-wmi-data-items

---
 drivers/platform/wmi/Makefile      |   2 +-
 drivers/platform/wmi/core.c        | 160 ++++++++++++++++++-
 drivers/platform/wmi/internal.h    |  17 ++
 drivers/platform/wmi/marshalling.c | 241 +++++++++++++++++++++++++++++
 include/linux/wmi.h                |  40 ++++-
 5 files changed, 453 insertions(+), 7 deletions(-)
 create mode 100644 drivers/platform/wmi/internal.h
 create mode 100644 drivers/platform/wmi/marshalling.c
drivers/platform/wmi/Makefile +1 -1
index 98393d7391ec..6f2bf8cc709e 100644
@@ -4,5 +4,5 @@
 # ACPI WMI core
 #
 
-wmi-y			:= core.o
+wmi-y			:= core.o marshalling.o
 obj-$(CONFIG_ACPI_WMI)	+= wmi.o
drivers/platform/wmi/core.c +156 -4

226 lines not on this page · raw message

drivers/platform/wmi/internal.h new file +17 -0
new file mode 100644
index 000000000000..9a39ffa31ad1
@@ -0,0 +1,17 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+/*
+ * Internal interfaces used by the WMI core.
+ *
+ * Copyright (C) 2025 Armin Wolf <[email protected]>
+ */
+
+#ifndef _WMI_INTERNAL_H_
+#define _WMI_INTERNAL_H_
+
+union acpi_object;
+struct wmi_buffer;
+
+int wmi_unmarshal_acpi_object(const union acpi_object *obj, struct wmi_buffer *buffer);
+int wmi_marshal_string(const struct wmi_buffer *buffer, struct acpi_buffer *out);
+
+#endif /* _WMI_INTERNAL_H_ */
drivers/platform/wmi/marshalling.c new file +241 -0

241 lines not on this page · raw message

include/linux/wmi.h +38 -2
index 665ea7dc8a92..81f24d238a2c 100644
@@ -8,9 +8,11 @@
 #ifndef _LINUX_WMI_H
 #define _LINUX_WMI_H
 
+#include <linux/compiler_attributes.h>
 #include <linux/device.h>
 #include <linux/acpi.h>
 #include <linux/mod_devicetable.h>
+#include <linux/types.h>
 
 /**
  * struct wmi_device - WMI device structure
@@ -36,6 +38,37 @@ struct wmi_device {
  */
 #define to_wmi_device(device)	container_of_const(device, struct wmi_device, dev)
 
+/**
+ * struct wmi_buffer - WMI data buffer
+ * @length: Buffer length in bytes
+ * @data: Pointer to the buffer content
+ *
+ * This structure is used to exchange data with the WMI driver core.
+ */
+struct wmi_buffer {
+	size_t length;
+	void *data;
+};
+
+/**
+ * struct wmi_string - WMI string representation
+ * @length: Size of @chars in bytes
+ * @chars: UTF16-LE characters with optional nul termination and padding
+ *
+ * This structure is used when exchanging string data over the WMI interface.
+ */
+struct wmi_string {
+	__le16 length;
+	__le16 chars[];
+} __packed;
+
+int wmidev_invoke_method(struct wmi_device *wdev, u8 instance, u32 method_id,
+			 const struct wmi_buffer *in, struct wmi_buffer *out);
+
+int wmidev_query_block(struct wmi_device *wdev, u8 instance, struct wmi_buffer *out);
+
+int wmidev_set_block(struct wmi_device *wdev, u8 instance, const struct wmi_buffer *in);
+
 acpi_status wmidev_evaluate_method(struct wmi_device *wdev, u8 instance, u32 method_id,
 				   const struct acpi_buffer *in, struct acpi_buffer *out);
 
@@ -54,9 +87,11 @@ u8 wmidev_instance_count(struct wmi_device *wdev);
  * @probe: Callback for device binding
  * @remove: Callback for device unbinding
  * @shutdown: Callback for device shutdown
- * @notify: Callback for receiving WMI events
+ * @notify: Callback for receiving WMI events (deprecated)
+ * @notify_new: Callback for receiving WMI events
  *
- * This represents WMI drivers which handle WMI devices.
+ * This represents WMI drivers which handle WMI devices. The data inside the buffer
+ * passed to the @notify_new callback is guaranteed to be aligned on a 8-byte boundary.
  */
 struct wmi_driver {
 	struct device_driver driver;
@@ -68,6 +103,7 @@ struct wmi_driver {
 	void (*remove)(struct wmi_device *wdev);
 	void (*shutdown)(struct wmi_device *wdev);
 	void (*notify)(struct wmi_device *device, union acpi_object *data);
+	void (*notify_new)(struct wmi_device *device, const struct wmi_buffer *data);
 };
 
 /**
Signature · 1 line
2.39.5
author maintainer
#2 lore raw

PATCH v3 2/9 platform/wmi: Add kunit test for the marshalling code

In reply to Armin Wolf

The marshalling code used by the WMI driver core is implemented as a separate component, suitable for unit tests.

Implmented such a unit test using KUnit. Those unit tests verify that ACPI objects are correctly converted into WMI buffers and that WMI strings are correctly converted into ACPI strings. They also verify that invalid ACPI data (like nested packages) is rejected.

---
 drivers/platform/wmi/Kconfig                  |   2 +
 drivers/platform/wmi/Makefile                 |   3 +
 drivers/platform/wmi/tests/Kconfig            |  16 +
 drivers/platform/wmi/tests/Makefile           |   8 +
 .../platform/wmi/tests/marshalling_kunit.c    | 449 ++++++++++++++++++
 5 files changed, 478 insertions(+)
 create mode 100644 drivers/platform/wmi/tests/Kconfig
 create mode 100644 drivers/platform/wmi/tests/Makefile
 create mode 100644 drivers/platform/wmi/tests/marshalling_kunit.c
drivers/platform/wmi/Kconfig +2 -0
index 77fcbb18746b..21fa3e440042 100644
@@ -31,4 +31,6 @@ config ACPI_WMI_LEGACY_DEVICE_NAMES
 	  userspace applications but will cause the registration of WMI devices with
 	  the same GUID to fail in some corner cases.
 
+source "drivers/platform/wmi/tests/Kconfig"
+
 endif # ACPI_WMI
drivers/platform/wmi/Makefile +3 -0
index 6f2bf8cc709e..93f37ce519ae 100644
@@ -6,3 +6,6 @@
 
 wmi-y			:= core.o marshalling.o
 obj-$(CONFIG_ACPI_WMI)	+= wmi.o
+
+# Unit tests
+obj-y			+= tests/
drivers/platform/wmi/tests/Kconfig new file +16 -0
new file mode 100644
index 000000000000..efcbcb51c251
@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+#
+# ACPI WMI KUnit tests
+#
+
+config ACPI_WMI_MARSHALLING_KUNIT_TEST
+	tristate "KUnit Test for ACPI-WMI marshalling" if !KUNIT_ALL_TESTS
+	depends on KUNIT
+	default KUNIT_ALL_TESTS
+	help
+	  This builds unit tests for the ACPI-WMI marshalling code.
+
+	  For more information on KUnit and unit tests in general, please refer
+	  to the KUnit documentation in Documentation/dev-tools/kunit/.
+
+	  If unsure, say N.
drivers/platform/wmi/tests/Makefile new file +8 -0
new file mode 100644
index 000000000000..252c3125353a
@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+#
+# Makefile for linux/drivers/platform/x86/wmi/tests
+# ACPI WMI KUnit tests
+#
+
+wmi_marshalling_kunit-y				:= marshalling_kunit.o
+obj-$(CONFIG_ACPI_WMI_MARSHALLING_KUNIT_TEST)	+= wmi_marshalling_kunit.o
drivers/platform/wmi/tests/marshalling_kunit.c new file +449 -0

449 lines not on this page · raw message

Signature · 1 line
2.39.5
author maintainer
#3 lore raw

PATCH v3 3/9 platform/wmi: Add helper functions for WMI string conversions

In reply to Armin Wolf

WMI strings are encoded using UTF16-LE characters, forcing WMI drivers to manually convert them to/from standard UTF8 strings. Add a two helper functions for those tasks.

---
 Documentation/driver-api/wmi.rst |  3 ++
 drivers/platform/wmi/Kconfig     |  1 +
 drivers/platform/wmi/Makefile    |  2 +-
 drivers/platform/wmi/string.c    | 92 ++++++++++++++++++++++++++++++++
 include/linux/wmi.h              |  5 ++
 5 files changed, 102 insertions(+), 1 deletion(-)
 create mode 100644 drivers/platform/wmi/string.c
Documentation/driver-api/wmi.rst +3 -0
index db835b43c937..b847bcdcbb09 100644
@@ -16,5 +16,8 @@ which will be bound to compatible WMI devices by the driver core.
 .. kernel-doc:: include/linux/wmi.h
    :internal:
 
+.. kernel-doc:: drivers/platform/wmi/string.c
+   :export:
+
 .. kernel-doc:: drivers/platform/wmi/core.c
    :export:
drivers/platform/wmi/Kconfig +1 -0
index 21fa3e440042..d62f51ff3b7f 100644
@@ -6,6 +6,7 @@
 menuconfig ACPI_WMI
 	tristate "ACPI-WMI support"
 	depends on ACPI && X86
+	select NLS
 	help
 	  This option enables support for the ACPI-WMI driver core.
 
drivers/platform/wmi/Makefile +1 -1
index 93f37ce519ae..2feff94a5594 100644
@@ -4,7 +4,7 @@
 # ACPI WMI core
 #
 
-wmi-y			:= core.o marshalling.o
+wmi-y			:= core.o marshalling.o string.o
 obj-$(CONFIG_ACPI_WMI)	+= wmi.o
 
 # Unit tests
drivers/platform/wmi/string.c new file +92 -0

92 lines not on this page · raw message

include/linux/wmi.h +5 -0
index 81f24d238a2c..75cb0c7cfe57 100644
@@ -62,6 +62,11 @@ struct wmi_string {
 	__le16 chars[];
 } __packed;
 
+ssize_t wmi_string_to_utf8s(const struct wmi_string *str, u8 *dst, size_t length);
+
+ssize_t wmi_string_from_utf8s(struct wmi_string *str, size_t max_chars, const u8 *src,
+			      size_t src_length);
+
 int wmidev_invoke_method(struct wmi_device *wdev, u8 instance, u32 method_id,
 			 const struct wmi_buffer *in, struct wmi_buffer *out);
 
Signature · 1 line
2.39.5
author maintainer
#4 lore raw

PATCH v3 4/9 platform/wmi: Add kunit test for the string conversion code

In reply to Armin Wolf

The string conversion frunctions provided by the WMI driver core have no dependencies on the remaining WMI API, making them suitable for unit tests.

Implement such a unit test using kunit. Those unit tests verify that converting between WMI strings and UTF8 strings works as expected. They also verify that edge cases are handled correctly.

---
 drivers/platform/wmi/tests/Kconfig        |  11 +
 drivers/platform/wmi/tests/Makefile       |   3 +
 drivers/platform/wmi/tests/string_kunit.c | 278 ++++++++++++++++++++++
 3 files changed, 292 insertions(+)
 create mode 100644 drivers/platform/wmi/tests/string_kunit.c
drivers/platform/wmi/tests/Kconfig +11 -0
index efcbcb51c251..f7f0f3c540f5 100644
@@ -14,3 +14,14 @@ config ACPI_WMI_MARSHALLING_KUNIT_TEST
 	  to the KUnit documentation in Documentation/dev-tools/kunit/.
 
 	  If unsure, say N.
+
+config ACPI_WMI_STRING_KUNIT_TEST
+	tristate "KUnit Test for ACPI-WMI string conversion" if !KUNIT_ALL_TESTS
+	depends on KUNIT
+	default KUNIT_ALL_TESTS
+	help
+	  This builds unit tests for the ACPI-WMI string conversion code.
+	  For more information on KUnit and unit tests in general, please refer
+	  to the KUnit documentation in Documentation/dev-tools/kunit/.
+
+	  If unsure, say N.
drivers/platform/wmi/tests/Makefile +3 -0
index 252c3125353a..62c438e26259 100644
@@ -6,3 +6,6 @@
 
 wmi_marshalling_kunit-y				:= marshalling_kunit.o
 obj-$(CONFIG_ACPI_WMI_MARSHALLING_KUNIT_TEST)	+= wmi_marshalling_kunit.o
+
+wmi_string_kunit-y				:= string_kunit.o
+obj-$(CONFIG_ACPI_WMI_STRING_KUNIT_TEST)	+= wmi_string_kunit.o
drivers/platform/wmi/tests/string_kunit.c new file +278 -0

278 lines not on this page · raw message

Signature · 1 line
2.39.5
maintainer
#5 lore raw

Re: [PATCH v3 4/9] platform/wmi: Add kunit test for the string conversion code

Quoted 78 lines · Armin Wolf

The string conversion frunctions provided by the WMI driver core have no dependencies on the remaining WMI API, making them suitable for unit tests.

Implement such a unit test using kunit. Those unit tests verify that converting between WMI strings and UTF8 strings works as expected. They also verify that edge cases are handled correctly.

---
 drivers/platform/wmi/tests/Kconfig        |  11 +
 drivers/platform/wmi/tests/Makefile       |   3 +
 drivers/platform/wmi/tests/string_kunit.c | 278 ++++++++++++++++++++++
 3 files changed, 292 insertions(+)
 create mode 100644 drivers/platform/wmi/tests/string_kunit.c
drivers/platform/wmi/tests/Kconfig +11 -0
index efcbcb51c251..f7f0f3c540f5 100644
@@ -14,3 +14,14 @@ config ACPI_WMI_MARSHALLING_KUNIT_TEST
 	  to the KUnit documentation in Documentation/dev-tools/kunit/.
 
 	  If unsure, say N.
+
+config ACPI_WMI_STRING_KUNIT_TEST
+	tristate "KUnit Test for ACPI-WMI string conversion" if !KUNIT_ALL_TESTS
+	depends on KUNIT
+	default KUNIT_ALL_TESTS
+	help
+	  This builds unit tests for the ACPI-WMI string conversion code.
+	  For more information on KUnit and unit tests in general, please refer
+	  to the KUnit documentation in Documentation/dev-tools/kunit/.
+
+	  If unsure, say N.
drivers/platform/wmi/tests/Makefile +3 -0
index 252c3125353a..62c438e26259 100644
@@ -6,3 +6,6 @@
 
 wmi_marshalling_kunit-y				:= marshalling_kunit.o
 obj-$(CONFIG_ACPI_WMI_MARSHALLING_KUNIT_TEST)	+= wmi_marshalling_kunit.o
+
+wmi_string_kunit-y				:= string_kunit.o
+obj-$(CONFIG_ACPI_WMI_STRING_KUNIT_TEST)	+= wmi_string_kunit.o
drivers/platform/wmi/tests/string_kunit.c new file +26 -0
new file mode 100644
index 000000000000..9aa3ffa85090
@@ -0,0 +1,278 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+/*
+ * KUnit test for the ACPI-WMI string conversion code.
+ *
+ * Copyright (C) 2025 Armin Wolf <[email protected]>
+ */
+
+#include <linux/module.h>
+#include <linux/slab.h>
+#include <linux/string.h>
+#include <linux/wmi.h>
+
+#include <kunit/resource.h>
+#include <kunit/test.h>
+
+#include <asm/byteorder.h>
+
+struct wmi_string_param {
+	const char *name;
+	const struct wmi_string *wmi_string;
+	/*
+	 * Remember that using sizeof() on a struct wmi_string will
+	 * always return a size of two bytes due to the flexible
+	 * array member!
+	 */
+	size_t wmi_string_length;

drivers/platform/wmi/tests/string_kunit.c line 36

Quoted 10 lines
drivers/platform/wmi/tests/string_kunit.c new file +10 -0
+	const u8 *utf8_string;
+	size_t utf8_string_length;
+};
+
+#define TEST_WMI_STRING_LENGTH 12
+
+static const struct wmi_string test_wmi_string = {
+	.length = cpu_to_le16(10),
+	.chars = {
+		cpu_to_le16(u'T'),

I've applied this to for-next and intend to keep these there but FYI these trigger sparse errors. I don't know if they're fixable or not with reasonable effort on kernel side.

$ sparse --version
0.6.4 (Debian: 0.6.4-3)

--
i.

author maintainer
#6 lore raw

Re: [PATCH v3 4/9] platform/wmi: Add kunit test for the string conversion code

Am 12.01.26 um 17:34 schrieb Ilpo Järvinen:

Quoted 85 lines · Armin Wolf
Quoted 84 lines

The string conversion frunctions provided by the WMI driver core have no dependencies on the remaining WMI API, making them suitable for unit tests.

Implement such a unit test using kunit. Those unit tests verify that converting between WMI strings and UTF8 strings works as expected. They also verify that edge cases are handled correctly.

---
  drivers/platform/wmi/tests/Kconfig        |  11 +
  drivers/platform/wmi/tests/Makefile       |   3 +
  drivers/platform/wmi/tests/string_kunit.c | 278 ++++++++++++++++++++++
  3 files changed, 292 insertions(+)

create mode 100644 drivers/platform/wmi/tests/string_kunit.c

drivers/platform/wmi/tests/Kconfig +11 -0
index efcbcb51c251..f7f0f3c540f5 100644
@@ -14,3 +14,14 @@ config ACPI_WMI_MARSHALLING_KUNIT_TEST
  	  to the KUnit documentation in Documentation/dev-tools/kunit/.
 
  	  If unsure, say N.
+
+config ACPI_WMI_STRING_KUNIT_TEST
+	tristate "KUnit Test for ACPI-WMI string conversion" if !KUNIT_ALL_TESTS
+	depends on KUNIT
+	default KUNIT_ALL_TESTS
+	help
+	  This builds unit tests for the ACPI-WMI string conversion code.
+	  For more information on KUnit and unit tests in general, please refer
+	  to the KUnit documentation in Documentation/dev-tools/kunit/.
+
+	  If unsure, say N.
drivers/platform/wmi/tests/Makefile +3 -0
index 252c3125353a..62c438e26259 100644
@@ -6,3 +6,6 @@
 
  wmi_marshalling_kunit-y				:= marshalling_kunit.o
  obj-$(CONFIG_ACPI_WMI_MARSHALLING_KUNIT_TEST)	+= wmi_marshalling_kunit.o
+
+wmi_string_kunit-y				:= string_kunit.o
+obj-$(CONFIG_ACPI_WMI_STRING_KUNIT_TEST)	+= wmi_string_kunit.o
drivers/platform/wmi/tests/string_kunit.c new file +31 -0
new file mode 100644
index 000000000000..9aa3ffa85090
@@ -0,0 +1,278 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+/*
+ * KUnit test for the ACPI-WMI string conversion code.
+ *
+ * Copyright (C) 2025 Armin Wolf <[email protected]>
+ */
+
+#include <linux/module.h>
+#include <linux/slab.h>
+#include <linux/string.h>
+#include <linux/wmi.h>
+
+#include <kunit/resource.h>
+#include <kunit/test.h>
+
+#include <asm/byteorder.h>
+
+struct wmi_string_param {
+	const char *name;
+	const struct wmi_string *wmi_string;
+	/*
+	 * Remember that using sizeof() on a struct wmi_string will
+	 * always return a size of two bytes due to the flexible
+	 * array member!
+	 */
+	size_t wmi_string_length;
+	const u8 *utf8_string;
+	size_t utf8_string_length;
+};
+
+#define TEST_WMI_STRING_LENGTH 12
Quoted 8 lines

drivers/platform/wmi/tests/string_kunit.c line 36

Quoted 5 lines
drivers/platform/wmi/tests/string_kunit.c new file +5 -0
+
+static const struct wmi_string test_wmi_string = {
+	.length = cpu_to_le16(10),
+	.chars = {
+		cpu_to_le16(u'T'),

I've applied this to for-next and intend to keep these there but FYI these trigger sparse errors. I don't know if they're fixable or not with reasonable effort on kernel side.

To me it seems that sparse ignores the u-prefix signaling that the character constant has a length of 16-bits, but good catch.

If this really is a problem then gcc would issue a warning anyway (happened when i was using the 🐧 character which does not fit into a 16-bit character constant).

Thanks,
Armin Wolf

Quoted 7 lines
$ sparse --version
0.6.4 (Debian: 0.6.4-3)

--
i.

maintainer
#7 lore raw

Re: [PATCH v3 4/9] platform/wmi: Add kunit test for the string conversion code

Quoted 100 lines · Armin Wolf

Am 12.01.26 um 17:34 schrieb Ilpo Järvinen:

Quoted 89 lines · Armin Wolf
Quoted 88 lines

The string conversion frunctions provided by the WMI driver core have no dependencies on the remaining WMI API, making them suitable for unit tests.

Implement such a unit test using kunit. Those unit tests verify that converting between WMI strings and UTF8 strings works as expected. They also verify that edge cases are handled correctly.

---
  drivers/platform/wmi/tests/Kconfig        |  11 +
  drivers/platform/wmi/tests/Makefile       |   3 +
  drivers/platform/wmi/tests/string_kunit.c | 278 ++++++++++++++++++++++
  3 files changed, 292 insertions(+)

create mode 100644 drivers/platform/wmi/tests/string_kunit.c

drivers/platform/wmi/tests/Kconfig +3 -0
index efcbcb51c251..f7f0f3c540f5 100644
@@ -14,3 +14,14 @@ config ACPI_WMI_MARSHALLING_KUNIT_TEST
  	  to the KUnit documentation in Documentation/dev-tools/kunit/.
    	  If unsure, say N.
+
+config ACPI_WMI_STRING_KUNIT_TEST
+	tristate "KUnit Test for ACPI-WMI string conversion" if

!KUNIT_ALL_TESTS

drivers/platform/wmi/tests/Kconfig +5 -0
+	depends on KUNIT
+	default KUNIT_ALL_TESTS
+	help
+	  This builds unit tests for the ACPI-WMI string conversion code.
+	  For more information on KUnit and unit tests in general, please

refer

drivers/platform/wmi/tests/Kconfig +3 -0
+	  to the KUnit documentation in Documentation/dev-tools/kunit/.
+
+	  If unsure, say N.
drivers/platform/wmi/tests/Makefile +0 -0
index 252c3125353a..62c438e26259 100644
@@ -6,3 +6,6 @@
    wmi_marshalling_kunit-y				:= marshalling_kunit.o
  obj-$(CONFIG_ACPI_WMI_MARSHALLING_KUNIT_TEST)	+=

wmi_marshalling_kunit.o

drivers/platform/wmi/tests/Makefile +3 -0
+
+wmi_string_kunit-y				:= string_kunit.o
+obj-$(CONFIG_ACPI_WMI_STRING_KUNIT_TEST)	+= wmi_string_kunit.o
drivers/platform/wmi/tests/string_kunit.c new file +31 -0
new file mode 100644
index 000000000000..9aa3ffa85090
@@ -0,0 +1,278 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+/*
+ * KUnit test for the ACPI-WMI string conversion code.
+ *
+ * Copyright (C) 2025 Armin Wolf <[email protected]>
+ */
+
+#include <linux/module.h>
+#include <linux/slab.h>
+#include <linux/string.h>
+#include <linux/wmi.h>
+
+#include <kunit/resource.h>
+#include <kunit/test.h>
+
+#include <asm/byteorder.h>
+
+struct wmi_string_param {
+	const char *name;
+	const struct wmi_string *wmi_string;
+	/*
+	 * Remember that using sizeof() on a struct wmi_string will
+	 * always return a size of two bytes due to the flexible
+	 * array member!
+	 */
+	size_t wmi_string_length;
+	const u8 *utf8_string;
+	size_t utf8_string_length;
+};
+
+#define TEST_WMI_STRING_LENGTH 12
Quoted 8 lines

drivers/platform/wmi/tests/string_kunit.c line 36

Quoted 5 lines
drivers/platform/wmi/tests/string_kunit.c new file +5 -0
+
+static const struct wmi_string test_wmi_string = {
+	.length = cpu_to_le16(10),
+	.chars = {
+		cpu_to_le16(u'T'),

I've applied this to for-next and intend to keep these there but FYI these trigger sparse errors. I don't know if they're fixable or not with reasonable effort on kernel side.

Quoted 7 lines

To me it seems that sparse ignores the u-prefix signaling that the character constant
has a length of 16-bits, but good catch.

If this really is a problem then gcc would issue a warning anyway (happened when i was
using the 🐧 character which does not fit into a 16-bit character constant).

I guess I'll have to add another filter to my build-test.sh for this file. I already -v -e 'error: bad constant expression' filter in use. Sadly sparse seems to be rotting.

Signature · 1 line
 i.
#8 lore raw

Re: [PATCH v3 4/9] platform/wmi: Add kunit test for the string conversion code

In reply to Armin Wolf

Hi Armin,

Quoted 9 lines · Armin Wolf

The string conversion frunctions provided by the WMI driver core have no dependencies on the remaining WMI API, making them suitable for unit tests.

Implement such a unit test using kunit. Those unit tests verify that converting between WMI strings and UTF8 strings works as expected. They also verify that edge cases are handled correctly.

...

Quoted 1 line

+++ b/drivers/platform/wmi/tests/string_kunit.c

...

Quoted 1 line

+static const u8 oversized_test_utf8_string[] = "TEST!";

...

drivers/platform/wmi/tests/string_kunit.c line 229

Quoted 10 lines
drivers/platform/wmi/tests/string_kunit.c new file +10 -0
+static void wmi_string_to_utf8s_oversized_test(struct kunit *test)
+{
+	u8 result[sizeof(oversized_test_utf8_string)];
+	ssize_t ret;
+
+	ret = wmi_string_to_utf8s(&oversized_test_wmi_string, result, sizeof(result));
+
+	KUNIT_EXPECT_EQ(test, ret, sizeof(test_utf8_string) - 1);
+	KUNIT_EXPECT_MEMEQ(test, result, test_utf8_string, sizeof(test_utf8_string));
+}

After this change in -next as commit 0e1a8143e797 ("platform/wmi: Add kunit test for the string conversion code"), I am seeing a warning from clang around oversized_test_utf8_string:

drivers/platform/wmi/tests/string_kunit.c:108:17: error: variable 'oversized_test_utf8_string' is not needed and will not be emitted [-Werror,-Wunneeded-internal-declaration]

    108 | static const u8 oversized_test_utf8_string[] = "TEST!";
        |                 ^~~~~~~~~~~~~~~~~~~~~~~~~~

oversized_test_utf8_string is only used in sizeof() in wmi_string_to_utf8s_oversized_test(). clang warns because sizeof() is evaluated at compile time, so oversized_test_utf8_string won't end up in the final binary. This is typically a bug since the developer may have intended to use the variable elsewhere but I was not able to easily determine that in this case.

If it is intentional that this variable is only needed in sizeof(), it could either be marked with __maybe_unused or eliminated in favor of a direct 'sizeof("TEST!")', depending on maintainer/developer preference. I am happy to send a patch.

Cheers,
Nathan

author maintainer
#9 lore raw

Re: [PATCH v3 4/9] platform/wmi: Add kunit test for the string conversion code

Am 23.01.26 um 00:45 schrieb Nathan Chancellor:

Quoted 42 lines

Hi Armin,

Quoted 9 lines · Armin Wolf

The string conversion frunctions provided by the WMI driver core have no dependencies on the remaining WMI API, making them suitable for unit tests.

Implement such a unit test using kunit. Those unit tests verify that converting between WMI strings and UTF8 strings works as expected. They also verify that edge cases are handled correctly.

...

Quoted 1 line

+++ b/drivers/platform/wmi/tests/string_kunit.c

...

Quoted 1 line

+static const u8 oversized_test_utf8_string[] = "TEST!";

...

drivers/platform/wmi/tests/string_kunit.c line 229

Quoted 10 lines
drivers/platform/wmi/tests/string_kunit.c new file +10 -0
+static void wmi_string_to_utf8s_oversized_test(struct kunit *test)
+{
+	u8 result[sizeof(oversized_test_utf8_string)];
+	ssize_t ret;
+
+	ret = wmi_string_to_utf8s(&oversized_test_wmi_string, result, sizeof(result));
+
+	KUNIT_EXPECT_EQ(test, ret, sizeof(test_utf8_string) - 1);
+	KUNIT_EXPECT_MEMEQ(test, result, test_utf8_string, sizeof(test_utf8_string));
+}

After this change in -next as commit 0e1a8143e797 ("platform/wmi: Add kunit test for the string conversion code"), I am seeing a warning from clang around oversized_test_utf8_string:

   drivers/platform/wmi/tests/string_kunit.c:108:17: error: variable 'oversized_test_utf8_string' is not needed and will not be emitted [-Werror,-Wunneeded-internal-declaration]
     108 | static const u8 oversized_test_utf8_string[] = "TEST!";
         |                 ^~~~~~~~~~~~~~~~~~~~~~~~~~

oversized_test_utf8_string is only used in sizeof() in wmi_string_to_utf8s_oversized_test(). clang warns because sizeof() is evaluated at compile time, so oversized_test_utf8_string won't end up in the final binary. This is typically a bug since the developer may have intended to use the variable elsewhere but I was not able to easily determine that in this case.

Quoted 7 lines

If it is intentional that this variable is only needed in sizeof(), it could either be marked with __maybe_unused or eliminated in favor of a direct 'sizeof("TEST!")', depending on maintainer/developer preference. I am happy to send a patch.

Cheers,
Nathan

Good catch, it seems that i forgot to add the test case that was supposed to use oversized_test_utf8_string. I will send a patch that adds this missing test case, fixing this warning in the process.

Thanks,
Armin Wolf

author maintainer
#10 lore raw

PATCH v3 5/9 platform/x86: intel-wmi-sbl-fw-update: Use new buffer-based WMI API

In reply to Armin Wolf

Use the new buffer-based WMI API to also support ACPI firmware implementations that return a ACPI buffer instead of a ACPI integer.

---
 .../platform/x86/intel/wmi/sbl-fw-update.c    | 43 ++++++++-----------
 1 file changed, 18 insertions(+), 25 deletions(-)
drivers/platform/x86/intel/wmi/sbl-fw-update.c +18 -25
index 75c82c08117f..3716ccaaed6a 100644
@@ -14,7 +14,6 @@
  * https://slimbootloader.github.io/security/firmware-update.html
  */
 
-#include <linux/acpi.h>
 #include <linux/device.h>
 #include <linux/module.h>
 #include <linux/slab.h>
@@ -25,41 +24,35 @@
 
 static int get_fwu_request(struct device *dev, u32 *out)
 {
-	union acpi_object *obj;
+	struct wmi_buffer buffer;
+	__le32 *result;
+	int ret;
 
-	obj = wmidev_block_query(to_wmi_device(dev), 0);
-	if (!obj)
-		return -ENODEV;
+	ret = wmidev_query_block(to_wmi_device(dev), 0, &buffer);
+	if (ret < 0)
+		return ret;
 
-	if (obj->type != ACPI_TYPE_INTEGER) {
-		dev_warn(dev, "wmidev_block_query returned invalid value\n");
-		kfree(obj);
-		return -EINVAL;
+	if (buffer.length < sizeof(*result)) {
+		kfree(buffer.data);
+		return -ENODATA;
 	}
 
-	*out = obj->integer.value;
-	kfree(obj);
+	result = buffer.data;
+	*out = le32_to_cpu(*result);
+	kfree(result);
 
 	return 0;
 }
 
 static int set_fwu_request(struct device *dev, u32 in)
 {
-	struct acpi_buffer input;
-	acpi_status status;
-	u32 value;
-
-	value = in;
-	input.length = sizeof(u32);
-	input.pointer = &value;
-
-	status = wmidev_block_set(to_wmi_device(dev), 0, &input);
-	if (ACPI_FAILURE(status)) {
-		dev_err(dev, "wmidev_block_set failed\n");
-		return -ENODEV;
-	}
+	__le32 value = cpu_to_le32(in);
+	struct wmi_buffer buffer = {
+		.length = sizeof(value),
+		.data = &value,
+	};
 
-	return 0;
+	return wmidev_set_block(to_wmi_device(dev), 0, &buffer);
 }
 
 static ssize_t firmware_update_request_show(struct device *dev,
Signature · 1 line
2.39.5
author maintainer
#11 lore raw

PATCH v3 6/9 platform/x86/intel/wmi: thunderbolt: Use new buffer-based WMI API

In reply to Armin Wolf

Use the new buffer-based WMI API to avoid having to deal with ACPI at all.

---
 drivers/platform/x86/intel/wmi/thunderbolt.c | 26 +++++++++-----------
 1 file changed, 11 insertions(+), 15 deletions(-)
drivers/platform/x86/intel/wmi/thunderbolt.c +11 -15
index 08df560a2c7a..f01dd096c689 100644
@@ -7,7 +7,6 @@
 
 #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
 
-#include <linux/acpi.h>
 #include <linux/device.h>
 #include <linux/fs.h>
 #include <linux/kernel.h>
@@ -23,24 +22,21 @@ static ssize_t force_power_store(struct device *dev,
 				 struct device_attribute *attr,
 				 const char *buf, size_t count)
 {
-	struct acpi_buffer input;
-	acpi_status status;
+	struct wmi_buffer buffer;
+	int ret;
 	u8 mode;
 
-	input.length = sizeof(u8);
-	input.pointer = &mode;
+	buffer.length = sizeof(mode);
+	buffer.data = &mode;
+
 	mode = hex_to_bin(buf[0]);
-	dev_dbg(dev, "force_power: storing %#x\n", mode);
-	if (mode == 0 || mode == 1) {
-		status = wmidev_evaluate_method(to_wmi_device(dev), 0, 1, &input, NULL);
-		if (ACPI_FAILURE(status)) {
-			dev_dbg(dev, "force_power: failed to evaluate ACPI method\n");
-			return -ENODEV;
-		}
-	} else {
-		dev_dbg(dev, "force_power: unsupported mode\n");
+	if (mode > 1)
 		return -EINVAL;
-	}
+
+	ret = wmidev_invoke_method(to_wmi_device(dev), 0, 1, &buffer, NULL);
+	if (ret < 0)
+		return ret;
+
 	return count;
 }
 
Signature · 1 line
2.39.5
author maintainer
#12 lore raw

PATCH v3 7/9 platform/x86: xiaomi-wmi: Use new buffer-based WMI API

In reply to Armin Wolf

Use the new buffer-based WMI API to avoid having to deal with ACPI at all.

---
 drivers/platform/x86/xiaomi-wmi.c | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)
drivers/platform/x86/xiaomi-wmi.c +2 -3
index b892007b9863..badf9e42e015 100644
@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: GPL-2.0
 /* WMI driver for Xiaomi Laptops */
 
-#include <linux/acpi.h>
 #include <linux/device.h>
 #include <linux/input.h>
 #include <linux/module.h>
@@ -56,7 +55,7 @@ static int xiaomi_wmi_probe(struct wmi_device *wdev, const void *context)
 	return input_register_device(data->input_dev);
 }
 
-static void xiaomi_wmi_notify(struct wmi_device *wdev, union acpi_object *dummy)
+static void xiaomi_wmi_notify(struct wmi_device *wdev, const struct wmi_buffer *dummy)
 {
 	struct xiaomi_wmi *data = dev_get_drvdata(&wdev->dev);
 
@@ -85,7 +84,7 @@ static struct wmi_driver xiaomi_wmi_driver = {
 	},
 	.id_table = xiaomi_wmi_id_table,
 	.probe = xiaomi_wmi_probe,
-	.notify = xiaomi_wmi_notify,
+	.notify_new = xiaomi_wmi_notify,
 	.no_singleton = true,
 };
 module_wmi_driver(xiaomi_wmi_driver);
Signature · 1 line
2.39.5
author maintainer
#13 lore raw

PATCH v3 8/9 platform/x86: wmi-bmof: Use new buffer-based WMI API

In reply to Armin Wolf

Use the new buffer-based WMI API to also support ACPI firmware implementations that do not use ACPI buffers to return the BMOF data.

---
 drivers/platform/x86/wmi-bmof.c | 34 +++++++++++++++------------------
 1 file changed, 15 insertions(+), 19 deletions(-)
drivers/platform/x86/wmi-bmof.c +15 -19
index 5b00370a9a22..e3a126de421b 100644
@@ -8,7 +8,6 @@
 
 #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
 
-#include <linux/acpi.h>
 #include <linux/device.h>
 #include <linux/fs.h>
 #include <linux/kernel.h>
@@ -24,9 +23,9 @@ static ssize_t bmof_read(struct file *filp, struct kobject *kobj, const struct b
 			 char *buf, loff_t off, size_t count)
 {
 	struct device *dev = kobj_to_dev(kobj);
-	union acpi_object *obj = dev_get_drvdata(dev);
+	struct wmi_buffer *buffer = dev_get_drvdata(dev);
 
-	return memory_read_from_buffer(buf, count, &off, obj->buffer.pointer, obj->buffer.length);
+	return memory_read_from_buffer(buf, count, &off, buffer->data, buffer->length);
 }
 
 static const BIN_ATTR_ADMIN_RO(bmof, 0);
@@ -39,9 +38,9 @@ static const struct bin_attribute * const bmof_attrs[] = {
 static size_t bmof_bin_size(struct kobject *kobj, const struct bin_attribute *attr, int n)
 {
 	struct device *dev = kobj_to_dev(kobj);
-	union acpi_object *obj = dev_get_drvdata(dev);
+	struct wmi_buffer *buffer = dev_get_drvdata(dev);
 
-	return obj->buffer.length;
+	return buffer->length;
 }
 
 static const struct attribute_group bmof_group = {
@@ -56,30 +55,27 @@ static const struct attribute_group *bmof_groups[] = {
 
 static int wmi_bmof_probe(struct wmi_device *wdev, const void *context)
 {
-	union acpi_object *obj;
+	struct wmi_buffer *buffer;
+	int ret;
 
-	obj = wmidev_block_query(wdev, 0);
-	if (!obj) {
-		dev_err(&wdev->dev, "failed to read Binary MOF\n");
-		return -EIO;
-	}
+	buffer = devm_kzalloc(&wdev->dev, sizeof(*buffer), GFP_KERNEL);
+	if (!buffer)
+		return -ENOMEM;
 
-	if (obj->type != ACPI_TYPE_BUFFER) {
-		dev_err(&wdev->dev, "Binary MOF is not a buffer\n");
-		kfree(obj);
-		return -EIO;
-	}
+	ret = wmidev_query_block(wdev, 0, buffer);
+	if (ret < 0)
+		return ret;
 
-	dev_set_drvdata(&wdev->dev, obj);
+	dev_set_drvdata(&wdev->dev, buffer);
 
 	return 0;
 }
 
 static void wmi_bmof_remove(struct wmi_device *wdev)
 {
-	union acpi_object *obj = dev_get_drvdata(&wdev->dev);
+	struct wmi_buffer *buffer = dev_get_drvdata(&wdev->dev);
 
-	kfree(obj);
+	kfree(buffer->data);
 }
 
 static const struct wmi_device_id wmi_bmof_id_table[] = {
Signature · 1 line
2.39.5
author maintainer
#14 lore raw

PATCH v3 9/9 platform/wmi: Update driver development guide

In reply to Armin Wolf

New WMI drivers should use the new buffer-based WMI API instead of the deprecated ACPI-based API. Update the driver development guide to recommend the buffer-based API to driver developers and explain the purpose of struct wmi_buffer.

Also update the ACPI interface documentation to describe the conversion rules for converting ACPI objects into WMI buffers.

---
 Documentation/wmi/acpi-interface.rst          | 68 +++++++++++++++++
 .../wmi/driver-development-guide.rst          | 76 +++++++++++++------
 2 files changed, 121 insertions(+), 23 deletions(-)
Documentation/wmi/acpi-interface.rst +68 -0
index 1ef003b033bf..4657101c528a 100644
@@ -104,3 +104,71 @@ holding the notification ID of the event. This method should be evaluated every
 time an ACPI notification is received, since some ACPI implementations use a
 queue to store WMI event data items. This queue will overflow after a couple
 of WMI events are received without retrieving the associated WMI event data.
+
+Conversion rules for ACPI data types
+------------------------------------
+
+Consumers of the ACPI-WMI interface use binary buffers to exchange data with the WMI driver core,
+with the internal structure of the buffer being only know to the consumers. The WMI driver core is
+thus responsible for converting the data inside the buffer into an appropriate ACPI data type for
+consumption by the ACPI firmware. Additionally, any data returned by the various ACPI methods needs
+to be converted back into a binary buffer.
+
+The layout of said buffers is defined by the MOF description of the WMI method or data block in
+question [1]_:
+
+=============== ======================================================================= =========
+Data Type       Layout                                                                  Alignment
+=============== ======================================================================= =========
+``string``      Starts with an unsigned 16-bit little endian integer specifying         2 bytes
+                the length of the string data in bytes, followed by the string data
+                encoded as UTF-16LE with **optional** NULL termination and padding.
+                Keep in mind that some firmware implementations might depend on the
+                terminating NULL character to be present. Also the padding should
+                always be performed with NULL characters.
+``boolean``     Single byte where 0 means ``false`` and nonzero means ``true``.         1 byte
+``sint8``       Signed 8-bit integer.                                                   1 byte
+``uint8``       Unsigned 8-bit integer.                                                 1 byte
+``sint16``      Signed 16-bit little endian integer.                                    2 bytes
+``uint16``      Unsigned 16-bit little endian integer.                                  2 bytes
+``sint32``      Signed 32-bit little endian integer.                                    4 bytes
+``uint32``      Unsigned 32-bit little endian integer.                                  4 bytes
+``sint64``      Signed 64-bit little endian integer.                                    8 bytes
+``uint64``      Unsigned 64-bit little endian integer.                                  8 bytes
+``datetime``    A fixed-length 25-character UTF-16LE string with the format             2 bytes
+                *yyyymmddhhmmss.mmmmmmsutc* where *yyyy* is the 4-digit year, *mm* is
+                the 2-digit month, *dd* is the 2-digit day, *hh* is the 2-digit hour
+                based on a 24-hour clock, *mm* is the 2-digit minute, *ss* is the
+                2-digit second, *mmmmmm* is the 6-digit microsecond, *s* is a plus or
+                minus character depending on whether *utc* is a positive or negative
+                offset from UTC (or a colon if the date is an interval). Unpopulated
+                fields should be filled with asterisks.
+=============== ======================================================================= =========
+
+Arrays should be aligned based on the alignment of their base type, while objects should be
+aligned based on the largest alignment of an element inside them.
+
+All buffers returned by the WMI driver core are 8-byte aligned. When converting ACPI data types
+into such buffers the following conversion rules apply:
+
+=============== ============================================================
+ACPI Data Type  Converted into
+=============== ============================================================
+Buffer          Copied as-is.
+Integer         Converted into a ``uint32``.
+String          Converted into a ``string`` with a terminating NULL character
+                to match the behavior the of the Windows driver.
+Package         Each element inside the package is converted with alignment
+                of the resulting data types being respected. Nested packages
+                are not allowed.
+=============== ============================================================
+
+The Windows driver does attempt to handle nested packages, but this results in internal data
+structures (``_ACPI_METHOD_ARGUMENT_V1``) erroneously being copied into the resulting buffer.
+ACPI firmware implementations should thus not return nested packages from ACPI methods
+associated with the ACPI-WMI interface.
+
+References
+==========
+
+.. [1] https://learn.microsoft.com/en-us/windows-hardware/drivers/kernel/driver-defined-wmi-data-items
Documentation/wmi/driver-development-guide.rst +53 -23

119 lines not on this page · raw message

Signature · 1 line
2.39.5
maintainer
#15 lore raw
In reply to Armin Wolf
Quoted 10 lines · Armin Wolf

The Windows WMI-ACPI driver likely uses wmilib [1] to interact with the WMI service in userspace. Said library uses plain byte buffers for exchanging data, so the WMI-ACPI driver has to convert between those byte buffers and ACPI objects returned by the ACPI firmware.

The format of the byte buffer is publicly documented [2], and after some reverse eingineering of the WMI-ACPI driver using a set of custom ACPI tables, the following conversion rules have been discovered:

[...]

Thank you for your contribution, it has been applied to my local review-ilpo-next branch. Note it will show up in the public platform-drivers-x86/review-ilpo-next branch only once I've pushed my local branch there, which might take a while.

The list of commits applied:
[1/9] platform/wmi: Introduce marshalling support

      commit: bfa284e9f5e77c9e7389116a403b1dc478f2d58e
[2/9] platform/wmi: Add kunit test for the marshalling code
      commit: 1e4746e93871168f50f237e9e316dc6c9a883719
[3/9] platform/wmi: Add helper functions for WMI string conversions
      commit: 3ae53ee45d5c958aae883173d1e4cafe15564cce
[4/9] platform/wmi: Add kunit test for the string conversion code
      commit: 3579df4cf0b5a3c1d50146c72b13bb4215d509b5
[5/9] platform/x86: intel-wmi-sbl-fw-update: Use new buffer-based WMI API
      commit: ca7861de6a37a52bf75fe41be51fd39162a9281d
[6/9] platform/x86/intel/wmi: thunderbolt: Use new buffer-based WMI API
      commit: 7f331e5f10ebb72d3bbc83470e4b409337024093
[7/9] platform/x86: xiaomi-wmi: Use new buffer-based WMI API
      commit: e9997669653bc0622f9ed8a3fe778cc989d1e254
[8/9] platform/x86: wmi-bmof: Use new buffer-based WMI API
      commit: 70d37a7fd341e5c0090385034feb8f6f93a56ae7
[9/9] platform/wmi: Update driver development guide
      commit: 0835f9737d4705a9f72de05fde09ba806dcbc862

--
i.

author maintainer
#16 lore raw

Am 12.01.26 um 16:33 schrieb Ilpo Järvinen:

Quoted 29 lines · Armin Wolf
Quoted 11 lines

The Windows WMI-ACPI driver likely uses wmilib [1] to interact with the WMI service in userspace. Said library uses plain byte buffers for exchanging data, so the WMI-ACPI driver has to convert between those byte buffers and ACPI objects returned by the ACPI firmware.

The format of the byte buffer is publicly documented [2], and after some reverse eingineering of the WMI-ACPI driver using a set of custom ACPI tables, the following conversion rules have been discovered:

[...]

Thank you for your contribution, it has been applied to my local review-ilpo-next branch. Note it will show up in the public platform-drivers-x86/review-ilpo-next branch only once I've pushed my local branch there, which might take a while.

The list of commits applied:
[1/9] platform/wmi: Introduce marshalling support

       commit: bfa284e9f5e77c9e7389116a403b1dc478f2d58e
[2/9] platform/wmi: Add kunit test for the marshalling code
       commit: 1e4746e93871168f50f237e9e316dc6c9a883719
[3/9] platform/wmi: Add helper functions for WMI string conversions
       commit: 3ae53ee45d5c958aae883173d1e4cafe15564cce
[4/9] platform/wmi: Add kunit test for the string conversion code
       commit: 3579df4cf0b5a3c1d50146c72b13bb4215d509b5
[5/9] platform/x86: intel-wmi-sbl-fw-update: Use new buffer-based WMI API
       commit: ca7861de6a37a52bf75fe41be51fd39162a9281d
Quoted 8 lines

[6/9] platform/x86/intel/wmi: thunderbolt: Use new buffer-based WMI API

       commit: 7f331e5f10ebb72d3bbc83470e4b409337024093
[7/9] platform/x86: xiaomi-wmi: Use new buffer-based WMI API
       commit: e9997669653bc0622f9ed8a3fe778cc989d1e254
[8/9] platform/x86: wmi-bmof: Use new buffer-based WMI API
       commit: 70d37a7fd341e5c0090385034feb8f6f93a56ae7
[9/9] platform/wmi: Update driver development guide
       commit: 0835f9737d4705a9f72de05fde09ba806dcbc862

Thank you :)

Quoted 4 lines

--
i.