Re: [PATCH v2 2/2] platform/x86: wmi: fail wmi_driver_register when no GUID is found

Re: [PATCH v2 2/2] platform/x86: wmi: fail wmi_driver_register when no GUID is found

[Hans de Goede]

Hi,

On 7/31/20 10:21 PM, Daniel Dadap wrote:
> If a driver registers with WMI, and none of the GUIDs in its ID table
> is present on the system, then that driver will not be probed and
> automatically loaded. However, it is still possible to load such a
> driver explicitly on a system which doesn't include the relevant
> hardware.
> 
> Update wmi_driver_register to test for the presence of at least one
> GUID from the driver's ID table at driver registration time, and
> fail registration if none are found.

This would make the WMI bus different from all the other kernel
bus subsystems where one can happily load drivers even if there
is no hardware using them.

And this would also break being able to manually bind a different
(hopefully compatible but different) guid device through
/sys/bus/wmi/drivers/foo/bind

So NACK to this one from me.

Note please do send a new version of patch 1/2 of this sets addressing
Andy's remarks to the other similar patch you did.

Regards,

Hans





> 
> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
> ---
>  drivers/platform/x86/wmi.c | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
> 
> diff --git a/drivers/platform/x86/wmi.c b/drivers/platform/x86/wmi.c
> index 941739db7199..19aa23d1cf8e 100644
> --- a/drivers/platform/x86/wmi.c
> +++ b/drivers/platform/x86/wmi.c
> @@ -130,6 +130,21 @@ static bool find_guid(const char *guid_string, struct wmi_block **out)
>  	return false;
>  }
>  
> +static bool find_driver_guid(const struct wmi_driver *wdriver)
> +{
> +	const struct wmi_device_id *id;
> +
> +	if (wdriver == NULL)
> +		return false;
> +
> +	for (id = wdriver->id_table; *id->guid_string; id++) {
> +		if (find_guid(id->guid_string, NULL))
> +			return true;
> +	}
> +
> +	return false;
> +}
> +
>  static const void *find_guid_context(struct wmi_block *wblock,
>  				      struct wmi_driver *wdriver)
>  {
> @@ -1419,6 +1434,9 @@ static int acpi_wmi_probe(struct platform_device *device)
>  int __must_check __wmi_driver_register(struct wmi_driver *driver,
>  				       struct module *owner)
>  {
> +	if (!find_driver_guid(driver))
> +		return -ENODEV;
> +
>  	driver->driver.owner = owner;
>  	driver->driver.bus = &wmi_bus_type;
>  
> 

Re: [PATCH v2 2/2] platform/x86: wmi: fail wmi_driver_register when no GUID is found

[Daniel Dadap]

On 11/10/20 3:34 AM, Hans de Goede wrote:
> External email: Use caution opening links or attachments
>
>
> Hi,
>
> On 7/31/20 10:21 PM, Daniel Dadap wrote:
>> If a driver registers with WMI, and none of the GUIDs in its ID table
>> is present on the system, then that driver will not be probed and
>> automatically loaded. However, it is still possible to load such a
>> driver explicitly on a system which doesn't include the relevant
>> hardware.
>>
>> Update wmi_driver_register to test for the presence of at least one
>> GUID from the driver's ID table at driver registration time, and
>> fail registration if none are found.
> This would make the WMI bus different from all the other kernel
> bus subsystems where one can happily load drivers even if there
> is no hardware using them.
>
> And this would also break being able to manually bind a different
> (hopefully compatible but different) guid device through
> /sys/bus/wmi/drivers/foo/bind
>
> So NACK to this one from me.
>
> Note please do send a new version of patch 1/2 of this sets addressing
> Andy's remarks to the other similar patch you did.


Not a problem. I'll remove this patch from the series and update the 
other one.


> Regards,
>
> Hans
>
>
>
>
>
>> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
>> ---
>>   drivers/platform/x86/wmi.c | 18 ++++++++++++++++++
>>   1 file changed, 18 insertions(+)
>>
>> diff --git a/drivers/platform/x86/wmi.c b/drivers/platform/x86/wmi.c
>> index 941739db7199..19aa23d1cf8e 100644
>> --- a/drivers/platform/x86/wmi.c
>> +++ b/drivers/platform/x86/wmi.c
>> @@ -130,6 +130,21 @@ static bool find_guid(const char *guid_string, struct wmi_block **out)
>>        return false;
>>   }
>>
>> +static bool find_driver_guid(const struct wmi_driver *wdriver)
>> +{
>> +     const struct wmi_device_id *id;
>> +
>> +     if (wdriver == NULL)
>> +             return false;
>> +
>> +     for (id = wdriver->id_table; *id->guid_string; id++) {
>> +             if (find_guid(id->guid_string, NULL))
>> +                     return true;
>> +     }
>> +
>> +     return false;
>> +}
>> +
>>   static const void *find_guid_context(struct wmi_block *wblock,
>>                                      struct wmi_driver *wdriver)
>>   {
>> @@ -1419,6 +1434,9 @@ static int acpi_wmi_probe(struct platform_device *device)
>>   int __must_check __wmi_driver_register(struct wmi_driver *driver,
>>                                       struct module *owner)
>>   {
>> +     if (!find_driver_guid(driver))
>> +             return -ENODEV;
>> +
>>        driver->driver.owner = owner;
>>        driver->driver.bus = &wmi_bus_type;
>>
>>

[PATCH v3] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

A number of upcoming notebook computer designs drive the internal
display panel's backlight PWM through the Embedded Controller (EC).
This EC-based backlight control can be plumbed through to an ACPI
"WMAA" method interface, which in turn can be wrapped by WMI with
the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.

Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
backlight class driver to control backlight levels on systems with
EC-driven backlights.

Signed-off-by: Aaron Plattner <aplattner@nvidia.com>
Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
---

v2: Convert to WMI subsystem driver, suggested by Mario Limonciello
    <mario.limonciello@outlook.com>; various cleanups suggested by
    Barnabás Pőcze <pobrn@protonmail.com>
v3: Address assorted style nits raised by Andy Shevchenko
    <andy.shevchenko@gmail.com> in response to a related patch; remove
    additional behavior change to WMI subsystem from patch series as
    recommended by Hans de Goede <hdegoede@redhat.com>

 MAINTAINERS                               |   6 +
 drivers/platform/x86/Kconfig              |  10 ++
 drivers/platform/x86/Makefile             |   1 +
 drivers/platform/x86/wmaa-backlight-wmi.c | 184 ++++++++++++++++++++++
 4 files changed, 201 insertions(+)
 create mode 100644 drivers/platform/x86/wmaa-backlight-wmi.c

diff --git a/MAINTAINERS b/MAINTAINERS
index bbaecde94aa0..fd7362a86c6d 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -20008,6 +20008,12 @@ L:	linux-wireless@vger.kernel.org
 S:	Odd fixes
 F:	drivers/net/wireless/wl3501*
 
+WMAA BACKLIGHT DRIVER
+M:	Daniel Dadap <ddadap@nvidia.com>
+L:	platform-driver-x86@vger.kernel.org
+S:	Supported
+F:	drivers/platform/x86/wmaa-backlight-wmi.c
+
 WOLFSON MICROELECTRONICS DRIVERS
 L:	patches@opensource.cirrus.com
 S:	Supported
diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
index d12db6c316ea..e54449c16d03 100644
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -113,6 +113,16 @@ config PEAQ_WMI
 	help
 	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
 
+config WMAA_BACKLIGHT_WMI
+	tristate "ACPI WMAA Backlight Driver"
+	depends on ACPI_WMI
+	depends on BACKLIGHT_CLASS_DEVICE
+	help
+	  This driver provides a sysfs backlight interface for notebook
+	  systems which expose the WMAA ACPI method and an associated WMI
+	  wrapper to drive LCD backlight levels through the system's
+	  Embedded Controller.
+
 config XIAOMI_WMI
 	tristate "Xiaomi WMI key driver"
 	depends on ACPI_WMI
diff --git a/drivers/platform/x86/Makefile b/drivers/platform/x86/Makefile
index 7ee369aab10d..109c1714237d 100644
--- a/drivers/platform/x86/Makefile
+++ b/drivers/platform/x86/Makefile
@@ -14,6 +14,7 @@ obj-$(CONFIG_INTEL_WMI_SBL_FW_UPDATE)	+= intel-wmi-sbl-fw-update.o
 obj-$(CONFIG_INTEL_WMI_THUNDERBOLT)	+= intel-wmi-thunderbolt.o
 obj-$(CONFIG_MXM_WMI)			+= mxm-wmi.o
 obj-$(CONFIG_PEAQ_WMI)			+= peaq-wmi.o
+obj-$(CONFIG_WMAA_BACKLIGHT_WMI)	+= wmaa-backlight-wmi.o
 obj-$(CONFIG_XIAOMI_WMI)		+= xiaomi-wmi.o
 obj-$(CONFIG_GIGABYTE_WMI)		+= gigabyte-wmi.o
 
diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
new file mode 100644
index 000000000000..b607d3f88fc2
--- /dev/null
+++ b/drivers/platform/x86/wmaa-backlight-wmi.c
@@ -0,0 +1,184 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * Copyright (c) 2020, NVIDIA CORPORATION.  All rights reserved.
+ */
+
+#define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
+
+#include <linux/acpi.h>
+#include <linux/backlight.h>
+#include <linux/module.h>
+#include <linux/wmi.h>
+
+#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
+
+struct wmi_wmaa_priv {
+	struct backlight_device *backlight;
+};
+
+enum wmaa_method {
+	WMAA_BRIGHTNESS_LEVEL = 1,
+	WMAA_BRIGHTNESS_SOURCE = 2,
+};
+
+enum wmaa_get_or_set {
+	WMAA_GET = 0,
+	WMAA_SET = 1,
+	WMAA_GET_MAX = 2, // for WMAA_BRIGHTNESS_LEVEL only
+};
+
+enum wmaa_source {
+	WMAA_SOURCE_CLEAR = 0,
+	WMAA_SOURCE_GPU = 1,
+	WMAA_SOURCE_EC = 2,
+	WMAA_SOURCE_AUX = 3,
+	WMAA_SOURCE_COUNT
+};
+
+struct wmaa_args {
+	u32 set;
+	u32 val;
+	u32 ret;
+	u32 ignored[3];
+};
+
+static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
+	{ .guid_string = WMAA_WMI_GUID },
+	{ },
+};
+
+static struct wmi_device *wdev;
+
+static int wmi_call_wmaa(enum wmaa_method method, enum wmaa_get_or_set set, u32 *val)
+{
+	struct wmaa_args args = {
+		.set = set,
+		.val = 0,
+		.ret = 0,
+	};
+	struct acpi_buffer buf = { (acpi_size)sizeof(args), &args };
+	acpi_status status;
+
+	if (set == WMAA_SET)
+		args.val = *val;
+
+	status = wmidev_evaluate_method(wdev, 0, method, &buf, &buf);
+	if (ACPI_FAILURE(status)) {
+		pr_err("ACPI WMAA failed with %s\n", acpi_format_exception(status));
+		return -EIO;
+	}
+
+	if (set != WMAA_SET)
+		*val = args.ret;
+
+	return 0;
+}
+
+static int wmaa_get_brightness(u32 *level)
+{
+	return wmi_call_wmaa(WMAA_BRIGHTNESS_LEVEL, WMAA_GET, level);
+}
+
+static int wmaa_set_brightness(u32 level)
+{
+	return wmi_call_wmaa(WMAA_BRIGHTNESS_LEVEL, WMAA_SET, &level);
+}
+
+static int wmaa_backlight_update_status(struct backlight_device *bd)
+{
+	return wmaa_set_brightness(bd->props.brightness);
+}
+
+static int wmaa_backlight_get_brightness(struct backlight_device *bd)
+{
+	u32 level;
+	int ret;
+
+	ret = wmaa_get_brightness(&level);
+
+	WARN_ON(ret != 0);
+	return ret == 0 ? level : 0;
+}
+
+static const struct backlight_ops wmaa_backlight_ops = {
+	.update_status = wmaa_backlight_update_status,
+	.get_brightness = wmaa_backlight_get_brightness,
+};
+
+static int wmaa_get_max_brightness(u32 *level)
+{
+	return wmi_call_wmaa(WMAA_BRIGHTNESS_LEVEL, WMAA_GET_MAX, level);
+}
+
+static int wmaa_get_brightness_source(u32 *source)
+{
+	return wmi_call_wmaa(WMAA_BRIGHTNESS_SOURCE, WMAA_GET, source);
+}
+
+static int wmaa_backlight_wmi_probe(struct wmi_device *w, const void *ctx)
+{
+	struct backlight_properties props = {0};
+	struct wmi_wmaa_priv *priv;
+	u32 source;
+	int ret;
+
+	priv = devm_kmalloc(&w->dev, sizeof(*priv), GFP_KERNEL);
+	if(!priv)
+		return -ENOMEM;
+
+	wdev = w;
+
+	ret = wmaa_get_brightness_source(&source);
+	if (ret)
+		goto done;
+
+	if (source != WMAA_SOURCE_EC) {
+		ret = -ENODEV;
+		goto done;
+	}
+
+	// Register a backlight handler
+	props.type = BACKLIGHT_PLATFORM;
+	ret = wmaa_get_max_brightness(&props.max_brightness);
+	if (ret)
+		goto done;
+
+	ret = wmaa_get_brightness(&props.brightness);
+	if (ret)
+		goto done;
+
+	priv->backlight = backlight_device_register("wmaa_backlight",
+		NULL, NULL, &wmaa_backlight_ops, &props);
+	if (IS_ERR(priv->backlight))
+		return PTR_ERR(priv->backlight);
+
+	dev_set_drvdata(&w->dev, priv);
+
+done:
+	return ret;
+}
+
+static void wmaa_backlight_wmi_remove(struct wmi_device *wdev)
+{
+	struct wmi_wmaa_priv *priv = dev_get_drvdata(&wdev->dev);
+
+	backlight_device_unregister(priv->backlight);
+}
+
+static struct wmi_driver wmaa_backlight_wmi_driver = {
+	.driver = {
+		.name = "wmaa-backlight",
+	},
+	.probe = wmaa_backlight_wmi_probe,
+	.remove = wmaa_backlight_wmi_remove,
+	.id_table = wmaa_backlight_wmi_id_table,
+};
+
+module_wmi_driver(wmaa_backlight_wmi_driver);
+
+MODULE_AUTHOR("Aaron Plattner <aplattner@nvidia.com>");
+MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
+MODULE_DESCRIPTION("WMAA Backlight WMI driver");
+MODULE_LICENSE("GPL v2");
+
+MODULE_ALIAS("wmi:"WMAA_WMI_GUID);
-- 
2.20.1

Re: [PATCH v3] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Barnabás Pőcze]

Hi


2021. augusztus 25., szerda 0:04 keltezéssel, Daniel Dadap írta:
> A number of upcoming notebook computer designs drive the internal
> display panel's backlight PWM through the Embedded Controller (EC).
> This EC-based backlight control can be plumbed through to an ACPI
> "WMAA" method interface, which in turn can be wrapped by WMI with
> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
>
> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
> backlight class driver to control backlight levels on systems with
> EC-driven backlights.
>
> Signed-off-by: Aaron Plattner <aplattner@nvidia.com>
> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
> ---
>
> v2: Convert to WMI subsystem driver, suggested by Mario Limonciello
>     <mario.limonciello@outlook.com>; various cleanups suggested by
>     Barnabás Pőcze <pobrn@protonmail.com>
> v3: Address assorted style nits raised by Andy Shevchenko
>     <andy.shevchenko@gmail.com> in response to a related patch; remove
>     additional behavior change to WMI subsystem from patch series as
>     recommended by Hans de Goede <hdegoede@redhat.com>
>
>  MAINTAINERS                               |   6 +
>  drivers/platform/x86/Kconfig              |  10 ++
>  drivers/platform/x86/Makefile             |   1 +
>  drivers/platform/x86/wmaa-backlight-wmi.c | 184 ++++++++++++++++++++++
>  4 files changed, 201 insertions(+)
>  create mode 100644 drivers/platform/x86/wmaa-backlight-wmi.c
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index bbaecde94aa0..fd7362a86c6d 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -20008,6 +20008,12 @@ L:	linux-wireless@vger.kernel.org
>  S:	Odd fixes
>  F:	drivers/net/wireless/wl3501*
>
> +WMAA BACKLIGHT DRIVER
> +M:	Daniel Dadap <ddadap@nvidia.com>
> +L:	platform-driver-x86@vger.kernel.org
> +S:	Supported
> +F:	drivers/platform/x86/wmaa-backlight-wmi.c
> +
>  WOLFSON MICROELECTRONICS DRIVERS
>  L:	patches@opensource.cirrus.com
>  S:	Supported
> diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
> index d12db6c316ea..e54449c16d03 100644
> --- a/drivers/platform/x86/Kconfig
> +++ b/drivers/platform/x86/Kconfig
> @@ -113,6 +113,16 @@ config PEAQ_WMI
>  	help
>  	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
>
> +config WMAA_BACKLIGHT_WMI
> +	tristate "ACPI WMAA Backlight Driver"
> +	depends on ACPI_WMI
> +	depends on BACKLIGHT_CLASS_DEVICE
> +	help
> +	  This driver provides a sysfs backlight interface for notebook
> +	  systems which expose the WMAA ACPI method and an associated WMI
> +	  wrapper to drive LCD backlight levels through the system's
> +	  Embedded Controller.
> +
>  config XIAOMI_WMI
>  	tristate "Xiaomi WMI key driver"
>  	depends on ACPI_WMI
> diff --git a/drivers/platform/x86/Makefile b/drivers/platform/x86/Makefile
> index 7ee369aab10d..109c1714237d 100644
> --- a/drivers/platform/x86/Makefile
> +++ b/drivers/platform/x86/Makefile
> @@ -14,6 +14,7 @@ obj-$(CONFIG_INTEL_WMI_SBL_FW_UPDATE)	+= intel-wmi-sbl-fw-update.o
>  obj-$(CONFIG_INTEL_WMI_THUNDERBOLT)	+= intel-wmi-thunderbolt.o
>  obj-$(CONFIG_MXM_WMI)			+= mxm-wmi.o
>  obj-$(CONFIG_PEAQ_WMI)			+= peaq-wmi.o
> +obj-$(CONFIG_WMAA_BACKLIGHT_WMI)	+= wmaa-backlight-wmi.o
>  obj-$(CONFIG_XIAOMI_WMI)		+= xiaomi-wmi.o
>  obj-$(CONFIG_GIGABYTE_WMI)		+= gigabyte-wmi.o
>
> diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
> new file mode 100644
> index 000000000000..b607d3f88fc2
> --- /dev/null
> +++ b/drivers/platform/x86/wmaa-backlight-wmi.c
> @@ -0,0 +1,184 @@
> +// SPDX-License-Identifier: GPL-2.0-only
> +/*
> + * Copyright (c) 2020, NVIDIA CORPORATION.  All rights reserved.
> + */
> +
> +#define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
> +
> +#include <linux/acpi.h>
> +#include <linux/backlight.h>
> +#include <linux/module.h>
> +#include <linux/wmi.h>
> +
> +#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
> +
> +struct wmi_wmaa_priv {
> +	struct backlight_device *backlight;
> +};
> +
> +enum wmaa_method {
> +	WMAA_BRIGHTNESS_LEVEL = 1,
> +	WMAA_BRIGHTNESS_SOURCE = 2,
> +};
> +
> +enum wmaa_get_or_set {
> +	WMAA_GET = 0,
> +	WMAA_SET = 1,
> +	WMAA_GET_MAX = 2, // for WMAA_BRIGHTNESS_LEVEL only

/* this type of comments is preferred */


> +};
> +
> +enum wmaa_source {
> +	WMAA_SOURCE_CLEAR = 0,
> +	WMAA_SOURCE_GPU = 1,
> +	WMAA_SOURCE_EC = 2,
> +	WMAA_SOURCE_AUX = 3,
> +	WMAA_SOURCE_COUNT
> +};
> +
> +struct wmaa_args {
> +	u32 set;
> +	u32 val;
> +	u32 ret;
> +	u32 ignored[3];
> +};
> +
> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
> +	{ .guid_string = WMAA_WMI_GUID },
> +	{ },
> +};
> +
> +static struct wmi_device *wdev;
> +
> +static int wmi_call_wmaa(enum wmaa_method method, enum wmaa_get_or_set set, u32 *val)
> +{
> +	struct wmaa_args args = {
> +		.set = set,
> +		.val = 0,
> +		.ret = 0,
> +	};
> +	struct acpi_buffer buf = { (acpi_size)sizeof(args), &args };
> +	acpi_status status;
> +
> +	if (set == WMAA_SET)
> +		args.val = *val;
> +
> +	status = wmidev_evaluate_method(wdev, 0, method, &buf, &buf);
> +	if (ACPI_FAILURE(status)) {
> +		pr_err("ACPI WMAA failed with %s\n", acpi_format_exception(status));

I think this could be `dev_err()` instead.


> +		return -EIO;
> +	}
> +
> +	if (set != WMAA_SET)
> +		*val = args.ret;
> +
> +	return 0;
> +}
> +
> +static int wmaa_get_brightness(u32 *level)
> +{
> +	return wmi_call_wmaa(WMAA_BRIGHTNESS_LEVEL, WMAA_GET, level);
> +}
> +
> +static int wmaa_set_brightness(u32 level)
> +{
> +	return wmi_call_wmaa(WMAA_BRIGHTNESS_LEVEL, WMAA_SET, &level);
> +}
> +
> +static int wmaa_backlight_update_status(struct backlight_device *bd)
> +{
> +	return wmaa_set_brightness(bd->props.brightness);
> +}
> +
> +static int wmaa_backlight_get_brightness(struct backlight_device *bd)
> +{
> +	u32 level;
> +	int ret;
> +
> +	ret = wmaa_get_brightness(&level);
> +
> +	WARN_ON(ret != 0);
> +	return ret == 0 ? level : 0;
> +}
> +
> +static const struct backlight_ops wmaa_backlight_ops = {
> +	.update_status = wmaa_backlight_update_status,
> +	.get_brightness = wmaa_backlight_get_brightness,
> +};
> +
> +static int wmaa_get_max_brightness(u32 *level)
> +{
> +	return wmi_call_wmaa(WMAA_BRIGHTNESS_LEVEL, WMAA_GET_MAX, level);
> +}
> +
> +static int wmaa_get_brightness_source(u32 *source)
> +{
> +	return wmi_call_wmaa(WMAA_BRIGHTNESS_SOURCE, WMAA_GET, source);
> +}
> +
> +static int wmaa_backlight_wmi_probe(struct wmi_device *w, const void *ctx)
> +{
> +	struct backlight_properties props = {0};
> +	struct wmi_wmaa_priv *priv;
> +	u32 source;
> +	int ret;
> +
> +	priv = devm_kmalloc(&w->dev, sizeof(*priv), GFP_KERNEL);
> +	if(!priv)
> +		return -ENOMEM;
> +
> +	wdev = w;

It seems odd to me that half of the state is per-device, but the other half is global.


> +
> +	ret = wmaa_get_brightness_source(&source);
> +	if (ret)
> +		goto done;
> +
> +	if (source != WMAA_SOURCE_EC) {
> +		ret = -ENODEV;
> +		goto done;
> +	}
> +
> +	// Register a backlight handler
> +	props.type = BACKLIGHT_PLATFORM;
> +	ret = wmaa_get_max_brightness(&props.max_brightness);
> +	if (ret)
> +		goto done;
> +
> +	ret = wmaa_get_brightness(&props.brightness);
> +	if (ret)
> +		goto done;
> +
> +	priv->backlight = backlight_device_register("wmaa_backlight",
> +		NULL, NULL, &wmaa_backlight_ops, &props);

Have you looked at `devm_backlight_device_register()`?


> +	if (IS_ERR(priv->backlight))
> +		return PTR_ERR(priv->backlight);
> +
> +	dev_set_drvdata(&w->dev, priv);
> +
> +done:
> +	return ret;
> +}
> +
> +static void wmaa_backlight_wmi_remove(struct wmi_device *wdev)
> +{
> +	struct wmi_wmaa_priv *priv = dev_get_drvdata(&wdev->dev);
> +
> +	backlight_device_unregister(priv->backlight);
> +}
> +
> +static struct wmi_driver wmaa_backlight_wmi_driver = {
> +	.driver = {
> +		.name = "wmaa-backlight",
> +	},
> +	.probe = wmaa_backlight_wmi_probe,
> +	.remove = wmaa_backlight_wmi_remove,
> +	.id_table = wmaa_backlight_wmi_id_table,
> +};
> +
> +module_wmi_driver(wmaa_backlight_wmi_driver);
> +
> +MODULE_AUTHOR("Aaron Plattner <aplattner@nvidia.com>");
> +MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
> +MODULE_DESCRIPTION("WMAA Backlight WMI driver");
> +MODULE_LICENSE("GPL v2");
> +
> +MODULE_ALIAS("wmi:"WMAA_WMI_GUID);
> --
> 2.20.1


Best regards,
Barnabás Pőcze

Re: [PATCH v3] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

Thanks again:

On 8/24/21 5:47 PM, Barnabás Pőcze wrote:
> Hi
>
>
> 2021. augusztus 25., szerda 0:04 keltezéssel, Daniel Dadap írta:
>> A number of upcoming notebook computer designs drive the internal
>> display panel's backlight PWM through the Embedded Controller (EC).
>> This EC-based backlight control can be plumbed through to an ACPI
>> "WMAA" method interface, which in turn can be wrapped by WMI with
>> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
>>
>> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
>> backlight class driver to control backlight levels on systems with
>> EC-driven backlights.
>>
>> Signed-off-by: Aaron Plattner <aplattner@nvidia.com>
>> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
>> ---
>>
>> v2: Convert to WMI subsystem driver, suggested by Mario Limonciello
>>      <mario.limonciello@outlook.com>; various cleanups suggested by
>>      Barnabás Pőcze <pobrn@protonmail.com>
>> v3: Address assorted style nits raised by Andy Shevchenko
>>      <andy.shevchenko@gmail.com> in response to a related patch; remove
>>      additional behavior change to WMI subsystem from patch series as
>>      recommended by Hans de Goede <hdegoede@redhat.com>
>>
>>   MAINTAINERS                               |   6 +
>>   drivers/platform/x86/Kconfig              |  10 ++
>>   drivers/platform/x86/Makefile             |   1 +
>>   drivers/platform/x86/wmaa-backlight-wmi.c | 184 ++++++++++++++++++++++
>>   4 files changed, 201 insertions(+)
>>   create mode 100644 drivers/platform/x86/wmaa-backlight-wmi.c
>>
>> diff --git a/MAINTAINERS b/MAINTAINERS
>> index bbaecde94aa0..fd7362a86c6d 100644
>> --- a/MAINTAINERS
>> +++ b/MAINTAINERS
>> @@ -20008,6 +20008,12 @@ L:	linux-wireless@vger.kernel.org
>>   S:	Odd fixes
>>   F:	drivers/net/wireless/wl3501*
>>
>> +WMAA BACKLIGHT DRIVER
>> +M:	Daniel Dadap <ddadap@nvidia.com>
>> +L:	platform-driver-x86@vger.kernel.org
>> +S:	Supported
>> +F:	drivers/platform/x86/wmaa-backlight-wmi.c
>> +
>>   WOLFSON MICROELECTRONICS DRIVERS
>>   L:	patches@opensource.cirrus.com
>>   S:	Supported
>> diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
>> index d12db6c316ea..e54449c16d03 100644
>> --- a/drivers/platform/x86/Kconfig
>> +++ b/drivers/platform/x86/Kconfig
>> @@ -113,6 +113,16 @@ config PEAQ_WMI
>>   	help
>>   	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
>>
>> +config WMAA_BACKLIGHT_WMI
>> +	tristate "ACPI WMAA Backlight Driver"
>> +	depends on ACPI_WMI
>> +	depends on BACKLIGHT_CLASS_DEVICE
>> +	help
>> +	  This driver provides a sysfs backlight interface for notebook
>> +	  systems which expose the WMAA ACPI method and an associated WMI
>> +	  wrapper to drive LCD backlight levels through the system's
>> +	  Embedded Controller.
>> +
>>   config XIAOMI_WMI
>>   	tristate "Xiaomi WMI key driver"
>>   	depends on ACPI_WMI
>> diff --git a/drivers/platform/x86/Makefile b/drivers/platform/x86/Makefile
>> index 7ee369aab10d..109c1714237d 100644
>> --- a/drivers/platform/x86/Makefile
>> +++ b/drivers/platform/x86/Makefile
>> @@ -14,6 +14,7 @@ obj-$(CONFIG_INTEL_WMI_SBL_FW_UPDATE)	+= intel-wmi-sbl-fw-update.o
>>   obj-$(CONFIG_INTEL_WMI_THUNDERBOLT)	+= intel-wmi-thunderbolt.o
>>   obj-$(CONFIG_MXM_WMI)			+= mxm-wmi.o
>>   obj-$(CONFIG_PEAQ_WMI)			+= peaq-wmi.o
>> +obj-$(CONFIG_WMAA_BACKLIGHT_WMI)	+= wmaa-backlight-wmi.o
>>   obj-$(CONFIG_XIAOMI_WMI)		+= xiaomi-wmi.o
>>   obj-$(CONFIG_GIGABYTE_WMI)		+= gigabyte-wmi.o
>>
>> diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
>> new file mode 100644
>> index 000000000000..b607d3f88fc2
>> --- /dev/null
>> +++ b/drivers/platform/x86/wmaa-backlight-wmi.c
>> @@ -0,0 +1,184 @@
>> +// SPDX-License-Identifier: GPL-2.0-only
>> +/*
>> + * Copyright (c) 2020, NVIDIA CORPORATION.  All rights reserved.
>> + */
>> +
>> +#define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
>> +
>> +#include <linux/acpi.h>
>> +#include <linux/backlight.h>
>> +#include <linux/module.h>
>> +#include <linux/wmi.h>
>> +
>> +#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
>> +
>> +struct wmi_wmaa_priv {
>> +	struct backlight_device *backlight;
>> +};
>> +
>> +enum wmaa_method {
>> +	WMAA_BRIGHTNESS_LEVEL = 1,
>> +	WMAA_BRIGHTNESS_SOURCE = 2,
>> +};
>> +
>> +enum wmaa_get_or_set {
>> +	WMAA_GET = 0,
>> +	WMAA_SET = 1,
>> +	WMAA_GET_MAX = 2, // for WMAA_BRIGHTNESS_LEVEL only
> /* this type of comments is preferred */
>
>
>> +};
>> +
>> +enum wmaa_source {
>> +	WMAA_SOURCE_CLEAR = 0,
>> +	WMAA_SOURCE_GPU = 1,
>> +	WMAA_SOURCE_EC = 2,
>> +	WMAA_SOURCE_AUX = 3,
>> +	WMAA_SOURCE_COUNT
>> +};
>> +
>> +struct wmaa_args {
>> +	u32 set;
>> +	u32 val;
>> +	u32 ret;
>> +	u32 ignored[3];
>> +};
>> +
>> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
>> +	{ .guid_string = WMAA_WMI_GUID },
>> +	{ },
>> +};
>> +
>> +static struct wmi_device *wdev;
>> +
>> +static int wmi_call_wmaa(enum wmaa_method method, enum wmaa_get_or_set set, u32 *val)
>> +{
>> +	struct wmaa_args args = {
>> +		.set = set,
>> +		.val = 0,
>> +		.ret = 0,
>> +	};
>> +	struct acpi_buffer buf = { (acpi_size)sizeof(args), &args };
>> +	acpi_status status;
>> +
>> +	if (set == WMAA_SET)
>> +		args.val = *val;
>> +
>> +	status = wmidev_evaluate_method(wdev, 0, method, &buf, &buf);
>> +	if (ACPI_FAILURE(status)) {
>> +		pr_err("ACPI WMAA failed with %s\n", acpi_format_exception(status));
> I think this could be `dev_err()` instead.


Yes, it could. Looks like this is the only pr_* macro used as well, so 
we can delete the pr_fmt define.


>
>> +		return -EIO;
>> +	}
>> +
>> +	if (set != WMAA_SET)
>> +		*val = args.ret;
>> +
>> +	return 0;
>> +}
>> +
>> +static int wmaa_get_brightness(u32 *level)
>> +{
>> +	return wmi_call_wmaa(WMAA_BRIGHTNESS_LEVEL, WMAA_GET, level);
>> +}
>> +
>> +static int wmaa_set_brightness(u32 level)
>> +{
>> +	return wmi_call_wmaa(WMAA_BRIGHTNESS_LEVEL, WMAA_SET, &level);
>> +}
>> +
>> +static int wmaa_backlight_update_status(struct backlight_device *bd)
>> +{
>> +	return wmaa_set_brightness(bd->props.brightness);
>> +}
>> +
>> +static int wmaa_backlight_get_brightness(struct backlight_device *bd)
>> +{
>> +	u32 level;
>> +	int ret;
>> +
>> +	ret = wmaa_get_brightness(&level);
>> +
>> +	WARN_ON(ret != 0);
>> +	return ret == 0 ? level : 0;
>> +}
>> +
>> +static const struct backlight_ops wmaa_backlight_ops = {
>> +	.update_status = wmaa_backlight_update_status,
>> +	.get_brightness = wmaa_backlight_get_brightness,
>> +};
>> +
>> +static int wmaa_get_max_brightness(u32 *level)
>> +{
>> +	return wmi_call_wmaa(WMAA_BRIGHTNESS_LEVEL, WMAA_GET_MAX, level);
>> +}
>> +
>> +static int wmaa_get_brightness_source(u32 *source)
>> +{
>> +	return wmi_call_wmaa(WMAA_BRIGHTNESS_SOURCE, WMAA_GET, source);
>> +}
>> +
>> +static int wmaa_backlight_wmi_probe(struct wmi_device *w, const void *ctx)
>> +{
>> +	struct backlight_properties props = {0};
>> +	struct wmi_wmaa_priv *priv;
>> +	u32 source;
>> +	int ret;
>> +
>> +	priv = devm_kmalloc(&w->dev, sizeof(*priv), GFP_KERNEL);
>> +	if(!priv)
>> +		return -ENOMEM;
>> +
>> +	wdev = w;
> It seems odd to me that half of the state is per-device, but the other half is global.


You're right; the global state is unnecessary since this can be 
associated with the backlight_dev.


>
>> +
>> +	ret = wmaa_get_brightness_source(&source);
>> +	if (ret)
>> +		goto done;
>> +
>> +	if (source != WMAA_SOURCE_EC) {
>> +		ret = -ENODEV;
>> +		goto done;
>> +	}
>> +
>> +	// Register a backlight handler
>> +	props.type = BACKLIGHT_PLATFORM;
>> +	ret = wmaa_get_max_brightness(&props.max_brightness);
>> +	if (ret)
>> +		goto done;
>> +
>> +	ret = wmaa_get_brightness(&props.brightness);
>> +	if (ret)
>> +		goto done;
>> +
>> +	priv->backlight = backlight_device_register("wmaa_backlight",
>> +		NULL, NULL, &wmaa_backlight_ops, &props);
> Have you looked at `devm_backlight_device_register()`?


No; I wasn't aware of it. That does seem like it would simplify things 
by removing some more boilerplate. I'm currently testing a new patch 
incorporating your suggestions.


>
>
>> +	if (IS_ERR(priv->backlight))
>> +		return PTR_ERR(priv->backlight);
>> +
>> +	dev_set_drvdata(&w->dev, priv);
>> +
>> +done:
>> +	return ret;
>> +}
>> +
>> +static void wmaa_backlight_wmi_remove(struct wmi_device *wdev)
>> +{
>> +	struct wmi_wmaa_priv *priv = dev_get_drvdata(&wdev->dev);
>> +
>> +	backlight_device_unregister(priv->backlight);
>> +}
>> +
>> +static struct wmi_driver wmaa_backlight_wmi_driver = {
>> +	.driver = {
>> +		.name = "wmaa-backlight",
>> +	},
>> +	.probe = wmaa_backlight_wmi_probe,
>> +	.remove = wmaa_backlight_wmi_remove,
>> +	.id_table = wmaa_backlight_wmi_id_table,
>> +};
>> +
>> +module_wmi_driver(wmaa_backlight_wmi_driver);
>> +
>> +MODULE_AUTHOR("Aaron Plattner <aplattner@nvidia.com>");
>> +MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
>> +MODULE_DESCRIPTION("WMAA Backlight WMI driver");
>> +MODULE_LICENSE("GPL v2");
>> +
>> +MODULE_ALIAS("wmi:"WMAA_WMI_GUID);
>> --
>> 2.20.1
>
> Best regards,
> Barnabás Pőcze

Re: [PATCH v3] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

On 8/24/21 5:47 PM, Barnabás Pőcze wrote:
> Have you looked at `devm_backlight_device_register()`?


So regarding this suggestion, I have switched to 
devm_backlight_device_register(), but now I can't unload the module; it 
fails with EBUSY. I tried unbinding the device (via 
/sys/class/backlight/wmaa_backlight/device/driver/unbind), but that 
fails with ENODEV, maybe due to missing plumbing in wmi?

I'm not sure if it's expected for users to be able to unload their 
backlight drivers; on the random selection of notebooks that I have 
immediately available to me at the moment, the backlight driver is 
registered by the GPU driver, and that tends to be not unloadable 
because e.g. it's driving the console.

It's probably best to use devm_backlight_device_register() anyway since 
it seems the ordinary backlight_device_register() is deprecated, but I 
wanted to see if there were any strong opinions about whether it would 
be a problem that the driver can't be unloaded.

Re: [PATCH v3] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

On 8/25/21 5:26 PM, Daniel Dadap wrote:
> On 8/24/21 5:47 PM, Barnabás Pőcze wrote:
>> Have you looked at `devm_backlight_device_register()`?
>
>
> So regarding this suggestion, I have switched to 
> devm_backlight_device_register(), but now I can't unload the module; 
> it fails with EBUSY. I tried unbinding the device (via 
> /sys/class/backlight/wmaa_backlight/device/driver/unbind), but that 
> fails with ENODEV, maybe due to missing plumbing in wmi?
>
> I'm not sure if it's expected for users to be able to unload their 
> backlight drivers; on the random selection of notebooks that I have 
> immediately available to me at the moment, the backlight driver is 
> registered by the GPU driver, and that tends to be not unloadable 
> because e.g. it's driving the console.
>
> It's probably best to use devm_backlight_device_register() anyway 
> since it seems the ordinary backlight_device_register() is deprecated, 
> but I wanted to see if there were any strong opinions about whether it 
> would be a problem that the driver can't be unloaded.
>

Okay, actually, I *can* unbind the device; I was apparently pasting a 
truncated GUID into the shell so it wasn't finding it. However, even 
after successfully unbinding, I still can't unload the module; it still 
fails with EBUSY, even if I explicitly call 
devm_backlight_device_unregister() in a wmi_driver .remove callback. I 
confirmed that .remove() is getting called when the device is unbound.

Re: [PATCH v3] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

On 8/27/21 11:47 AM, Daniel Dadap wrote:
> On 8/25/21 5:26 PM, Daniel Dadap wrote:
>> On 8/24/21 5:47 PM, Barnabás Pőcze wrote:
>>> Have you looked at `devm_backlight_device_register()`?
>>
>>
>> So regarding this suggestion, I have switched to 
>> devm_backlight_device_register(), but now I can't unload the module; 
>> it fails with EBUSY. I tried unbinding the device (via 
>> /sys/class/backlight/wmaa_backlight/device/driver/unbind), but that 
>> fails with ENODEV, maybe due to missing plumbing in wmi?
>>
>> I'm not sure if it's expected for users to be able to unload their 
>> backlight drivers; on the random selection of notebooks that I have 
>> immediately available to me at the moment, the backlight driver is 
>> registered by the GPU driver, and that tends to be not unloadable 
>> because e.g. it's driving the console.
>>
>> It's probably best to use devm_backlight_device_register() anyway 
>> since it seems the ordinary backlight_device_register() is 
>> deprecated, but I wanted to see if there were any strong opinions 
>> about whether it would be a problem that the driver can't be unloaded.
>>
>
> Okay, actually, I *can* unbind the device; I was apparently pasting a 
> truncated GUID into the shell so it wasn't finding it. However, even 
> after successfully unbinding, I still can't unload the module; it 
> still fails with EBUSY, even if I explicitly call 
> devm_backlight_device_unregister() in a wmi_driver .remove callback. I 
> confirmed that .remove() is getting called when the device is unbound.


Sorry for the noise. It can be unloaded after unbinding if I *don't* 
explicitly call devm_backlight_device_unregister() and leave the 
.remove() callback unimplemented. I must have accidentally been 
test-loading the wrong version of the kernel module in an earlier 
experiment. So all does indeed seem to be well. I'll provide a revised 
patch shortly, after some additional testing.

Re: [PATCH v3] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Andy Shevchenko]

On Wed, Aug 25, 2021 at 1:09 AM Daniel Dadap <ddadap@nvidia.com> wrote:
>
> A number of upcoming notebook computer designs drive the internal
> display panel's backlight PWM through the Embedded Controller (EC).
> This EC-based backlight control can be plumbed through to an ACPI
> "WMAA" method interface, which in turn can be wrapped by WMI with
> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
>
> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
> backlight class driver to control backlight levels on systems with
> EC-driven backlights.

I tried to avoid repetition of the comments given by others.

So, mine below.

...

> +config WMAA_BACKLIGHT_WMI
> +       tristate "ACPI WMAA Backlight Driver"
> +       depends on ACPI_WMI
> +       depends on BACKLIGHT_CLASS_DEVICE
> +       help
> +         This driver provides a sysfs backlight interface for notebook
> +         systems which expose the WMAA ACPI method and an associated WMI
> +         wrapper to drive LCD backlight levels through the system's
> +         Embedded Controller.

Please, add a sentence to tell how the module will be called. There
are plenty of examples in the kernel.

...

> +struct wmaa_args {
> +       u32 set;
> +       u32 val;
> +       u32 ret;
> +       u32 ignored[3];
> +};

I guess this structure deserves a kernel doc.

...

> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
> +       { .guid_string = WMAA_WMI_GUID },

> +       { },

No comma for termination.

> +};

...

> +static int wmaa_backlight_get_brightness(struct backlight_device *bd)
> +{
> +       u32 level;
> +       int ret;
> +
> +       ret = wmaa_get_brightness(&level);

> +       WARN_ON(ret != 0);

Why?

> +       return ret == 0 ? level : 0;
> +}

...

> +static int wmaa_backlight_wmi_probe(struct wmi_device *w, const void *ctx)
> +{
> +       struct backlight_properties props = {0};

{} is slightly better.

> +       struct wmi_wmaa_priv *priv;
> +       u32 source;
> +       int ret;
> +
> +       priv = devm_kmalloc(&w->dev, sizeof(*priv), GFP_KERNEL);
> +       if(!priv)
> +               return -ENOMEM;

> +       wdev = w;

I'm wondering if it's possible to avoid having a global variable.

> +       ret = wmaa_get_brightness_source(&source);
> +       if (ret)
> +               goto done;
> +
> +       if (source != WMAA_SOURCE_EC) {
> +               ret = -ENODEV;
> +               goto done;
> +       }
> +
> +       // Register a backlight handler
> +       props.type = BACKLIGHT_PLATFORM;
> +       ret = wmaa_get_max_brightness(&props.max_brightness);
> +       if (ret)
> +               goto done;
> +
> +       ret = wmaa_get_brightness(&props.brightness);
> +       if (ret)
> +               goto done;
> +
> +       priv->backlight = backlight_device_register("wmaa_backlight",
> +               NULL, NULL, &wmaa_backlight_ops, &props);
> +       if (IS_ERR(priv->backlight))
> +               return PTR_ERR(priv->backlight);
> +
> +       dev_set_drvdata(&w->dev, priv);

> +done:

Useless. Return directly.

> +       return ret;
> +}

...

> +static struct wmi_driver wmaa_backlight_wmi_driver = {
> +       .driver = {
> +               .name = "wmaa-backlight",
> +       },
> +       .probe = wmaa_backlight_wmi_probe,
> +       .remove = wmaa_backlight_wmi_remove,
> +       .id_table = wmaa_backlight_wmi_id_table,
> +};

> +

Redundant blank line.

> +module_wmi_driver(wmaa_backlight_wmi_driver);

...

> +
> +MODULE_ALIAS("wmi:"WMAA_WMI_GUID);

Can you move this closer to GUID? But I'm not sure what is the
preferred style. Hans?

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v3] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

Thanks again:

On 8/25/21 4:05 AM, Andy Shevchenko wrote:
> On Wed, Aug 25, 2021 at 1:09 AM Daniel Dadap <ddadap@nvidia.com> wrote:
>> A number of upcoming notebook computer designs drive the internal
>> display panel's backlight PWM through the Embedded Controller (EC).
>> This EC-based backlight control can be plumbed through to an ACPI
>> "WMAA" method interface, which in turn can be wrapped by WMI with
>> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
>>
>> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
>> backlight class driver to control backlight levels on systems with
>> EC-driven backlights.
> I tried to avoid repetition of the comments given by others.
>
> So, mine below.
>
> ...
>
>> +config WMAA_BACKLIGHT_WMI
>> +       tristate "ACPI WMAA Backlight Driver"
>> +       depends on ACPI_WMI
>> +       depends on BACKLIGHT_CLASS_DEVICE
>> +       help
>> +         This driver provides a sysfs backlight interface for notebook
>> +         systems which expose the WMAA ACPI method and an associated WMI
>> +         wrapper to drive LCD backlight levels through the system's
>> +         Embedded Controller.
> Please, add a sentence to tell how the module will be called. There
> are plenty of examples in the kernel.
>
> ...
>
>> +struct wmaa_args {
>> +       u32 set;
>> +       u32 val;
>> +       u32 ret;
>> +       u32 ignored[3];
>> +};
> I guess this structure deserves a kernel doc.


Do you have a recommended location? From a quick skim I didn't see any 
document in Documentation/ that seemed most appropriate to add this to.


>
> ...
>
>> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
>> +       { .guid_string = WMAA_WMI_GUID },
>> +       { },
> No comma for termination.
>
>> +};
> ...
>
>> +static int wmaa_backlight_get_brightness(struct backlight_device *bd)
>> +{
>> +       u32 level;
>> +       int ret;
>> +
>> +       ret = wmaa_get_brightness(&level);
>> +       WARN_ON(ret != 0);
> Why?


To differentiate a 0 because the level is actually 0 versus a 0 because 
there was an error. The backlight device API doesn't seem to have a way 
to report errors.


>> +       return ret == 0 ? level : 0;
>> +}
> ...
>
>> +static int wmaa_backlight_wmi_probe(struct wmi_device *w, const void *ctx)
>> +{
>> +       struct backlight_properties props = {0};
> {} is slightly better.
>
>> +       struct wmi_wmaa_priv *priv;
>> +       u32 source;
>> +       int ret;
>> +
>> +       priv = devm_kmalloc(&w->dev, sizeof(*priv), GFP_KERNEL);
>> +       if(!priv)
>> +               return -ENOMEM;
>> +       wdev = w;
> I'm wondering if it's possible to avoid having a global variable.


It is; this can be stored in the struct backlight_device.


>
>> +       ret = wmaa_get_brightness_source(&source);
>> +       if (ret)
>> +               goto done;
>> +
>> +       if (source != WMAA_SOURCE_EC) {
>> +               ret = -ENODEV;
>> +               goto done;
>> +       }
>> +
>> +       // Register a backlight handler
>> +       props.type = BACKLIGHT_PLATFORM;
>> +       ret = wmaa_get_max_brightness(&props.max_brightness);
>> +       if (ret)
>> +               goto done;
>> +
>> +       ret = wmaa_get_brightness(&props.brightness);
>> +       if (ret)
>> +               goto done;
>> +
>> +       priv->backlight = backlight_device_register("wmaa_backlight",
>> +               NULL, NULL, &wmaa_backlight_ops, &props);
>> +       if (IS_ERR(priv->backlight))
>> +               return PTR_ERR(priv->backlight);
>> +
>> +       dev_set_drvdata(&w->dev, priv);
>> +done:
> Useless. Return directly.


Yeah, most likely there used to be some other cleanup here. Thanks.


>
>> +       return ret;
>> +}
> ...
>
>> +static struct wmi_driver wmaa_backlight_wmi_driver = {
>> +       .driver = {
>> +               .name = "wmaa-backlight",
>> +       },
>> +       .probe = wmaa_backlight_wmi_probe,
>> +       .remove = wmaa_backlight_wmi_remove,
>> +       .id_table = wmaa_backlight_wmi_id_table,
>> +};
>> +
> Redundant blank line.
>
>> +module_wmi_driver(wmaa_backlight_wmi_driver);
> ...
>
>> +
>> +MODULE_ALIAS("wmi:"WMAA_WMI_GUID);
> Can you move this closer to GUID? But I'm not sure what is the
> preferred style. Hans?


I'll do whatever is most stylistically preferred.

Re: [PATCH v3] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Thomas Weißschuh]

On Mi, 2021-08-25T11:47-0500, Daniel Dadap wrote:
>> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
>> +       { .guid_string = WMAA_WMI_GUID },
>> +       { },

> > > +MODULE_ALIAS("wmi:"WMAA_WMI_GUID);
> > Can you move this closer to GUID? But I'm not sure what is the
> > preferred style. Hans?
> 
> 
> I'll do whatever is most stylistically preferred.
> 

This could also be expressed as, which is presumably the nicer way:

MODULE_DEVICE_TABLE(wmi, wmaa_backlight_wmi_id_table);

Thomas

Re: [PATCH v3] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

On 8/25/21 5:06 PM, Thomas Weißschuh wrote:
> On Mi, 2021-08-25T11:47-0500, Daniel Dadap wrote:
>>> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
>>> +       { .guid_string = WMAA_WMI_GUID },
>>> +       { },
>>>> +MODULE_ALIAS("wmi:"WMAA_WMI_GUID);
>>> Can you move this closer to GUID? But I'm not sure what is the
>>> preferred style. Hans?
>>
>> I'll do whatever is most stylistically preferred.
>>
> This could also be expressed as, which is presumably the nicer way:
>
> MODULE_DEVICE_TABLE(wmi, wmaa_backlight_wmi_id_table);


Okay, thanks. In the meantime I've moved the declaration of this table 
and the #define for the WMAA_WMI_GUID macro down to the end of the file, 
right before the pile of MODULE_* macros where we also use WMAA_WMI_GUID 
for the modalias, but if there's a more preferred style here just let me 
know.

Re: [PATCH v3] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Andy Shevchenko]

On Wed, Aug 25, 2021 at 7:48 PM Daniel Dadap <ddadap@nvidia.com> wrote:
> On 8/25/21 4:05 AM, Andy Shevchenko wrote:
> > On Wed, Aug 25, 2021 at 1:09 AM Daniel Dadap <ddadap@nvidia.com> wrote:

...

> >> +struct wmaa_args {
> >> +       u32 set;
> >> +       u32 val;
> >> +       u32 ret;
> >> +       u32 ignored[3];
> >> +};
> > I guess this structure deserves a kernel doc.
>
> Do you have a recommended location? From a quick skim I didn't see any
> document in Documentation/ that seemed most appropriate to add this to.

It's in a form of the comment on top of the data structure

/**
 * struct wmaa_args ....
 * ...
 */

...

> >> +       WARN_ON(ret != 0);
> > Why?
>
> To differentiate a 0 because the level is actually 0 versus a 0 because
> there was an error. The backlight device API doesn't seem to have a way
> to report errors.

I meant why do you need WARN_ON() here? This kind of stuff must be justified.

--
With Best Regards,
Andy Shevchenko

Re: [PATCH v3] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

On 8/26/21 8:35 AM, Andy Shevchenko wrote:
> On Wed, Aug 25, 2021 at 7:48 PM Daniel Dadap <ddadap@nvidia.com> wrote:
>> On 8/25/21 4:05 AM, Andy Shevchenko wrote:
>>> On Wed, Aug 25, 2021 at 1:09 AM Daniel Dadap <ddadap@nvidia.com> wrote:
> ...
>
>>>> +struct wmaa_args {
>>>> +       u32 set;
>>>> +       u32 val;
>>>> +       u32 ret;
>>>> +       u32 ignored[3];
>>>> +};
>>> I guess this structure deserves a kernel doc.
>> Do you have a recommended location? From a quick skim I didn't see any
>> document in Documentation/ that seemed most appropriate to add this to.
> It's in a form of the comment on top of the data structure
>
> /**
>   * struct wmaa_args ....
>   * ...
>   */
>
> ...


Ah, of course. Sorry for misunderstanding.


>>>> +       WARN_ON(ret != 0);
>>> Why?
>> To differentiate a 0 because the level is actually 0 versus a 0 because
>> there was an error. The backlight device API doesn't seem to have a way
>> to report errors.
> I meant why do you need WARN_ON() here? This kind of stuff must be justified.


Thanks, I see what you mean now. I'll change it to a dev_warn() or maybe 
even a dev_err(), since if the ACPI call does fail there probably is 
something quite amiss.

[PATCH v4] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

A number of upcoming notebook computer designs drive the internal
display panel's backlight PWM through the Embedded Controller (EC).
This EC-based backlight control can be plumbed through to an ACPI
"WMAA" method interface, which in turn can be wrapped by WMI with
the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.

Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
backlight class driver to control backlight levels on systems with
EC-driven backlights.

Signed-off-by: Aaron Plattner <aplattner@nvidia.com>
Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
---

v2: Convert to WMI subsystem driver, suggested by Mario Limonciello
     <mario.limonciello@outlook.com>; various cleanups suggested by
     Barnabás Pőcze <pobrn@protonmail.com>
v3: Address assorted style nits raised by Andy Shevchenko
     <andy.shevchenko@gmail.com> in response to a related patch; remove
     additional behavior change to WMI subsystem from patch series as
     recommended by Hans de Goede <hdegoede@redhat.com> 
v4: Use MODULE_DEVICE_TABLE() (Thomas Weißschuh <thomas@t-8ch.de>)
    Fix scope of internal driver state; various style fixes (Barnabás
    PÅ‘cze, Andy Shevchenko)
    Use devm_backlight_device_register() (Barnabás Pőcze)
    Add kerneldoc comments for enums and structs (Andy Shevchenko)

 MAINTAINERS                               |   6 +
 drivers/platform/x86/Kconfig              |  16 ++
 drivers/platform/x86/Makefile             |   1 +
 drivers/platform/x86/wmaa-backlight-wmi.c | 185 ++++++++++++++++++++++
 4 files changed, 208 insertions(+)
 create mode 100644 drivers/platform/x86/wmaa-backlight-wmi.c

diff --git a/MAINTAINERS b/MAINTAINERS
index bbaecde94aa0..fd7362a86c6d 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -20008,6 +20008,12 @@ L:	linux-wireless@vger.kernel.org
 S:	Odd fixes
 F:	drivers/net/wireless/wl3501*
 
+WMAA BACKLIGHT DRIVER
+M:	Daniel Dadap <ddadap@nvidia.com>
+L:	platform-driver-x86@vger.kernel.org
+S:	Supported
+F:	drivers/platform/x86/wmaa-backlight-wmi.c
+
 WOLFSON MICROELECTRONICS DRIVERS
 L:	patches@opensource.cirrus.com
 S:	Supported
diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
index d12db6c316ea..0df908ef8d7c 100644
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -113,6 +113,22 @@ config PEAQ_WMI
 	help
 	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
 
+config WMAA_BACKLIGHT_WMI
+	tristate "ACPI WMAA Backlight Driver"
+	depends on ACPI_WMI
+	depends on BACKLIGHT_CLASS_DEVICE
+	help
+	  This driver provides a sysfs backlight interface for notebook
+	  systems which expose the WMAA ACPI method and an associated WMI
+	  wrapper to drive LCD backlight levels through the system's
+	  Embedded Controller (EC).
+
+	  Say Y or M here if you want to control the backlight on a notebook
+	  system with an EC-driven backlight using the ACPI WMAA method.
+
+	  If you choose to compile this driver as a module the module will be
+	  called wmaa-backlight-wmi.
+
 config XIAOMI_WMI
 	tristate "Xiaomi WMI key driver"
 	depends on ACPI_WMI
diff --git a/drivers/platform/x86/Makefile b/drivers/platform/x86/Makefile
index 7ee369aab10d..109c1714237d 100644
--- a/drivers/platform/x86/Makefile
+++ b/drivers/platform/x86/Makefile
@@ -14,6 +14,7 @@ obj-$(CONFIG_INTEL_WMI_SBL_FW_UPDATE)	+= intel-wmi-sbl-fw-update.o
 obj-$(CONFIG_INTEL_WMI_THUNDERBOLT)	+= intel-wmi-thunderbolt.o
 obj-$(CONFIG_MXM_WMI)			+= mxm-wmi.o
 obj-$(CONFIG_PEAQ_WMI)			+= peaq-wmi.o
+obj-$(CONFIG_WMAA_BACKLIGHT_WMI)	+= wmaa-backlight-wmi.o
 obj-$(CONFIG_XIAOMI_WMI)		+= xiaomi-wmi.o
 obj-$(CONFIG_GIGABYTE_WMI)		+= gigabyte-wmi.o
 
diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
new file mode 100644
index 000000000000..cb1a973803b1
--- /dev/null
+++ b/drivers/platform/x86/wmaa-backlight-wmi.c
@@ -0,0 +1,185 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * Copyright (c) 2020, NVIDIA CORPORATION.  All rights reserved.
+ */
+
+#include <linux/backlight.h>
+#include <linux/module.h>
+#include <linux/wmi.h>
+
+/**
+ * enum wmaa_method - WMI method IDs for ACPI WMAA
+ *
+ * @WMAA_LEVEL:  Get or set the brightness level,
+ *               or get the maximum brightness level.
+ * @WMAA_SOURCE: Get the source for backlight control.
+ */
+enum wmaa_method {
+	WMAA_LEVEL = 1,
+	WMAA_SOURCE = 2,
+};
+
+/**
+ * enum wmaa_get_or_set - Operation mode for ACPI WMAA method
+ *
+ * @WMAA_GET:     Get the current brightness level or backlight source.
+ * @WMAA_SET:     Set the brightness level.
+ * @WMAA_GET_MAX: Get the maximum brightness level. This is only valid when the
+ *                WMI method is %WMAA_LEVEL.
+ */
+enum wmaa_get_or_set {
+	WMAA_GET = 0,
+	WMAA_SET = 1,
+	WMAA_GET_MAX = 2
+};
+
+/**
+ * enum wmaa_source - Backlight brightness control source identification
+ *
+ * @WMAA_SOURCE_GPU:   Backlight brightness is controlled by the GPU.
+ * @WMAA_SOURCE_EC:    Backlight brightness is controlled by the system's
+ *                     Embedded Controller (EC).
+ * @WMAA_SOURCE_AUX:   Backlight brightness is controlled over the DisplayPort
+ *                     AUX channel.
+ */
+enum wmaa_source {
+	WMAA_SOURCE_GPU = 1,
+	WMAA_SOURCE_EC = 2,
+	WMAA_SOURCE_AUX = 3
+};
+
+/**
+ * struct wmaa_args - arguments for the ACPI WMAA method
+ *
+ * @set:     Pass in an &enum wmaa_get_or_set value to select between getting or
+ *           setting a value.
+ * @val:     In parameter for value to set when operating in %WMAA_SET mode. Not
+ *           used in %WMAA_GET or %WMAA_GET_MAX mode.
+ * @ret:     Out parameter returning retrieved value when operating in %WMAA_GET
+ *           or %WMAA_GET_MAX mode. Not used in %WMAA_SET mode.
+ * @ignored: Padding; not used. The ACPI method expects a 24 byte params struct.
+ *
+ * This is the parameters structure for the ACPI WMAA method as wrapped by WMI.
+ * The value passed in to @val or returned by @ret will be a brightness value
+ * when the WMI method ID is %WMAA_LEVEL, or an &enum wmaa_source value when
+ * the WMI method ID is %WMAA_SOURCE.
+ */
+struct wmaa_args {
+	u32 set;
+	u32 val;
+	u32 ret;
+	u32 ignored[3];
+};
+
+static int wmi_call_wmaa(struct wmi_device *w, enum wmaa_method method, enum wmaa_get_or_set set, u32 *val)
+{
+	struct wmaa_args args = {
+		.set = set,
+		.val = 0,
+		.ret = 0,
+	};
+	struct acpi_buffer buf = { (acpi_size)sizeof(args), &args };
+	acpi_status status;
+
+	if (set == WMAA_SET)
+		args.val = *val;
+
+	status = wmidev_evaluate_method(w, 0, method, &buf, &buf);
+	if (ACPI_FAILURE(status)) {
+		dev_err(&w->dev, "ACPI WMAA failed with %s\n",
+			acpi_format_exception(status));
+		return -EIO;
+	}
+
+	if (set != WMAA_SET)
+		*val = args.ret;
+
+	return 0;
+}
+
+static int wmaa_backlight_update_status(struct backlight_device *bd)
+{
+	struct wmi_device *wdev = bl_get_data(bd);
+
+	return wmi_call_wmaa(wdev, WMAA_LEVEL, WMAA_SET, &bd->props.brightness);
+}
+
+static int wmaa_backlight_get_brightness(struct backlight_device *bd)
+{
+	struct wmi_device *wdev = bl_get_data(bd);
+	u32 level = 0;
+	int ret;
+
+	ret = wmi_call_wmaa(wdev, WMAA_LEVEL, WMAA_GET, &level);
+
+	if (ret)
+		dev_err(&bd->dev, "ACPI WMAA failed to get backlight level.\n");
+
+	return level;
+}
+
+static const struct backlight_ops wmaa_backlight_ops = {
+	.update_status = wmaa_backlight_update_status,
+	.get_brightness = wmaa_backlight_get_brightness
+};
+
+static int wmaa_backlight_wmi_probe(struct wmi_device *w, const void *ctx)
+{
+	struct backlight_properties props = {};
+	struct backlight_device *backlight;
+	u32 source;
+	int ret;
+
+	ret = wmi_call_wmaa(w, WMAA_SOURCE, WMAA_GET, &source);
+	if (ret)
+		return ret;
+
+	if (source != WMAA_SOURCE_EC) {
+		/* This driver is only to be used when brightness control is
+		 * handled by the EC; otherwise, the GPU driver(s) should handle
+		 * brightness control. */
+		return -ENODEV;
+	}
+
+	/* Identify this backlight device as a platform device so that it can
+	 * be prioritized over any exposed GPU-driven raw device(s). */
+	props.type = BACKLIGHT_PLATFORM;
+
+	ret = wmi_call_wmaa(w, WMAA_LEVEL, WMAA_GET_MAX, &props.max_brightness);
+	if (ret)
+		return ret;
+
+	ret = wmi_call_wmaa(w, WMAA_LEVEL, WMAA_GET, &props.brightness);
+	if (ret)
+		return ret;
+
+	backlight = devm_backlight_device_register(
+		&w->dev, "wmaa_backlight",
+		&w->dev, w, &wmaa_backlight_ops, &props);
+	if (IS_ERR(backlight))
+		return PTR_ERR(backlight);
+
+	return 0;
+}
+
+#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
+
+static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
+	{ .guid_string = WMAA_WMI_GUID },
+	{ }
+};
+MODULE_DEVICE_TABLE(wmi, wmaa_backlight_wmi_id_table);
+
+static struct wmi_driver wmaa_backlight_wmi_driver = {
+	.driver = {
+		.name = "wmaa-backlight"
+	},
+	.probe = wmaa_backlight_wmi_probe,
+	.id_table = wmaa_backlight_wmi_id_table
+};
+module_wmi_driver(wmaa_backlight_wmi_driver);
+
+MODULE_AUTHOR("Aaron Plattner <aplattner@nvidia.com>");
+MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
+MODULE_DESCRIPTION("WMAA Backlight WMI driver");
+MODULE_LICENSE("GPL v2");
-- 
2.20.1

Re: [PATCH v4] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Thomas Weißschuh]

Hi Daniel,

a few minor comments, not sure if they should be reason for a reroll.

Thomas

Reviewed-By: Thomas Weißschuh <linux@weissschuh.net>

On Di, 2021-08-31T17:49-0500, Daniel Dadap wrote:
> 
> A number of upcoming notebook computer designs drive the internal
> display panel's backlight PWM through the Embedded Controller (EC).
> This EC-based backlight control can be plumbed through to an ACPI
> "WMAA" method interface, which in turn can be wrapped by WMI with
> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
> 
> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
> backlight class driver to control backlight levels on systems with
> EC-driven backlights.
> 
> Signed-off-by: Aaron Plattner <aplattner@nvidia.com>
> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
> ---
> 
> v2: Convert to WMI subsystem driver, suggested by Mario Limonciello
>      <mario.limonciello@outlook.com>; various cleanups suggested by
>      Barnab??s P??cze <pobrn@protonmail.com>
> v3: Address assorted style nits raised by Andy Shevchenko
>      <andy.shevchenko@gmail.com> in response to a related patch; remove
>      additional behavior change to WMI subsystem from patch series as
>      recommended by Hans de Goede <hdegoede@redhat.com> 
> v4: Use MODULE_DEVICE_TABLE() (Thomas Wei??schuh <thomas@t-8ch.de>)
>     Fix scope of internal driver state; various style fixes (Barnab??s
>     P??cze, Andy Shevchenko)
>     Use devm_backlight_device_register() (Barnab??s P??cze)
>     Add kerneldoc comments for enums and structs (Andy Shevchenko)

It seems your Mailsetup breaks Unicode.

>  MAINTAINERS                               |   6 +
>  drivers/platform/x86/Kconfig              |  16 ++
>  drivers/platform/x86/Makefile             |   1 +
>  drivers/platform/x86/wmaa-backlight-wmi.c | 185 ++++++++++++++++++++++
>  4 files changed, 208 insertions(+)
>  create mode 100644 drivers/platform/x86/wmaa-backlight-wmi.c
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index bbaecde94aa0..fd7362a86c6d 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -20008,6 +20008,12 @@ L:	linux-wireless@vger.kernel.org
>  S:	Odd fixes
>  F:	drivers/net/wireless/wl3501*
>  
> +WMAA BACKLIGHT DRIVER
> +M:	Daniel Dadap <ddadap@nvidia.com>
> +L:	platform-driver-x86@vger.kernel.org
> +S:	Supported
> +F:	drivers/platform/x86/wmaa-backlight-wmi.c
> +
>  WOLFSON MICROELECTRONICS DRIVERS
>  L:	patches@opensource.cirrus.com
>  S:	Supported
> diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
> index d12db6c316ea..0df908ef8d7c 100644
> --- a/drivers/platform/x86/Kconfig
> +++ b/drivers/platform/x86/Kconfig
> @@ -113,6 +113,22 @@ config PEAQ_WMI
>  	help
>  	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
>  
> +config WMAA_BACKLIGHT_WMI
> +	tristate "ACPI WMAA Backlight Driver"
> +	depends on ACPI_WMI
> +	depends on BACKLIGHT_CLASS_DEVICE
> +	help
> +	  This driver provides a sysfs backlight interface for notebook
> +	  systems which expose the WMAA ACPI method and an associated WMI
> +	  wrapper to drive LCD backlight levels through the system's
> +	  Embedded Controller (EC).
> +
> +	  Say Y or M here if you want to control the backlight on a notebook
> +	  system with an EC-driven backlight using the ACPI WMAA method.
> +
> +	  If you choose to compile this driver as a module the module will be
> +	  called wmaa-backlight-wmi.
> +
>  config XIAOMI_WMI
>  	tristate "Xiaomi WMI key driver"
>  	depends on ACPI_WMI
> diff --git a/drivers/platform/x86/Makefile b/drivers/platform/x86/Makefile
> index 7ee369aab10d..109c1714237d 100644
> --- a/drivers/platform/x86/Makefile
> +++ b/drivers/platform/x86/Makefile
> @@ -14,6 +14,7 @@ obj-$(CONFIG_INTEL_WMI_SBL_FW_UPDATE)	+= intel-wmi-sbl-fw-update.o
>  obj-$(CONFIG_INTEL_WMI_THUNDERBOLT)	+= intel-wmi-thunderbolt.o
>  obj-$(CONFIG_MXM_WMI)			+= mxm-wmi.o
>  obj-$(CONFIG_PEAQ_WMI)			+= peaq-wmi.o
> +obj-$(CONFIG_WMAA_BACKLIGHT_WMI)	+= wmaa-backlight-wmi.o
>  obj-$(CONFIG_XIAOMI_WMI)		+= xiaomi-wmi.o
>  obj-$(CONFIG_GIGABYTE_WMI)		+= gigabyte-wmi.o
>  
> diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
> new file mode 100644
> index 000000000000..cb1a973803b1
> --- /dev/null
> +++ b/drivers/platform/x86/wmaa-backlight-wmi.c
> @@ -0,0 +1,185 @@
> +// SPDX-License-Identifier: GPL-2.0-only
> +/*
> + * Copyright (c) 2020, NVIDIA CORPORATION.  All rights reserved.

Also 2021?

> + */
> +
> +#include <linux/backlight.h>
> +#include <linux/module.h>
> +#include <linux/wmi.h>
> +
> +/**
> + * enum wmaa_method - WMI method IDs for ACPI WMAA
> + *
> + * @WMAA_LEVEL:  Get or set the brightness level,
> + *               or get the maximum brightness level.
> + * @WMAA_SOURCE: Get the source for backlight control.
> + */
> +enum wmaa_method {
> +	WMAA_LEVEL = 1,
> +	WMAA_SOURCE = 2,
> +};

Nitpick: No need for explicit values here.

> +/**
> + * enum wmaa_get_or_set - Operation mode for ACPI WMAA method
> + *
> + * @WMAA_GET:     Get the current brightness level or backlight source.
> + * @WMAA_SET:     Set the brightness level.
> + * @WMAA_GET_MAX: Get the maximum brightness level. This is only valid when the
> + *                WMI method is %WMAA_LEVEL.
> + */
> +enum wmaa_get_or_set {

Nitpick: wmaa_operation/command

> +	WMAA_GET = 0,
> +	WMAA_SET = 1,
> +	WMAA_GET_MAX = 2
> +};

Nitpick: No need for explicit values here.

> +/**
> + * enum wmaa_source - Backlight brightness control source identification
> + *
> + * @WMAA_SOURCE_GPU:   Backlight brightness is controlled by the GPU.
> + * @WMAA_SOURCE_EC:    Backlight brightness is controlled by the system's
> + *                     Embedded Controller (EC).
> + * @WMAA_SOURCE_AUX:   Backlight brightness is controlled over the DisplayPort
> + *                     AUX channel.
> + */
> +enum wmaa_source {
> +	WMAA_SOURCE_GPU = 1,
> +	WMAA_SOURCE_EC = 2,
> +	WMAA_SOURCE_AUX = 3
> +};
> +
> +/**
> + * struct wmaa_args - arguments for the ACPI WMAA method
> + *
> + * @set:     Pass in an &enum wmaa_get_or_set value to select between getting or
> + *           setting a value.
> + * @val:     In parameter for value to set when operating in %WMAA_SET mode. Not
> + *           used in %WMAA_GET or %WMAA_GET_MAX mode.
> + * @ret:     Out parameter returning retrieved value when operating in %WMAA_GET
> + *           or %WMAA_GET_MAX mode. Not used in %WMAA_SET mode.
> + * @ignored: Padding; not used. The ACPI method expects a 24 byte params struct.
> + *
> + * This is the parameters structure for the ACPI WMAA method as wrapped by WMI.
> + * The value passed in to @val or returned by @ret will be a brightness value
> + * when the WMI method ID is %WMAA_LEVEL, or an &enum wmaa_source value when
> + * the WMI method ID is %WMAA_SOURCE.
> + */
> +struct wmaa_args {
> +	u32 set;
> +	u32 val;
> +	u32 ret;
> +	u32 ignored[3];
> +};
> +
> +static int wmi_call_wmaa(struct wmi_device *w, enum wmaa_method method, enum wmaa_get_or_set set, u32 *val)
> +{
> +	struct wmaa_args args = {
> +		.set = set,
> +		.val = 0,
> +		.ret = 0,
> +	};
> +	struct acpi_buffer buf = { (acpi_size)sizeof(args), &args };
> +	acpi_status status;
> +
> +	if (set == WMAA_SET)
> +		args.val = *val;
> +
> +	status = wmidev_evaluate_method(w, 0, method, &buf, &buf);
> +	if (ACPI_FAILURE(status)) {
> +		dev_err(&w->dev, "ACPI WMAA failed with %s\n",
> +			acpi_format_exception(status));
> +		return -EIO;
> +	}
> +
> +	if (set != WMAA_SET)
> +		*val = args.ret;
> +
> +	return 0;
> +}
> +
> +static int wmaa_backlight_update_status(struct backlight_device *bd)
> +{
> +	struct wmi_device *wdev = bl_get_data(bd);
> +
> +	return wmi_call_wmaa(wdev, WMAA_LEVEL, WMAA_SET, &bd->props.brightness);
> +}
> +
> +static int wmaa_backlight_get_brightness(struct backlight_device *bd)
> +{
> +	struct wmi_device *wdev = bl_get_data(bd);
> +	u32 level = 0;
> +	int ret;
> +
> +	ret = wmi_call_wmaa(wdev, WMAA_LEVEL, WMAA_GET, &level);
> +
> +	if (ret)
> +		dev_err(&bd->dev, "ACPI WMAA failed to get backlight level.\n");

Would it make sense to log the actual error?

Also while the backlight core does not seem to actually handle it, other
drivers return a negative errno on failure.

> +
> +	return level;
> +}
> +
> +static const struct backlight_ops wmaa_backlight_ops = {
> +	.update_status = wmaa_backlight_update_status,
> +	.get_brightness = wmaa_backlight_get_brightness
> +};
> +
> +static int wmaa_backlight_wmi_probe(struct wmi_device *w, const void *ctx)
> +{
> +	struct backlight_properties props = {};
> +	struct backlight_device *backlight;
> +	u32 source;
> +	int ret;
> +
> +	ret = wmi_call_wmaa(w, WMAA_SOURCE, WMAA_GET, &source);
> +	if (ret)
> +		return ret;
> +
> +	if (source != WMAA_SOURCE_EC) {
> +		/* This driver is only to be used when brightness control is
> +		 * handled by the EC; otherwise, the GPU driver(s) should handle
> +		 * brightness control. */

checkpatch.pl wants this end-of-comment to be on its own line.

> +		return -ENODEV;
> +	}
> +
> +	/* Identify this backlight device as a platform device so that it can
> +	 * be prioritized over any exposed GPU-driven raw device(s). */

checkpatch.pl wants this end-of-comment to be on its own line.

> +	props.type = BACKLIGHT_PLATFORM;

Is this WMI method a standard interface?
If so, BACKLIGHT_FIRMWARE might actually fit better and still fulfill the
requirements.
The actual maintainers would know better than me, though.

> +
> +	ret = wmi_call_wmaa(w, WMAA_LEVEL, WMAA_GET_MAX, &props.max_brightness);
> +	if (ret)
> +		return ret;
> +
> +	ret = wmi_call_wmaa(w, WMAA_LEVEL, WMAA_GET, &props.brightness);
> +	if (ret)
> +		return ret;
> +
> +	backlight = devm_backlight_device_register(
> +		&w->dev, "wmaa_backlight",
> +		&w->dev, w, &wmaa_backlight_ops, &props);
> +	if (IS_ERR(backlight))
> +		return PTR_ERR(backlight);
> +
> +	return 0;

Could use PTR_ERR_OR_ZERO().

> +}
> +
> +#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
> +
> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
> +	{ .guid_string = WMAA_WMI_GUID },
> +	{ }
> +};
> +MODULE_DEVICE_TABLE(wmi, wmaa_backlight_wmi_id_table);
> +
> +static struct wmi_driver wmaa_backlight_wmi_driver = {
> +	.driver = {
> +		.name = "wmaa-backlight"
> +	},
> +	.probe = wmaa_backlight_wmi_probe,
> +	.id_table = wmaa_backlight_wmi_id_table
> +};
> +module_wmi_driver(wmaa_backlight_wmi_driver);
> +
> +MODULE_AUTHOR("Aaron Plattner <aplattner@nvidia.com>");
> +MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
> +MODULE_DESCRIPTION("WMAA Backlight WMI driver");
> +MODULE_LICENSE("GPL v2");

"GPL" seems to be the more modern one.
(Equivalent to  "GPL v2", see Documentation/process/license-rules.rst)

Re: [PATCH v4] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

Thanks, Thomas:

On 9/1/21 4:25 AM, Thomas Weißschuh wrote:
> Hi Daniel,
>
> a few minor comments, not sure if they should be reason for a reroll.


I don't mind rerolling until I get an ACK from the maintainer. :)


>
> Thomas
>
> Reviewed-By: Thomas Weißschuh <linux@weissschuh.net>
>
> On Di, 2021-08-31T17:49-0500, Daniel Dadap wrote:
>> A number of upcoming notebook computer designs drive the internal
>> display panel's backlight PWM through the Embedded Controller (EC).
>> This EC-based backlight control can be plumbed through to an ACPI
>> "WMAA" method interface, which in turn can be wrapped by WMI with
>> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
>>
>> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
>> backlight class driver to control backlight levels on systems with
>> EC-driven backlights.
>>
>> Signed-off-by: Aaron Plattner <aplattner@nvidia.com>
>> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
>> ---
>>
>> v2: Convert to WMI subsystem driver, suggested by Mario Limonciello
>>       <mario.limonciello@outlook.com>; various cleanups suggested by
>>       Barnab??s P??cze <pobrn@protonmail.com>
>> v3: Address assorted style nits raised by Andy Shevchenko
>>       <andy.shevchenko@gmail.com> in response to a related patch; remove
>>       additional behavior change to WMI subsystem from patch series as
>>       recommended by Hans de Goede <hdegoede@redhat.com>
>> v4: Use MODULE_DEVICE_TABLE() (Thomas Wei??schuh <thomas@t-8ch.de>)
>>      Fix scope of internal driver state; various style fixes (Barnab??s
>>      P??cze, Andy Shevchenko)
>>      Use devm_backlight_device_register() (Barnab??s P??cze)
>>      Add kerneldoc comments for enums and structs (Andy Shevchenko)
> It seems your Mailsetup breaks Unicode.


Strange. I've just been sending the patches via git email-patch. These 
characters are appearing correctly with my MUA (Thunderbird) in the copy 
of the message I received, so I don't know where in the pipeline they're 
getting corrupted. I'll ignore this problem unless anybody has some 
specific tips on fixing it, since the non-ASCII characters aren't going 
to actually be part of the git history of the patch.


>
>>   MAINTAINERS                               |   6 +
>>   drivers/platform/x86/Kconfig              |  16 ++
>>   drivers/platform/x86/Makefile             |   1 +
>>   drivers/platform/x86/wmaa-backlight-wmi.c | 185 ++++++++++++++++++++++
>>   4 files changed, 208 insertions(+)
>>   create mode 100644 drivers/platform/x86/wmaa-backlight-wmi.c
>>
>> diff --git a/MAINTAINERS b/MAINTAINERS
>> index bbaecde94aa0..fd7362a86c6d 100644
>> --- a/MAINTAINERS
>> +++ b/MAINTAINERS
>> @@ -20008,6 +20008,12 @@ L:	linux-wireless@vger.kernel.org
>>   S:	Odd fixes
>>   F:	drivers/net/wireless/wl3501*
>>   
>> +WMAA BACKLIGHT DRIVER
>> +M:	Daniel Dadap <ddadap@nvidia.com>
>> +L:	platform-driver-x86@vger.kernel.org
>> +S:	Supported
>> +F:	drivers/platform/x86/wmaa-backlight-wmi.c
>> +
>>   WOLFSON MICROELECTRONICS DRIVERS
>>   L:	patches@opensource.cirrus.com
>>   S:	Supported
>> diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
>> index d12db6c316ea..0df908ef8d7c 100644
>> --- a/drivers/platform/x86/Kconfig
>> +++ b/drivers/platform/x86/Kconfig
>> @@ -113,6 +113,22 @@ config PEAQ_WMI
>>   	help
>>   	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
>>   
>> +config WMAA_BACKLIGHT_WMI
>> +	tristate "ACPI WMAA Backlight Driver"
>> +	depends on ACPI_WMI
>> +	depends on BACKLIGHT_CLASS_DEVICE
>> +	help
>> +	  This driver provides a sysfs backlight interface for notebook
>> +	  systems which expose the WMAA ACPI method and an associated WMI
>> +	  wrapper to drive LCD backlight levels through the system's
>> +	  Embedded Controller (EC).
>> +
>> +	  Say Y or M here if you want to control the backlight on a notebook
>> +	  system with an EC-driven backlight using the ACPI WMAA method.
>> +
>> +	  If you choose to compile this driver as a module the module will be
>> +	  called wmaa-backlight-wmi.
>> +
>>   config XIAOMI_WMI
>>   	tristate "Xiaomi WMI key driver"
>>   	depends on ACPI_WMI
>> diff --git a/drivers/platform/x86/Makefile b/drivers/platform/x86/Makefile
>> index 7ee369aab10d..109c1714237d 100644
>> --- a/drivers/platform/x86/Makefile
>> +++ b/drivers/platform/x86/Makefile
>> @@ -14,6 +14,7 @@ obj-$(CONFIG_INTEL_WMI_SBL_FW_UPDATE)	+= intel-wmi-sbl-fw-update.o
>>   obj-$(CONFIG_INTEL_WMI_THUNDERBOLT)	+= intel-wmi-thunderbolt.o
>>   obj-$(CONFIG_MXM_WMI)			+= mxm-wmi.o
>>   obj-$(CONFIG_PEAQ_WMI)			+= peaq-wmi.o
>> +obj-$(CONFIG_WMAA_BACKLIGHT_WMI)	+= wmaa-backlight-wmi.o
>>   obj-$(CONFIG_XIAOMI_WMI)		+= xiaomi-wmi.o
>>   obj-$(CONFIG_GIGABYTE_WMI)		+= gigabyte-wmi.o
>>   
>> diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
>> new file mode 100644
>> index 000000000000..cb1a973803b1
>> --- /dev/null
>> +++ b/drivers/platform/x86/wmaa-backlight-wmi.c
>> @@ -0,0 +1,185 @@
>> +// SPDX-License-Identifier: GPL-2.0-only
>> +/*
>> + * Copyright (c) 2020, NVIDIA CORPORATION.  All rights reserved.
> Also 2021?


The code was originally written in 2020. I'm not certain it's changed 
substantially enough to warrant updating the copyright date. Certainly 
there's no need to change the copyright date every time the file is 
touched. I suppose it wouldn't be wrong to have it read 2020-2021 or the 
like for the initial commit, but I personally prefer just having the 
initial date unless there's stronger guidance to do otherwise.


>
>> + */
>> +
>> +#include <linux/backlight.h>
>> +#include <linux/module.h>
>> +#include <linux/wmi.h>
>> +
>> +/**
>> + * enum wmaa_method - WMI method IDs for ACPI WMAA
>> + *
>> + * @WMAA_LEVEL:  Get or set the brightness level,
>> + *               or get the maximum brightness level.
>> + * @WMAA_SOURCE: Get the source for backlight control.
>> + */
>> +enum wmaa_method {
>> +	WMAA_LEVEL = 1,
>> +	WMAA_SOURCE = 2,
>> +};
> Nitpick: No need for explicit values here.


I think at least the 1 is required, but in any case I prefer to be 
explicit here to make it clear that these are the exact values required 
by the ACPI WMAA interface.


>
>> +/**
>> + * enum wmaa_get_or_set - Operation mode for ACPI WMAA method
>> + *
>> + * @WMAA_GET:     Get the current brightness level or backlight source.
>> + * @WMAA_SET:     Set the brightness level.
>> + * @WMAA_GET_MAX: Get the maximum brightness level. This is only valid when the
>> + *                WMI method is %WMAA_LEVEL.
>> + */
>> +enum wmaa_get_or_set {
> Nitpick: wmaa_operation/command


That is indeed better; thanks. I'll go with "mode", mainly because it's 
shorter.


>
>> +	WMAA_GET = 0,
>> +	WMAA_SET = 1,
>> +	WMAA_GET_MAX = 2
>> +};
> Nitpick: No need for explicit values here.
>
>> +/**
>> + * enum wmaa_source - Backlight brightness control source identification
>> + *
>> + * @WMAA_SOURCE_GPU:   Backlight brightness is controlled by the GPU.
>> + * @WMAA_SOURCE_EC:    Backlight brightness is controlled by the system's
>> + *                     Embedded Controller (EC).
>> + * @WMAA_SOURCE_AUX:   Backlight brightness is controlled over the DisplayPort
>> + *                     AUX channel.
>> + */
>> +enum wmaa_source {
>> +	WMAA_SOURCE_GPU = 1,
>> +	WMAA_SOURCE_EC = 2,
>> +	WMAA_SOURCE_AUX = 3
>> +};
>> +
>> +/**
>> + * struct wmaa_args - arguments for the ACPI WMAA method
>> + *
>> + * @set:     Pass in an &enum wmaa_get_or_set value to select between getting or
>> + *           setting a value.
>> + * @val:     In parameter for value to set when operating in %WMAA_SET mode. Not
>> + *           used in %WMAA_GET or %WMAA_GET_MAX mode.
>> + * @ret:     Out parameter returning retrieved value when operating in %WMAA_GET
>> + *           or %WMAA_GET_MAX mode. Not used in %WMAA_SET mode.
>> + * @ignored: Padding; not used. The ACPI method expects a 24 byte params struct.
>> + *
>> + * This is the parameters structure for the ACPI WMAA method as wrapped by WMI.
>> + * The value passed in to @val or returned by @ret will be a brightness value
>> + * when the WMI method ID is %WMAA_LEVEL, or an &enum wmaa_source value when
>> + * the WMI method ID is %WMAA_SOURCE.
>> + */
>> +struct wmaa_args {
>> +	u32 set;
>> +	u32 val;
>> +	u32 ret;
>> +	u32 ignored[3];
>> +};
>> +
>> +static int wmi_call_wmaa(struct wmi_device *w, enum wmaa_method method, enum wmaa_get_or_set set, u32 *val)
>> +{
>> +	struct wmaa_args args = {
>> +		.set = set,
>> +		.val = 0,
>> +		.ret = 0,
>> +	};
>> +	struct acpi_buffer buf = { (acpi_size)sizeof(args), &args };
>> +	acpi_status status;
>> +
>> +	if (set == WMAA_SET)
>> +		args.val = *val;
>> +
>> +	status = wmidev_evaluate_method(w, 0, method, &buf, &buf);
>> +	if (ACPI_FAILURE(status)) {
>> +		dev_err(&w->dev, "ACPI WMAA failed with %s\n",
>> +			acpi_format_exception(status));
>> +		return -EIO;
>> +	}
>> +
>> +	if (set != WMAA_SET)
>> +		*val = args.ret;
>> +
>> +	return 0;
>> +}
>> +
>> +static int wmaa_backlight_update_status(struct backlight_device *bd)
>> +{
>> +	struct wmi_device *wdev = bl_get_data(bd);
>> +
>> +	return wmi_call_wmaa(wdev, WMAA_LEVEL, WMAA_SET, &bd->props.brightness);
>> +}
>> +
>> +static int wmaa_backlight_get_brightness(struct backlight_device *bd)
>> +{
>> +	struct wmi_device *wdev = bl_get_data(bd);
>> +	u32 level = 0;
>> +	int ret;
>> +
>> +	ret = wmi_call_wmaa(wdev, WMAA_LEVEL, WMAA_GET, &level);
>> +
>> +	if (ret)
>> +		dev_err(&bd->dev, "ACPI WMAA failed to get backlight level.\n");
> Would it make sense to log the actual error?


I think the underlying ACPI error is already logged by wmi_call_wmaa().


> Also while the backlight core does not seem to actually handle it, other
> drivers return a negative errno on failure.


Thanks, I was aware that the backlight core doesn't seem to handle 
errors at all for .get_brightness, but I didn't think to check for 
precedent on backlight drivers returning error codes anyway. Returning 
negative errno does seem somewhat common amongst backlight drivers, so 
I'll go ahead and do that in case the backlight core is updated to 
handle them in the future.


>
>> +
>> +	return level;
>> +}
>> +
>> +static const struct backlight_ops wmaa_backlight_ops = {
>> +	.update_status = wmaa_backlight_update_status,
>> +	.get_brightness = wmaa_backlight_get_brightness
>> +};
>> +
>> +static int wmaa_backlight_wmi_probe(struct wmi_device *w, const void *ctx)
>> +{
>> +	struct backlight_properties props = {};
>> +	struct backlight_device *backlight;
>> +	u32 source;
>> +	int ret;
>> +
>> +	ret = wmi_call_wmaa(w, WMAA_SOURCE, WMAA_GET, &source);
>> +	if (ret)
>> +		return ret;
>> +
>> +	if (source != WMAA_SOURCE_EC) {
>> +		/* This driver is only to be used when brightness control is
>> +		 * handled by the EC; otherwise, the GPU driver(s) should handle
>> +		 * brightness control. */
> checkpatch.pl wants this end-of-comment to be on its own line.
>
>> +		return -ENODEV;
>> +	}
>> +
>> +	/* Identify this backlight device as a platform device so that it can
>> +	 * be prioritized over any exposed GPU-driven raw device(s). */
> checkpatch.pl wants this end-of-comment to be on its own line.


Thanks. I neglected to run checkpatch.pl after adding those comments. 
Running it on the current version of the patch now only flags an 
over-long line (the signature of wmi_call_wmaa()); I had originally 
wrapped that to 80 characters, but was told to leave it as one line 
earlier in the review process.


>> +	props.type = BACKLIGHT_PLATFORM;
> Is this WMI method a standard interface?
> If so, BACKLIGHT_FIRMWARE might actually fit better and still fulfill the
> requirements.
> The actual maintainers would know better than me, though.


I'm not certain what you mean by standard. It's defined as part of 
system design guidelines that NVIDIA shares with OEMs, but I'm not sure 
if it's part of the ACPI spec. It is implemented by multiple notebook 
system vendors, hence naming the driver after the ACPI method rather 
than a particular vendor. Reading the documentation on the backlight 
driver types, it does seem that this may fall more under the purview of 
BACKLIGHT_FIRMWARE than BACKLIGHT_PLATFORM. I'll go ahead and retest 
with the driver registered as BACKLIGHT_FIRMWARE, but I'm sure it'll 
still work after inspecting the code for at least gnome-settings-daemon, 
which implements the policy recommended by 
Documentation/ABI/stable/sysfs-class-backlight.


>> +
>> +	ret = wmi_call_wmaa(w, WMAA_LEVEL, WMAA_GET_MAX, &props.max_brightness);
>> +	if (ret)
>> +		return ret;
>> +
>> +	ret = wmi_call_wmaa(w, WMAA_LEVEL, WMAA_GET, &props.brightness);
>> +	if (ret)
>> +		return ret;
>> +
>> +	backlight = devm_backlight_device_register(
>> +		&w->dev, "wmaa_backlight",
>> +		&w->dev, w, &wmaa_backlight_ops, &props);
>> +	if (IS_ERR(backlight))
>> +		return PTR_ERR(backlight);
>> +
>> +	return 0;
> Could use PTR_ERR_OR_ZERO().


Thanks, Andy suggested this too.


>
>> +}
>> +
>> +#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
>> +
>> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
>> +	{ .guid_string = WMAA_WMI_GUID },
>> +	{ }
>> +};
>> +MODULE_DEVICE_TABLE(wmi, wmaa_backlight_wmi_id_table);
>> +
>> +static struct wmi_driver wmaa_backlight_wmi_driver = {
>> +	.driver = {
>> +		.name = "wmaa-backlight"
>> +	},
>> +	.probe = wmaa_backlight_wmi_probe,
>> +	.id_table = wmaa_backlight_wmi_id_table
>> +};
>> +module_wmi_driver(wmaa_backlight_wmi_driver);
>> +
>> +MODULE_AUTHOR("Aaron Plattner <aplattner@nvidia.com>");
>> +MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
>> +MODULE_DESCRIPTION("WMAA Backlight WMI driver");
>> +MODULE_LICENSE("GPL v2");
> "GPL" seems to be the more modern one.
> (Equivalent to  "GPL v2", see Documentation/process/license-rules.rst)

Re: [PATCH v4] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Thomas Weißschuh]

On Mi, 2021-09-01T21:12-0500, Daniel Dadap wrote:
> Thanks, Thomas:
> 
> On 9/1/21 4:25 AM, Thomas Weißschuh wrote:
> > Hi Daniel,
> > 
> > a few minor comments, not sure if they should be reason for a reroll.
> 
> 
> I don't mind rerolling until I get an ACK from the maintainer. :)
> 
> 
> > 
> > Thomas
> > 
> > Reviewed-By: Thomas Weißschuh <linux@weissschuh.net>
> > 
> > On Di, 2021-08-31T17:49-0500, Daniel Dadap wrote:
> > > v2: Convert to WMI subsystem driver, suggested by Mario Limonciello
> > >       <mario.limonciello@outlook.com>; various cleanups suggested by
> > >       Barnab??s P??cze <pobrn@protonmail.com>
> > > v3: Address assorted style nits raised by Andy Shevchenko
> > >       <andy.shevchenko@gmail.com> in response to a related patch; remove
> > >       additional behavior change to WMI subsystem from patch series as
> > >       recommended by Hans de Goede <hdegoede@redhat.com>
> > > v4: Use MODULE_DEVICE_TABLE() (Thomas Wei??schuh <thomas@t-8ch.de>)
> > >      Fix scope of internal driver state; various style fixes (Barnab??s
> > >      P??cze, Andy Shevchenko)
> > >      Use devm_backlight_device_register() (Barnab??s P??cze)
> > >      Add kerneldoc comments for enums and structs (Andy Shevchenko)
> > It seems your Mailsetup breaks Unicode.
> 
> 
> Strange. I've just been sending the patches via git email-patch. These
> characters are appearing correctly with my MUA (Thunderbird) in the copy of
> the message I received, so I don't know where in the pipeline they're
> getting corrupted. I'll ignore this problem unless anybody has some specific
> tips on fixing it, since the non-ASCII characters aren't going to actually
> be part of the git history of the patch.

It seems that the encoding of the mail has been set as plain ASCII while it is
actually UTF-8.
Thunderbird is probly correctly inferring the actual encoding.
Normally git-format-patch would detect the Unicode characters and add a
matching content-type header to the patch.
But as these Unicode characters are added after format-patch has run it is now
git-send-emails task to add those headers again.

In my version of git I get the following message from git-send-email:

  The following files are 8bit, but do not declare a Content-Transfer-Encoding.
      0001-....patch
  Which 8bit encoding should I declare [UTF-8]?

As this feature seems to be really old already it should be available.
Is your "git email-patch" using "git send-email"?
Do you have "sendemail.assume8bitEncoding" set in your git config?
(It should either not be set or to UTF-8.

> > > diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
> > > new file mode 100644
> > > index 000000000000..cb1a973803b1
> > > --- /dev/null
> > > +++ b/drivers/platform/x86/wmaa-backlight-wmi.c
> > > @@ -0,0 +1,185 @@
> > > +// SPDX-License-Identifier: GPL-2.0-only
> > > +/*
> > > + * Copyright (c) 2020, NVIDIA CORPORATION.  All rights reserved.
> > Also 2021?
> 
> 
> The code was originally written in 2020. I'm not certain it's changed
> substantially enough to warrant updating the copyright date. Certainly
> there's no need to change the copyright date every time the file is touched.
> I suppose it wouldn't be wrong to have it read 2020-2021 or the like for the
> initial commit, but I personally prefer just having the initial date unless
> there's stronger guidance to do otherwise.

Ok.

> > 
> > > + */
> > > +
> > > +#include <linux/backlight.h>
> > > +#include <linux/module.h>
> > > +#include <linux/wmi.h>
> > > +
> > > +/**
> > > + * enum wmaa_method - WMI method IDs for ACPI WMAA
> > > + *
> > > + * @WMAA_LEVEL:  Get or set the brightness level,
> > > + *               or get the maximum brightness level.
> > > + * @WMAA_SOURCE: Get the source for backlight control.
> > > + */
> > > +enum wmaa_method {
> > > +	WMAA_LEVEL = 1,
> > > +	WMAA_SOURCE = 2,
> > > +};
> > Nitpick: No need for explicit values here.
> 
> 
> I think at least the 1 is required, but in any case I prefer to be explicit
> here to make it clear that these are the exact values required by the ACPI
> WMAA interface.

As this enum is part of the ABI to the firmware, the values should indeed have
explicit values.  Sorry for the noise.

> > > +
> > > +	if (ret)
> > > +		dev_err(&bd->dev, "ACPI WMAA failed to get backlight level.\n");
> > Would it make sense to log the actual error?
> 
> 
> I think the underlying ACPI error is already logged by wmi_call_wmaa().

Good point, disregard that comment then.

> > Also while the backlight core does not seem to actually handle it, other
> > drivers return a negative errno on failure.
> 
> 
> Thanks, I was aware that the backlight core doesn't seem to handle errors at
> all for .get_brightness, but I didn't think to check for precedent on
> backlight drivers returning error codes anyway. Returning negative errno
> does seem somewhat common amongst backlight drivers, so I'll go ahead and do
> that in case the backlight core is updated to handle them in the future.

FYI I plan on sending a patch that adds the missing errorhandling next week.

> > > +	props.type = BACKLIGHT_PLATFORM;
> > Is this WMI method a standard interface?
> > If so, BACKLIGHT_FIRMWARE might actually fit better and still fulfill the
> > requirements.
> > The actual maintainers would know better than me, though.
> 
> 
> I'm not certain what you mean by standard. It's defined as part of system
> design guidelines that NVIDIA shares with OEMs, but I'm not sure if it's
> part of the ACPI spec. It is implemented by multiple notebook system
> vendors, hence naming the driver after the ACPI method rather than a
> particular vendor. Reading the documentation on the backlight driver types,
> it does seem that this may fall more under the purview of BACKLIGHT_FIRMWARE
> than BACKLIGHT_PLATFORM. I'll go ahead and retest with the driver registered
> as BACKLIGHT_FIRMWARE, but I'm sure it'll still work after inspecting the
> code for at least gnome-settings-daemon, which implements the policy
> recommended by Documentation/ABI/stable/sysfs-class-backlight.

I only went by the comment about "standard firmware interface" from
backlight.h.
This was mostly a pointer for you (and the pdx86 maintainers) to take a look
and decide.

Thomas

Re: [PATCH v4] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

On 9/2/21 5:19 AM, Thomas Weißschuh wrote:
> It seems that the encoding of the mail has been set as plain ASCII while it is
> actually UTF-8.
> Thunderbird is probly correctly inferring the actual encoding.
> Normally git-format-patch would detect the Unicode characters and add a
> matching content-type header to the patch.
> But as these Unicode characters are added after format-patch has run it is now
> git-send-emails task to add those headers again.
>
> In my version of git I get the following message from git-send-email:
>
>    The following files are 8bit, but do not declare a Content-Transfer-Encoding.
>        0001-....patch
>    Which 8bit encoding should I declare [UTF-8]?
>
> As this feature seems to be really old already it should be available.
> Is your "git email-patch" using "git send-email"?
> Do you have "sendemail.assume8bitEncoding" set in your git config?
> (It should either not be set or to UTF-8.


Ah. That's likely the problem. The actual patch and associated commit 
message don't contain any characters that require more than 7 bits to 
encode, but the eventually sent e-mail does, since I added the 
information about the review revisions. Presumably git send-email is 
evaluating the encoding before the edit stage, but not after. 
sendemail.assume8bitEncoding is unset in my git config; I'll explicitly 
set it to UTF-8.


>>>> +	props.type = BACKLIGHT_PLATFORM;
>>> Is this WMI method a standard interface?
>>> If so, BACKLIGHT_FIRMWARE might actually fit better and still fulfill the
>>> requirements.
>>> The actual maintainers would know better than me, though.
>> I'm not certain what you mean by standard. It's defined as part of system
>> design guidelines that NVIDIA shares with OEMs, but I'm not sure if it's
>> part of the ACPI spec. It is implemented by multiple notebook system
>> vendors, hence naming the driver after the ACPI method rather than a
>> particular vendor. Reading the documentation on the backlight driver types,
>> it does seem that this may fall more under the purview of BACKLIGHT_FIRMWARE
>> than BACKLIGHT_PLATFORM. I'll go ahead and retest with the driver registered
>> as BACKLIGHT_FIRMWARE, but I'm sure it'll still work after inspecting the
>> code for at least gnome-settings-daemon, which implements the policy
>> recommended by Documentation/ABI/stable/sysfs-class-backlight.
> I only went by the comment about "standard firmware interface" from
> backlight.h.
> This was mostly a pointer for you (and the pdx86 maintainers) to take a look
> and decide.


Got it. From my interpretation of linux/backlight.h and 
Documentation/ABI/stable/sysfs-class-backlight, I *think* 
BACKLIGHT_FIRMWARE is probably more appropriate, so I'll change it to 
that, unless a maintainer disagrees. Hans/Andy?

Re: [PATCH v4] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Hans de Goede]

Hi,

On 9/2/21 10:15 PM, Daniel Dadap wrote:
> 
> On 9/2/21 5:19 AM, Thomas Weißschuh wrote:
>> It seems that the encoding of the mail has been set as plain ASCII while it is
>> actually UTF-8.
>> Thunderbird is probly correctly inferring the actual encoding.
>> Normally git-format-patch would detect the Unicode characters and add a
>> matching content-type header to the patch.
>> But as these Unicode characters are added after format-patch has run it is now
>> git-send-emails task to add those headers again.
>>
>> In my version of git I get the following message from git-send-email:
>>
>>    The following files are 8bit, but do not declare a Content-Transfer-Encoding.
>>        0001-....patch
>>    Which 8bit encoding should I declare [UTF-8]?
>>
>> As this feature seems to be really old already it should be available.
>> Is your "git email-patch" using "git send-email"?
>> Do you have "sendemail.assume8bitEncoding" set in your git config?
>> (It should either not be set or to UTF-8.
> 
> 
> Ah. That's likely the problem. The actual patch and associated commit message don't contain any characters that require more than 7 bits to encode, but the eventually sent e-mail does, since I added the information about the review revisions. Presumably git send-email is evaluating the encoding before the edit stage, but not after. sendemail.assume8bitEncoding is unset in my git config; I'll explicitly set it to UTF-8.
> 
> 
>>>>> +    props.type = BACKLIGHT_PLATFORM;
>>>> Is this WMI method a standard interface?
>>>> If so, BACKLIGHT_FIRMWARE might actually fit better and still fulfill the
>>>> requirements.
>>>> The actual maintainers would know better than me, though.
>>> I'm not certain what you mean by standard. It's defined as part of system
>>> design guidelines that NVIDIA shares with OEMs, but I'm not sure if it's
>>> part of the ACPI spec. It is implemented by multiple notebook system
>>> vendors, hence naming the driver after the ACPI method rather than a
>>> particular vendor. Reading the documentation on the backlight driver types,
>>> it does seem that this may fall more under the purview of BACKLIGHT_FIRMWARE
>>> than BACKLIGHT_PLATFORM. I'll go ahead and retest with the driver registered
>>> as BACKLIGHT_FIRMWARE, but I'm sure it'll still work after inspecting the
>>> code for at least gnome-settings-daemon, which implements the policy
>>> recommended by Documentation/ABI/stable/sysfs-class-backlight.
>> I only went by the comment about "standard firmware interface" from
>> backlight.h.
>> This was mostly a pointer for you (and the pdx86 maintainers) to take a look
>> and decide.
> 
> 
> Got it. From my interpretation of linux/backlight.h and Documentation/ABI/stable/sysfs-class-backlight, I *think* BACKLIGHT_FIRMWARE is probably more appropriate, so I'll change it to that, unless a maintainer disagrees. Hans/Andy?

I agree that BACKLIGHT_FIRMWARE is more appropriate, that is the same
as what drivers/acpi/acpi_video.c uses and this is in essence operating
at the same level.

Regards,

Hans

[PATCH v5] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

A number of upcoming notebook computer designs drive the internal
display panel's backlight PWM through the Embedded Controller (EC).
This EC-based backlight control can be plumbed through to an ACPI
"WMAA" method interface, which in turn can be wrapped by WMI with
the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.

Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
backlight class driver to control backlight levels on systems with
EC-driven backlights.

Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
Reviewed-By: Thomas Weißschuh <linux@weissschuh.net>
---

v2: Convert to WMI subsystem driver, suggested by Mario Limonciello
    <mario.limonciello@outlook.com>; various cleanups suggested by
    Barnabás Pőcze <pobrn@protonmail.com>
v3: Address assorted style nits raised by Andy Shevchenko
    <andy.shevchenko@gmail.com> in response to a related patch; remove
    additional behavior change to WMI subsystem from patch series as
    recommended by Hans de Goede <hdegoede@redhat.com> 
v4: Use MODULE_DEVICE_TABLE() (Thomas Weißschuh <thomas@t-8ch.de>)
    Fix scope of internal driver state; various style fixes (Barnabás
    Pőcze, Andy Shevchenko)
    Use devm_backlight_device_register() (Barnabás Pőcze)
    Add kerneldoc comments for enums and structs (Andy Shevchenko)
v5: Remove Aaron Plattner as author, as suggested by Aaron Plattner
    <aplattner@nvidia.com>
    Register as BACKLIGHT_FIRMWARE rather than BACKLIGHT_PLATFORM;
    Return negative errno if .get_brightness() fails (Thomas Weißschuh)
    Assorted style improvements (Andy Shevchenko, Thomas Weißschuh)
 MAINTAINERS                               |   6 +
 drivers/platform/x86/Kconfig              |  16 ++
 drivers/platform/x86/Makefile             |   1 +
 drivers/platform/x86/wmaa-backlight-wmi.c | 194 ++++++++++++++++++++++
 4 files changed, 217 insertions(+)
 create mode 100644 drivers/platform/x86/wmaa-backlight-wmi.c

diff --git a/MAINTAINERS b/MAINTAINERS
index bbaecde94aa0..fd7362a86c6d 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -20008,6 +20008,12 @@ L:	linux-wireless@vger.kernel.org
 S:	Odd fixes
 F:	drivers/net/wireless/wl3501*
 
+WMAA BACKLIGHT DRIVER
+M:	Daniel Dadap <ddadap@nvidia.com>
+L:	platform-driver-x86@vger.kernel.org
+S:	Supported
+F:	drivers/platform/x86/wmaa-backlight-wmi.c
+
 WOLFSON MICROELECTRONICS DRIVERS
 L:	patches@opensource.cirrus.com
 S:	Supported
diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
index d12db6c316ea..0df908ef8d7c 100644
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -113,6 +113,22 @@ config PEAQ_WMI
 	help
 	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
 
+config WMAA_BACKLIGHT_WMI
+	tristate "ACPI WMAA Backlight Driver"
+	depends on ACPI_WMI
+	depends on BACKLIGHT_CLASS_DEVICE
+	help
+	  This driver provides a sysfs backlight interface for notebook
+	  systems which expose the WMAA ACPI method and an associated WMI
+	  wrapper to drive LCD backlight levels through the system's
+	  Embedded Controller (EC).
+
+	  Say Y or M here if you want to control the backlight on a notebook
+	  system with an EC-driven backlight using the ACPI WMAA method.
+
+	  If you choose to compile this driver as a module the module will be
+	  called wmaa-backlight-wmi.
+
 config XIAOMI_WMI
 	tristate "Xiaomi WMI key driver"
 	depends on ACPI_WMI
diff --git a/drivers/platform/x86/Makefile b/drivers/platform/x86/Makefile
index 7ee369aab10d..109c1714237d 100644
--- a/drivers/platform/x86/Makefile
+++ b/drivers/platform/x86/Makefile
@@ -14,6 +14,7 @@ obj-$(CONFIG_INTEL_WMI_SBL_FW_UPDATE)	+= intel-wmi-sbl-fw-update.o
 obj-$(CONFIG_INTEL_WMI_THUNDERBOLT)	+= intel-wmi-thunderbolt.o
 obj-$(CONFIG_MXM_WMI)			+= mxm-wmi.o
 obj-$(CONFIG_PEAQ_WMI)			+= peaq-wmi.o
+obj-$(CONFIG_WMAA_BACKLIGHT_WMI)	+= wmaa-backlight-wmi.o
 obj-$(CONFIG_XIAOMI_WMI)		+= xiaomi-wmi.o
 obj-$(CONFIG_GIGABYTE_WMI)		+= gigabyte-wmi.o
 
diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
new file mode 100644
index 000000000000..fa3f41302299
--- /dev/null
+++ b/drivers/platform/x86/wmaa-backlight-wmi.c
@@ -0,0 +1,194 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * Copyright (c) 2020, NVIDIA CORPORATION.  All rights reserved.
+ */
+
+#include <linux/acpi.h>
+#include <linux/backlight.h>
+#include <linux/mod_devicetable.h>
+#include <linux/module.h>
+#include <linux/types.h>
+#include <linux/wmi.h>
+
+/**
+ * enum wmaa_method - WMI method IDs for ACPI WMAA
+ * @WMAA_METHOD_LEVEL:  Get or set the brightness level,
+ *                      or get the maximum brightness level.
+ * @WMAA_METHOD_SOURCE: Get the source for backlight control.
+ */
+enum wmaa_method {
+	WMAA_METHOD_LEVEL = 1,
+	WMAA_METHOD_SOURCE = 2,
+	WMAA_METHOD_MAX
+};
+
+/**
+ * enum wmaa_mode - Operation mode for ACPI WMAA method
+ * @WMAA_MODE_GET:           Get the current brightness level or source.
+ * @WMAA_MODE_SET:           Set the brightness level.
+ * @WMAA_MODE_GET_MAX_LEVEL: Get the maximum brightness level. This is only
+ *                           valid when the WMI method is %WMAA_METHOD_LEVEL.
+ */
+enum wmaa_mode {
+	WMAA_MODE_GET = 0,
+	WMAA_MODE_SET = 1,
+	WMAA_MODE_GET_MAX_LEVEL = 2,
+	WMAA_MODE_MAX
+};
+
+/**
+ * enum wmaa_source - Backlight brightness control source identification
+ * @WMAA_SOURCE_GPU:   Backlight brightness is controlled by the GPU.
+ * @WMAA_SOURCE_EC:    Backlight brightness is controlled by the system's
+ *                     Embedded Controller (EC).
+ * @WMAA_SOURCE_AUX:   Backlight brightness is controlled over the DisplayPort
+ *                     AUX channel.
+ */
+enum wmaa_source {
+	WMAA_SOURCE_GPU = 1,
+	WMAA_SOURCE_EC = 2,
+	WMAA_SOURCE_AUX = 3,
+	WMAA_SOURCE_MAX
+};
+
+/**
+ * struct wmaa_args - arguments for the ACPI WMAA method
+ * @mode:    Pass in an &enum wmaa_mode value to select between getting or
+ *           setting a value.
+ * @val:     In parameter for value to set when operating in %WMAA_MODE_SET
+ *           mode. Not used in %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode.
+ * @ret:     Out parameter returning retrieved value when operating in
+ *           %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode. Not used in
+ *           %WMAA_MODE_SET mode.
+ * @ignored: Padding; not used. The ACPI method expects a 24 byte params struct.
+ *
+ * This is the parameters structure for the ACPI WMAA method as wrapped by WMI.
+ * The value passed in to @val or returned by @ret will be a brightness value
+ * when the WMI method ID is %WMAA_METHOD_LEVEL, or an &enum wmaa_source value
+ * when the WMI method ID is %WMAA_METHOD_SOURCE.
+ */
+struct wmaa_args {
+	u32 mode;
+	u32 val;
+	u32 ret;
+	u32 ignored[3];
+};
+
+static int wmi_call_wmaa(struct wmi_device *w, enum wmaa_method id, enum wmaa_mode mode, u32 *val)
+{
+	struct wmaa_args args = {
+		.mode = mode,
+		.val = 0,
+		.ret = 0,
+	};
+	struct acpi_buffer buf = { (acpi_size)sizeof(args), &args };
+	acpi_status status;
+
+	if (id < WMAA_METHOD_LEVEL || id >= WMAA_METHOD_MAX ||
+	    mode < WMAA_MODE_GET || mode >= WMAA_MODE_MAX)
+		return -EINVAL;
+
+	if (mode == WMAA_MODE_SET)
+		args.val = *val;
+
+	status = wmidev_evaluate_method(w, 0, id, &buf, &buf);
+	if (ACPI_FAILURE(status)) {
+		dev_err(&w->dev, "ACPI WMAA failed: %s\n",
+			acpi_format_exception(status));
+		return -EIO;
+	}
+
+	if (mode != WMAA_MODE_SET)
+		*val = args.ret;
+
+	return 0;
+}
+
+static int wmaa_backlight_update_status(struct backlight_device *bd)
+{
+	struct wmi_device *wdev = bl_get_data(bd);
+
+	return wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_SET,
+			     &bd->props.brightness);
+}
+
+static int wmaa_backlight_get_brightness(struct backlight_device *bd)
+{
+	struct wmi_device *wdev = bl_get_data(bd);
+	u32 level;
+	int ret;
+
+	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET, &level);
+	if (ret > 0)
+		return -EINVAL;
+	else if (ret < 0)
+		return ret;
+
+	return level;
+}
+
+static const struct backlight_ops wmaa_backlight_ops = {
+	.update_status = wmaa_backlight_update_status,
+	.get_brightness = wmaa_backlight_get_brightness,
+};
+
+static int wmaa_backlight_wmi_probe(struct wmi_device *wdev, const void *ctx)
+{
+	struct backlight_properties props = {};
+	struct backlight_device *bdev;
+	u32 source;
+	int ret;
+
+	ret = wmi_call_wmaa(wdev, WMAA_METHOD_SOURCE, WMAA_MODE_GET, &source);
+	if (ret)
+		return ret;
+
+	/*
+	 * This driver is only to be used when brightness control is handled
+	 * by the EC; otherwise, the GPU driver(s) should control brightness.
+	 */
+	if (source != WMAA_SOURCE_EC)
+		return -ENODEV;
+
+	/*
+	 * Identify this backlight device as a firmware device so that it can
+	 * be prioritized over any exposed GPU-driven raw device(s).
+	 */
+	props.type = BACKLIGHT_FIRMWARE;
+
+	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET_MAX_LEVEL,
+			    &props.max_brightness);
+	if (ret)
+		return ret;
+
+	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET,
+			    &props.brightness);
+	if (ret)
+		return ret;
+
+	bdev = devm_backlight_device_register(&wdev->dev, "wmaa_backlight",
+					      &wdev->dev, wdev,
+					      &wmaa_backlight_ops, &props);
+	return PTR_ERR_OR_ZERO(bdev);
+}
+
+#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
+
+static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
+	{ .guid_string = WMAA_WMI_GUID },
+	{ }
+};
+MODULE_DEVICE_TABLE(wmi, wmaa_backlight_wmi_id_table);
+
+static struct wmi_driver wmaa_backlight_wmi_driver = {
+	.driver = {
+		.name = "wmaa-backlight",
+	},
+	.probe = wmaa_backlight_wmi_probe,
+	.id_table = wmaa_backlight_wmi_id_table,
+};
+module_wmi_driver(wmaa_backlight_wmi_driver);
+
+MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
+MODULE_DESCRIPTION("WMAA Backlight WMI driver");
+MODULE_LICENSE("GPL");
-- 
2.20.1

Re: [PATCH v5] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Thomas Weißschuh]

Hi Daniel,

one more actual thing and two tiny nitpicks.

On 2021-09-02T16:47-0500, Daniel Dadap wrote:
> diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
> index d12db6c316ea..0df908ef8d7c 100644
> --- a/drivers/platform/x86/Kconfig
> +++ b/drivers/platform/x86/Kconfig
> @@ -113,6 +113,22 @@ config PEAQ_WMI
>  	help
>  	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
>  
> +config WMAA_BACKLIGHT_WMI
> +	tristate "ACPI WMAA Backlight Driver"
> +	depends on ACPI_WMI
> +	depends on BACKLIGHT_CLASS_DEVICE
> +	help
> +	  This driver provides a sysfs backlight interface for notebook
> +	  systems which expose the WMAA ACPI method and an associated WMI
> +	  wrapper to drive LCD backlight levels through the system's
> +	  Embedded Controller (EC).

system's -> systems

> +
> +	  Say Y or M here if you want to control the backlight on a notebook
> +	  system with an EC-driven backlight using the ACPI WMAA method.
> +
> +	  If you choose to compile this driver as a module the module will be
> +	  called wmaa-backlight-wmi.
> +
>  config XIAOMI_WMI
>  	tristate "Xiaomi WMI key driver"
>  	depends on ACPI_WMI
> diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
> new file mode 100644
> index 000000000000..fa3f41302299
> --- /dev/null
> +++ b/drivers/platform/x86/wmaa-backlight-wmi.c
> @@ -0,0 +1,194 @@
> [..]
> +static int wmaa_backlight_update_status(struct backlight_device *bd)
> +{
> +	struct wmi_device *wdev = bl_get_data(bd);
> +
> +	return wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_SET,
> +			     &bd->props.brightness);
> +}
> +
> +static int wmaa_backlight_get_brightness(struct backlight_device *bd)
> +{
> +	struct wmi_device *wdev = bl_get_data(bd);
> +	u32 level;
> +	int ret;
> +
> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET, &level);
> +	if (ret > 0)
> +		return -EINVAL;
> +	else if (ret < 0)
> +		return ret;

Nowhere else is the return value of wmi_call_wmaa() checked explicitly for
greater than zero and less than zero. Why here?
At least wmaa_backlight_update_status() should have identical semantics.
The case ret > 0 should never happen.

> +
> +	return level;
> +}
> [..]
> +
> +
> +#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
> +
> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
> +	{ .guid_string = WMAA_WMI_GUID },

This could also be inlined as:
	{ "603E9613-EF25-4338-A3D0-C46177516DB7" },

More a stylistic thing though.

Thomas

Re: [PATCH v5] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

On 9/2/21 6:20 PM, Thomas Weißschuh wrote:
> Hi Daniel,
>
> one more actual thing and two tiny nitpicks.
>
> On 2021-09-02T16:47-0500, Daniel Dadap wrote:
>> diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
>> index d12db6c316ea..0df908ef8d7c 100644
>> --- a/drivers/platform/x86/Kconfig
>> +++ b/drivers/platform/x86/Kconfig
>> @@ -113,6 +113,22 @@ config PEAQ_WMI
>>   	help
>>   	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
>>   
>> +config WMAA_BACKLIGHT_WMI
>> +	tristate "ACPI WMAA Backlight Driver"
>> +	depends on ACPI_WMI
>> +	depends on BACKLIGHT_CLASS_DEVICE
>> +	help
>> +	  This driver provides a sysfs backlight interface for notebook
>> +	  systems which expose the WMAA ACPI method and an associated WMI
>> +	  wrapper to drive LCD backlight levels through the system's
>> +	  Embedded Controller (EC).
> system's -> systems


"system's" is what I intended, and I believe it's correct. The meaning 
I'm going for here is "the Embedded Controller (EC) belonging to the 
system". I guess maybe there could be some confusion because earlier in 
the same sentence I refer to "systems" plural, referring to the class of 
systems that expose this backlight control scheme, and later in the 
sentence "system's" refers to something belonging to a singular member 
of this class. It would probably be more clear if I just drop the word 
"system's" here.


>
>> +
>> +	  Say Y or M here if you want to control the backlight on a notebook
>> +	  system with an EC-driven backlight using the ACPI WMAA method.
>> +
>> +	  If you choose to compile this driver as a module the module will be
>> +	  called wmaa-backlight-wmi.
>> +
>>   config XIAOMI_WMI
>>   	tristate "Xiaomi WMI key driver"
>>   	depends on ACPI_WMI
>> diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
>> new file mode 100644
>> index 000000000000..fa3f41302299
>> --- /dev/null
>> +++ b/drivers/platform/x86/wmaa-backlight-wmi.c
>> @@ -0,0 +1,194 @@
>> [..]
>> +static int wmaa_backlight_update_status(struct backlight_device *bd)
>> +{
>> +	struct wmi_device *wdev = bl_get_data(bd);
>> +
>> +	return wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_SET,
>> +			     &bd->props.brightness);
>> +}
>> +
>> +static int wmaa_backlight_get_brightness(struct backlight_device *bd)
>> +{
>> +	struct wmi_device *wdev = bl_get_data(bd);
>> +	u32 level;
>> +	int ret;
>> +
>> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET, &level);
>> +	if (ret > 0)
>> +		return -EINVAL;
>> +	else if (ret < 0)
>> +		return ret;
> Nowhere else is the return value of wmi_call_wmaa() checked explicitly for
> greater than zero and less than zero. Why here?
> At least wmaa_backlight_update_status() should have identical semantics.
> The case ret > 0 should never happen.


wmaa_backlight_update_status() has different semantics precisely because 
the .get_brightness() and .update_status() callbacks registered in the 
struct backlight_ops have different semantics. The return value of 
.get_brightness() serves dual duty, where a positive return value could 
be interpreted as a valid brightness level value, while in the case of 
.update_status() a positive return value is invalid.

I agree that wmi_call_wmaa() should never return > 0, but I wanted to 
protect against someone deciding in the future (for whatever reason) to 
add a code path that returns a positive value, without checking all of 
the callers of wmi_call_wmaa() to realize that this could cause a 
problem. There are not many callers of the function, though, and they're 
all in the same file, so perhaps this is not something worth worrying 
about. I suppose I could check for just the < 0 case, and add document 
the API of wmi_call_wmaa(), explicitly stating that the return value 
should be zero or negative errno.


>
>> +
>> +	return level;
>> +}
>> [..]
>> +
>> +
>> +#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
>> +
>> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
>> +	{ .guid_string = WMAA_WMI_GUID },
> This could also be inlined as:
> 	{ "603E9613-EF25-4338-A3D0-C46177516DB7" },
>
> More a stylistic thing though.


I considered that when switching to MODULE_DEVICE_TABLE, since the value 
is now only used in one place, but looking at other similar drivers, it 
does seem that the most common convention is to define the GUID as a 
macro even if it's only used once. I'll leave this as-is, I think.

Re: [PATCH v5] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Andy Shevchenko]

On Fri, Sep 3, 2021 at 3:22 AM Daniel Dadap <ddadap@nvidia.com> wrote:
> On 9/2/21 6:20 PM, Thomas Weißschuh wrote:

...

> >> +#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
> >> +
> >> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
> >> +    { .guid_string = WMAA_WMI_GUID },
> > This could also be inlined as:
> >       { "603E9613-EF25-4338-A3D0-C46177516DB7" },
> >
> > More a stylistic thing though.
>
> I considered that when switching to MODULE_DEVICE_TABLE, since the value
> is now only used in one place, but looking at other similar drivers, it
> does seem that the most common convention is to define the GUID as a
> macro even if it's only used once. I'll leave this as-is, I think.

I'm on Daniel's side here. But the problem I have noticed with the
proposal is different, i.e. it loses the C99 style of member
definitions.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v5] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

On 9/3/21 3:14 AM, Andy Shevchenko wrote:
> On Fri, Sep 3, 2021 at 3:22 AM Daniel Dadap <ddadap@nvidia.com> wrote:
>> On 9/2/21 6:20 PM, Thomas Weißschuh wrote:
> ...
>
>>>> +#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
>>>> +
>>>> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
>>>> +    { .guid_string = WMAA_WMI_GUID },
>>> This could also be inlined as:
>>>        { "603E9613-EF25-4338-A3D0-C46177516DB7" },
>>>
>>> More a stylistic thing though.
>> I considered that when switching to MODULE_DEVICE_TABLE, since the value
>> is now only used in one place, but looking at other similar drivers, it
>> does seem that the most common convention is to define the GUID as a
>> macro even if it's only used once. I'll leave this as-is, I think.
> I'm on Daniel's side here. But the problem I have noticed with the
> proposal is different, i.e. it loses the C99 style of member
> definitions.


Oh. I didn't even notice that the proposal excluded the designated 
initializer. What I had been considering was inlining the GUID string 
and getting rid of the preprocessor macro, while retaining the 
designated initializer. In any case, the prevailing style does seem to 
be to avoid inlining the constant, AFAICT.

[PATCH v6] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

A number of upcoming notebook computer designs drive the internal
display panel's backlight PWM through the Embedded Controller (EC).
This EC-based backlight control can be plumbed through to an ACPI
"WMAA" method interface, which in turn can be wrapped by WMI with
the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.

Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
backlight class driver to control backlight levels on systems with
EC-driven backlights.

Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
Reviewed-By: Thomas Weißschuh <linux@weissschuh.net>
---

v2: Convert to WMI subsystem driver, suggested by Mario Limonciello
    <mario.limonciello@outlook.com>; various cleanups suggested by
    Barnabás Pőcze <pobrn@protonmail.com>
v3: Address assorted style nits raised by Andy Shevchenko
    <andy.shevchenko@gmail.com> in response to a related patch; remove
    additional behavior change to WMI subsystem from patch series as
    recommended by Hans de Goede <hdegoede@redhat.com> 
v4: Use MODULE_DEVICE_TABLE() (Thomas Weißschuh <thomas@t-8ch.de>)
    Fix scope of internal driver state; various style fixes (Barnabás
    Pőcze, Andy Shevchenko)
    Use devm_backlight_device_register() (Barnabás Pőcze)
    Add kerneldoc comments for enums and structs (Andy Shevchenko)
v5: Remove Aaron Plattner as author, as suggested by Aaron Plattner
    <aplattner@nvidia.com>
    Register as BACKLIGHT_FIRMWARE rather than BACKLIGHT_PLATFORM;
    Return negative errno if .get_brightness() fails (Thomas Weißschuh)
    Assorted style improvements (Andy Shevchenko, Thomas Weißschuh)
v6: Make behavior of callers of wmi_call_wmaa() more consistent;
    simplify potentially confusing description in Kconfig help text
    (Thomas Weißschuh)

 MAINTAINERS                               |   6 +
 drivers/platform/x86/Kconfig              |  16 ++
 drivers/platform/x86/Makefile             |   1 +
 drivers/platform/x86/wmaa-backlight-wmi.c | 205 ++++++++++++++++++++++
 4 files changed, 228 insertions(+)
 create mode 100644 drivers/platform/x86/wmaa-backlight-wmi.c

diff --git a/MAINTAINERS b/MAINTAINERS
index bbaecde94aa0..fd7362a86c6d 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -20008,6 +20008,12 @@ L:	linux-wireless@vger.kernel.org
 S:	Odd fixes
 F:	drivers/net/wireless/wl3501*
 
+WMAA BACKLIGHT DRIVER
+M:	Daniel Dadap <ddadap@nvidia.com>
+L:	platform-driver-x86@vger.kernel.org
+S:	Supported
+F:	drivers/platform/x86/wmaa-backlight-wmi.c
+
 WOLFSON MICROELECTRONICS DRIVERS
 L:	patches@opensource.cirrus.com
 S:	Supported
diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
index d12db6c316ea..00f021eda25c 100644
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -113,6 +113,22 @@ config PEAQ_WMI
 	help
 	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
 
+config WMAA_BACKLIGHT_WMI
+	tristate "ACPI WMAA Backlight Driver"
+	depends on ACPI_WMI
+	depends on BACKLIGHT_CLASS_DEVICE
+	help
+	  This driver provides a sysfs backlight interface for notebook
+	  systems which expose the WMAA ACPI method and an associated WMI
+	  wrapper to drive LCD backlight levels through the Embedded Controller
+	  (EC).
+
+	  Say Y or M here if you want to control the backlight on a notebook
+	  system with an EC-driven backlight using the ACPI WMAA method.
+
+	  If you choose to compile this driver as a module the module will be
+	  called wmaa-backlight-wmi.
+
 config XIAOMI_WMI
 	tristate "Xiaomi WMI key driver"
 	depends on ACPI_WMI
diff --git a/drivers/platform/x86/Makefile b/drivers/platform/x86/Makefile
index 7ee369aab10d..109c1714237d 100644
--- a/drivers/platform/x86/Makefile
+++ b/drivers/platform/x86/Makefile
@@ -14,6 +14,7 @@ obj-$(CONFIG_INTEL_WMI_SBL_FW_UPDATE)	+= intel-wmi-sbl-fw-update.o
 obj-$(CONFIG_INTEL_WMI_THUNDERBOLT)	+= intel-wmi-thunderbolt.o
 obj-$(CONFIG_MXM_WMI)			+= mxm-wmi.o
 obj-$(CONFIG_PEAQ_WMI)			+= peaq-wmi.o
+obj-$(CONFIG_WMAA_BACKLIGHT_WMI)	+= wmaa-backlight-wmi.o
 obj-$(CONFIG_XIAOMI_WMI)		+= xiaomi-wmi.o
 obj-$(CONFIG_GIGABYTE_WMI)		+= gigabyte-wmi.o
 
diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
new file mode 100644
index 000000000000..f5c4f8337c2c
--- /dev/null
+++ b/drivers/platform/x86/wmaa-backlight-wmi.c
@@ -0,0 +1,205 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * Copyright (c) 2020, NVIDIA CORPORATION.  All rights reserved.
+ */
+
+#include <linux/acpi.h>
+#include <linux/backlight.h>
+#include <linux/mod_devicetable.h>
+#include <linux/module.h>
+#include <linux/types.h>
+#include <linux/wmi.h>
+
+/**
+ * enum wmaa_method - WMI method IDs for ACPI WMAA
+ * @WMAA_METHOD_LEVEL:  Get or set the brightness level,
+ *                      or get the maximum brightness level.
+ * @WMAA_METHOD_SOURCE: Get the source for backlight control.
+ */
+enum wmaa_method {
+	WMAA_METHOD_LEVEL = 1,
+	WMAA_METHOD_SOURCE = 2,
+	WMAA_METHOD_MAX
+};
+
+/**
+ * enum wmaa_mode - Operation mode for ACPI WMAA method
+ * @WMAA_MODE_GET:           Get the current brightness level or source.
+ * @WMAA_MODE_SET:           Set the brightness level.
+ * @WMAA_MODE_GET_MAX_LEVEL: Get the maximum brightness level. This is only
+ *                           valid when the WMI method is %WMAA_METHOD_LEVEL.
+ */
+enum wmaa_mode {
+	WMAA_MODE_GET = 0,
+	WMAA_MODE_SET = 1,
+	WMAA_MODE_GET_MAX_LEVEL = 2,
+	WMAA_MODE_MAX
+};
+
+/**
+ * enum wmaa_source - Backlight brightness control source identification
+ * @WMAA_SOURCE_GPU:   Backlight brightness is controlled by the GPU.
+ * @WMAA_SOURCE_EC:    Backlight brightness is controlled by the system's
+ *                     Embedded Controller (EC).
+ * @WMAA_SOURCE_AUX:   Backlight brightness is controlled over the DisplayPort
+ *                     AUX channel.
+ */
+enum wmaa_source {
+	WMAA_SOURCE_GPU = 1,
+	WMAA_SOURCE_EC = 2,
+	WMAA_SOURCE_AUX = 3,
+	WMAA_SOURCE_MAX
+};
+
+/**
+ * struct wmaa_args - arguments for the ACPI WMAA method
+ * @mode:    Pass in an &enum wmaa_mode value to select between getting or
+ *           setting a value.
+ * @val:     In parameter for value to set when operating in %WMAA_MODE_SET
+ *           mode. Not used in %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode.
+ * @ret:     Out parameter returning retrieved value when operating in
+ *           %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode. Not used in
+ *           %WMAA_MODE_SET mode.
+ * @ignored: Padding; not used. The ACPI method expects a 24 byte params struct.
+ *
+ * This is the parameters structure for the ACPI WMAA method as wrapped by WMI.
+ * The value passed in to @val or returned by @ret will be a brightness value
+ * when the WMI method ID is %WMAA_METHOD_LEVEL, or an &enum wmaa_source value
+ * when the WMI method ID is %WMAA_METHOD_SOURCE.
+ */
+struct wmaa_args {
+	u32 mode;
+	u32 val;
+	u32 ret;
+	u32 ignored[3];
+};
+
+/**
+ * wmi_call_wmaa() - helper function for calling ACPI WMAA via its WMI wrapper
+ * @w:    Pointer to the struct wmi_device identified by %WMAA_WMI_GUID
+ * @id:   The method ID for the ACPI WMAA method (e.g. %WMAA_METHOD_LEVEL or
+ *        %WMAA_METHOD_SOURCE)
+ * @mode: The operation to perform on the ACPI WMAA method (e.g. %WMAA_MODE_SET
+ *        or %WMAA_MODE_GET)
+ * @val:  Pointer to a value passed in by the caller when @mode is
+ *        %WMAA_MODE_SET, or a value passed out to the caller when @mode is
+ *        %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL.
+ *
+ * Returns 0 on success, or a negative error number on failure.
+ */
+static int wmi_call_wmaa(struct wmi_device *w, enum wmaa_method id, enum wmaa_mode mode, u32 *val)
+{
+	struct wmaa_args args = {
+		.mode = mode,
+		.val = 0,
+		.ret = 0,
+	};
+	struct acpi_buffer buf = { (acpi_size)sizeof(args), &args };
+	acpi_status status;
+
+	if (id < WMAA_METHOD_LEVEL || id >= WMAA_METHOD_MAX ||
+	    mode < WMAA_MODE_GET || mode >= WMAA_MODE_MAX)
+		return -EINVAL;
+
+	if (mode == WMAA_MODE_SET)
+		args.val = *val;
+
+	status = wmidev_evaluate_method(w, 0, id, &buf, &buf);
+	if (ACPI_FAILURE(status)) {
+		dev_err(&w->dev, "ACPI WMAA failed: %s\n",
+			acpi_format_exception(status));
+		return -EIO;
+	}
+
+	if (mode != WMAA_MODE_SET)
+		*val = args.ret;
+
+	return 0;
+}
+
+static int wmaa_backlight_update_status(struct backlight_device *bd)
+{
+	struct wmi_device *wdev = bl_get_data(bd);
+
+	return wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_SET,
+			     &bd->props.brightness);
+}
+
+static int wmaa_backlight_get_brightness(struct backlight_device *bd)
+{
+	struct wmi_device *wdev = bl_get_data(bd);
+	u32 level;
+	int ret;
+
+	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET, &level);
+	if (ret < 0)
+		return ret;
+
+	return level;
+}
+
+static const struct backlight_ops wmaa_backlight_ops = {
+	.update_status = wmaa_backlight_update_status,
+	.get_brightness = wmaa_backlight_get_brightness,
+};
+
+static int wmaa_backlight_wmi_probe(struct wmi_device *wdev, const void *ctx)
+{
+	struct backlight_properties props = {};
+	struct backlight_device *bdev;
+	u32 source;
+	int ret;
+
+	ret = wmi_call_wmaa(wdev, WMAA_METHOD_SOURCE, WMAA_MODE_GET, &source);
+	if (ret)
+		return ret;
+
+	/*
+	 * This driver is only to be used when brightness control is handled
+	 * by the EC; otherwise, the GPU driver(s) should control brightness.
+	 */
+	if (source != WMAA_SOURCE_EC)
+		return -ENODEV;
+
+	/*
+	 * Identify this backlight device as a firmware device so that it can
+	 * be prioritized over any exposed GPU-driven raw device(s).
+	 */
+	props.type = BACKLIGHT_FIRMWARE;
+
+	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET_MAX_LEVEL,
+			    &props.max_brightness);
+	if (ret)
+		return ret;
+
+	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET,
+			    &props.brightness);
+	if (ret)
+		return ret;
+
+	bdev = devm_backlight_device_register(&wdev->dev, "wmaa_backlight",
+					      &wdev->dev, wdev,
+					      &wmaa_backlight_ops, &props);
+	return PTR_ERR_OR_ZERO(bdev);
+}
+
+#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
+
+static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
+	{ .guid_string = WMAA_WMI_GUID },
+	{ }
+};
+MODULE_DEVICE_TABLE(wmi, wmaa_backlight_wmi_id_table);
+
+static struct wmi_driver wmaa_backlight_wmi_driver = {
+	.driver = {
+		.name = "wmaa-backlight",
+	},
+	.probe = wmaa_backlight_wmi_probe,
+	.id_table = wmaa_backlight_wmi_id_table,
+};
+module_wmi_driver(wmaa_backlight_wmi_driver);
+
+MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
+MODULE_DESCRIPTION("WMAA Backlight WMI driver");
+MODULE_LICENSE("GPL");
-- 
2.20.1

Re: [PATCH v6] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Hans de Goede]

Hi,

On 9/3/21 2:38 AM, Daniel Dadap wrote:
> A number of upcoming notebook computer designs drive the internal
> display panel's backlight PWM through the Embedded Controller (EC).
> This EC-based backlight control can be plumbed through to an ACPI
> "WMAA" method interface, which in turn can be wrapped by WMI with
> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
> 
> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
> backlight class driver to control backlight levels on systems with
> EC-driven backlights.
> 
> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
> Reviewed-By: Thomas Weißschuh <linux@weissschuh.net>

Thank you for your patch, I've applied this patch to my review-hans 
branch:
https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=review-hans

Note it will show up in my review-hans branch once I've pushed my
local branch there, which might take a while.

Once I've run some tests on this branch the patches there will be
added to the platform-drivers-x86/for-next branch and eventually
will be included in the pdx86 pull-request to Linus for the next
merge-window.

Regards,

Hans


> ---
> 
> v2: Convert to WMI subsystem driver, suggested by Mario Limonciello
>     <mario.limonciello@outlook.com>; various cleanups suggested by
>     Barnabás Pőcze <pobrn@protonmail.com>
> v3: Address assorted style nits raised by Andy Shevchenko
>     <andy.shevchenko@gmail.com> in response to a related patch; remove
>     additional behavior change to WMI subsystem from patch series as
>     recommended by Hans de Goede <hdegoede@redhat.com> 
> v4: Use MODULE_DEVICE_TABLE() (Thomas Weißschuh <thomas@t-8ch.de>)
>     Fix scope of internal driver state; various style fixes (Barnabás
>     Pőcze, Andy Shevchenko)
>     Use devm_backlight_device_register() (Barnabás Pőcze)
>     Add kerneldoc comments for enums and structs (Andy Shevchenko)
> v5: Remove Aaron Plattner as author, as suggested by Aaron Plattner
>     <aplattner@nvidia.com>
>     Register as BACKLIGHT_FIRMWARE rather than BACKLIGHT_PLATFORM;
>     Return negative errno if .get_brightness() fails (Thomas Weißschuh)
>     Assorted style improvements (Andy Shevchenko, Thomas Weißschuh)
> v6: Make behavior of callers of wmi_call_wmaa() more consistent;
>     simplify potentially confusing description in Kconfig help text
>     (Thomas Weißschuh)
> 
>  MAINTAINERS                               |   6 +
>  drivers/platform/x86/Kconfig              |  16 ++
>  drivers/platform/x86/Makefile             |   1 +
>  drivers/platform/x86/wmaa-backlight-wmi.c | 205 ++++++++++++++++++++++
>  4 files changed, 228 insertions(+)
>  create mode 100644 drivers/platform/x86/wmaa-backlight-wmi.c
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index bbaecde94aa0..fd7362a86c6d 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -20008,6 +20008,12 @@ L:	linux-wireless@vger.kernel.org
>  S:	Odd fixes
>  F:	drivers/net/wireless/wl3501*
>  
> +WMAA BACKLIGHT DRIVER
> +M:	Daniel Dadap <ddadap@nvidia.com>
> +L:	platform-driver-x86@vger.kernel.org
> +S:	Supported
> +F:	drivers/platform/x86/wmaa-backlight-wmi.c
> +
>  WOLFSON MICROELECTRONICS DRIVERS
>  L:	patches@opensource.cirrus.com
>  S:	Supported
> diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
> index d12db6c316ea..00f021eda25c 100644
> --- a/drivers/platform/x86/Kconfig
> +++ b/drivers/platform/x86/Kconfig
> @@ -113,6 +113,22 @@ config PEAQ_WMI
>  	help
>  	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
>  
> +config WMAA_BACKLIGHT_WMI
> +	tristate "ACPI WMAA Backlight Driver"
> +	depends on ACPI_WMI
> +	depends on BACKLIGHT_CLASS_DEVICE
> +	help
> +	  This driver provides a sysfs backlight interface for notebook
> +	  systems which expose the WMAA ACPI method and an associated WMI
> +	  wrapper to drive LCD backlight levels through the Embedded Controller
> +	  (EC).
> +
> +	  Say Y or M here if you want to control the backlight on a notebook
> +	  system with an EC-driven backlight using the ACPI WMAA method.
> +
> +	  If you choose to compile this driver as a module the module will be
> +	  called wmaa-backlight-wmi.
> +
>  config XIAOMI_WMI
>  	tristate "Xiaomi WMI key driver"
>  	depends on ACPI_WMI
> diff --git a/drivers/platform/x86/Makefile b/drivers/platform/x86/Makefile
> index 7ee369aab10d..109c1714237d 100644
> --- a/drivers/platform/x86/Makefile
> +++ b/drivers/platform/x86/Makefile
> @@ -14,6 +14,7 @@ obj-$(CONFIG_INTEL_WMI_SBL_FW_UPDATE)	+= intel-wmi-sbl-fw-update.o
>  obj-$(CONFIG_INTEL_WMI_THUNDERBOLT)	+= intel-wmi-thunderbolt.o
>  obj-$(CONFIG_MXM_WMI)			+= mxm-wmi.o
>  obj-$(CONFIG_PEAQ_WMI)			+= peaq-wmi.o
> +obj-$(CONFIG_WMAA_BACKLIGHT_WMI)	+= wmaa-backlight-wmi.o
>  obj-$(CONFIG_XIAOMI_WMI)		+= xiaomi-wmi.o
>  obj-$(CONFIG_GIGABYTE_WMI)		+= gigabyte-wmi.o
>  
> diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
> new file mode 100644
> index 000000000000..f5c4f8337c2c
> --- /dev/null
> +++ b/drivers/platform/x86/wmaa-backlight-wmi.c
> @@ -0,0 +1,205 @@
> +// SPDX-License-Identifier: GPL-2.0-only
> +/*
> + * Copyright (c) 2020, NVIDIA CORPORATION.  All rights reserved.
> + */
> +
> +#include <linux/acpi.h>
> +#include <linux/backlight.h>
> +#include <linux/mod_devicetable.h>
> +#include <linux/module.h>
> +#include <linux/types.h>
> +#include <linux/wmi.h>
> +
> +/**
> + * enum wmaa_method - WMI method IDs for ACPI WMAA
> + * @WMAA_METHOD_LEVEL:  Get or set the brightness level,
> + *                      or get the maximum brightness level.
> + * @WMAA_METHOD_SOURCE: Get the source for backlight control.
> + */
> +enum wmaa_method {
> +	WMAA_METHOD_LEVEL = 1,
> +	WMAA_METHOD_SOURCE = 2,
> +	WMAA_METHOD_MAX
> +};
> +
> +/**
> + * enum wmaa_mode - Operation mode for ACPI WMAA method
> + * @WMAA_MODE_GET:           Get the current brightness level or source.
> + * @WMAA_MODE_SET:           Set the brightness level.
> + * @WMAA_MODE_GET_MAX_LEVEL: Get the maximum brightness level. This is only
> + *                           valid when the WMI method is %WMAA_METHOD_LEVEL.
> + */
> +enum wmaa_mode {
> +	WMAA_MODE_GET = 0,
> +	WMAA_MODE_SET = 1,
> +	WMAA_MODE_GET_MAX_LEVEL = 2,
> +	WMAA_MODE_MAX
> +};
> +
> +/**
> + * enum wmaa_source - Backlight brightness control source identification
> + * @WMAA_SOURCE_GPU:   Backlight brightness is controlled by the GPU.
> + * @WMAA_SOURCE_EC:    Backlight brightness is controlled by the system's
> + *                     Embedded Controller (EC).
> + * @WMAA_SOURCE_AUX:   Backlight brightness is controlled over the DisplayPort
> + *                     AUX channel.
> + */
> +enum wmaa_source {
> +	WMAA_SOURCE_GPU = 1,
> +	WMAA_SOURCE_EC = 2,
> +	WMAA_SOURCE_AUX = 3,
> +	WMAA_SOURCE_MAX
> +};
> +
> +/**
> + * struct wmaa_args - arguments for the ACPI WMAA method
> + * @mode:    Pass in an &enum wmaa_mode value to select between getting or
> + *           setting a value.
> + * @val:     In parameter for value to set when operating in %WMAA_MODE_SET
> + *           mode. Not used in %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode.
> + * @ret:     Out parameter returning retrieved value when operating in
> + *           %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode. Not used in
> + *           %WMAA_MODE_SET mode.
> + * @ignored: Padding; not used. The ACPI method expects a 24 byte params struct.
> + *
> + * This is the parameters structure for the ACPI WMAA method as wrapped by WMI.
> + * The value passed in to @val or returned by @ret will be a brightness value
> + * when the WMI method ID is %WMAA_METHOD_LEVEL, or an &enum wmaa_source value
> + * when the WMI method ID is %WMAA_METHOD_SOURCE.
> + */
> +struct wmaa_args {
> +	u32 mode;
> +	u32 val;
> +	u32 ret;
> +	u32 ignored[3];
> +};
> +
> +/**
> + * wmi_call_wmaa() - helper function for calling ACPI WMAA via its WMI wrapper
> + * @w:    Pointer to the struct wmi_device identified by %WMAA_WMI_GUID
> + * @id:   The method ID for the ACPI WMAA method (e.g. %WMAA_METHOD_LEVEL or
> + *        %WMAA_METHOD_SOURCE)
> + * @mode: The operation to perform on the ACPI WMAA method (e.g. %WMAA_MODE_SET
> + *        or %WMAA_MODE_GET)
> + * @val:  Pointer to a value passed in by the caller when @mode is
> + *        %WMAA_MODE_SET, or a value passed out to the caller when @mode is
> + *        %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL.
> + *
> + * Returns 0 on success, or a negative error number on failure.
> + */
> +static int wmi_call_wmaa(struct wmi_device *w, enum wmaa_method id, enum wmaa_mode mode, u32 *val)
> +{
> +	struct wmaa_args args = {
> +		.mode = mode,
> +		.val = 0,
> +		.ret = 0,
> +	};
> +	struct acpi_buffer buf = { (acpi_size)sizeof(args), &args };
> +	acpi_status status;
> +
> +	if (id < WMAA_METHOD_LEVEL || id >= WMAA_METHOD_MAX ||
> +	    mode < WMAA_MODE_GET || mode >= WMAA_MODE_MAX)
> +		return -EINVAL;
> +
> +	if (mode == WMAA_MODE_SET)
> +		args.val = *val;
> +
> +	status = wmidev_evaluate_method(w, 0, id, &buf, &buf);
> +	if (ACPI_FAILURE(status)) {
> +		dev_err(&w->dev, "ACPI WMAA failed: %s\n",
> +			acpi_format_exception(status));
> +		return -EIO;
> +	}
> +
> +	if (mode != WMAA_MODE_SET)
> +		*val = args.ret;
> +
> +	return 0;
> +}
> +
> +static int wmaa_backlight_update_status(struct backlight_device *bd)
> +{
> +	struct wmi_device *wdev = bl_get_data(bd);
> +
> +	return wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_SET,
> +			     &bd->props.brightness);
> +}
> +
> +static int wmaa_backlight_get_brightness(struct backlight_device *bd)
> +{
> +	struct wmi_device *wdev = bl_get_data(bd);
> +	u32 level;
> +	int ret;
> +
> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET, &level);
> +	if (ret < 0)
> +		return ret;
> +
> +	return level;
> +}
> +
> +static const struct backlight_ops wmaa_backlight_ops = {
> +	.update_status = wmaa_backlight_update_status,
> +	.get_brightness = wmaa_backlight_get_brightness,
> +};
> +
> +static int wmaa_backlight_wmi_probe(struct wmi_device *wdev, const void *ctx)
> +{
> +	struct backlight_properties props = {};
> +	struct backlight_device *bdev;
> +	u32 source;
> +	int ret;
> +
> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_SOURCE, WMAA_MODE_GET, &source);
> +	if (ret)
> +		return ret;
> +
> +	/*
> +	 * This driver is only to be used when brightness control is handled
> +	 * by the EC; otherwise, the GPU driver(s) should control brightness.
> +	 */
> +	if (source != WMAA_SOURCE_EC)
> +		return -ENODEV;
> +
> +	/*
> +	 * Identify this backlight device as a firmware device so that it can
> +	 * be prioritized over any exposed GPU-driven raw device(s).
> +	 */
> +	props.type = BACKLIGHT_FIRMWARE;
> +
> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET_MAX_LEVEL,
> +			    &props.max_brightness);
> +	if (ret)
> +		return ret;
> +
> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET,
> +			    &props.brightness);
> +	if (ret)
> +		return ret;
> +
> +	bdev = devm_backlight_device_register(&wdev->dev, "wmaa_backlight",
> +					      &wdev->dev, wdev,
> +					      &wmaa_backlight_ops, &props);
> +	return PTR_ERR_OR_ZERO(bdev);
> +}
> +
> +#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
> +
> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
> +	{ .guid_string = WMAA_WMI_GUID },
> +	{ }
> +};
> +MODULE_DEVICE_TABLE(wmi, wmaa_backlight_wmi_id_table);
> +
> +static struct wmi_driver wmaa_backlight_wmi_driver = {
> +	.driver = {
> +		.name = "wmaa-backlight",
> +	},
> +	.probe = wmaa_backlight_wmi_probe,
> +	.id_table = wmaa_backlight_wmi_id_table,
> +};
> +module_wmi_driver(wmaa_backlight_wmi_driver);
> +
> +MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
> +MODULE_DESCRIPTION("WMAA Backlight WMI driver");
> +MODULE_LICENSE("GPL");
> 

Re: [PATCH v6] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Pali Rohár]

On Monday 13 September 2021 11:01:50 Hans de Goede wrote:
> Hi,
> 
> On 9/3/21 2:38 AM, Daniel Dadap wrote:
> > A number of upcoming notebook computer designs drive the internal
> > display panel's backlight PWM through the Embedded Controller (EC).
> > This EC-based backlight control can be plumbed through to an ACPI
> > "WMAA" method interface, which in turn can be wrapped by WMI with
> > the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
> > 
> > Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
> > backlight class driver to control backlight levels on systems with
> > EC-driven backlights.
> > 
> > Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
> > Reviewed-By: Thomas Weißschuh <linux@weissschuh.net>
> 
> Thank you for your patch, I've applied this patch to my review-hans 
> branch:
> https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=review-hans
> 
> Note it will show up in my review-hans branch once I've pushed my
> local branch there, which might take a while.
> 
> Once I've run some tests on this branch the patches there will be
> added to the platform-drivers-x86/for-next branch and eventually
> will be included in the pdx86 pull-request to Linus for the next
> merge-window.

Hello Hans!

I would suggest to rename this driver and config option to not include
-AA in its name. WMAA is just internal name of ACPI method, composed
from two parts: "WM" and "AA". Second part "AA" is read from the _WDG
where is the translation table from WMI GUID (in this case 603E9613...)
to ACPI method name. "AA" is just autogenerated identifier by wmi
compiler and because names are ASCII strings, I guess "AA" could mean
the first (autogenerated) method. In the whole driver code you are not
using AA function name, but directly WMI GUID, which also means that
driver is prepared if vendor "recompiles" wmi code in acpi (and compiler
generates another identifier, not AA). Also another argument is that
there can be lot of other laptops which have WMAA ACPI method but they
can have different API or do something totally different. So name WMAA
is in this wmi context very misleading. Rather it should be named by
vendor.

Anyway, could you provide BMF code for this wmi acpi functionality? In
BMF could be encoded more informations, including real, meaning human
readable name of this function. Not only internal (autogenerated) AA
identifier. BMF can be extracted from dumps created by 'acpidump' tool
or with new kernels directly from files 'find /sys/ -name bmof'.

For example Windows drivers use directly those real function names and
let Windows NT kernel to translate real function names. So if for this
functionality there is Windows driver, its .ini (or other text files)
could also provide more information.

In past I have written bmf2mof decompiler which decompiles binary BMF
code back to MOF source code: https://github.com/pali/bmfdec

So if you extract BMF code from that machine, then this bmf2mof tool can
help with developing or identifying parts of wmi, and showing real
function names. Sometimes there are also comments/descriptions in binary
BMF code (but due to its format, not readable by 'strings', and
decompilation is needed) which can provide even more information about
usage.

> Regards,
> 
> Hans
> 
> 
> > ---
> > 
> > v2: Convert to WMI subsystem driver, suggested by Mario Limonciello
> >     <mario.limonciello@outlook.com>; various cleanups suggested by
> >     Barnabás Pőcze <pobrn@protonmail.com>
> > v3: Address assorted style nits raised by Andy Shevchenko
> >     <andy.shevchenko@gmail.com> in response to a related patch; remove
> >     additional behavior change to WMI subsystem from patch series as
> >     recommended by Hans de Goede <hdegoede@redhat.com> 
> > v4: Use MODULE_DEVICE_TABLE() (Thomas Weißschuh <thomas@t-8ch.de>)
> >     Fix scope of internal driver state; various style fixes (Barnabás
> >     Pőcze, Andy Shevchenko)
> >     Use devm_backlight_device_register() (Barnabás Pőcze)
> >     Add kerneldoc comments for enums and structs (Andy Shevchenko)
> > v5: Remove Aaron Plattner as author, as suggested by Aaron Plattner
> >     <aplattner@nvidia.com>
> >     Register as BACKLIGHT_FIRMWARE rather than BACKLIGHT_PLATFORM;
> >     Return negative errno if .get_brightness() fails (Thomas Weißschuh)
> >     Assorted style improvements (Andy Shevchenko, Thomas Weißschuh)
> > v6: Make behavior of callers of wmi_call_wmaa() more consistent;
> >     simplify potentially confusing description in Kconfig help text
> >     (Thomas Weißschuh)
> > 
> >  MAINTAINERS                               |   6 +
> >  drivers/platform/x86/Kconfig              |  16 ++
> >  drivers/platform/x86/Makefile             |   1 +
> >  drivers/platform/x86/wmaa-backlight-wmi.c | 205 ++++++++++++++++++++++
> >  4 files changed, 228 insertions(+)
> >  create mode 100644 drivers/platform/x86/wmaa-backlight-wmi.c
> > 
> > diff --git a/MAINTAINERS b/MAINTAINERS
> > index bbaecde94aa0..fd7362a86c6d 100644
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -20008,6 +20008,12 @@ L:	linux-wireless@vger.kernel.org
> >  S:	Odd fixes
> >  F:	drivers/net/wireless/wl3501*
> >  
> > +WMAA BACKLIGHT DRIVER
> > +M:	Daniel Dadap <ddadap@nvidia.com>
> > +L:	platform-driver-x86@vger.kernel.org
> > +S:	Supported
> > +F:	drivers/platform/x86/wmaa-backlight-wmi.c
> > +
> >  WOLFSON MICROELECTRONICS DRIVERS
> >  L:	patches@opensource.cirrus.com
> >  S:	Supported
> > diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
> > index d12db6c316ea..00f021eda25c 100644
> > --- a/drivers/platform/x86/Kconfig
> > +++ b/drivers/platform/x86/Kconfig
> > @@ -113,6 +113,22 @@ config PEAQ_WMI
> >  	help
> >  	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
> >  
> > +config WMAA_BACKLIGHT_WMI
> > +	tristate "ACPI WMAA Backlight Driver"
> > +	depends on ACPI_WMI
> > +	depends on BACKLIGHT_CLASS_DEVICE
> > +	help
> > +	  This driver provides a sysfs backlight interface for notebook
> > +	  systems which expose the WMAA ACPI method and an associated WMI
> > +	  wrapper to drive LCD backlight levels through the Embedded Controller
> > +	  (EC).
> > +
> > +	  Say Y or M here if you want to control the backlight on a notebook
> > +	  system with an EC-driven backlight using the ACPI WMAA method.
> > +
> > +	  If you choose to compile this driver as a module the module will be
> > +	  called wmaa-backlight-wmi.
> > +
> >  config XIAOMI_WMI
> >  	tristate "Xiaomi WMI key driver"
> >  	depends on ACPI_WMI
> > diff --git a/drivers/platform/x86/Makefile b/drivers/platform/x86/Makefile
> > index 7ee369aab10d..109c1714237d 100644
> > --- a/drivers/platform/x86/Makefile
> > +++ b/drivers/platform/x86/Makefile
> > @@ -14,6 +14,7 @@ obj-$(CONFIG_INTEL_WMI_SBL_FW_UPDATE)	+= intel-wmi-sbl-fw-update.o
> >  obj-$(CONFIG_INTEL_WMI_THUNDERBOLT)	+= intel-wmi-thunderbolt.o
> >  obj-$(CONFIG_MXM_WMI)			+= mxm-wmi.o
> >  obj-$(CONFIG_PEAQ_WMI)			+= peaq-wmi.o
> > +obj-$(CONFIG_WMAA_BACKLIGHT_WMI)	+= wmaa-backlight-wmi.o
> >  obj-$(CONFIG_XIAOMI_WMI)		+= xiaomi-wmi.o
> >  obj-$(CONFIG_GIGABYTE_WMI)		+= gigabyte-wmi.o
> >  
> > diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
> > new file mode 100644
> > index 000000000000..f5c4f8337c2c
> > --- /dev/null
> > +++ b/drivers/platform/x86/wmaa-backlight-wmi.c
> > @@ -0,0 +1,205 @@
> > +// SPDX-License-Identifier: GPL-2.0-only
> > +/*
> > + * Copyright (c) 2020, NVIDIA CORPORATION.  All rights reserved.
> > + */
> > +
> > +#include <linux/acpi.h>
> > +#include <linux/backlight.h>
> > +#include <linux/mod_devicetable.h>
> > +#include <linux/module.h>
> > +#include <linux/types.h>
> > +#include <linux/wmi.h>
> > +
> > +/**
> > + * enum wmaa_method - WMI method IDs for ACPI WMAA
> > + * @WMAA_METHOD_LEVEL:  Get or set the brightness level,
> > + *                      or get the maximum brightness level.
> > + * @WMAA_METHOD_SOURCE: Get the source for backlight control.
> > + */
> > +enum wmaa_method {
> > +	WMAA_METHOD_LEVEL = 1,
> > +	WMAA_METHOD_SOURCE = 2,
> > +	WMAA_METHOD_MAX
> > +};
> > +
> > +/**
> > + * enum wmaa_mode - Operation mode for ACPI WMAA method
> > + * @WMAA_MODE_GET:           Get the current brightness level or source.
> > + * @WMAA_MODE_SET:           Set the brightness level.
> > + * @WMAA_MODE_GET_MAX_LEVEL: Get the maximum brightness level. This is only
> > + *                           valid when the WMI method is %WMAA_METHOD_LEVEL.
> > + */
> > +enum wmaa_mode {
> > +	WMAA_MODE_GET = 0,
> > +	WMAA_MODE_SET = 1,
> > +	WMAA_MODE_GET_MAX_LEVEL = 2,
> > +	WMAA_MODE_MAX
> > +};
> > +
> > +/**
> > + * enum wmaa_source - Backlight brightness control source identification
> > + * @WMAA_SOURCE_GPU:   Backlight brightness is controlled by the GPU.
> > + * @WMAA_SOURCE_EC:    Backlight brightness is controlled by the system's
> > + *                     Embedded Controller (EC).
> > + * @WMAA_SOURCE_AUX:   Backlight brightness is controlled over the DisplayPort
> > + *                     AUX channel.
> > + */
> > +enum wmaa_source {
> > +	WMAA_SOURCE_GPU = 1,
> > +	WMAA_SOURCE_EC = 2,
> > +	WMAA_SOURCE_AUX = 3,
> > +	WMAA_SOURCE_MAX
> > +};
> > +
> > +/**
> > + * struct wmaa_args - arguments for the ACPI WMAA method
> > + * @mode:    Pass in an &enum wmaa_mode value to select between getting or
> > + *           setting a value.
> > + * @val:     In parameter for value to set when operating in %WMAA_MODE_SET
> > + *           mode. Not used in %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode.
> > + * @ret:     Out parameter returning retrieved value when operating in
> > + *           %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode. Not used in
> > + *           %WMAA_MODE_SET mode.
> > + * @ignored: Padding; not used. The ACPI method expects a 24 byte params struct.
> > + *
> > + * This is the parameters structure for the ACPI WMAA method as wrapped by WMI.
> > + * The value passed in to @val or returned by @ret will be a brightness value
> > + * when the WMI method ID is %WMAA_METHOD_LEVEL, or an &enum wmaa_source value
> > + * when the WMI method ID is %WMAA_METHOD_SOURCE.
> > + */
> > +struct wmaa_args {
> > +	u32 mode;
> > +	u32 val;
> > +	u32 ret;
> > +	u32 ignored[3];
> > +};
> > +
> > +/**
> > + * wmi_call_wmaa() - helper function for calling ACPI WMAA via its WMI wrapper
> > + * @w:    Pointer to the struct wmi_device identified by %WMAA_WMI_GUID
> > + * @id:   The method ID for the ACPI WMAA method (e.g. %WMAA_METHOD_LEVEL or
> > + *        %WMAA_METHOD_SOURCE)
> > + * @mode: The operation to perform on the ACPI WMAA method (e.g. %WMAA_MODE_SET
> > + *        or %WMAA_MODE_GET)
> > + * @val:  Pointer to a value passed in by the caller when @mode is
> > + *        %WMAA_MODE_SET, or a value passed out to the caller when @mode is
> > + *        %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL.
> > + *
> > + * Returns 0 on success, or a negative error number on failure.
> > + */
> > +static int wmi_call_wmaa(struct wmi_device *w, enum wmaa_method id, enum wmaa_mode mode, u32 *val)
> > +{
> > +	struct wmaa_args args = {
> > +		.mode = mode,
> > +		.val = 0,
> > +		.ret = 0,
> > +	};
> > +	struct acpi_buffer buf = { (acpi_size)sizeof(args), &args };
> > +	acpi_status status;
> > +
> > +	if (id < WMAA_METHOD_LEVEL || id >= WMAA_METHOD_MAX ||
> > +	    mode < WMAA_MODE_GET || mode >= WMAA_MODE_MAX)
> > +		return -EINVAL;
> > +
> > +	if (mode == WMAA_MODE_SET)
> > +		args.val = *val;
> > +
> > +	status = wmidev_evaluate_method(w, 0, id, &buf, &buf);
> > +	if (ACPI_FAILURE(status)) {
> > +		dev_err(&w->dev, "ACPI WMAA failed: %s\n",
> > +			acpi_format_exception(status));
> > +		return -EIO;
> > +	}
> > +
> > +	if (mode != WMAA_MODE_SET)
> > +		*val = args.ret;
> > +
> > +	return 0;
> > +}
> > +
> > +static int wmaa_backlight_update_status(struct backlight_device *bd)
> > +{
> > +	struct wmi_device *wdev = bl_get_data(bd);
> > +
> > +	return wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_SET,
> > +			     &bd->props.brightness);
> > +}
> > +
> > +static int wmaa_backlight_get_brightness(struct backlight_device *bd)
> > +{
> > +	struct wmi_device *wdev = bl_get_data(bd);
> > +	u32 level;
> > +	int ret;
> > +
> > +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET, &level);
> > +	if (ret < 0)
> > +		return ret;
> > +
> > +	return level;
> > +}
> > +
> > +static const struct backlight_ops wmaa_backlight_ops = {
> > +	.update_status = wmaa_backlight_update_status,
> > +	.get_brightness = wmaa_backlight_get_brightness,
> > +};
> > +
> > +static int wmaa_backlight_wmi_probe(struct wmi_device *wdev, const void *ctx)
> > +{
> > +	struct backlight_properties props = {};
> > +	struct backlight_device *bdev;
> > +	u32 source;
> > +	int ret;
> > +
> > +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_SOURCE, WMAA_MODE_GET, &source);
> > +	if (ret)
> > +		return ret;
> > +
> > +	/*
> > +	 * This driver is only to be used when brightness control is handled
> > +	 * by the EC; otherwise, the GPU driver(s) should control brightness.
> > +	 */
> > +	if (source != WMAA_SOURCE_EC)
> > +		return -ENODEV;
> > +
> > +	/*
> > +	 * Identify this backlight device as a firmware device so that it can
> > +	 * be prioritized over any exposed GPU-driven raw device(s).
> > +	 */
> > +	props.type = BACKLIGHT_FIRMWARE;
> > +
> > +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET_MAX_LEVEL,
> > +			    &props.max_brightness);
> > +	if (ret)
> > +		return ret;
> > +
> > +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET,
> > +			    &props.brightness);
> > +	if (ret)
> > +		return ret;
> > +
> > +	bdev = devm_backlight_device_register(&wdev->dev, "wmaa_backlight",
> > +					      &wdev->dev, wdev,
> > +					      &wmaa_backlight_ops, &props);
> > +	return PTR_ERR_OR_ZERO(bdev);
> > +}
> > +
> > +#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
> > +
> > +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
> > +	{ .guid_string = WMAA_WMI_GUID },
> > +	{ }
> > +};
> > +MODULE_DEVICE_TABLE(wmi, wmaa_backlight_wmi_id_table);
> > +
> > +static struct wmi_driver wmaa_backlight_wmi_driver = {
> > +	.driver = {
> > +		.name = "wmaa-backlight",
> > +	},
> > +	.probe = wmaa_backlight_wmi_probe,
> > +	.id_table = wmaa_backlight_wmi_id_table,
> > +};
> > +module_wmi_driver(wmaa_backlight_wmi_driver);
> > +
> > +MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
> > +MODULE_DESCRIPTION("WMAA Backlight WMI driver");
> > +MODULE_LICENSE("GPL");
> > 
> 

Re: [PATCH v6] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Hans de Goede]

Hi Pali,

On 9/20/21 3:29 PM, Pali Rohár wrote:
> On Monday 13 September 2021 11:01:50 Hans de Goede wrote:
>> Hi,
>>
>> On 9/3/21 2:38 AM, Daniel Dadap wrote:
>>> A number of upcoming notebook computer designs drive the internal
>>> display panel's backlight PWM through the Embedded Controller (EC).
>>> This EC-based backlight control can be plumbed through to an ACPI
>>> "WMAA" method interface, which in turn can be wrapped by WMI with
>>> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
>>>
>>> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
>>> backlight class driver to control backlight levels on systems with
>>> EC-driven backlights.
>>>
>>> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
>>> Reviewed-By: Thomas Weißschuh <linux@weissschuh.net>
>>
>> Thank you for your patch, I've applied this patch to my review-hans 
>> branch:
>> https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=review-hans
>>
>> Note it will show up in my review-hans branch once I've pushed my
>> local branch there, which might take a while.
>>
>> Once I've run some tests on this branch the patches there will be
>> added to the platform-drivers-x86/for-next branch and eventually
>> will be included in the pdx86 pull-request to Linus for the next
>> merge-window.
> 
> Hello Hans!
> 
> I would suggest to rename this driver and config option to not include
> -AA in its name. WMAA is just internal name of ACPI method, composed
> from two parts: "WM" and "AA". Second part "AA" is read from the _WDG
> where is the translation table from WMI GUID (in this case 603E9613...)
> to ACPI method name. "AA" is just autogenerated identifier by wmi
> compiler and because names are ASCII strings, I guess "AA" could mean
> the first (autogenerated) method. In the whole driver code you are not
> using AA function name, but directly WMI GUID, which also means that
> driver is prepared if vendor "recompiles" wmi code in acpi (and compiler
> generates another identifier, not AA). Also another argument is that
> there can be lot of other laptops which have WMAA ACPI method but they
> can have different API or do something totally different. So name WMAA
> is in this wmi context very misleading. Rather it should be named by
> vendor.

Right, that is a very valid point. I should have spotted this myself.

So what would be a better name wmi-nvidia-backlight.ko I guess ?
(and update the rest to match ?)

> Anyway, could you provide BMF code for this wmi acpi functionality? In
> BMF could be encoded more informations, including real, meaning human
> readable name of this function. Not only internal (autogenerated) AA
> identifier. BMF can be extracted from dumps created by 'acpidump' tool
> or with new kernels directly from files 'find /sys/ -name bmof'.

I will leave answering this part up to Daniel Dadap, since I don't
have access to any of this.

Regards,

Hans


> For example Windows drivers use directly those real function names and
> let Windows NT kernel to translate real function names. So if for this
> functionality there is Windows driver, its .ini (or other text files)
> could also provide more information.
> 
> In past I have written bmf2mof decompiler which decompiles binary BMF
> code back to MOF source code: https://github.com/pali/bmfdec
> 
> So if you extract BMF code from that machine, then this bmf2mof tool can
> help with developing or identifying parts of wmi, and showing real
> function names. Sometimes there are also comments/descriptions in binary
> BMF code (but due to its format, not readable by 'strings', and
> decompilation is needed) which can provide even more information about
> usage.
> 
>> Regards,
>>
>> Hans
>>
>>
>>> ---
>>>
>>> v2: Convert to WMI subsystem driver, suggested by Mario Limonciello
>>>     <mario.limonciello@outlook.com>; various cleanups suggested by
>>>     Barnabás Pőcze <pobrn@protonmail.com>
>>> v3: Address assorted style nits raised by Andy Shevchenko
>>>     <andy.shevchenko@gmail.com> in response to a related patch; remove
>>>     additional behavior change to WMI subsystem from patch series as
>>>     recommended by Hans de Goede <hdegoede@redhat.com> 
>>> v4: Use MODULE_DEVICE_TABLE() (Thomas Weißschuh <thomas@t-8ch.de>)
>>>     Fix scope of internal driver state; various style fixes (Barnabás
>>>     Pőcze, Andy Shevchenko)
>>>     Use devm_backlight_device_register() (Barnabás Pőcze)
>>>     Add kerneldoc comments for enums and structs (Andy Shevchenko)
>>> v5: Remove Aaron Plattner as author, as suggested by Aaron Plattner
>>>     <aplattner@nvidia.com>
>>>     Register as BACKLIGHT_FIRMWARE rather than BACKLIGHT_PLATFORM;
>>>     Return negative errno if .get_brightness() fails (Thomas Weißschuh)
>>>     Assorted style improvements (Andy Shevchenko, Thomas Weißschuh)
>>> v6: Make behavior of callers of wmi_call_wmaa() more consistent;
>>>     simplify potentially confusing description in Kconfig help text
>>>     (Thomas Weißschuh)
>>>
>>>  MAINTAINERS                               |   6 +
>>>  drivers/platform/x86/Kconfig              |  16 ++
>>>  drivers/platform/x86/Makefile             |   1 +
>>>  drivers/platform/x86/wmaa-backlight-wmi.c | 205 ++++++++++++++++++++++
>>>  4 files changed, 228 insertions(+)
>>>  create mode 100644 drivers/platform/x86/wmaa-backlight-wmi.c
>>>
>>> diff --git a/MAINTAINERS b/MAINTAINERS
>>> index bbaecde94aa0..fd7362a86c6d 100644
>>> --- a/MAINTAINERS
>>> +++ b/MAINTAINERS
>>> @@ -20008,6 +20008,12 @@ L:	linux-wireless@vger.kernel.org
>>>  S:	Odd fixes
>>>  F:	drivers/net/wireless/wl3501*
>>>  
>>> +WMAA BACKLIGHT DRIVER
>>> +M:	Daniel Dadap <ddadap@nvidia.com>
>>> +L:	platform-driver-x86@vger.kernel.org
>>> +S:	Supported
>>> +F:	drivers/platform/x86/wmaa-backlight-wmi.c
>>> +
>>>  WOLFSON MICROELECTRONICS DRIVERS
>>>  L:	patches@opensource.cirrus.com
>>>  S:	Supported
>>> diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
>>> index d12db6c316ea..00f021eda25c 100644
>>> --- a/drivers/platform/x86/Kconfig
>>> +++ b/drivers/platform/x86/Kconfig
>>> @@ -113,6 +113,22 @@ config PEAQ_WMI
>>>  	help
>>>  	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
>>>  
>>> +config WMAA_BACKLIGHT_WMI
>>> +	tristate "ACPI WMAA Backlight Driver"
>>> +	depends on ACPI_WMI
>>> +	depends on BACKLIGHT_CLASS_DEVICE
>>> +	help
>>> +	  This driver provides a sysfs backlight interface for notebook
>>> +	  systems which expose the WMAA ACPI method and an associated WMI
>>> +	  wrapper to drive LCD backlight levels through the Embedded Controller
>>> +	  (EC).
>>> +
>>> +	  Say Y or M here if you want to control the backlight on a notebook
>>> +	  system with an EC-driven backlight using the ACPI WMAA method.
>>> +
>>> +	  If you choose to compile this driver as a module the module will be
>>> +	  called wmaa-backlight-wmi.
>>> +
>>>  config XIAOMI_WMI
>>>  	tristate "Xiaomi WMI key driver"
>>>  	depends on ACPI_WMI
>>> diff --git a/drivers/platform/x86/Makefile b/drivers/platform/x86/Makefile
>>> index 7ee369aab10d..109c1714237d 100644
>>> --- a/drivers/platform/x86/Makefile
>>> +++ b/drivers/platform/x86/Makefile
>>> @@ -14,6 +14,7 @@ obj-$(CONFIG_INTEL_WMI_SBL_FW_UPDATE)	+= intel-wmi-sbl-fw-update.o
>>>  obj-$(CONFIG_INTEL_WMI_THUNDERBOLT)	+= intel-wmi-thunderbolt.o
>>>  obj-$(CONFIG_MXM_WMI)			+= mxm-wmi.o
>>>  obj-$(CONFIG_PEAQ_WMI)			+= peaq-wmi.o
>>> +obj-$(CONFIG_WMAA_BACKLIGHT_WMI)	+= wmaa-backlight-wmi.o
>>>  obj-$(CONFIG_XIAOMI_WMI)		+= xiaomi-wmi.o
>>>  obj-$(CONFIG_GIGABYTE_WMI)		+= gigabyte-wmi.o
>>>  
>>> diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
>>> new file mode 100644
>>> index 000000000000..f5c4f8337c2c
>>> --- /dev/null
>>> +++ b/drivers/platform/x86/wmaa-backlight-wmi.c
>>> @@ -0,0 +1,205 @@
>>> +// SPDX-License-Identifier: GPL-2.0-only
>>> +/*
>>> + * Copyright (c) 2020, NVIDIA CORPORATION.  All rights reserved.
>>> + */
>>> +
>>> +#include <linux/acpi.h>
>>> +#include <linux/backlight.h>
>>> +#include <linux/mod_devicetable.h>
>>> +#include <linux/module.h>
>>> +#include <linux/types.h>
>>> +#include <linux/wmi.h>
>>> +
>>> +/**
>>> + * enum wmaa_method - WMI method IDs for ACPI WMAA
>>> + * @WMAA_METHOD_LEVEL:  Get or set the brightness level,
>>> + *                      or get the maximum brightness level.
>>> + * @WMAA_METHOD_SOURCE: Get the source for backlight control.
>>> + */
>>> +enum wmaa_method {
>>> +	WMAA_METHOD_LEVEL = 1,
>>> +	WMAA_METHOD_SOURCE = 2,
>>> +	WMAA_METHOD_MAX
>>> +};
>>> +
>>> +/**
>>> + * enum wmaa_mode - Operation mode for ACPI WMAA method
>>> + * @WMAA_MODE_GET:           Get the current brightness level or source.
>>> + * @WMAA_MODE_SET:           Set the brightness level.
>>> + * @WMAA_MODE_GET_MAX_LEVEL: Get the maximum brightness level. This is only
>>> + *                           valid when the WMI method is %WMAA_METHOD_LEVEL.
>>> + */
>>> +enum wmaa_mode {
>>> +	WMAA_MODE_GET = 0,
>>> +	WMAA_MODE_SET = 1,
>>> +	WMAA_MODE_GET_MAX_LEVEL = 2,
>>> +	WMAA_MODE_MAX
>>> +};
>>> +
>>> +/**
>>> + * enum wmaa_source - Backlight brightness control source identification
>>> + * @WMAA_SOURCE_GPU:   Backlight brightness is controlled by the GPU.
>>> + * @WMAA_SOURCE_EC:    Backlight brightness is controlled by the system's
>>> + *                     Embedded Controller (EC).
>>> + * @WMAA_SOURCE_AUX:   Backlight brightness is controlled over the DisplayPort
>>> + *                     AUX channel.
>>> + */
>>> +enum wmaa_source {
>>> +	WMAA_SOURCE_GPU = 1,
>>> +	WMAA_SOURCE_EC = 2,
>>> +	WMAA_SOURCE_AUX = 3,
>>> +	WMAA_SOURCE_MAX
>>> +};
>>> +
>>> +/**
>>> + * struct wmaa_args - arguments for the ACPI WMAA method
>>> + * @mode:    Pass in an &enum wmaa_mode value to select between getting or
>>> + *           setting a value.
>>> + * @val:     In parameter for value to set when operating in %WMAA_MODE_SET
>>> + *           mode. Not used in %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode.
>>> + * @ret:     Out parameter returning retrieved value when operating in
>>> + *           %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode. Not used in
>>> + *           %WMAA_MODE_SET mode.
>>> + * @ignored: Padding; not used. The ACPI method expects a 24 byte params struct.
>>> + *
>>> + * This is the parameters structure for the ACPI WMAA method as wrapped by WMI.
>>> + * The value passed in to @val or returned by @ret will be a brightness value
>>> + * when the WMI method ID is %WMAA_METHOD_LEVEL, or an &enum wmaa_source value
>>> + * when the WMI method ID is %WMAA_METHOD_SOURCE.
>>> + */
>>> +struct wmaa_args {
>>> +	u32 mode;
>>> +	u32 val;
>>> +	u32 ret;
>>> +	u32 ignored[3];
>>> +};
>>> +
>>> +/**
>>> + * wmi_call_wmaa() - helper function for calling ACPI WMAA via its WMI wrapper
>>> + * @w:    Pointer to the struct wmi_device identified by %WMAA_WMI_GUID
>>> + * @id:   The method ID for the ACPI WMAA method (e.g. %WMAA_METHOD_LEVEL or
>>> + *        %WMAA_METHOD_SOURCE)
>>> + * @mode: The operation to perform on the ACPI WMAA method (e.g. %WMAA_MODE_SET
>>> + *        or %WMAA_MODE_GET)
>>> + * @val:  Pointer to a value passed in by the caller when @mode is
>>> + *        %WMAA_MODE_SET, or a value passed out to the caller when @mode is
>>> + *        %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL.
>>> + *
>>> + * Returns 0 on success, or a negative error number on failure.
>>> + */
>>> +static int wmi_call_wmaa(struct wmi_device *w, enum wmaa_method id, enum wmaa_mode mode, u32 *val)
>>> +{
>>> +	struct wmaa_args args = {
>>> +		.mode = mode,
>>> +		.val = 0,
>>> +		.ret = 0,
>>> +	};
>>> +	struct acpi_buffer buf = { (acpi_size)sizeof(args), &args };
>>> +	acpi_status status;
>>> +
>>> +	if (id < WMAA_METHOD_LEVEL || id >= WMAA_METHOD_MAX ||
>>> +	    mode < WMAA_MODE_GET || mode >= WMAA_MODE_MAX)
>>> +		return -EINVAL;
>>> +
>>> +	if (mode == WMAA_MODE_SET)
>>> +		args.val = *val;
>>> +
>>> +	status = wmidev_evaluate_method(w, 0, id, &buf, &buf);
>>> +	if (ACPI_FAILURE(status)) {
>>> +		dev_err(&w->dev, "ACPI WMAA failed: %s\n",
>>> +			acpi_format_exception(status));
>>> +		return -EIO;
>>> +	}
>>> +
>>> +	if (mode != WMAA_MODE_SET)
>>> +		*val = args.ret;
>>> +
>>> +	return 0;
>>> +}
>>> +
>>> +static int wmaa_backlight_update_status(struct backlight_device *bd)
>>> +{
>>> +	struct wmi_device *wdev = bl_get_data(bd);
>>> +
>>> +	return wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_SET,
>>> +			     &bd->props.brightness);
>>> +}
>>> +
>>> +static int wmaa_backlight_get_brightness(struct backlight_device *bd)
>>> +{
>>> +	struct wmi_device *wdev = bl_get_data(bd);
>>> +	u32 level;
>>> +	int ret;
>>> +
>>> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET, &level);
>>> +	if (ret < 0)
>>> +		return ret;
>>> +
>>> +	return level;
>>> +}
>>> +
>>> +static const struct backlight_ops wmaa_backlight_ops = {
>>> +	.update_status = wmaa_backlight_update_status,
>>> +	.get_brightness = wmaa_backlight_get_brightness,
>>> +};
>>> +
>>> +static int wmaa_backlight_wmi_probe(struct wmi_device *wdev, const void *ctx)
>>> +{
>>> +	struct backlight_properties props = {};
>>> +	struct backlight_device *bdev;
>>> +	u32 source;
>>> +	int ret;
>>> +
>>> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_SOURCE, WMAA_MODE_GET, &source);
>>> +	if (ret)
>>> +		return ret;
>>> +
>>> +	/*
>>> +	 * This driver is only to be used when brightness control is handled
>>> +	 * by the EC; otherwise, the GPU driver(s) should control brightness.
>>> +	 */
>>> +	if (source != WMAA_SOURCE_EC)
>>> +		return -ENODEV;
>>> +
>>> +	/*
>>> +	 * Identify this backlight device as a firmware device so that it can
>>> +	 * be prioritized over any exposed GPU-driven raw device(s).
>>> +	 */
>>> +	props.type = BACKLIGHT_FIRMWARE;
>>> +
>>> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET_MAX_LEVEL,
>>> +			    &props.max_brightness);
>>> +	if (ret)
>>> +		return ret;
>>> +
>>> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET,
>>> +			    &props.brightness);
>>> +	if (ret)
>>> +		return ret;
>>> +
>>> +	bdev = devm_backlight_device_register(&wdev->dev, "wmaa_backlight",
>>> +					      &wdev->dev, wdev,
>>> +					      &wmaa_backlight_ops, &props);
>>> +	return PTR_ERR_OR_ZERO(bdev);
>>> +}
>>> +
>>> +#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
>>> +
>>> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
>>> +	{ .guid_string = WMAA_WMI_GUID },
>>> +	{ }
>>> +};
>>> +MODULE_DEVICE_TABLE(wmi, wmaa_backlight_wmi_id_table);
>>> +
>>> +static struct wmi_driver wmaa_backlight_wmi_driver = {
>>> +	.driver = {
>>> +		.name = "wmaa-backlight",
>>> +	},
>>> +	.probe = wmaa_backlight_wmi_probe,
>>> +	.id_table = wmaa_backlight_wmi_id_table,
>>> +};
>>> +module_wmi_driver(wmaa_backlight_wmi_driver);
>>> +
>>> +MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
>>> +MODULE_DESCRIPTION("WMAA Backlight WMI driver");
>>> +MODULE_LICENSE("GPL");
>>>
>>
> 

Re: [PATCH v6] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Pali Rohár]

On Monday 20 September 2021 15:33:20 Hans de Goede wrote:
> Hi Pali,
> 
> On 9/20/21 3:29 PM, Pali Rohár wrote:
> > On Monday 13 September 2021 11:01:50 Hans de Goede wrote:
> >> Hi,
> >>
> >> On 9/3/21 2:38 AM, Daniel Dadap wrote:
> >>> A number of upcoming notebook computer designs drive the internal
> >>> display panel's backlight PWM through the Embedded Controller (EC).
> >>> This EC-based backlight control can be plumbed through to an ACPI
> >>> "WMAA" method interface, which in turn can be wrapped by WMI with
> >>> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
> >>>
> >>> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
> >>> backlight class driver to control backlight levels on systems with
> >>> EC-driven backlights.
> >>>
> >>> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
> >>> Reviewed-By: Thomas Weißschuh <linux@weissschuh.net>
> >>
> >> Thank you for your patch, I've applied this patch to my review-hans 
> >> branch:
> >> https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=review-hans
> >>
> >> Note it will show up in my review-hans branch once I've pushed my
> >> local branch there, which might take a while.
> >>
> >> Once I've run some tests on this branch the patches there will be
> >> added to the platform-drivers-x86/for-next branch and eventually
> >> will be included in the pdx86 pull-request to Linus for the next
> >> merge-window.
> > 
> > Hello Hans!
> > 
> > I would suggest to rename this driver and config option to not include
> > -AA in its name. WMAA is just internal name of ACPI method, composed
> > from two parts: "WM" and "AA". Second part "AA" is read from the _WDG
> > where is the translation table from WMI GUID (in this case 603E9613...)
> > to ACPI method name. "AA" is just autogenerated identifier by wmi
> > compiler and because names are ASCII strings, I guess "AA" could mean
> > the first (autogenerated) method. In the whole driver code you are not
> > using AA function name, but directly WMI GUID, which also means that
> > driver is prepared if vendor "recompiles" wmi code in acpi (and compiler
> > generates another identifier, not AA). Also another argument is that
> > there can be lot of other laptops which have WMAA ACPI method but they
> > can have different API or do something totally different. So name WMAA
> > is in this wmi context very misleading. Rather it should be named by
> > vendor.
> 
> Right, that is a very valid point. I should have spotted this myself.
> 
> So what would be a better name wmi-nvidia-backlight.ko I guess ?
> (and update the rest to match ?)

It looks like that no vendor driver starts with "wmi-" prefix. "-wmi"
string is used as a suffix. So for consistency it would be better to
choose "nvidia-backlight-wmi.ko".

But it would be a nice to know if this wmi "API" is nvidia specific or
not. Because it is possible that there is vendor C who this "API"
invented, is licensing it and nvidia was just first who started using
this "API" + send patch to kernel. Embedded Controller, including its
programming is done by laptop vendor, it is fully in laptop vendor
control and I do not think that nvidia sells laptops. So there is a high
chance that we will see laptops without any nvidia component (with e.g.
amd or intel graphics card) and with this "API" :)

Some information may be available in bmf / acpidump code. Also there can
be information if this GUID is just for backlight or if it can provide
also some other functionality.

So for now lets stick with nvidia and I guess later driver can be
renamed (if we find out that this "API" is used also on non-nvidia based
laptops).

> > Anyway, could you provide BMF code for this wmi acpi functionality? In
> > BMF could be encoded more informations, including real, meaning human
> > readable name of this function. Not only internal (autogenerated) AA
> > identifier. BMF can be extracted from dumps created by 'acpidump' tool
> > or with new kernels directly from files 'find /sys/ -name bmof'.
> 
> I will leave answering this part up to Daniel Dadap, since I don't
> have access to any of this.
> 
> Regards,
> 
> Hans
> 
> 
> > For example Windows drivers use directly those real function names and
> > let Windows NT kernel to translate real function names. So if for this
> > functionality there is Windows driver, its .ini (or other text files)
> > could also provide more information.
> > 
> > In past I have written bmf2mof decompiler which decompiles binary BMF
> > code back to MOF source code: https://github.com/pali/bmfdec
> > 
> > So if you extract BMF code from that machine, then this bmf2mof tool can
> > help with developing or identifying parts of wmi, and showing real
> > function names. Sometimes there are also comments/descriptions in binary
> > BMF code (but due to its format, not readable by 'strings', and
> > decompilation is needed) which can provide even more information about
> > usage.
> > 
> >> Regards,
> >>
> >> Hans
> >>
> >>
> >>> ---
> >>>
> >>> v2: Convert to WMI subsystem driver, suggested by Mario Limonciello
> >>>     <mario.limonciello@outlook.com>; various cleanups suggested by
> >>>     Barnabás Pőcze <pobrn@protonmail.com>
> >>> v3: Address assorted style nits raised by Andy Shevchenko
> >>>     <andy.shevchenko@gmail.com> in response to a related patch; remove
> >>>     additional behavior change to WMI subsystem from patch series as
> >>>     recommended by Hans de Goede <hdegoede@redhat.com> 
> >>> v4: Use MODULE_DEVICE_TABLE() (Thomas Weißschuh <thomas@t-8ch.de>)
> >>>     Fix scope of internal driver state; various style fixes (Barnabás
> >>>     Pőcze, Andy Shevchenko)
> >>>     Use devm_backlight_device_register() (Barnabás Pőcze)
> >>>     Add kerneldoc comments for enums and structs (Andy Shevchenko)
> >>> v5: Remove Aaron Plattner as author, as suggested by Aaron Plattner
> >>>     <aplattner@nvidia.com>
> >>>     Register as BACKLIGHT_FIRMWARE rather than BACKLIGHT_PLATFORM;
> >>>     Return negative errno if .get_brightness() fails (Thomas Weißschuh)
> >>>     Assorted style improvements (Andy Shevchenko, Thomas Weißschuh)
> >>> v6: Make behavior of callers of wmi_call_wmaa() more consistent;
> >>>     simplify potentially confusing description in Kconfig help text
> >>>     (Thomas Weißschuh)
> >>>
> >>>  MAINTAINERS                               |   6 +
> >>>  drivers/platform/x86/Kconfig              |  16 ++
> >>>  drivers/platform/x86/Makefile             |   1 +
> >>>  drivers/platform/x86/wmaa-backlight-wmi.c | 205 ++++++++++++++++++++++
> >>>  4 files changed, 228 insertions(+)
> >>>  create mode 100644 drivers/platform/x86/wmaa-backlight-wmi.c
> >>>
> >>> diff --git a/MAINTAINERS b/MAINTAINERS
> >>> index bbaecde94aa0..fd7362a86c6d 100644
> >>> --- a/MAINTAINERS
> >>> +++ b/MAINTAINERS
> >>> @@ -20008,6 +20008,12 @@ L:	linux-wireless@vger.kernel.org
> >>>  S:	Odd fixes
> >>>  F:	drivers/net/wireless/wl3501*
> >>>  
> >>> +WMAA BACKLIGHT DRIVER
> >>> +M:	Daniel Dadap <ddadap@nvidia.com>
> >>> +L:	platform-driver-x86@vger.kernel.org
> >>> +S:	Supported
> >>> +F:	drivers/platform/x86/wmaa-backlight-wmi.c
> >>> +
> >>>  WOLFSON MICROELECTRONICS DRIVERS
> >>>  L:	patches@opensource.cirrus.com
> >>>  S:	Supported
> >>> diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
> >>> index d12db6c316ea..00f021eda25c 100644
> >>> --- a/drivers/platform/x86/Kconfig
> >>> +++ b/drivers/platform/x86/Kconfig
> >>> @@ -113,6 +113,22 @@ config PEAQ_WMI
> >>>  	help
> >>>  	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
> >>>  
> >>> +config WMAA_BACKLIGHT_WMI
> >>> +	tristate "ACPI WMAA Backlight Driver"
> >>> +	depends on ACPI_WMI
> >>> +	depends on BACKLIGHT_CLASS_DEVICE
> >>> +	help
> >>> +	  This driver provides a sysfs backlight interface for notebook
> >>> +	  systems which expose the WMAA ACPI method and an associated WMI
> >>> +	  wrapper to drive LCD backlight levels through the Embedded Controller
> >>> +	  (EC).
> >>> +
> >>> +	  Say Y or M here if you want to control the backlight on a notebook
> >>> +	  system with an EC-driven backlight using the ACPI WMAA method.
> >>> +
> >>> +	  If you choose to compile this driver as a module the module will be
> >>> +	  called wmaa-backlight-wmi.
> >>> +
> >>>  config XIAOMI_WMI
> >>>  	tristate "Xiaomi WMI key driver"
> >>>  	depends on ACPI_WMI
> >>> diff --git a/drivers/platform/x86/Makefile b/drivers/platform/x86/Makefile
> >>> index 7ee369aab10d..109c1714237d 100644
> >>> --- a/drivers/platform/x86/Makefile
> >>> +++ b/drivers/platform/x86/Makefile
> >>> @@ -14,6 +14,7 @@ obj-$(CONFIG_INTEL_WMI_SBL_FW_UPDATE)	+= intel-wmi-sbl-fw-update.o
> >>>  obj-$(CONFIG_INTEL_WMI_THUNDERBOLT)	+= intel-wmi-thunderbolt.o
> >>>  obj-$(CONFIG_MXM_WMI)			+= mxm-wmi.o
> >>>  obj-$(CONFIG_PEAQ_WMI)			+= peaq-wmi.o
> >>> +obj-$(CONFIG_WMAA_BACKLIGHT_WMI)	+= wmaa-backlight-wmi.o
> >>>  obj-$(CONFIG_XIAOMI_WMI)		+= xiaomi-wmi.o
> >>>  obj-$(CONFIG_GIGABYTE_WMI)		+= gigabyte-wmi.o
> >>>  
> >>> diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
> >>> new file mode 100644
> >>> index 000000000000..f5c4f8337c2c
> >>> --- /dev/null
> >>> +++ b/drivers/platform/x86/wmaa-backlight-wmi.c
> >>> @@ -0,0 +1,205 @@
> >>> +// SPDX-License-Identifier: GPL-2.0-only
> >>> +/*
> >>> + * Copyright (c) 2020, NVIDIA CORPORATION.  All rights reserved.
> >>> + */
> >>> +
> >>> +#include <linux/acpi.h>
> >>> +#include <linux/backlight.h>
> >>> +#include <linux/mod_devicetable.h>
> >>> +#include <linux/module.h>
> >>> +#include <linux/types.h>
> >>> +#include <linux/wmi.h>
> >>> +
> >>> +/**
> >>> + * enum wmaa_method - WMI method IDs for ACPI WMAA
> >>> + * @WMAA_METHOD_LEVEL:  Get or set the brightness level,
> >>> + *                      or get the maximum brightness level.
> >>> + * @WMAA_METHOD_SOURCE: Get the source for backlight control.
> >>> + */
> >>> +enum wmaa_method {
> >>> +	WMAA_METHOD_LEVEL = 1,
> >>> +	WMAA_METHOD_SOURCE = 2,
> >>> +	WMAA_METHOD_MAX
> >>> +};
> >>> +
> >>> +/**
> >>> + * enum wmaa_mode - Operation mode for ACPI WMAA method
> >>> + * @WMAA_MODE_GET:           Get the current brightness level or source.
> >>> + * @WMAA_MODE_SET:           Set the brightness level.
> >>> + * @WMAA_MODE_GET_MAX_LEVEL: Get the maximum brightness level. This is only
> >>> + *                           valid when the WMI method is %WMAA_METHOD_LEVEL.
> >>> + */
> >>> +enum wmaa_mode {
> >>> +	WMAA_MODE_GET = 0,
> >>> +	WMAA_MODE_SET = 1,
> >>> +	WMAA_MODE_GET_MAX_LEVEL = 2,
> >>> +	WMAA_MODE_MAX
> >>> +};
> >>> +
> >>> +/**
> >>> + * enum wmaa_source - Backlight brightness control source identification
> >>> + * @WMAA_SOURCE_GPU:   Backlight brightness is controlled by the GPU.
> >>> + * @WMAA_SOURCE_EC:    Backlight brightness is controlled by the system's
> >>> + *                     Embedded Controller (EC).
> >>> + * @WMAA_SOURCE_AUX:   Backlight brightness is controlled over the DisplayPort
> >>> + *                     AUX channel.
> >>> + */
> >>> +enum wmaa_source {
> >>> +	WMAA_SOURCE_GPU = 1,
> >>> +	WMAA_SOURCE_EC = 2,
> >>> +	WMAA_SOURCE_AUX = 3,
> >>> +	WMAA_SOURCE_MAX
> >>> +};
> >>> +
> >>> +/**
> >>> + * struct wmaa_args - arguments for the ACPI WMAA method
> >>> + * @mode:    Pass in an &enum wmaa_mode value to select between getting or
> >>> + *           setting a value.
> >>> + * @val:     In parameter for value to set when operating in %WMAA_MODE_SET
> >>> + *           mode. Not used in %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode.
> >>> + * @ret:     Out parameter returning retrieved value when operating in
> >>> + *           %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode. Not used in
> >>> + *           %WMAA_MODE_SET mode.
> >>> + * @ignored: Padding; not used. The ACPI method expects a 24 byte params struct.
> >>> + *
> >>> + * This is the parameters structure for the ACPI WMAA method as wrapped by WMI.
> >>> + * The value passed in to @val or returned by @ret will be a brightness value
> >>> + * when the WMI method ID is %WMAA_METHOD_LEVEL, or an &enum wmaa_source value
> >>> + * when the WMI method ID is %WMAA_METHOD_SOURCE.
> >>> + */
> >>> +struct wmaa_args {
> >>> +	u32 mode;
> >>> +	u32 val;
> >>> +	u32 ret;
> >>> +	u32 ignored[3];
> >>> +};
> >>> +
> >>> +/**
> >>> + * wmi_call_wmaa() - helper function for calling ACPI WMAA via its WMI wrapper
> >>> + * @w:    Pointer to the struct wmi_device identified by %WMAA_WMI_GUID
> >>> + * @id:   The method ID for the ACPI WMAA method (e.g. %WMAA_METHOD_LEVEL or
> >>> + *        %WMAA_METHOD_SOURCE)
> >>> + * @mode: The operation to perform on the ACPI WMAA method (e.g. %WMAA_MODE_SET
> >>> + *        or %WMAA_MODE_GET)
> >>> + * @val:  Pointer to a value passed in by the caller when @mode is
> >>> + *        %WMAA_MODE_SET, or a value passed out to the caller when @mode is
> >>> + *        %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL.
> >>> + *
> >>> + * Returns 0 on success, or a negative error number on failure.
> >>> + */
> >>> +static int wmi_call_wmaa(struct wmi_device *w, enum wmaa_method id, enum wmaa_mode mode, u32 *val)
> >>> +{
> >>> +	struct wmaa_args args = {
> >>> +		.mode = mode,
> >>> +		.val = 0,
> >>> +		.ret = 0,
> >>> +	};
> >>> +	struct acpi_buffer buf = { (acpi_size)sizeof(args), &args };
> >>> +	acpi_status status;
> >>> +
> >>> +	if (id < WMAA_METHOD_LEVEL || id >= WMAA_METHOD_MAX ||
> >>> +	    mode < WMAA_MODE_GET || mode >= WMAA_MODE_MAX)
> >>> +		return -EINVAL;
> >>> +
> >>> +	if (mode == WMAA_MODE_SET)
> >>> +		args.val = *val;
> >>> +
> >>> +	status = wmidev_evaluate_method(w, 0, id, &buf, &buf);
> >>> +	if (ACPI_FAILURE(status)) {
> >>> +		dev_err(&w->dev, "ACPI WMAA failed: %s\n",
> >>> +			acpi_format_exception(status));
> >>> +		return -EIO;
> >>> +	}
> >>> +
> >>> +	if (mode != WMAA_MODE_SET)
> >>> +		*val = args.ret;
> >>> +
> >>> +	return 0;
> >>> +}
> >>> +
> >>> +static int wmaa_backlight_update_status(struct backlight_device *bd)
> >>> +{
> >>> +	struct wmi_device *wdev = bl_get_data(bd);
> >>> +
> >>> +	return wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_SET,
> >>> +			     &bd->props.brightness);
> >>> +}
> >>> +
> >>> +static int wmaa_backlight_get_brightness(struct backlight_device *bd)
> >>> +{
> >>> +	struct wmi_device *wdev = bl_get_data(bd);
> >>> +	u32 level;
> >>> +	int ret;
> >>> +
> >>> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET, &level);
> >>> +	if (ret < 0)
> >>> +		return ret;
> >>> +
> >>> +	return level;
> >>> +}
> >>> +
> >>> +static const struct backlight_ops wmaa_backlight_ops = {
> >>> +	.update_status = wmaa_backlight_update_status,
> >>> +	.get_brightness = wmaa_backlight_get_brightness,
> >>> +};
> >>> +
> >>> +static int wmaa_backlight_wmi_probe(struct wmi_device *wdev, const void *ctx)
> >>> +{
> >>> +	struct backlight_properties props = {};
> >>> +	struct backlight_device *bdev;
> >>> +	u32 source;
> >>> +	int ret;
> >>> +
> >>> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_SOURCE, WMAA_MODE_GET, &source);
> >>> +	if (ret)
> >>> +		return ret;
> >>> +
> >>> +	/*
> >>> +	 * This driver is only to be used when brightness control is handled
> >>> +	 * by the EC; otherwise, the GPU driver(s) should control brightness.
> >>> +	 */
> >>> +	if (source != WMAA_SOURCE_EC)
> >>> +		return -ENODEV;
> >>> +
> >>> +	/*
> >>> +	 * Identify this backlight device as a firmware device so that it can
> >>> +	 * be prioritized over any exposed GPU-driven raw device(s).
> >>> +	 */
> >>> +	props.type = BACKLIGHT_FIRMWARE;
> >>> +
> >>> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET_MAX_LEVEL,
> >>> +			    &props.max_brightness);
> >>> +	if (ret)
> >>> +		return ret;
> >>> +
> >>> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET,
> >>> +			    &props.brightness);
> >>> +	if (ret)
> >>> +		return ret;
> >>> +
> >>> +	bdev = devm_backlight_device_register(&wdev->dev, "wmaa_backlight",
> >>> +					      &wdev->dev, wdev,
> >>> +					      &wmaa_backlight_ops, &props);
> >>> +	return PTR_ERR_OR_ZERO(bdev);
> >>> +}
> >>> +
> >>> +#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
> >>> +
> >>> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
> >>> +	{ .guid_string = WMAA_WMI_GUID },
> >>> +	{ }
> >>> +};
> >>> +MODULE_DEVICE_TABLE(wmi, wmaa_backlight_wmi_id_table);
> >>> +
> >>> +static struct wmi_driver wmaa_backlight_wmi_driver = {
> >>> +	.driver = {
> >>> +		.name = "wmaa-backlight",
> >>> +	},
> >>> +	.probe = wmaa_backlight_wmi_probe,
> >>> +	.id_table = wmaa_backlight_wmi_id_table,
> >>> +};
> >>> +module_wmi_driver(wmaa_backlight_wmi_driver);
> >>> +
> >>> +MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
> >>> +MODULE_DESCRIPTION("WMAA Backlight WMI driver");
> >>> +MODULE_LICENSE("GPL");
> >>>
> >>
> > 
> 

Re: [PATCH v6] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

[-- Attachment #1: Type: text/plain, Size: 18309 bytes --]

On 9/20/21 8:51 AM, Pali Rohár wrote:
> On Monday 20 September 2021 15:33:20 Hans de Goede wrote:
>> Hi Pali,
>>
>> On 9/20/21 3:29 PM, Pali Rohár wrote:
>>> On Monday 13 September 2021 11:01:50 Hans de Goede wrote:
>>>> Hi,
>>>>
>>>> On 9/3/21 2:38 AM, Daniel Dadap wrote:
>>>>> A number of upcoming notebook computer designs drive the internal
>>>>> display panel's backlight PWM through the Embedded Controller (EC).
>>>>> This EC-based backlight control can be plumbed through to an ACPI
>>>>> "WMAA" method interface, which in turn can be wrapped by WMI with
>>>>> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
>>>>>
>>>>> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
>>>>> backlight class driver to control backlight levels on systems with
>>>>> EC-driven backlights.
>>>>>
>>>>> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
>>>>> Reviewed-By: Thomas Weißschuh <linux@weissschuh.net>
>>>> Thank you for your patch, I've applied this patch to my review-hans
>>>> branch:
>>>> https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=review-hans
>>>>
>>>> Note it will show up in my review-hans branch once I've pushed my
>>>> local branch there, which might take a while.
>>>>
>>>> Once I've run some tests on this branch the patches there will be
>>>> added to the platform-drivers-x86/for-next branch and eventually
>>>> will be included in the pdx86 pull-request to Linus for the next
>>>> merge-window.
>>> Hello Hans!
>>>
>>> I would suggest to rename this driver and config option to not include
>>> -AA in its name. WMAA is just internal name of ACPI method, composed
>>> from two parts: "WM" and "AA". Second part "AA" is read from the _WDG
>>> where is the translation table from WMI GUID (in this case 603E9613...)
>>> to ACPI method name. "AA" is just autogenerated identifier by wmi
>>> compiler and because names are ASCII strings, I guess "AA" could mean
>>> the first (autogenerated) method. In the whole driver code you are not
>>> using AA function name, but directly WMI GUID, which also means that
>>> driver is prepared if vendor "recompiles" wmi code in acpi (and compiler
>>> generates another identifier, not AA). Also another argument is that
>>> there can be lot of other laptops which have WMAA ACPI method but they
>>> can have different API or do something totally different. So name WMAA
>>> is in this wmi context very misleading. Rather it should be named by
>>> vendor.
>> Right, that is a very valid point. I should have spotted this myself.


My apologies. I wasn't aware that WMAA was an autogenerated method name; 
I thought it was the name of the ACPI method and that the 603E9613... 
WMI GUID happened to wrap it. Given your explanation, I agree that the 
current name is inappropriate.


>> So what would be a better name wmi-nvidia-backlight.ko I guess ?
>> (and update the rest to match ?)
> It looks like that no vendor driver starts with "wmi-" prefix. "-wmi"
> string is used as a suffix. So for consistency it would be better to
> choose "nvidia-backlight-wmi.ko".
>
> But it would be a nice to know if this wmi "API" is nvidia specific or
> not. Because it is possible that there is vendor C who this "API"
> invented, is licensing it and nvidia was just first who started using
> this "API" + send patch to kernel. Embedded Controller, including its
> programming is done by laptop vendor, it is fully in laptop vendor
> control and I do not think that nvidia sells laptops. So there is a high
> chance that we will see laptops without any nvidia component (with e.g.
> amd or intel graphics card) and with this "API" :)


I will have to check about the origin of the "API" to be certain. My 
understanding is that this WMI backlight control scheme is part of 
NVIDIA design recommendations to notebook OEMs, with multiple OEMs 
potentially implementing it (I'm aware of at least two off the top of my 
head which already have systems in the wild). Specifically, this is 
meant to address an issue in hybrid systems with switchable graphics, by 
placing control of the backlight level with the EC rather than having to 
coordinate it between the different GPUs which might happen to be 
connected to the panel at any given time. It seems appropriate to me to 
include "nvidia" in the driver name for now; it could be renamed if it 
turns out non-NVIDIA designs use it as well. I don't have any specific 
information on whether or not that would be the case.


> Some information may be available in bmf / acpidump code. Also there can
> be information if this GUID is just for backlight or if it can provide
> also some other functionality.
>
> So for now lets stick with nvidia and I guess later driver can be
> renamed (if we find out that this "API" is used also on non-nvidia based
> laptops).


Okay, I'll send a follow-up patch to do the renaming once I get a little 
more clarification from someone who knows more about where the interface 
came from.


>
>>> Anyway, could you provide BMF code for this wmi acpi functionality? In
>>> BMF could be encoded more informations, including real, meaning human
>>> readable name of this function. Not only internal (autogenerated) AA
>>> identifier. BMF can be extracted from dumps created by 'acpidump' tool
>>> or with new kernels directly from files 'find /sys/ -name bmof'.


I've attached the output of your bmf2mof tool. Seems it's named 
"WmiBrightnessNotify", which isn't especially helpful.


>> I will leave answering this part up to Daniel Dadap, since I don't
>> have access to any of this.
>>
>> Regards,
>>
>> Hans
>>
>>
>>> For example Windows drivers use directly those real function names and
>>> let Windows NT kernel to translate real function names. So if for this
>>> functionality there is Windows driver, its .ini (or other text files)
>>> could also provide more information.
>>>
>>> In past I have written bmf2mof decompiler which decompiles binary BMF
>>> code back to MOF source code: https://github.com/pali/bmfdec
>>>
>>> So if you extract BMF code from that machine, then this bmf2mof tool can
>>> help with developing or identifying parts of wmi, and showing real
>>> function names. Sometimes there are also comments/descriptions in binary
>>> BMF code (but due to its format, not readable by 'strings', and
>>> decompilation is needed) which can provide even more information about
>>> usage.
>>>
>>>> Regards,
>>>>
>>>> Hans
>>>>
>>>>
>>>>> ---
>>>>>
>>>>> v2: Convert to WMI subsystem driver, suggested by Mario Limonciello
>>>>>      <mario.limonciello@outlook.com>; various cleanups suggested by
>>>>>      Barnabás Pőcze <pobrn@protonmail.com>
>>>>> v3: Address assorted style nits raised by Andy Shevchenko
>>>>>      <andy.shevchenko@gmail.com> in response to a related patch; remove
>>>>>      additional behavior change to WMI subsystem from patch series as
>>>>>      recommended by Hans de Goede <hdegoede@redhat.com>
>>>>> v4: Use MODULE_DEVICE_TABLE() (Thomas Weißschuh <thomas@t-8ch.de>)
>>>>>      Fix scope of internal driver state; various style fixes (Barnabás
>>>>>      Pőcze, Andy Shevchenko)
>>>>>      Use devm_backlight_device_register() (Barnabás Pőcze)
>>>>>      Add kerneldoc comments for enums and structs (Andy Shevchenko)
>>>>> v5: Remove Aaron Plattner as author, as suggested by Aaron Plattner
>>>>>      <aplattner@nvidia.com>
>>>>>      Register as BACKLIGHT_FIRMWARE rather than BACKLIGHT_PLATFORM;
>>>>>      Return negative errno if .get_brightness() fails (Thomas Weißschuh)
>>>>>      Assorted style improvements (Andy Shevchenko, Thomas Weißschuh)
>>>>> v6: Make behavior of callers of wmi_call_wmaa() more consistent;
>>>>>      simplify potentially confusing description in Kconfig help text
>>>>>      (Thomas Weißschuh)
>>>>>
>>>>>   MAINTAINERS                               |   6 +
>>>>>   drivers/platform/x86/Kconfig              |  16 ++
>>>>>   drivers/platform/x86/Makefile             |   1 +
>>>>>   drivers/platform/x86/wmaa-backlight-wmi.c | 205 ++++++++++++++++++++++
>>>>>   4 files changed, 228 insertions(+)
>>>>>   create mode 100644 drivers/platform/x86/wmaa-backlight-wmi.c
>>>>>
>>>>> diff --git a/MAINTAINERS b/MAINTAINERS
>>>>> index bbaecde94aa0..fd7362a86c6d 100644
>>>>> --- a/MAINTAINERS
>>>>> +++ b/MAINTAINERS
>>>>> @@ -20008,6 +20008,12 @@ L:	linux-wireless@vger.kernel.org
>>>>>   S:	Odd fixes
>>>>>   F:	drivers/net/wireless/wl3501*
>>>>>   
>>>>> +WMAA BACKLIGHT DRIVER
>>>>> +M:	Daniel Dadap <ddadap@nvidia.com>
>>>>> +L:	platform-driver-x86@vger.kernel.org
>>>>> +S:	Supported
>>>>> +F:	drivers/platform/x86/wmaa-backlight-wmi.c
>>>>> +
>>>>>   WOLFSON MICROELECTRONICS DRIVERS
>>>>>   L:	patches@opensource.cirrus.com
>>>>>   S:	Supported
>>>>> diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
>>>>> index d12db6c316ea..00f021eda25c 100644
>>>>> --- a/drivers/platform/x86/Kconfig
>>>>> +++ b/drivers/platform/x86/Kconfig
>>>>> @@ -113,6 +113,22 @@ config PEAQ_WMI
>>>>>   	help
>>>>>   	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
>>>>>   
>>>>> +config WMAA_BACKLIGHT_WMI
>>>>> +	tristate "ACPI WMAA Backlight Driver"
>>>>> +	depends on ACPI_WMI
>>>>> +	depends on BACKLIGHT_CLASS_DEVICE
>>>>> +	help
>>>>> +	  This driver provides a sysfs backlight interface for notebook
>>>>> +	  systems which expose the WMAA ACPI method and an associated WMI
>>>>> +	  wrapper to drive LCD backlight levels through the Embedded Controller
>>>>> +	  (EC).
>>>>> +
>>>>> +	  Say Y or M here if you want to control the backlight on a notebook
>>>>> +	  system with an EC-driven backlight using the ACPI WMAA method.
>>>>> +
>>>>> +	  If you choose to compile this driver as a module the module will be
>>>>> +	  called wmaa-backlight-wmi.
>>>>> +
>>>>>   config XIAOMI_WMI
>>>>>   	tristate "Xiaomi WMI key driver"
>>>>>   	depends on ACPI_WMI
>>>>> diff --git a/drivers/platform/x86/Makefile b/drivers/platform/x86/Makefile
>>>>> index 7ee369aab10d..109c1714237d 100644
>>>>> --- a/drivers/platform/x86/Makefile
>>>>> +++ b/drivers/platform/x86/Makefile
>>>>> @@ -14,6 +14,7 @@ obj-$(CONFIG_INTEL_WMI_SBL_FW_UPDATE)	+= intel-wmi-sbl-fw-update.o
>>>>>   obj-$(CONFIG_INTEL_WMI_THUNDERBOLT)	+= intel-wmi-thunderbolt.o
>>>>>   obj-$(CONFIG_MXM_WMI)			+= mxm-wmi.o
>>>>>   obj-$(CONFIG_PEAQ_WMI)			+= peaq-wmi.o
>>>>> +obj-$(CONFIG_WMAA_BACKLIGHT_WMI)	+= wmaa-backlight-wmi.o
>>>>>   obj-$(CONFIG_XIAOMI_WMI)		+= xiaomi-wmi.o
>>>>>   obj-$(CONFIG_GIGABYTE_WMI)		+= gigabyte-wmi.o
>>>>>   
>>>>> diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
>>>>> new file mode 100644
>>>>> index 000000000000..f5c4f8337c2c
>>>>> --- /dev/null
>>>>> +++ b/drivers/platform/x86/wmaa-backlight-wmi.c
>>>>> @@ -0,0 +1,205 @@
>>>>> +// SPDX-License-Identifier: GPL-2.0-only
>>>>> +/*
>>>>> + * Copyright (c) 2020, NVIDIA CORPORATION.  All rights reserved.
>>>>> + */
>>>>> +
>>>>> +#include <linux/acpi.h>
>>>>> +#include <linux/backlight.h>
>>>>> +#include <linux/mod_devicetable.h>
>>>>> +#include <linux/module.h>
>>>>> +#include <linux/types.h>
>>>>> +#include <linux/wmi.h>
>>>>> +
>>>>> +/**
>>>>> + * enum wmaa_method - WMI method IDs for ACPI WMAA
>>>>> + * @WMAA_METHOD_LEVEL:  Get or set the brightness level,
>>>>> + *                      or get the maximum brightness level.
>>>>> + * @WMAA_METHOD_SOURCE: Get the source for backlight control.
>>>>> + */
>>>>> +enum wmaa_method {
>>>>> +	WMAA_METHOD_LEVEL = 1,
>>>>> +	WMAA_METHOD_SOURCE = 2,
>>>>> +	WMAA_METHOD_MAX
>>>>> +};
>>>>> +
>>>>> +/**
>>>>> + * enum wmaa_mode - Operation mode for ACPI WMAA method
>>>>> + * @WMAA_MODE_GET:           Get the current brightness level or source.
>>>>> + * @WMAA_MODE_SET:           Set the brightness level.
>>>>> + * @WMAA_MODE_GET_MAX_LEVEL: Get the maximum brightness level. This is only
>>>>> + *                           valid when the WMI method is %WMAA_METHOD_LEVEL.
>>>>> + */
>>>>> +enum wmaa_mode {
>>>>> +	WMAA_MODE_GET = 0,
>>>>> +	WMAA_MODE_SET = 1,
>>>>> +	WMAA_MODE_GET_MAX_LEVEL = 2,
>>>>> +	WMAA_MODE_MAX
>>>>> +};
>>>>> +
>>>>> +/**
>>>>> + * enum wmaa_source - Backlight brightness control source identification
>>>>> + * @WMAA_SOURCE_GPU:   Backlight brightness is controlled by the GPU.
>>>>> + * @WMAA_SOURCE_EC:    Backlight brightness is controlled by the system's
>>>>> + *                     Embedded Controller (EC).
>>>>> + * @WMAA_SOURCE_AUX:   Backlight brightness is controlled over the DisplayPort
>>>>> + *                     AUX channel.
>>>>> + */
>>>>> +enum wmaa_source {
>>>>> +	WMAA_SOURCE_GPU = 1,
>>>>> +	WMAA_SOURCE_EC = 2,
>>>>> +	WMAA_SOURCE_AUX = 3,
>>>>> +	WMAA_SOURCE_MAX
>>>>> +};
>>>>> +
>>>>> +/**
>>>>> + * struct wmaa_args - arguments for the ACPI WMAA method
>>>>> + * @mode:    Pass in an &enum wmaa_mode value to select between getting or
>>>>> + *           setting a value.
>>>>> + * @val:     In parameter for value to set when operating in %WMAA_MODE_SET
>>>>> + *           mode. Not used in %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode.
>>>>> + * @ret:     Out parameter returning retrieved value when operating in
>>>>> + *           %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode. Not used in
>>>>> + *           %WMAA_MODE_SET mode.
>>>>> + * @ignored: Padding; not used. The ACPI method expects a 24 byte params struct.
>>>>> + *
>>>>> + * This is the parameters structure for the ACPI WMAA method as wrapped by WMI.
>>>>> + * The value passed in to @val or returned by @ret will be a brightness value
>>>>> + * when the WMI method ID is %WMAA_METHOD_LEVEL, or an &enum wmaa_source value
>>>>> + * when the WMI method ID is %WMAA_METHOD_SOURCE.
>>>>> + */
>>>>> +struct wmaa_args {
>>>>> +	u32 mode;
>>>>> +	u32 val;
>>>>> +	u32 ret;
>>>>> +	u32 ignored[3];
>>>>> +};
>>>>> +
>>>>> +/**
>>>>> + * wmi_call_wmaa() - helper function for calling ACPI WMAA via its WMI wrapper
>>>>> + * @w:    Pointer to the struct wmi_device identified by %WMAA_WMI_GUID
>>>>> + * @id:   The method ID for the ACPI WMAA method (e.g. %WMAA_METHOD_LEVEL or
>>>>> + *        %WMAA_METHOD_SOURCE)
>>>>> + * @mode: The operation to perform on the ACPI WMAA method (e.g. %WMAA_MODE_SET
>>>>> + *        or %WMAA_MODE_GET)
>>>>> + * @val:  Pointer to a value passed in by the caller when @mode is
>>>>> + *        %WMAA_MODE_SET, or a value passed out to the caller when @mode is
>>>>> + *        %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL.
>>>>> + *
>>>>> + * Returns 0 on success, or a negative error number on failure.
>>>>> + */
>>>>> +static int wmi_call_wmaa(struct wmi_device *w, enum wmaa_method id, enum wmaa_mode mode, u32 *val)
>>>>> +{
>>>>> +	struct wmaa_args args = {
>>>>> +		.mode = mode,
>>>>> +		.val = 0,
>>>>> +		.ret = 0,
>>>>> +	};
>>>>> +	struct acpi_buffer buf = { (acpi_size)sizeof(args), &args };
>>>>> +	acpi_status status;
>>>>> +
>>>>> +	if (id < WMAA_METHOD_LEVEL || id >= WMAA_METHOD_MAX ||
>>>>> +	    mode < WMAA_MODE_GET || mode >= WMAA_MODE_MAX)
>>>>> +		return -EINVAL;
>>>>> +
>>>>> +	if (mode == WMAA_MODE_SET)
>>>>> +		args.val = *val;
>>>>> +
>>>>> +	status = wmidev_evaluate_method(w, 0, id, &buf, &buf);
>>>>> +	if (ACPI_FAILURE(status)) {
>>>>> +		dev_err(&w->dev, "ACPI WMAA failed: %s\n",
>>>>> +			acpi_format_exception(status));
>>>>> +		return -EIO;
>>>>> +	}
>>>>> +
>>>>> +	if (mode != WMAA_MODE_SET)
>>>>> +		*val = args.ret;
>>>>> +
>>>>> +	return 0;
>>>>> +}
>>>>> +
>>>>> +static int wmaa_backlight_update_status(struct backlight_device *bd)
>>>>> +{
>>>>> +	struct wmi_device *wdev = bl_get_data(bd);
>>>>> +
>>>>> +	return wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_SET,
>>>>> +			     &bd->props.brightness);
>>>>> +}
>>>>> +
>>>>> +static int wmaa_backlight_get_brightness(struct backlight_device *bd)
>>>>> +{
>>>>> +	struct wmi_device *wdev = bl_get_data(bd);
>>>>> +	u32 level;
>>>>> +	int ret;
>>>>> +
>>>>> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET, &level);
>>>>> +	if (ret < 0)
>>>>> +		return ret;
>>>>> +
>>>>> +	return level;
>>>>> +}
>>>>> +
>>>>> +static const struct backlight_ops wmaa_backlight_ops = {
>>>>> +	.update_status = wmaa_backlight_update_status,
>>>>> +	.get_brightness = wmaa_backlight_get_brightness,
>>>>> +};
>>>>> +
>>>>> +static int wmaa_backlight_wmi_probe(struct wmi_device *wdev, const void *ctx)
>>>>> +{
>>>>> +	struct backlight_properties props = {};
>>>>> +	struct backlight_device *bdev;
>>>>> +	u32 source;
>>>>> +	int ret;
>>>>> +
>>>>> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_SOURCE, WMAA_MODE_GET, &source);
>>>>> +	if (ret)
>>>>> +		return ret;
>>>>> +
>>>>> +	/*
>>>>> +	 * This driver is only to be used when brightness control is handled
>>>>> +	 * by the EC; otherwise, the GPU driver(s) should control brightness.
>>>>> +	 */
>>>>> +	if (source != WMAA_SOURCE_EC)
>>>>> +		return -ENODEV;
>>>>> +
>>>>> +	/*
>>>>> +	 * Identify this backlight device as a firmware device so that it can
>>>>> +	 * be prioritized over any exposed GPU-driven raw device(s).
>>>>> +	 */
>>>>> +	props.type = BACKLIGHT_FIRMWARE;
>>>>> +
>>>>> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET_MAX_LEVEL,
>>>>> +			    &props.max_brightness);
>>>>> +	if (ret)
>>>>> +		return ret;
>>>>> +
>>>>> +	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET,
>>>>> +			    &props.brightness);
>>>>> +	if (ret)
>>>>> +		return ret;
>>>>> +
>>>>> +	bdev = devm_backlight_device_register(&wdev->dev, "wmaa_backlight",
>>>>> +					      &wdev->dev, wdev,
>>>>> +					      &wmaa_backlight_ops, &props);
>>>>> +	return PTR_ERR_OR_ZERO(bdev);
>>>>> +}
>>>>> +
>>>>> +#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
>>>>> +
>>>>> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
>>>>> +	{ .guid_string = WMAA_WMI_GUID },
>>>>> +	{ }
>>>>> +};
>>>>> +MODULE_DEVICE_TABLE(wmi, wmaa_backlight_wmi_id_table);
>>>>> +
>>>>> +static struct wmi_driver wmaa_backlight_wmi_driver = {
>>>>> +	.driver = {
>>>>> +		.name = "wmaa-backlight",
>>>>> +	},
>>>>> +	.probe = wmaa_backlight_wmi_probe,
>>>>> +	.id_table = wmaa_backlight_wmi_id_table,
>>>>> +};
>>>>> +module_wmi_driver(wmaa_backlight_wmi_driver);
>>>>> +
>>>>> +MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
>>>>> +MODULE_DESCRIPTION("WMAA Backlight WMI driver");
>>>>> +MODULE_LICENSE("GPL");
>>>>>

[-- Attachment #2: mof --]
[-- Type: text/plain, Size: 594 bytes --]

[WMI, Dynamic, Provider("WmiProv"), Locale("MS\\0x409"), Description("WMI Function"), guid("{603e9613-ef25-4338-a3d0-c46177516db7}")]
class WmiBrightnessNotify {
  [key, read] String InstanceName;
  [read] Boolean Active;

  [WmiMethodId(1), Implemented, read, write, Description("Get/Set EC brightness level status")] void NotifyBrightnessLevel([in] uint32 inArg, [in] uint32 Level, [out] uint32 Result);
  [WmiMethodId(2), Implemented, read, write, Description("Get/Set Display Brightness Source")] void NotifyBrightnessSource([in] uint32 inArg0, [in] uint32 inArg1, [out] uint32 Result);
};

Re: [PATCH v6] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Pali Rohár]

On Monday 20 September 2021 12:34:09 Daniel Dadap wrote:
> My apologies. I wasn't aware that WMAA was an autogenerated method name; I
> thought it was the name of the ACPI method and that the 603E9613... WMI GUID
> happened to wrap it. Given your explanation, I agree that the current name
> is inappropriate.
> 
> 
> > > So what would be a better name wmi-nvidia-backlight.ko I guess ?
> > > (and update the rest to match ?)
> > It looks like that no vendor driver starts with "wmi-" prefix. "-wmi"
> > string is used as a suffix. So for consistency it would be better to
> > choose "nvidia-backlight-wmi.ko".
> > 
> > But it would be a nice to know if this wmi "API" is nvidia specific or
> > not. Because it is possible that there is vendor C who this "API"
> > invented, is licensing it and nvidia was just first who started using
> > this "API" + send patch to kernel. Embedded Controller, including its
> > programming is done by laptop vendor, it is fully in laptop vendor
> > control and I do not think that nvidia sells laptops. So there is a high
> > chance that we will see laptops without any nvidia component (with e.g.
> > amd or intel graphics card) and with this "API" :)
> 
> 
> I will have to check about the origin of the "API" to be certain. My
> understanding is that this WMI backlight control scheme is part of NVIDIA
> design recommendations to notebook OEMs, with multiple OEMs potentially
> implementing it (I'm aware of at least two off the top of my head which
> already have systems in the wild). Specifically, this is meant to address an
> issue in hybrid systems with switchable graphics, by placing control of the
> backlight level with the EC rather than having to coordinate it between the
> different GPUs which might happen to be connected to the panel at any given
> time. It seems appropriate to me to include "nvidia" in the driver name for
> now; it could be renamed if it turns out non-NVIDIA designs use it as well.
> I don't have any specific information on whether or not that would be the
> case.

Ok! So lets stick with nvidia name for now.

> > Some information may be available in bmf / acpidump code. Also there can
> > be information if this GUID is just for backlight or if it can provide
> > also some other functionality.
> > 
> > So for now lets stick with nvidia and I guess later driver can be
> > renamed (if we find out that this "API" is used also on non-nvidia based
> > laptops).
> 
> 
> Okay, I'll send a follow-up patch to do the renaming once I get a little
> more clarification from someone who knows more about where the interface
> came from.
> 
> 
> > 
> > > > Anyway, could you provide BMF code for this wmi acpi functionality? In
> > > > BMF could be encoded more informations, including real, meaning human
> > > > readable name of this function. Not only internal (autogenerated) AA
> > > > identifier. BMF can be extracted from dumps created by 'acpidump' tool
> > > > or with new kernels directly from files 'find /sys/ -name bmof'.
> 
> 
> I've attached the output of your bmf2mof tool. Seems it's named
> "WmiBrightnessNotify", which isn't especially helpful.

I see... no (interesting) additional details.

Just one check, has bmf2mof showed some warning on stderr? I see
"instance" in class definition and bmf2mof does not support decompiling
MOF instances yet, it shows warning.

> [WMI, Dynamic, Provider("WmiProv"), Locale("MS\\0x409"), Description("WMI Function"), guid("{603e9613-ef25-4338-a3d0-c46177516db7}")]
> class WmiBrightnessNotify {
>   [key, read] String InstanceName;
>   [read] Boolean Active;
> 
>   [WmiMethodId(1), Implemented, read, write, Description("Get/Set EC brightness level status")] void NotifyBrightnessLevel([in] uint32 inArg, [in] uint32 Level, [out] uint32 Result);
>   [WmiMethodId(2), Implemented, read, write, Description("Get/Set Display Brightness Source")] void NotifyBrightnessSource([in] uint32 inArg0, [in] uint32 inArg1, [out] uint32 Result);
> };

Re: [PATCH v6] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

[-- Attachment #1: Type: text/plain, Size: 753 bytes --]

On 9/20/21 12:55 PM, Pali Rohár wrote:
> Just one check, has bmf2mof showed some warning on stderr? I see
> "instance" in class definition and bmf2mof does not support decompiling
> MOF instances yet, it shows warning.


None of bmf2mof, bmfdec, nor bmfparse print anything to stderr, and all 
exit with status 0 when I feed them the BMF data from this system. I am 
using bmfdec from your GitHub repository at 7f47b073... which is the 
current commit at the top of the master branch. I have attached the raw 
bmof dump in case it is of any use to you. This is from a commercially 
available system, so I don't believe there ought to be anything 
sensitive in there, as anybody who purchases the same system should be 
able to retrieve the same data.


[-- Attachment #2: bmof --]
[-- Type: application/octet-stream, Size: 893 bytes --]

Re: [PATCH v6] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Pali Rohár]

On Monday 20 September 2021 14:38:14 Daniel Dadap wrote:
> On 9/20/21 12:55 PM, Pali Rohár wrote:
> > Just one check, has bmf2mof showed some warning on stderr? I see
> > "instance" in class definition and bmf2mof does not support decompiling
> > MOF instances yet, it shows warning.
> 
> 
> None of bmf2mof, bmfdec, nor bmfparse print anything to stderr, and all exit
> with status 0 when I feed them the BMF data from this system. I am using
> bmfdec from your GitHub repository at 7f47b073... which is the current
> commit at the top of the master branch. I have attached the raw bmof dump in
> case it is of any use to you. This is from a commercially available system,
> so I don't believe there ought to be anything sensitive in there, as anybody
> who purchases the same system should be able to retrieve the same data.

Ok, seems that there is really nothing more. I run also just
decompression phase './bmfdec < /tmp/bmof | strings -el' to check.

That raw bmof binary should contain only compiled MOF code which has
corresponding 1:1 text variant, just my bmf2mof does not support
decompiling of all features and properties, specially instances yet.
There should not be anything secret. On windows system with right tool
(some WMI o WBEM browser) you should be able to view it. And moreover
access to it is available directly from userspace and no (nt kernel)
driver is required. So if vendor put there something sensitive it
already has some big problem and new vector for malware...

Re: [PATCH v6] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Hans de Goede]

Hi,

On 9/20/21 3:51 PM, Pali Rohár wrote:
> On Monday 20 September 2021 15:33:20 Hans de Goede wrote:
>> Hi Pali,
>>
>> On 9/20/21 3:29 PM, Pali Rohár wrote:
>>> On Monday 13 September 2021 11:01:50 Hans de Goede wrote:
>>>> Hi,
>>>>
>>>> On 9/3/21 2:38 AM, Daniel Dadap wrote:
>>>>> A number of upcoming notebook computer designs drive the internal
>>>>> display panel's backlight PWM through the Embedded Controller (EC).
>>>>> This EC-based backlight control can be plumbed through to an ACPI
>>>>> "WMAA" method interface, which in turn can be wrapped by WMI with
>>>>> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
>>>>>
>>>>> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
>>>>> backlight class driver to control backlight levels on systems with
>>>>> EC-driven backlights.
>>>>>
>>>>> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
>>>>> Reviewed-By: Thomas Weißschuh <linux@weissschuh.net>
>>>>
>>>> Thank you for your patch, I've applied this patch to my review-hans 
>>>> branch:
>>>> https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=review-hans
>>>>
>>>> Note it will show up in my review-hans branch once I've pushed my
>>>> local branch there, which might take a while.
>>>>
>>>> Once I've run some tests on this branch the patches there will be
>>>> added to the platform-drivers-x86/for-next branch and eventually
>>>> will be included in the pdx86 pull-request to Linus for the next
>>>> merge-window.
>>>
>>> Hello Hans!
>>>
>>> I would suggest to rename this driver and config option to not include
>>> -AA in its name. WMAA is just internal name of ACPI method, composed
>>> from two parts: "WM" and "AA". Second part "AA" is read from the _WDG
>>> where is the translation table from WMI GUID (in this case 603E9613...)
>>> to ACPI method name. "AA" is just autogenerated identifier by wmi
>>> compiler and because names are ASCII strings, I guess "AA" could mean
>>> the first (autogenerated) method. In the whole driver code you are not
>>> using AA function name, but directly WMI GUID, which also means that
>>> driver is prepared if vendor "recompiles" wmi code in acpi (and compiler
>>> generates another identifier, not AA). Also another argument is that
>>> there can be lot of other laptops which have WMAA ACPI method but they
>>> can have different API or do something totally different. So name WMAA
>>> is in this wmi context very misleading. Rather it should be named by
>>> vendor.
>>
>> Right, that is a very valid point. I should have spotted this myself.
>>
>> So what would be a better name wmi-nvidia-backlight.ko I guess ?
>> (and update the rest to match ?)
> 
> It looks like that no vendor driver starts with "wmi-" prefix. "-wmi"
> string is used as a suffix. So for consistency it would be better to
> choose "nvidia-backlight-wmi.ko".

Right, I should have checked first.

So I just checked and the standard pattern used is:
vendor_wmi_feature

So lets go with nvidia_wmi_backlight.ko

Daniel, can you prepare a patch on top of your merged patch to do
the rename of the Kconfig entry and the module-name please?

Regards,

Hans

Re: [PATCH v6] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Pali Rohár]

On Tuesday 21 September 2021 15:53:29 Hans de Goede wrote:
> Hi,
> 
> On 9/20/21 3:51 PM, Pali Rohár wrote:
> > It looks like that no vendor driver starts with "wmi-" prefix. "-wmi"
> > string is used as a suffix. So for consistency it would be better to
> > choose "nvidia-backlight-wmi.ko".
> 
> Right, I should have checked first.
> 
> So I just checked and the standard pattern used is:
> vendor_wmi_feature
> 
> So lets go with nvidia_wmi_backlight.ko

Just source code filenames use hyphen (-) not underscore (_).

> Daniel, can you prepare a patch on top of your merged patch to do
> the rename of the Kconfig entry and the module-name please?
> 
> Regards,
> 
> Hans
> 

Re: [PATCH v6] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

> On Sep 21, 2021, at 08:53, Hans de Goede <hdegoede@redhat.com> wrote:
> 
> Hi,
> 
>> On 9/20/21 3:51 PM, Pali Rohár wrote:
>>> On Monday 20 September 2021 15:33:20 Hans de Goede wrote:
>>> Hi Pali,
>>> 
>>> On 9/20/21 3:29 PM, Pali Rohár wrote:
>>>> On Monday 13 September 2021 11:01:50 Hans de Goede wrote:
>>>>> Hi,
>>>>> 
>>>>> On 9/3/21 2:38 AM, Daniel Dadap wrote:
>>>>>> A number of upcoming notebook computer designs drive the internal
>>>>>> display panel's backlight PWM through the Embedded Controller (EC).
>>>>>> This EC-based backlight control can be plumbed through to an ACPI
>>>>>> "WMAA" method interface, which in turn can be wrapped by WMI with
>>>>>> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
>>>>>> 
>>>>>> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
>>>>>> backlight class driver to control backlight levels on systems with
>>>>>> EC-driven backlights.
>>>>>> 
>>>>>> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
>>>>>> Reviewed-By: Thomas Weißschuh <linux@weissschuh.net>
>>>>> 
>>>>> Thank you for your patch, I've applied this patch to my review-hans 
>>>>> branch:
>>>>> https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=review-hans
>>>>> 
>>>>> Note it will show up in my review-hans branch once I've pushed my
>>>>> local branch there, which might take a while.
>>>>> 
>>>>> Once I've run some tests on this branch the patches there will be
>>>>> added to the platform-drivers-x86/for-next branch and eventually
>>>>> will be included in the pdx86 pull-request to Linus for the next
>>>>> merge-window.
>>>> 
>>>> Hello Hans!
>>>> 
>>>> I would suggest to rename this driver and config option to not include
>>>> -AA in its name. WMAA is just internal name of ACPI method, composed
>>>> from two parts: "WM" and "AA". Second part "AA" is read from the _WDG
>>>> where is the translation table from WMI GUID (in this case 603E9613...)
>>>> to ACPI method name. "AA" is just autogenerated identifier by wmi
>>>> compiler and because names are ASCII strings, I guess "AA" could mean
>>>> the first (autogenerated) method. In the whole driver code you are not
>>>> using AA function name, but directly WMI GUID, which also means that
>>>> driver is prepared if vendor "recompiles" wmi code in acpi (and compiler
>>>> generates another identifier, not AA). Also another argument is that
>>>> there can be lot of other laptops which have WMAA ACPI method but they
>>>> can have different API or do something totally different. So name WMAA
>>>> is in this wmi context very misleading. Rather it should be named by
>>>> vendor.
>>> 
>>> Right, that is a very valid point. I should have spotted this myself.
>>> 
>>> So what would be a better name wmi-nvidia-backlight.ko I guess ?
>>> (and update the rest to match ?)
>> 
>> It looks like that no vendor driver starts with "wmi-" prefix. "-wmi"
>> string is used as a suffix. So for consistency it would be better to
>> choose "nvidia-backlight-wmi.ko".
> 
> Right, I should have checked first.
> 
> So I just checked and the standard pattern used is:
> vendor_wmi_feature
> 
> So lets go with nvidia_wmi_backlight.ko
> 
> Daniel, can you prepare a patch on top of your merged patch to do
> the rename of the Kconfig entry and the module-name please?
> 

Yes, I already had a patch prepared to rename things to nvidia-backlight-wmi; I am waiting to hear back from some folks if there’s a more specific name that might be appropriate (e.g. a name of a particular feature tied to this) or if it should be more generic (e.g., if there is a strong possibility this design may be used in systems with no NVIDIA GPU); while I’m waiting for those answers, I’ll switch to nvidia-wmi-backlight as the assumed option, if there isn’t something more appropriate.

> Regards,
> 
> Hans
> 

Re: [PATCH v6] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Hans de Goede]

Hi,

On 9/21/21 4:29 PM, Daniel Dadap wrote:
> 
>> On Sep 21, 2021, at 08:53, Hans de Goede <hdegoede@redhat.com> wrote:
>>
>> Hi,
>>
>>> On 9/20/21 3:51 PM, Pali Rohár wrote:
>>>> On Monday 20 September 2021 15:33:20 Hans de Goede wrote:
>>>> Hi Pali,
>>>>
>>>> On 9/20/21 3:29 PM, Pali Rohár wrote:
>>>>> On Monday 13 September 2021 11:01:50 Hans de Goede wrote:
>>>>>> Hi,
>>>>>>
>>>>>> On 9/3/21 2:38 AM, Daniel Dadap wrote:
>>>>>>> A number of upcoming notebook computer designs drive the internal
>>>>>>> display panel's backlight PWM through the Embedded Controller (EC).
>>>>>>> This EC-based backlight control can be plumbed through to an ACPI
>>>>>>> "WMAA" method interface, which in turn can be wrapped by WMI with
>>>>>>> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
>>>>>>>
>>>>>>> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
>>>>>>> backlight class driver to control backlight levels on systems with
>>>>>>> EC-driven backlights.
>>>>>>>
>>>>>>> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
>>>>>>> Reviewed-By: Thomas Weißschuh <linux@weissschuh.net>
>>>>>>
>>>>>> Thank you for your patch, I've applied this patch to my review-hans 
>>>>>> branch:
>>>>>> https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=review-hans
>>>>>>
>>>>>> Note it will show up in my review-hans branch once I've pushed my
>>>>>> local branch there, which might take a while.
>>>>>>
>>>>>> Once I've run some tests on this branch the patches there will be
>>>>>> added to the platform-drivers-x86/for-next branch and eventually
>>>>>> will be included in the pdx86 pull-request to Linus for the next
>>>>>> merge-window.
>>>>>
>>>>> Hello Hans!
>>>>>
>>>>> I would suggest to rename this driver and config option to not include
>>>>> -AA in its name. WMAA is just internal name of ACPI method, composed
>>>>> from two parts: "WM" and "AA". Second part "AA" is read from the _WDG
>>>>> where is the translation table from WMI GUID (in this case 603E9613...)
>>>>> to ACPI method name. "AA" is just autogenerated identifier by wmi
>>>>> compiler and because names are ASCII strings, I guess "AA" could mean
>>>>> the first (autogenerated) method. In the whole driver code you are not
>>>>> using AA function name, but directly WMI GUID, which also means that
>>>>> driver is prepared if vendor "recompiles" wmi code in acpi (and compiler
>>>>> generates another identifier, not AA). Also another argument is that
>>>>> there can be lot of other laptops which have WMAA ACPI method but they
>>>>> can have different API or do something totally different. So name WMAA
>>>>> is in this wmi context very misleading. Rather it should be named by
>>>>> vendor.
>>>>
>>>> Right, that is a very valid point. I should have spotted this myself.
>>>>
>>>> So what would be a better name wmi-nvidia-backlight.ko I guess ?
>>>> (and update the rest to match ?)
>>>
>>> It looks like that no vendor driver starts with "wmi-" prefix. "-wmi"
>>> string is used as a suffix. So for consistency it would be better to
>>> choose "nvidia-backlight-wmi.ko".
>>
>> Right, I should have checked first.
>>
>> So I just checked and the standard pattern used is:
>> vendor_wmi_feature
>>
>> So lets go with nvidia_wmi_backlight.ko
>>
>> Daniel, can you prepare a patch on top of your merged patch to do
>> the rename of the Kconfig entry and the module-name please?
>>
> 
> Yes, I already had a patch prepared to rename things to nvidia-backlight-wmi; I am waiting to hear back from some folks if there’s a more specific name that might be appropriate (e.g. a name of a particular feature tied to this) or if it should be more generic (e.g., if there is a strong possibility this design may be used in systems with no NVIDIA GPU); while I’m waiting for those answers, I’ll switch to nvidia-wmi-backlight as the assumed option, if there isn’t something more appropriate.

Ok, sounds good, thank you.

Regards,

Hans

[PATCH 1/2] platform/x86: Remove "WMAA" from identifier names in wmaa-backlight-wmi.c

[Daniel Dadap]

The "wmaa" in the name of the wmaa-backlight-wmi driver was named after
the ACPI method handle for EC-based backlight control on the systems
this driver was tested on during development. However, this "WMAA"
handle is generated by the WMI compilation process, and isn't actually
a part of the backlight control mechanism which this driver supports.
Since the "WMAA" handle isn't actually a part of the firmware backlight
interface, the various identifiers in this driver using "WMAA" or
"wmaa" aren't actually appropriate.

As a common denominator across the systems supported by this driver is
that they are hybrid graphics systems with NVIDIA GPUs, using "nvidia"
in the driver name seems more appropriate than "wmaa". Update the
driver to remove "wmaa" and "WMAA" in identifier names where they
appear. The kerneldoc comments for the enum wmi_brightness_method
values are replaced with the verbatim text from the decompiled BMF code
for this WMI class.

Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
---
 drivers/platform/x86/wmaa-backlight-wmi.c | 174 +++++++++++-----------
 1 file changed, 91 insertions(+), 83 deletions(-)

diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
index f5c4f8337c2c..61e37194df70 100644
--- a/drivers/platform/x86/wmaa-backlight-wmi.c
+++ b/drivers/platform/x86/wmaa-backlight-wmi.c
@@ -11,63 +11,64 @@
 #include <linux/wmi.h>
 
 /**
- * enum wmaa_method - WMI method IDs for ACPI WMAA
- * @WMAA_METHOD_LEVEL:  Get or set the brightness level,
- *                      or get the maximum brightness level.
- * @WMAA_METHOD_SOURCE: Get the source for backlight control.
+ * enum wmi_brightness_method - WMI method IDs
+ * @WMI_BRIGHTNESS_METHOD_LEVEL:  Get/Set EC brightness level status
+ * @WMI_BRIGHTNESS_METHOD_SOURCE: Get/Set EC Brightness Source
  */
-enum wmaa_method {
-	WMAA_METHOD_LEVEL = 1,
-	WMAA_METHOD_SOURCE = 2,
-	WMAA_METHOD_MAX
+enum wmi_brightness_method {
+	WMI_BRIGHTNESS_METHOD_LEVEL = 1,
+	WMI_BRIGHTNESS_METHOD_SOURCE = 2,
+	WMI_BRIGHTNESS_METHOD_MAX
 };
 
 /**
- * enum wmaa_mode - Operation mode for ACPI WMAA method
- * @WMAA_MODE_GET:           Get the current brightness level or source.
- * @WMAA_MODE_SET:           Set the brightness level.
- * @WMAA_MODE_GET_MAX_LEVEL: Get the maximum brightness level. This is only
- *                           valid when the WMI method is %WMAA_METHOD_LEVEL.
+ * enum wmi_brightness_mode - Operation mode for WMI-wrapped method
+ * @WMI_BRIGHTNESS_MODE_GET:            Get the current brightness level/source.
+ * @WMI_BRIGHTNESS_MODE_SET:            Set the brightness level.
+ * @WMI_BRIGHTNESS_MODE_GET_MAX_LEVEL:  Get the maximum brightness level. This
+ *                                      is only valid when the WMI method is
+ *                                      %WMI_BRIGHTNESS_METHOD_LEVEL.
  */
-enum wmaa_mode {
-	WMAA_MODE_GET = 0,
-	WMAA_MODE_SET = 1,
-	WMAA_MODE_GET_MAX_LEVEL = 2,
-	WMAA_MODE_MAX
+enum wmi_brightness_mode {
+	WMI_BRIGHTNESS_MODE_GET = 0,
+	WMI_BRIGHTNESS_MODE_SET = 1,
+	WMI_BRIGHTNESS_MODE_GET_MAX_LEVEL = 2,
+	WMI_BRIGHTNESS_MODE_MAX
 };
 
 /**
- * enum wmaa_source - Backlight brightness control source identification
- * @WMAA_SOURCE_GPU:   Backlight brightness is controlled by the GPU.
- * @WMAA_SOURCE_EC:    Backlight brightness is controlled by the system's
- *                     Embedded Controller (EC).
- * @WMAA_SOURCE_AUX:   Backlight brightness is controlled over the DisplayPort
- *                     AUX channel.
+ * enum wmi_brightness_source - Backlight brightness control source selection
+ * @WMI_BRIGHTNESS_SOURCE_GPU: Backlight brightness is controlled by the GPU.
+ * @WMI_BRIGHTNESS_SOURCE_EC:  Backlight brightness is controlled by the
+ *                             system's Embedded Controller (EC).
+ * @WMI_BRIGHTNESS_SOURCE_AUX: Backlight brightness is controlled over the
+ *                             DisplayPort AUX channel.
  */
-enum wmaa_source {
-	WMAA_SOURCE_GPU = 1,
-	WMAA_SOURCE_EC = 2,
-	WMAA_SOURCE_AUX = 3,
-	WMAA_SOURCE_MAX
+enum wmi_brightness_source {
+	WMI_BRIGHTNESS_SOURCE_GPU = 1,
+	WMI_BRIGHTNESS_SOURCE_EC = 2,
+	WMI_BRIGHTNESS_SOURCE_AUX = 3,
+	WMI_BRIGHTNESS_SOURCE_MAX
 };
 
 /**
- * struct wmaa_args - arguments for the ACPI WMAA method
- * @mode:    Pass in an &enum wmaa_mode value to select between getting or
- *           setting a value.
- * @val:     In parameter for value to set when operating in %WMAA_MODE_SET
- *           mode. Not used in %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode.
+ * struct wmi_brightness_args - arguments for the WMI-wrapped ACPI method
+ * @mode:    Pass in an &enum wmi_brightness_mode value to select between
+ *           getting or setting a value.
+ * @val:     In parameter for value to set when using %WMI_BRIGHTNESS_MODE_SET
+ *           mode. Not used in conjunction with %WMI_BRIGHTNESS_MODE_GET or
+ *           %WMI_BRIGHTNESS_MODE_GET_MAX_LEVEL mode.
  * @ret:     Out parameter returning retrieved value when operating in
- *           %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode. Not used in
- *           %WMAA_MODE_SET mode.
+ *           %WMI_BRIGHTNESS_MODE_GET or %WMI_BRIGHTNESS_MODE_GET_MAX_LEVEL
+ *           mode. Not used in %WMI_BRIGHTNESS_MODE_SET mode.
  * @ignored: Padding; not used. The ACPI method expects a 24 byte params struct.
  *
- * This is the parameters structure for the ACPI WMAA method as wrapped by WMI.
- * The value passed in to @val or returned by @ret will be a brightness value
- * when the WMI method ID is %WMAA_METHOD_LEVEL, or an &enum wmaa_source value
- * when the WMI method ID is %WMAA_METHOD_SOURCE.
+ * This is the parameters structure for the WmiBrightnessNotify ACPI method as
+ * wrapped by WMI. The value passed in to @val or returned by @ret will be a
+ * brightness value when the WMI method ID is %WMI_BRIGHTNESS_METHOD_LEVEL, or
+ * an &enum wmi_brightness_source value with %WMI_BRIGHTNESS_METHOD_SOURCE.
  */
-struct wmaa_args {
+struct wmi_brightness_args {
 	u32 mode;
 	u32 val;
 	u32 ret;
@@ -75,21 +76,21 @@ struct wmaa_args {
 };
 
 /**
- * wmi_call_wmaa() - helper function for calling ACPI WMAA via its WMI wrapper
- * @w:    Pointer to the struct wmi_device identified by %WMAA_WMI_GUID
- * @id:   The method ID for the ACPI WMAA method (e.g. %WMAA_METHOD_LEVEL or
- *        %WMAA_METHOD_SOURCE)
- * @mode: The operation to perform on the ACPI WMAA method (e.g. %WMAA_MODE_SET
- *        or %WMAA_MODE_GET)
+ * wmi_brightness_notify() - helper function for calling WMI-wrapped ACPI method
+ * @w:    Pointer to the struct wmi_device identified by %WMI_BRIGHTNESS_GUID
+ * @id:   The WMI method ID to call (e.g. %WMI_BRIGHTNESS_METHOD_LEVEL or
+ *        %WMI_BRIGHTNESS_METHOD_SOURCE)
+ * @mode: The operation to perform on the method (e.g. %WMI_BRIGHTNESS_MODE_SET
+ *        or %WMI_BRIGHTNESS_MODE_GET)
  * @val:  Pointer to a value passed in by the caller when @mode is
- *        %WMAA_MODE_SET, or a value passed out to the caller when @mode is
- *        %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL.
+ *        %WMI_BRIGHTNESS_MODE_SET, or a value passed out to caller when @mode
+ *        is %WMI_BRIGHTNESS_MODE_GET or %WMI_BRIGHTNESS_MODE_GET_MAX_LEVEL.
  *
  * Returns 0 on success, or a negative error number on failure.
  */
-static int wmi_call_wmaa(struct wmi_device *w, enum wmaa_method id, enum wmaa_mode mode, u32 *val)
+static int wmi_brightness_notify(struct wmi_device *w, enum wmi_brightness_method id, enum wmi_brightness_mode mode, u32 *val)
 {
-	struct wmaa_args args = {
+	struct wmi_brightness_args args = {
 		.mode = mode,
 		.val = 0,
 		.ret = 0,
@@ -97,60 +98,64 @@ static int wmi_call_wmaa(struct wmi_device *w, enum wmaa_method id, enum wmaa_mo
 	struct acpi_buffer buf = { (acpi_size)sizeof(args), &args };
 	acpi_status status;
 
-	if (id < WMAA_METHOD_LEVEL || id >= WMAA_METHOD_MAX ||
-	    mode < WMAA_MODE_GET || mode >= WMAA_MODE_MAX)
+	if (id < WMI_BRIGHTNESS_METHOD_LEVEL ||
+	    id >= WMI_BRIGHTNESS_METHOD_MAX ||
+	    mode < WMI_BRIGHTNESS_MODE_GET || mode >= WMI_BRIGHTNESS_MODE_MAX)
 		return -EINVAL;
 
-	if (mode == WMAA_MODE_SET)
+	if (mode == WMI_BRIGHTNESS_MODE_SET)
 		args.val = *val;
 
 	status = wmidev_evaluate_method(w, 0, id, &buf, &buf);
 	if (ACPI_FAILURE(status)) {
-		dev_err(&w->dev, "ACPI WMAA failed: %s\n",
+		dev_err(&w->dev, "EC backlight control failed: %s\n",
 			acpi_format_exception(status));
 		return -EIO;
 	}
 
-	if (mode != WMAA_MODE_SET)
+	if (mode != WMI_BRIGHTNESS_MODE_SET)
 		*val = args.ret;
 
 	return 0;
 }
 
-static int wmaa_backlight_update_status(struct backlight_device *bd)
+static int nvidia_wmi_ec_backlight_update_status(struct backlight_device *bd)
 {
 	struct wmi_device *wdev = bl_get_data(bd);
 
-	return wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_SET,
-			     &bd->props.brightness);
+	return wmi_brightness_notify(wdev, WMI_BRIGHTNESS_METHOD_LEVEL,
+	                             WMI_BRIGHTNESS_MODE_SET,
+			             &bd->props.brightness);
 }
 
-static int wmaa_backlight_get_brightness(struct backlight_device *bd)
+static int nvidia_wmi_ec_backlight_get_brightness(struct backlight_device *bd)
 {
 	struct wmi_device *wdev = bl_get_data(bd);
 	u32 level;
 	int ret;
 
-	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET, &level);
+	ret = wmi_brightness_notify(wdev, WMI_BRIGHTNESS_METHOD_LEVEL,
+	                            WMI_BRIGHTNESS_MODE_GET, &level);
 	if (ret < 0)
 		return ret;
 
 	return level;
 }
 
-static const struct backlight_ops wmaa_backlight_ops = {
-	.update_status = wmaa_backlight_update_status,
-	.get_brightness = wmaa_backlight_get_brightness,
+static const struct backlight_ops nvidia_wmi_ec_backlight_ops = {
+	.update_status = nvidia_wmi_ec_backlight_update_status,
+	.get_brightness = nvidia_wmi_ec_backlight_get_brightness,
 };
 
-static int wmaa_backlight_wmi_probe(struct wmi_device *wdev, const void *ctx)
+static int nvidia_wmi_ec_backlight_probe(struct wmi_device *wdev, const void *ctx)
 {
 	struct backlight_properties props = {};
 	struct backlight_device *bdev;
 	u32 source;
 	int ret;
 
-	ret = wmi_call_wmaa(wdev, WMAA_METHOD_SOURCE, WMAA_MODE_GET, &source);
+	ret = wmi_brightness_notify(wdev, WMI_BRIGHTNESS_METHOD_SOURCE,
+	                           WMI_BRIGHTNESS_MODE_GET, &source);
 	if (ret)
 		return ret;
 
@@ -158,7 +163,7 @@ static int wmaa_backlight_wmi_probe(struct wmi_device *wdev, const void *ctx)
 	 * This driver is only to be used when brightness control is handled
 	 * by the EC; otherwise, the GPU driver(s) should control brightness.
 	 */
-	if (source != WMAA_SOURCE_EC)
+	if (source != WMI_BRIGHTNESS_SOURCE_EC)
 		return -ENODEV;
 
 	/*
@@ -167,39 +172,42 @@ static int wmaa_backlight_wmi_probe(struct wmi_device *wdev, const void *ctx)
 	 */
 	props.type = BACKLIGHT_FIRMWARE;
 
-	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET_MAX_LEVEL,
-			    &props.max_brightness);
+	ret = wmi_brightness_notify(wdev, WMI_BRIGHTNESS_METHOD_LEVEL,
+	                           WMI_BRIGHTNESS_MODE_GET_MAX_LEVEL,
+	                           &props.max_brightness);
 	if (ret)
 		return ret;
 
-	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET,
-			    &props.brightness);
+	ret = wmi_brightness_notify(wdev, WMI_BRIGHTNESS_METHOD_LEVEL,
+	                           WMI_BRIGHTNESS_MODE_GET, &props.brightness);
 	if (ret)
 		return ret;
 
-	bdev = devm_backlight_device_register(&wdev->dev, "wmaa_backlight",
+	bdev = devm_backlight_device_register(&wdev->dev,
+	                                      "nvidia_wmi_ec_backlight",
 					      &wdev->dev, wdev,
-					      &wmaa_backlight_ops, &props);
+					      &nvidia_wmi_ec_backlight_ops,
+					      &props);
 	return PTR_ERR_OR_ZERO(bdev);
 }
 
-#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
+#define WMI_BRIGHTNESS_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
 
-static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
-	{ .guid_string = WMAA_WMI_GUID },
+static const struct wmi_device_id nvidia_wmi_ec_backlight_id_table[] = {
+	{ .guid_string = WMI_BRIGHTNESS_GUID },
 	{ }
 };
-MODULE_DEVICE_TABLE(wmi, wmaa_backlight_wmi_id_table);
+MODULE_DEVICE_TABLE(wmi, nvidia_wmi_ec_backlight_id_table);
 
-static struct wmi_driver wmaa_backlight_wmi_driver = {
+static struct wmi_driver nvidia_wmi_ec_backlight_driver = {
 	.driver = {
-		.name = "wmaa-backlight",
+		.name = "nvidia-wmi-ec-backlight",
 	},
-	.probe = wmaa_backlight_wmi_probe,
-	.id_table = wmaa_backlight_wmi_id_table,
+	.probe = nvidia_wmi_ec_backlight_probe,
+	.id_table = nvidia_wmi_ec_backlight_id_table,
 };
-module_wmi_driver(wmaa_backlight_wmi_driver);
+module_wmi_driver(nvidia_wmi_ec_backlight_driver);
 
 MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
-MODULE_DESCRIPTION("WMAA Backlight WMI driver");
+MODULE_DESCRIPTION("NVIDIA WMI EC Backlight driver");
 MODULE_LICENSE("GPL");
-- 
2.20.1

[PATCH 2/2] platform/x86: Rename wmaa-backlight-wmi to nvidia-wmi-ec-backlight

[Daniel Dadap]

Rename the wmaa-backlight-wmi driver and associated KConfig option to
remove the remaining references to the "WMAA" ACPI handle which was
used in the previous name. The driver has already been updated to
remove internal references to "WMAA". As part of the renaming, the
components in the name have been rearranged to reflect the standard
vendor_wmi_feature pattern.

Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
---
 MAINTAINERS                                       | 12 ++++++------
 drivers/platform/x86/Kconfig                      | 15 +++++++--------
 drivers/platform/x86/Makefile                     |  2 +-
 ...-backlight-wmi.c => nvidia-wmi-ec-backlight.c} |  0
 4 files changed, 14 insertions(+), 15 deletions(-)
 rename drivers/platform/x86/{wmaa-backlight-wmi.c => nvidia-wmi-ec-backlight.c} (100%)

diff --git a/MAINTAINERS b/MAINTAINERS
index 2b990794ec35..eb2d54b36ab3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -13423,6 +13423,12 @@ S:	Maintained
 F:	drivers/video/fbdev/nvidia/
 F:	drivers/video/fbdev/riva/
 
+NVIDIA WMI EC BACKLIGHT DRIVER
+M:	Daniel Dadap <ddadap@nvidia.com>
+L:	platform-driver-x86@vger.kernel.org
+S:	Supported
+F:	drivers/platform/x86/nvidia-wmi-ec-backlight.c
+
 NVM EXPRESS DRIVER
 M:	Keith Busch <kbusch@kernel.org>
 M:	Jens Axboe <axboe@fb.com>
@@ -20302,12 +20308,6 @@ L:	linux-wireless@vger.kernel.org
 S:	Odd fixes
 F:	drivers/net/wireless/wl3501*
 
-WMAA BACKLIGHT DRIVER
-M:	Daniel Dadap <ddadap@nvidia.com>
-L:	platform-driver-x86@vger.kernel.org
-S:	Supported
-F:	drivers/platform/x86/wmaa-backlight-wmi.c
-
 WOLFSON MICROELECTRONICS DRIVERS
 L:	patches@opensource.cirrus.com
 S:	Supported
diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
index f3dbb0273884..520da0a6acd1 100644
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -91,21 +91,20 @@ config PEAQ_WMI
 	help
 	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
 
-config WMAA_BACKLIGHT_WMI
-	tristate "ACPI WMAA Backlight Driver"
+config NVIDIA_WMI_EC_BACKLIGHT
+	tristate "EC Backlight Driver for Hybrid Graphics Notebook Systems"
 	depends on ACPI_WMI
 	depends on BACKLIGHT_CLASS_DEVICE
 	help
-	  This driver provides a sysfs backlight interface for notebook
-	  systems which expose the WMAA ACPI method and an associated WMI
-	  wrapper to drive LCD backlight levels through the Embedded Controller
-	  (EC).
+	  This driver provides a sysfs backlight interface for notebook systems
+	  which are equipped with NVIDIA hybrid graphics and drive LCD backlight
+	  levels through the Embedded Controller (EC).
 
 	  Say Y or M here if you want to control the backlight on a notebook
-	  system with an EC-driven backlight using the ACPI WMAA method.
+	  system with an EC-driven backlight.
 
 	  If you choose to compile this driver as a module the module will be
-	  called wmaa-backlight-wmi.
+	  called nvidia-wmi-ec-backlight.
 
 config XIAOMI_WMI
 	tristate "Xiaomi WMI key driver"
diff --git a/drivers/platform/x86/Makefile b/drivers/platform/x86/Makefile
index edde481c14ad..0d046ed70da1 100644
--- a/drivers/platform/x86/Makefile
+++ b/drivers/platform/x86/Makefile
@@ -11,8 +11,8 @@ obj-$(CONFIG_WMI_BMOF)		+= wmi-bmof.o
 # WMI drivers
 obj-$(CONFIG_HUAWEI_WMI)		+= huawei-wmi.o
 obj-$(CONFIG_MXM_WMI)			+= mxm-wmi.o
+obj-$(CONFIG_NVIDIA_WMI_EC_BACKLIGHT)	+= nvidia-wmi-ec-backlight.o
 obj-$(CONFIG_PEAQ_WMI)			+= peaq-wmi.o
-obj-$(CONFIG_WMAA_BACKLIGHT_WMI)	+= wmaa-backlight-wmi.o
 obj-$(CONFIG_XIAOMI_WMI)		+= xiaomi-wmi.o
 obj-$(CONFIG_GIGABYTE_WMI)		+= gigabyte-wmi.o
 
diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/nvidia-wmi-ec-backlight.c
similarity index 100%
rename from drivers/platform/x86/wmaa-backlight-wmi.c
rename to drivers/platform/x86/nvidia-wmi-ec-backlight.c
-- 
2.20.1

Re: [PATCH 1/2] platform/x86: Remove "WMAA" from identifier names in wmaa-backlight-wmi.c

[Hans de Goede]

Hi,

On 9/27/21 10:23 PM, Daniel Dadap wrote:
> The "wmaa" in the name of the wmaa-backlight-wmi driver was named after
> the ACPI method handle for EC-based backlight control on the systems
> this driver was tested on during development. However, this "WMAA"
> handle is generated by the WMI compilation process, and isn't actually
> a part of the backlight control mechanism which this driver supports.
> Since the "WMAA" handle isn't actually a part of the firmware backlight
> interface, the various identifiers in this driver using "WMAA" or
> "wmaa" aren't actually appropriate.
> 
> As a common denominator across the systems supported by this driver is
> that they are hybrid graphics systems with NVIDIA GPUs, using "nvidia"
> in the driver name seems more appropriate than "wmaa". Update the
> driver to remove "wmaa" and "WMAA" in identifier names where they
> appear. The kerneldoc comments for the enum wmi_brightness_method
> values are replaced with the verbatim text from the decompiled BMF code
> for this WMI class.
> 
> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>

Thank you for your patch-series, I've applied the series to my
review-hans branch:
https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=review-hans

Note it will show up in my review-hans branch once I've pushed my
local branch there, which might take a while.

Once I've run some tests on this branch the patches there will be
added to the platform-drivers-x86/for-next branch and eventually
will be included in the pdx86 pull-request to Linus for the next
merge-window.

Regards,

Hans


> ---
>  drivers/platform/x86/wmaa-backlight-wmi.c | 174 +++++++++++-----------
>  1 file changed, 91 insertions(+), 83 deletions(-)
> 
> diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
> index f5c4f8337c2c..61e37194df70 100644
> --- a/drivers/platform/x86/wmaa-backlight-wmi.c
> +++ b/drivers/platform/x86/wmaa-backlight-wmi.c
> @@ -11,63 +11,64 @@
>  #include <linux/wmi.h>
>  
>  /**
> - * enum wmaa_method - WMI method IDs for ACPI WMAA
> - * @WMAA_METHOD_LEVEL:  Get or set the brightness level,
> - *                      or get the maximum brightness level.
> - * @WMAA_METHOD_SOURCE: Get the source for backlight control.
> + * enum wmi_brightness_method - WMI method IDs
> + * @WMI_BRIGHTNESS_METHOD_LEVEL:  Get/Set EC brightness level status
> + * @WMI_BRIGHTNESS_METHOD_SOURCE: Get/Set EC Brightness Source
>   */
> -enum wmaa_method {
> -	WMAA_METHOD_LEVEL = 1,
> -	WMAA_METHOD_SOURCE = 2,
> -	WMAA_METHOD_MAX
> +enum wmi_brightness_method {
> +	WMI_BRIGHTNESS_METHOD_LEVEL = 1,
> +	WMI_BRIGHTNESS_METHOD_SOURCE = 2,
> +	WMI_BRIGHTNESS_METHOD_MAX
>  };
>  
>  /**
> - * enum wmaa_mode - Operation mode for ACPI WMAA method
> - * @WMAA_MODE_GET:           Get the current brightness level or source.
> - * @WMAA_MODE_SET:           Set the brightness level.
> - * @WMAA_MODE_GET_MAX_LEVEL: Get the maximum brightness level. This is only
> - *                           valid when the WMI method is %WMAA_METHOD_LEVEL.
> + * enum wmi_brightness_mode - Operation mode for WMI-wrapped method
> + * @WMI_BRIGHTNESS_MODE_GET:            Get the current brightness level/source.
> + * @WMI_BRIGHTNESS_MODE_SET:            Set the brightness level.
> + * @WMI_BRIGHTNESS_MODE_GET_MAX_LEVEL:  Get the maximum brightness level. This
> + *                                      is only valid when the WMI method is
> + *                                      %WMI_BRIGHTNESS_METHOD_LEVEL.
>   */
> -enum wmaa_mode {
> -	WMAA_MODE_GET = 0,
> -	WMAA_MODE_SET = 1,
> -	WMAA_MODE_GET_MAX_LEVEL = 2,
> -	WMAA_MODE_MAX
> +enum wmi_brightness_mode {
> +	WMI_BRIGHTNESS_MODE_GET = 0,
> +	WMI_BRIGHTNESS_MODE_SET = 1,
> +	WMI_BRIGHTNESS_MODE_GET_MAX_LEVEL = 2,
> +	WMI_BRIGHTNESS_MODE_MAX
>  };
>  
>  /**
> - * enum wmaa_source - Backlight brightness control source identification
> - * @WMAA_SOURCE_GPU:   Backlight brightness is controlled by the GPU.
> - * @WMAA_SOURCE_EC:    Backlight brightness is controlled by the system's
> - *                     Embedded Controller (EC).
> - * @WMAA_SOURCE_AUX:   Backlight brightness is controlled over the DisplayPort
> - *                     AUX channel.
> + * enum wmi_brightness_source - Backlight brightness control source selection
> + * @WMI_BRIGHTNESS_SOURCE_GPU: Backlight brightness is controlled by the GPU.
> + * @WMI_BRIGHTNESS_SOURCE_EC:  Backlight brightness is controlled by the
> + *                             system's Embedded Controller (EC).
> + * @WMI_BRIGHTNESS_SOURCE_AUX: Backlight brightness is controlled over the
> + *                             DisplayPort AUX channel.
>   */
> -enum wmaa_source {
> -	WMAA_SOURCE_GPU = 1,
> -	WMAA_SOURCE_EC = 2,
> -	WMAA_SOURCE_AUX = 3,
> -	WMAA_SOURCE_MAX
> +enum wmi_brightness_source {
> +	WMI_BRIGHTNESS_SOURCE_GPU = 1,
> +	WMI_BRIGHTNESS_SOURCE_EC = 2,
> +	WMI_BRIGHTNESS_SOURCE_AUX = 3,
> +	WMI_BRIGHTNESS_SOURCE_MAX
>  };
>  
>  /**
> - * struct wmaa_args - arguments for the ACPI WMAA method
> - * @mode:    Pass in an &enum wmaa_mode value to select between getting or
> - *           setting a value.
> - * @val:     In parameter for value to set when operating in %WMAA_MODE_SET
> - *           mode. Not used in %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode.
> + * struct wmi_brightness_args - arguments for the WMI-wrapped ACPI method
> + * @mode:    Pass in an &enum wmi_brightness_mode value to select between
> + *           getting or setting a value.
> + * @val:     In parameter for value to set when using %WMI_BRIGHTNESS_MODE_SET
> + *           mode. Not used in conjunction with %WMI_BRIGHTNESS_MODE_GET or
> + *           %WMI_BRIGHTNESS_MODE_GET_MAX_LEVEL mode.
>   * @ret:     Out parameter returning retrieved value when operating in
> - *           %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL mode. Not used in
> - *           %WMAA_MODE_SET mode.
> + *           %WMI_BRIGHTNESS_MODE_GET or %WMI_BRIGHTNESS_MODE_GET_MAX_LEVEL
> + *           mode. Not used in %WMI_BRIGHTNESS_MODE_SET mode.
>   * @ignored: Padding; not used. The ACPI method expects a 24 byte params struct.
>   *
> - * This is the parameters structure for the ACPI WMAA method as wrapped by WMI.
> - * The value passed in to @val or returned by @ret will be a brightness value
> - * when the WMI method ID is %WMAA_METHOD_LEVEL, or an &enum wmaa_source value
> - * when the WMI method ID is %WMAA_METHOD_SOURCE.
> + * This is the parameters structure for the WmiBrightnessNotify ACPI method as
> + * wrapped by WMI. The value passed in to @val or returned by @ret will be a
> + * brightness value when the WMI method ID is %WMI_BRIGHTNESS_METHOD_LEVEL, or
> + * an &enum wmi_brightness_source value with %WMI_BRIGHTNESS_METHOD_SOURCE.
>   */
> -struct wmaa_args {
> +struct wmi_brightness_args {
>  	u32 mode;
>  	u32 val;
>  	u32 ret;
> @@ -75,21 +76,21 @@ struct wmaa_args {
>  };
>  
>  /**
> - * wmi_call_wmaa() - helper function for calling ACPI WMAA via its WMI wrapper
> - * @w:    Pointer to the struct wmi_device identified by %WMAA_WMI_GUID
> - * @id:   The method ID for the ACPI WMAA method (e.g. %WMAA_METHOD_LEVEL or
> - *        %WMAA_METHOD_SOURCE)
> - * @mode: The operation to perform on the ACPI WMAA method (e.g. %WMAA_MODE_SET
> - *        or %WMAA_MODE_GET)
> + * wmi_brightness_notify() - helper function for calling WMI-wrapped ACPI method
> + * @w:    Pointer to the struct wmi_device identified by %WMI_BRIGHTNESS_GUID
> + * @id:   The WMI method ID to call (e.g. %WMI_BRIGHTNESS_METHOD_LEVEL or
> + *        %WMI_BRIGHTNESS_METHOD_SOURCE)
> + * @mode: The operation to perform on the method (e.g. %WMI_BRIGHTNESS_MODE_SET
> + *        or %WMI_BRIGHTNESS_MODE_GET)
>   * @val:  Pointer to a value passed in by the caller when @mode is
> - *        %WMAA_MODE_SET, or a value passed out to the caller when @mode is
> - *        %WMAA_MODE_GET or %WMAA_MODE_GET_MAX_LEVEL.
> + *        %WMI_BRIGHTNESS_MODE_SET, or a value passed out to caller when @mode
> + *        is %WMI_BRIGHTNESS_MODE_GET or %WMI_BRIGHTNESS_MODE_GET_MAX_LEVEL.
>   *
>   * Returns 0 on success, or a negative error number on failure.
>   */
> -static int wmi_call_wmaa(struct wmi_device *w, enum wmaa_method id, enum wmaa_mode mode, u32 *val)
> +static int wmi_brightness_notify(struct wmi_device *w, enum wmi_brightness_method id, enum wmi_brightness_mode mode, u32 *val)
>  {
> -	struct wmaa_args args = {
> +	struct wmi_brightness_args args = {
>  		.mode = mode,
>  		.val = 0,
>  		.ret = 0,
> @@ -97,60 +98,64 @@ static int wmi_call_wmaa(struct wmi_device *w, enum wmaa_method id, enum wmaa_mo
>  	struct acpi_buffer buf = { (acpi_size)sizeof(args), &args };
>  	acpi_status status;
>  
> -	if (id < WMAA_METHOD_LEVEL || id >= WMAA_METHOD_MAX ||
> -	    mode < WMAA_MODE_GET || mode >= WMAA_MODE_MAX)
> +	if (id < WMI_BRIGHTNESS_METHOD_LEVEL ||
> +	    id >= WMI_BRIGHTNESS_METHOD_MAX ||
> +	    mode < WMI_BRIGHTNESS_MODE_GET || mode >= WMI_BRIGHTNESS_MODE_MAX)
>  		return -EINVAL;
>  
> -	if (mode == WMAA_MODE_SET)
> +	if (mode == WMI_BRIGHTNESS_MODE_SET)
>  		args.val = *val;
>  
>  	status = wmidev_evaluate_method(w, 0, id, &buf, &buf);
>  	if (ACPI_FAILURE(status)) {
> -		dev_err(&w->dev, "ACPI WMAA failed: %s\n",
> +		dev_err(&w->dev, "EC backlight control failed: %s\n",
>  			acpi_format_exception(status));
>  		return -EIO;
>  	}
>  
> -	if (mode != WMAA_MODE_SET)
> +	if (mode != WMI_BRIGHTNESS_MODE_SET)
>  		*val = args.ret;
>  
>  	return 0;
>  }
>  
> -static int wmaa_backlight_update_status(struct backlight_device *bd)
> +static int nvidia_wmi_ec_backlight_update_status(struct backlight_device *bd)
>  {
>  	struct wmi_device *wdev = bl_get_data(bd);
>  
> -	return wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_SET,
> -			     &bd->props.brightness);
> +	return wmi_brightness_notify(wdev, WMI_BRIGHTNESS_METHOD_LEVEL,
> +	                             WMI_BRIGHTNESS_MODE_SET,
> +			             &bd->props.brightness);
>  }
>  
> -static int wmaa_backlight_get_brightness(struct backlight_device *bd)
> +static int nvidia_wmi_ec_backlight_get_brightness(struct backlight_device *bd)
>  {
>  	struct wmi_device *wdev = bl_get_data(bd);
>  	u32 level;
>  	int ret;
>  
> -	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET, &level);
> +	ret = wmi_brightness_notify(wdev, WMI_BRIGHTNESS_METHOD_LEVEL,
> +	                            WMI_BRIGHTNESS_MODE_GET, &level);
>  	if (ret < 0)
>  		return ret;
>  
>  	return level;
>  }
>  
> -static const struct backlight_ops wmaa_backlight_ops = {
> -	.update_status = wmaa_backlight_update_status,
> -	.get_brightness = wmaa_backlight_get_brightness,
> +static const struct backlight_ops nvidia_wmi_ec_backlight_ops = {
> +	.update_status = nvidia_wmi_ec_backlight_update_status,
> +	.get_brightness = nvidia_wmi_ec_backlight_get_brightness,
>  };
>  
> -static int wmaa_backlight_wmi_probe(struct wmi_device *wdev, const void *ctx)
> +static int nvidia_wmi_ec_backlight_probe(struct wmi_device *wdev, const void *ctx)
>  {
>  	struct backlight_properties props = {};
>  	struct backlight_device *bdev;
>  	u32 source;
>  	int ret;
>  
> -	ret = wmi_call_wmaa(wdev, WMAA_METHOD_SOURCE, WMAA_MODE_GET, &source);
> +	ret = wmi_brightness_notify(wdev, WMI_BRIGHTNESS_METHOD_SOURCE,
> +	                           WMI_BRIGHTNESS_MODE_GET, &source);
>  	if (ret)
>  		return ret;
>  
> @@ -158,7 +163,7 @@ static int wmaa_backlight_wmi_probe(struct wmi_device *wdev, const void *ctx)
>  	 * This driver is only to be used when brightness control is handled
>  	 * by the EC; otherwise, the GPU driver(s) should control brightness.
>  	 */
> -	if (source != WMAA_SOURCE_EC)
> +	if (source != WMI_BRIGHTNESS_SOURCE_EC)
>  		return -ENODEV;
>  
>  	/*
> @@ -167,39 +172,42 @@ static int wmaa_backlight_wmi_probe(struct wmi_device *wdev, const void *ctx)
>  	 */
>  	props.type = BACKLIGHT_FIRMWARE;
>  
> -	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET_MAX_LEVEL,
> -			    &props.max_brightness);
> +	ret = wmi_brightness_notify(wdev, WMI_BRIGHTNESS_METHOD_LEVEL,
> +	                           WMI_BRIGHTNESS_MODE_GET_MAX_LEVEL,
> +	                           &props.max_brightness);
>  	if (ret)
>  		return ret;
>  
> -	ret = wmi_call_wmaa(wdev, WMAA_METHOD_LEVEL, WMAA_MODE_GET,
> -			    &props.brightness);
> +	ret = wmi_brightness_notify(wdev, WMI_BRIGHTNESS_METHOD_LEVEL,
> +	                           WMI_BRIGHTNESS_MODE_GET, &props.brightness);
>  	if (ret)
>  		return ret;
>  
> -	bdev = devm_backlight_device_register(&wdev->dev, "wmaa_backlight",
> +	bdev = devm_backlight_device_register(&wdev->dev,
> +	                                      "nvidia_wmi_ec_backlight",
>  					      &wdev->dev, wdev,
> -					      &wmaa_backlight_ops, &props);
> +					      &nvidia_wmi_ec_backlight_ops,
> +					      &props);
>  	return PTR_ERR_OR_ZERO(bdev);
>  }
>  
> -#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
> +#define WMI_BRIGHTNESS_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
>  
> -static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
> -	{ .guid_string = WMAA_WMI_GUID },
> +static const struct wmi_device_id nvidia_wmi_ec_backlight_id_table[] = {
> +	{ .guid_string = WMI_BRIGHTNESS_GUID },
>  	{ }
>  };
> -MODULE_DEVICE_TABLE(wmi, wmaa_backlight_wmi_id_table);
> +MODULE_DEVICE_TABLE(wmi, nvidia_wmi_ec_backlight_id_table);
>  
> -static struct wmi_driver wmaa_backlight_wmi_driver = {
> +static struct wmi_driver nvidia_wmi_ec_backlight_driver = {
>  	.driver = {
> -		.name = "wmaa-backlight",
> +		.name = "nvidia-wmi-ec-backlight",
>  	},
> -	.probe = wmaa_backlight_wmi_probe,
> -	.id_table = wmaa_backlight_wmi_id_table,
> +	.probe = nvidia_wmi_ec_backlight_probe,
> +	.id_table = nvidia_wmi_ec_backlight_id_table,
>  };
> -module_wmi_driver(wmaa_backlight_wmi_driver);
> +module_wmi_driver(nvidia_wmi_ec_backlight_driver);
>  
>  MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
> -MODULE_DESCRIPTION("WMAA Backlight WMI driver");
> +MODULE_DESCRIPTION("NVIDIA WMI EC Backlight driver");
>  MODULE_LICENSE("GPL");
> 

Re: [PATCH v6] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

On 9/21/21 9:58 AM, Hans de Goede wrote:
> Hi,
>
> On 9/21/21 4:29 PM, Daniel Dadap wrote:
>>> On Sep 21, 2021, at 08:53, Hans de Goede <hdegoede@redhat.com> wrote:
>>>
>>> Hi,
>>>
>>>> On 9/20/21 3:51 PM, Pali Rohár wrote:
>>>>> On Monday 20 September 2021 15:33:20 Hans de Goede wrote:
>>>>> Hi Pali,
>>>>>
>>>>> On 9/20/21 3:29 PM, Pali Rohár wrote:
>>>>>> On Monday 13 September 2021 11:01:50 Hans de Goede wrote:
>>>>>>> Hi,
>>>>>>>
>>>>>>> On 9/3/21 2:38 AM, Daniel Dadap wrote:
>>>>>>>> A number of upcoming notebook computer designs drive the internal
>>>>>>>> display panel's backlight PWM through the Embedded Controller (EC).
>>>>>>>> This EC-based backlight control can be plumbed through to an ACPI
>>>>>>>> "WMAA" method interface, which in turn can be wrapped by WMI with
>>>>>>>> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
>>>>>>>>
>>>>>>>> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
>>>>>>>> backlight class driver to control backlight levels on systems with
>>>>>>>> EC-driven backlights.
>>>>>>>>
>>>>>>>> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
>>>>>>>> Reviewed-By: Thomas Weißschuh <linux@weissschuh.net>
>>>>>>> Thank you for your patch, I've applied this patch to my review-hans
>>>>>>> branch:
>>>>>>> https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=review-hans
>>>>>>>
>>>>>>> Note it will show up in my review-hans branch once I've pushed my
>>>>>>> local branch there, which might take a while.
>>>>>>>
>>>>>>> Once I've run some tests on this branch the patches there will be
>>>>>>> added to the platform-drivers-x86/for-next branch and eventually
>>>>>>> will be included in the pdx86 pull-request to Linus for the next
>>>>>>> merge-window.
>>>>>> Hello Hans!
>>>>>>
>>>>>> I would suggest to rename this driver and config option to not include
>>>>>> -AA in its name. WMAA is just internal name of ACPI method, composed
>>>>>> from two parts: "WM" and "AA". Second part "AA" is read from the _WDG
>>>>>> where is the translation table from WMI GUID (in this case 603E9613...)
>>>>>> to ACPI method name. "AA" is just autogenerated identifier by wmi
>>>>>> compiler and because names are ASCII strings, I guess "AA" could mean
>>>>>> the first (autogenerated) method. In the whole driver code you are not
>>>>>> using AA function name, but directly WMI GUID, which also means that
>>>>>> driver is prepared if vendor "recompiles" wmi code in acpi (and compiler
>>>>>> generates another identifier, not AA). Also another argument is that
>>>>>> there can be lot of other laptops which have WMAA ACPI method but they
>>>>>> can have different API or do something totally different. So name WMAA
>>>>>> is in this wmi context very misleading. Rather it should be named by
>>>>>> vendor.
>>>>> Right, that is a very valid point. I should have spotted this myself.
>>>>>
>>>>> So what would be a better name wmi-nvidia-backlight.ko I guess ?
>>>>> (and update the rest to match ?)
>>>> It looks like that no vendor driver starts with "wmi-" prefix. "-wmi"
>>>> string is used as a suffix. So for consistency it would be better to
>>>> choose "nvidia-backlight-wmi.ko".
>>> Right, I should have checked first.
>>>
>>> So I just checked and the standard pattern used is:
>>> vendor_wmi_feature
>>>
>>> So lets go with nvidia_wmi_backlight.ko
>>>
>>> Daniel, can you prepare a patch on top of your merged patch to do
>>> the rename of the Kconfig entry and the module-name please?
>>>
>> Yes, I already had a patch prepared to rename things to nvidia-backlight-wmi; I am waiting to hear back from some folks if there’s a more specific name that might be appropriate (e.g. a name of a particular feature tied to this) or if it should be more generic (e.g., if there is a strong possibility this design may be used in systems with no NVIDIA GPU); while I’m waiting for those answers, I’ll switch to nvidia-wmi-backlight as the assumed option, if there isn’t something more appropriate.
> Ok, sounds good, thank you.


The one suggestion I got for improving the name we've discussed here is 
to include "ec" in the name, to make it clear that this isn't a driver 
for the normal backlight interface that is driven by the NVIDIA GPU. I 
intended to send this message before the rename patches that I sent a 
few hours ago, but apparently I didn't.


> Regards,
>
> Hans
>

Re: [PATCH v4] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Andy Shevchenko]

On Wed, Sep 1, 2021 at 12:25 PM Thomas Weißschuh <linux@weissschuh.net> wrote:

> > v4: Use MODULE_DEVICE_TABLE() (Thomas Wei??schuh <thomas@t-8ch.de>)
> >     Fix scope of internal driver state; various style fixes (Barnab??s
> >     P??cze, Andy Shevchenko)
> >     Use devm_backlight_device_register() (Barnab??s P??cze)
> >     Add kerneldoc comments for enums and structs (Andy Shevchenko)
>
> It seems your Mailsetup breaks Unicode.

I see it properly, so, the problem is on your branch of email delivery.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v4] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Thomas Weißschuh]

On Do, 2021-09-02T12:28+0300, Andy Shevchenko wrote:
> On Wed, Sep 1, 2021 at 12:25 PM Thomas Weißschuh <linux@weissschuh.net> wrote:
> 
> > > v4: Use MODULE_DEVICE_TABLE() (Thomas Wei??schuh <thomas@t-8ch.de>)
> > >     Fix scope of internal driver state; various style fixes (Barnab??s
> > >     P??cze, Andy Shevchenko)
> > >     Use devm_backlight_device_register() (Barnab??s P??cze)
> > >     Add kerneldoc comments for enums and structs (Andy Shevchenko)
> >
> > It seems your Mailsetup breaks Unicode.
> 
> I see it properly, so, the problem is on your branch of email delivery.

It's also broken on lore.kernel.org:
https://lore.kernel.org/platform-driver-x86/20210831224906.1072-1-ddadap@nvidia.com/

Anyways, as it won't be part of the history it shouldn't be urgent.

Thomas

Re: [PATCH v4] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Andy Shevchenko]

On Thu, Sep 2, 2021 at 12:33 PM Thomas Weißschuh <linux@weissschuh.net> wrote:
> On Do, 2021-09-02T12:28+0300, Andy Shevchenko wrote:
> > On Wed, Sep 1, 2021 at 12:25 PM Thomas Weißschuh <linux@weissschuh.net> wrote:
> >
> > > > v4: Use MODULE_DEVICE_TABLE() (Thomas Wei??schuh <thomas@t-8ch.de>)
> > > >     Fix scope of internal driver state; various style fixes (Barnab??s
> > > >     P??cze, Andy Shevchenko)
> > > >     Use devm_backlight_device_register() (Barnab??s P??cze)
> > > >     Add kerneldoc comments for enums and structs (Andy Shevchenko)
> > >
> > > It seems your Mailsetup breaks Unicode.
> >
> > I see it properly, so, the problem is on your branch of email delivery.
>
> It's also broken on lore.kernel.org:
> https://lore.kernel.org/platform-driver-x86/20210831224906.1072-1-ddadap@nvidia.com/

Ah, okay then. It seems I got a direct copy through a different chain
of servers.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v4] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Andy Shevchenko]

On Wed, Sep 1, 2021 at 2:27 AM Daniel Dadap <ddadap@nvidia.com> wrote:
>
> A number of upcoming notebook computer designs drive the internal
> display panel's backlight PWM through the Embedded Controller (EC).
> This EC-based backlight control can be plumbed through to an ACPI
> "WMAA" method interface, which in turn can be wrapped by WMI with
> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
>
> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
> backlight class driver to control backlight levels on systems with
> EC-driven backlights.

> Signed-off-by: Aaron Plattner <aplattner@nvidia.com>

Seems like missed Co-developed-by. Or you are the wrong author. Fix accordingly.

> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>

...

> +#include <linux/backlight.h>
> +#include <linux/module.h>
> +#include <linux/wmi.h>

types.h ?
mod_devicetable.h ?

...

> +enum wmaa_get_or_set {
> +       WMAA_GET = 0,
> +       WMAA_SET = 1,
> +       WMAA_GET_MAX = 2

Is it part of HW protocol? Otherwise drop assignments.

> +};

...

> + */
> +enum wmaa_source {
> +       WMAA_SOURCE_GPU = 1,
> +       WMAA_SOURCE_EC = 2,

> +       WMAA_SOURCE_AUX = 3

Missed comma.

> +};

...

> +/**
> + * struct wmaa_args - arguments for the ACPI WMAA method

> + *

Redundant blank line.

> + * @set:     Pass in an &enum wmaa_get_or_set value to select between getting or
> + *           setting a value.
> + * @val:     In parameter for value to set when operating in %WMAA_SET mode. Not
> + *           used in %WMAA_GET or %WMAA_GET_MAX mode.
> + * @ret:     Out parameter returning retrieved value when operating in %WMAA_GET
> + *           or %WMAA_GET_MAX mode. Not used in %WMAA_SET mode.
> + * @ignored: Padding; not used. The ACPI method expects a 24 byte params struct.
> + *
> + * This is the parameters structure for the ACPI WMAA method as wrapped by WMI.
> + * The value passed in to @val or returned by @ret will be a brightness value
> + * when the WMI method ID is %WMAA_LEVEL, or an &enum wmaa_source value when
> + * the WMI method ID is %WMAA_SOURCE.
> + */

...

> +       ret = wmi_call_wmaa(wdev, WMAA_LEVEL, WMAA_GET, &level);

> +

Ditto.

> +       if (ret)
> +               dev_err(&bd->dev, "ACPI WMAA failed to get backlight level.\n");

...
> +static const struct backlight_ops wmaa_backlight_ops = {
> +       .update_status = wmaa_backlight_update_status,
> +       .get_brightness = wmaa_backlight_get_brightness

Missed comma.

> +};

...

> +       if (source != WMAA_SOURCE_EC) {
> +               /* This driver is only to be used when brightness control is
> +                * handled by the EC; otherwise, the GPU driver(s) should handle
> +                * brightness control. */

/*
 * Wrong multi-line comment
 * style. Use this example to fix
 * it properly.
 */

> +               return -ENODEV;
> +       }

> +       /* Identify this backlight device as a platform device so that it can
> +        * be prioritized over any exposed GPU-driven raw device(s). */

Ditto.
And for any other multi-line comments in this driver.

...

> +       backlight = devm_backlight_device_register(
> +               &w->dev, "wmaa_backlight",
> +               &w->dev, w, &wmaa_backlight_ops, &props);

> +       if (IS_ERR(backlight))
> +               return PTR_ERR(backlight);
> +
> +       return 0;

return PTR_ERR_OR_ZERO(backlight);

...

> +MODULE_AUTHOR("Aaron Plattner <aplattner@nvidia.com>");
> +MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");

So, Co-developed-by seems missing above.

...

> +MODULE_LICENSE("GPL v2");

"GPL" is enough (it's a synonim).

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v4] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Aaron Plattner]

On 9/1/21 8:57 AM, Andy Shevchenko wrote:
> On Wed, Sep 1, 2021 at 2:27 AM Daniel Dadap <ddadap@nvidia.com> wrote:
>> A number of upcoming notebook computer designs drive the internal
>> display panel's backlight PWM through the Embedded Controller (EC).
>> This EC-based backlight control can be plumbed through to an ACPI
>> "WMAA" method interface, which in turn can be wrapped by WMI with
>> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
>>
>> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
>> backlight class driver to control backlight levels on systems with
>> EC-driven backlights.
>> Signed-off-by: Aaron Plattner <aplattner@nvidia.com>
> Seems like missed Co-developed-by. Or you are the wrong author. Fix accordingly.

I wrote the initial version of this driver that we used internally for 
testing, but Daniel almost completely rewrote it for upstreaming. I'd be 
fine with just dropping me from the patch entirely and listing Daniel as 
the author since it looks almost nothing like the code I wrote.

-- Aaron

Re: [PATCH v4] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

Thanks again, Andy:

On 9/1/21 10:57 AM, Andy Shevchenko wrote:
> On Wed, Sep 1, 2021 at 2:27 AM Daniel Dadap <ddadap@nvidia.com> wrote:
>> A number of upcoming notebook computer designs drive the internal
>> display panel's backlight PWM through the Embedded Controller (EC).
>> This EC-based backlight control can be plumbed through to an ACPI
>> "WMAA" method interface, which in turn can be wrapped by WMI with
>> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
>>
>> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
>> backlight class driver to control backlight levels on systems with
>> EC-driven backlights.
>> Signed-off-by: Aaron Plattner <aplattner@nvidia.com>
> Seems like missed Co-developed-by. Or you are the wrong author. Fix accordingly.


Indeed; as Aaron mentioned, he was the author of a much earlier version 
of this driver which we used internally for testing purposes. He 
actually gave me his blessing to leave his name off the patch even 
before I submitted the original version of the patch for review on this 
list, but I figured it wasn't a big deal to leave him on. Since Aaron 
has suggested taking him off the patch again, I'll just go ahead and do 
that.


>
>> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
> ...
>
>> +#include <linux/backlight.h>
>> +#include <linux/module.h>
>> +#include <linux/wmi.h>
> types.h ?
> mod_devicetable.h ?


Evidently, these must already be implicitly picked up by the headers 
which I am explicitly including here. I can see the argument for 
types.h, since it's always possible that future changes to the kernel 
might remove it from the implicit include chain, but I'm not certain why 
you're recommending mod_devicetable.h here. If it's because I use the 
MODULE_DEVICE_TABLE() macro, that seems to be defined in module.h.


>
> ...
>
>> +enum wmaa_get_or_set {
>> +       WMAA_GET = 0,
>> +       WMAA_SET = 1,
>> +       WMAA_GET_MAX = 2
> Is it part of HW protocol? Otherwise drop assignments.


Does ACPI count as HW here? I'd certainly prefer to keep the 
assignments, since the other side of this interface is not in the Linux 
kernel.


>
>> +};
> ...
>
>> + */
>> +enum wmaa_source {
>> +       WMAA_SOURCE_GPU = 1,
>> +       WMAA_SOURCE_EC = 2,
>> +       WMAA_SOURCE_AUX = 3
> Missed comma.


Oops. I am definitely a fan of using commas here, but I removed the 
commas that I had in place for the last elements of these enums, and 
members of static initialized structs, because I was trying to more 
broadly apply feedback from earlier to drop the terminal comma in the 
static initialized device table. I realize now that this feedback was 
meant only for the case of the empty struct terminator element in the 
device table.


>
>> +};
> ...
>
>> +/**
>> + * struct wmaa_args - arguments for the ACPI WMAA method
>> + *
> Redundant blank line.
>
>> + * @set:     Pass in an &enum wmaa_get_or_set value to select between getting or
>> + *           setting a value.
>> + * @val:     In parameter for value to set when operating in %WMAA_SET mode. Not
>> + *           used in %WMAA_GET or %WMAA_GET_MAX mode.
>> + * @ret:     Out parameter returning retrieved value when operating in %WMAA_GET
>> + *           or %WMAA_GET_MAX mode. Not used in %WMAA_SET mode.
>> + * @ignored: Padding; not used. The ACPI method expects a 24 byte params struct.
>> + *
>> + * This is the parameters structure for the ACPI WMAA method as wrapped by WMI.
>> + * The value passed in to @val or returned by @ret will be a brightness value
>> + * when the WMI method ID is %WMAA_LEVEL, or an &enum wmaa_source value when
>> + * the WMI method ID is %WMAA_SOURCE.
>> + */
> ...
>
>> +       ret = wmi_call_wmaa(wdev, WMAA_LEVEL, WMAA_GET, &level);
>> +
> Ditto.
>
>> +       if (ret)
>> +               dev_err(&bd->dev, "ACPI WMAA failed to get backlight level.\n");
> ...
>> +static const struct backlight_ops wmaa_backlight_ops = {
>> +       .update_status = wmaa_backlight_update_status,
>> +       .get_brightness = wmaa_backlight_get_brightness
> Missed comma.
>
>> +};
> ...
>
>> +       if (source != WMAA_SOURCE_EC) {
>> +               /* This driver is only to be used when brightness control is
>> +                * handled by the EC; otherwise, the GPU driver(s) should handle
>> +                * brightness control. */
> /*
>   * Wrong multi-line comment
>   * style. Use this example to fix
>   * it properly.
>   */
>
>> +               return -ENODEV;
>> +       }
>> +       /* Identify this backlight device as a platform device so that it can
>> +        * be prioritized over any exposed GPU-driven raw device(s). */
> Ditto.
> And for any other multi-line comments in this driver.
>
> ...
>
>> +       backlight = devm_backlight_device_register(
>> +               &w->dev, "wmaa_backlight",
>> +               &w->dev, w, &wmaa_backlight_ops, &props);
>> +       if (IS_ERR(backlight))
>> +               return PTR_ERR(backlight);
>> +
>> +       return 0;
> return PTR_ERR_OR_ZERO(backlight);
>
> ...


Thanks; Thomas made the same suggestion.


>
>> +MODULE_AUTHOR("Aaron Plattner <aplattner@nvidia.com>");
>> +MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
> So, Co-developed-by seems missing above.
>
> ...
>
>> +MODULE_LICENSE("GPL v2");
> "GPL" is enough (it's a synonim).


Indeed, Thomas pointed this out as well. I will do some retesting since 
I am changing the backlight driver type from BACKLIGHT_PLATFORM to 
BACKLIGHT_FIRMWARE, then send the updated patch.

Re: [PATCH v4] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Andy Shevchenko]

On Thu, Sep 2, 2021 at 5:37 AM Daniel Dadap <ddadap@nvidia.com> wrote:
> On 9/1/21 10:57 AM, Andy Shevchenko wrote:
> > On Wed, Sep 1, 2021 at 2:27 AM Daniel Dadap <ddadap@nvidia.com> wrote:

...

> >> +#include <linux/backlight.h>
> >> +#include <linux/module.h>
> >> +#include <linux/wmi.h>
> > types.h ?
> > mod_devicetable.h ?
>
> Evidently, these must already be implicitly picked up by the headers
> which I am explicitly including here. I can see the argument for
> types.h, since it's always possible that future changes to the kernel
> might remove it from the implicit include chain, but I'm not certain why
> you're recommending mod_devicetable.h here. If it's because I use the
> MODULE_DEVICE_TABLE() macro, that seems to be defined in module.h.

No, it's because of the ID table type which leaves there.

Basically you have to find a compromise between what to include and
what to not. At least those I have mentioned are kinda core stuff that
usually should be included explicitly in the modules like this driver.

...

> >> +enum wmaa_get_or_set {
> >> +       WMAA_GET = 0,
> >> +       WMAA_SET = 1,
> >> +       WMAA_GET_MAX = 2
> > Is it part of HW protocol? Otherwise drop assignments.
>
>
> Does ACPI count as HW here? I'd certainly prefer to keep the
> assignments, since the other side of this interface is not in the Linux
> kernel.

Yes, that counts as FW and as you noticed out of the Linux kernel realm.

> >> +};

...

> >> + */
> >> +enum wmaa_source {
> >> +       WMAA_SOURCE_GPU = 1,
> >> +       WMAA_SOURCE_EC = 2,
> >> +       WMAA_SOURCE_AUX = 3
> > Missed comma.
>
>
> Oops. I am definitely a fan of using commas here, but I removed the
> commas that I had in place for the last elements of these enums, and
> members of static initialized structs, because I was trying to more
> broadly apply feedback from earlier to drop the terminal comma in the
> static initialized device table. I realize now that this feedback was
> meant only for the case of the empty struct terminator element in the
> device table.

Not only, the _MAX in the above enum is correct in leaving commas out.

> >> +};

...

> >> +       backlight = devm_backlight_device_register(
> >> +               &w->dev, "wmaa_backlight",

Strange indentation, btw.

> >> +               &w->dev, w, &wmaa_backlight_ops, &props);

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v4] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Daniel Dadap]

On 9/2/21 4:35 AM, Andy Shevchenko wrote:
> On Thu, Sep 2, 2021 at 5:37 AM Daniel Dadap<ddadap@nvidia.com>  wrote:
>> On 9/1/21 10:57 AM, Andy Shevchenko wrote:
>>> On Wed, Sep 1, 2021 at 2:27 AM Daniel Dadap<ddadap@nvidia.com>  wrote:
> ...
>
>>>> +#include <linux/backlight.h>
>>>> +#include <linux/module.h>
>>>> +#include <linux/wmi.h>
>>> types.h ?
>>> mod_devicetable.h ?
>> Evidently, these must already be implicitly picked up by the headers
>> which I am explicitly including here. I can see the argument for
>> types.h, since it's always possible that future changes to the kernel
>> might remove it from the implicit include chain, but I'm not certain why
>> you're recommending mod_devicetable.h here. If it's because I use the
>> MODULE_DEVICE_TABLE() macro, that seems to be defined in module.h.
> No, it's because of the ID table type which leaves there.
>
> Basically you have to find a compromise between what to include and
> what to not. At least those I have mentioned are kinda core stuff that
> usually should be included explicitly in the modules like this driver.


Okay, thanks. I suppose I should have <linux/acpi.h> as well: I 
originally had that on there, then removed it when I realized that it's 
included implicitly via <linux/wmi.h>, but I do use some ACPI types and 
macros that are defined in that header.


> ...
>
>>>> +enum wmaa_get_or_set {
>>>> +       WMAA_GET = 0,
>>>> +       WMAA_SET = 1,
>>>> +       WMAA_GET_MAX = 2
>>> Is it part of HW protocol? Otherwise drop assignments.
>> Does ACPI count as HW here? I'd certainly prefer to keep the
>> assignments, since the other side of this interface is not in the Linux
>> kernel.
> Yes, that counts as FW and as you noticed out of the Linux kernel realm.
>
>>>> +};
> ...
>
>>>> + */
>>>> +enum wmaa_source {
>>>> +       WMAA_SOURCE_GPU = 1,
>>>> +       WMAA_SOURCE_EC = 2,
>>>> +       WMAA_SOURCE_AUX = 3
>>> Missed comma.
>> Oops. I am definitely a fan of using commas here, but I removed the
>> commas that I had in place for the last elements of these enums, and
>> members of static initialized structs, because I was trying to more
>> broadly apply feedback from earlier to drop the terminal comma in the
>> static initialized device table. I realize now that this feedback was
>> meant only for the case of the empty struct terminator element in the
>> device table.
> Not only, the _MAX in the above enum is correct in leaving commas out.


No, I think it does need a comma, unless I'm misunderstanding why you're 
saying it doesn't. WMAA_GET_MAX here isn't saying "this is the final 
element of the enum which is also a count of the 'real' enum values"; 
it's saying "retrieve the maximum valid brightness level from the 
firmware". I renamed the enumerant to WMAA_GET_MAX_LEVEL to avoid 
aliasing with the common "_MAX" convention for the final value defined 
in an enum.


>
>>>> +};
> ...
>
>>>> +       backlight = devm_backlight_device_register(
>>>> +               &w->dev, "wmaa_backlight",
> Strange indentation, btw.


Indeed. I'm not totally sure why I did it that way, maybe because the 
long variable and function name didn't leave much space for arguments to 
indent normally? I shortened the variable name and reindented it.


>
>>>> +               &w->dev, w, &wmaa_backlight_ops, &props);

Re: [PATCH v4] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Andy Shevchenko]

On Thu, Sep 2, 2021 at 11:15 PM Daniel Dadap <ddadap@nvidia.com> wrote:
> On 9/2/21 4:35 AM, Andy Shevchenko wrote:
> > On Thu, Sep 2, 2021 at 5:37 AM Daniel Dadap<ddadap@nvidia.com>  wrote:
> >> On 9/1/21 10:57 AM, Andy Shevchenko wrote:
> >>> On Wed, Sep 1, 2021 at 2:27 AM Daniel Dadap<ddadap@nvidia.com>  wrote:

...

> Okay, thanks. I suppose I should have <linux/acpi.h> as well:

Yes.

...

> >>> Missed comma.
> >> Oops. I am definitely a fan of using commas here, but I removed the
> >> commas that I had in place for the last elements of these enums, and
> >> members of static initialized structs, because I was trying to more
> >> broadly apply feedback from earlier to drop the terminal comma in the
> >> static initialized device table. I realize now that this feedback was
> >> meant only for the case of the empty struct terminator element in the
> >> device table.
> > Not only, the _MAX in the above enum is correct in leaving commas out.
>
> No, I think it does need a comma, unless I'm misunderstanding why you're
> saying it doesn't. WMAA_GET_MAX here isn't saying "this is the final
> element of the enum which is also a count of the 'real' enum values";
> it's saying "retrieve the maximum valid brightness level from the
> firmware". I renamed the enumerant to WMAA_GET_MAX_LEVEL to avoid
> aliasing with the common "_MAX" convention for the final value defined
> in an enum.

In that case, you are right.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v4] platform/x86: Add driver for ACPI WMAA EC-based backlight control

[Hans de Goede]

Hi Daniel,

On 9/1/21 12:49 AM, Daniel Dadap wrote:
> A number of upcoming notebook computer designs drive the internal
> display panel's backlight PWM through the Embedded Controller (EC).
> This EC-based backlight control can be plumbed through to an ACPI
> "WMAA" method interface, which in turn can be wrapped by WMI with
> the GUID handle 603E9613-EF25-4338-A3D0-C46177516DB7.
> 
> Add a new driver, aliased to the WMAA WMI GUID, to expose a sysfs
> backlight class driver to control backlight levels on systems with
> EC-driven backlights.
> 
> Signed-off-by: Aaron Plattner <aplattner@nvidia.com>
> Signed-off-by: Daniel Dadap <ddadap@nvidia.com>
> ---
> 
> v2: Convert to WMI subsystem driver, suggested by Mario Limonciello
>      <mario.limonciello@outlook.com>; various cleanups suggested by
>      Barnabás Pőcze <pobrn@protonmail.com>
> v3: Address assorted style nits raised by Andy Shevchenko
>      <andy.shevchenko@gmail.com> in response to a related patch; remove
>      additional behavior change to WMI subsystem from patch series as
>      recommended by Hans de Goede <hdegoede@redhat.com> 
> v4: Use MODULE_DEVICE_TABLE() (Thomas Weißschuh <thomas@t-8ch.de>)
>     Fix scope of internal driver state; various style fixes (Barnabás
>     Pőcze, Andy Shevchenko)
>     Use devm_backlight_device_register() (Barnabás Pőcze)
>     Add kerneldoc comments for enums and structs (Andy Shevchenko)

Thank you for your patch, given Andy's (small) set of remarks
I believe it would be best to do a v5 addressing those, after that
I expect this to be ready for merging.

Regards,

Hans




> 
>  MAINTAINERS                               |   6 +
>  drivers/platform/x86/Kconfig              |  16 ++
>  drivers/platform/x86/Makefile             |   1 +
>  drivers/platform/x86/wmaa-backlight-wmi.c | 185 ++++++++++++++++++++++
>  4 files changed, 208 insertions(+)
>  create mode 100644 drivers/platform/x86/wmaa-backlight-wmi.c
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index bbaecde94aa0..fd7362a86c6d 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -20008,6 +20008,12 @@ L:	linux-wireless@vger.kernel.org
>  S:	Odd fixes
>  F:	drivers/net/wireless/wl3501*
>  
> +WMAA BACKLIGHT DRIVER
> +M:	Daniel Dadap <ddadap@nvidia.com>
> +L:	platform-driver-x86@vger.kernel.org
> +S:	Supported
> +F:	drivers/platform/x86/wmaa-backlight-wmi.c
> +
>  WOLFSON MICROELECTRONICS DRIVERS
>  L:	patches@opensource.cirrus.com
>  S:	Supported
> diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
> index d12db6c316ea..0df908ef8d7c 100644
> --- a/drivers/platform/x86/Kconfig
> +++ b/drivers/platform/x86/Kconfig
> @@ -113,6 +113,22 @@ config PEAQ_WMI
>  	help
>  	 Say Y here if you want to support WMI-based hotkeys on PEAQ 2-in-1s.
>  
> +config WMAA_BACKLIGHT_WMI
> +	tristate "ACPI WMAA Backlight Driver"
> +	depends on ACPI_WMI
> +	depends on BACKLIGHT_CLASS_DEVICE
> +	help
> +	  This driver provides a sysfs backlight interface for notebook
> +	  systems which expose the WMAA ACPI method and an associated WMI
> +	  wrapper to drive LCD backlight levels through the system's
> +	  Embedded Controller (EC).
> +
> +	  Say Y or M here if you want to control the backlight on a notebook
> +	  system with an EC-driven backlight using the ACPI WMAA method.
> +
> +	  If you choose to compile this driver as a module the module will be
> +	  called wmaa-backlight-wmi.
> +
>  config XIAOMI_WMI
>  	tristate "Xiaomi WMI key driver"
>  	depends on ACPI_WMI
> diff --git a/drivers/platform/x86/Makefile b/drivers/platform/x86/Makefile
> index 7ee369aab10d..109c1714237d 100644
> --- a/drivers/platform/x86/Makefile
> +++ b/drivers/platform/x86/Makefile
> @@ -14,6 +14,7 @@ obj-$(CONFIG_INTEL_WMI_SBL_FW_UPDATE)	+= intel-wmi-sbl-fw-update.o
>  obj-$(CONFIG_INTEL_WMI_THUNDERBOLT)	+= intel-wmi-thunderbolt.o
>  obj-$(CONFIG_MXM_WMI)			+= mxm-wmi.o
>  obj-$(CONFIG_PEAQ_WMI)			+= peaq-wmi.o
> +obj-$(CONFIG_WMAA_BACKLIGHT_WMI)	+= wmaa-backlight-wmi.o
>  obj-$(CONFIG_XIAOMI_WMI)		+= xiaomi-wmi.o
>  obj-$(CONFIG_GIGABYTE_WMI)		+= gigabyte-wmi.o
>  
> diff --git a/drivers/platform/x86/wmaa-backlight-wmi.c b/drivers/platform/x86/wmaa-backlight-wmi.c
> new file mode 100644
> index 000000000000..cb1a973803b1
> --- /dev/null
> +++ b/drivers/platform/x86/wmaa-backlight-wmi.c
> @@ -0,0 +1,185 @@
> +// SPDX-License-Identifier: GPL-2.0-only
> +/*
> + * Copyright (c) 2020, NVIDIA CORPORATION.  All rights reserved.
> + */
> +
> +#include <linux/backlight.h>
> +#include <linux/module.h>
> +#include <linux/wmi.h>
> +
> +/**
> + * enum wmaa_method - WMI method IDs for ACPI WMAA
> + *
> + * @WMAA_LEVEL:  Get or set the brightness level,
> + *               or get the maximum brightness level.
> + * @WMAA_SOURCE: Get the source for backlight control.
> + */
> +enum wmaa_method {
> +	WMAA_LEVEL = 1,
> +	WMAA_SOURCE = 2,
> +};
> +
> +/**
> + * enum wmaa_get_or_set - Operation mode for ACPI WMAA method
> + *
> + * @WMAA_GET:     Get the current brightness level or backlight source.
> + * @WMAA_SET:     Set the brightness level.
> + * @WMAA_GET_MAX: Get the maximum brightness level. This is only valid when the
> + *                WMI method is %WMAA_LEVEL.
> + */
> +enum wmaa_get_or_set {
> +	WMAA_GET = 0,
> +	WMAA_SET = 1,
> +	WMAA_GET_MAX = 2
> +};
> +
> +/**
> + * enum wmaa_source - Backlight brightness control source identification
> + *
> + * @WMAA_SOURCE_GPU:   Backlight brightness is controlled by the GPU.
> + * @WMAA_SOURCE_EC:    Backlight brightness is controlled by the system's
> + *                     Embedded Controller (EC).
> + * @WMAA_SOURCE_AUX:   Backlight brightness is controlled over the DisplayPort
> + *                     AUX channel.
> + */
> +enum wmaa_source {
> +	WMAA_SOURCE_GPU = 1,
> +	WMAA_SOURCE_EC = 2,
> +	WMAA_SOURCE_AUX = 3
> +};
> +
> +/**
> + * struct wmaa_args - arguments for the ACPI WMAA method
> + *
> + * @set:     Pass in an &enum wmaa_get_or_set value to select between getting or
> + *           setting a value.
> + * @val:     In parameter for value to set when operating in %WMAA_SET mode. Not
> + *           used in %WMAA_GET or %WMAA_GET_MAX mode.
> + * @ret:     Out parameter returning retrieved value when operating in %WMAA_GET
> + *           or %WMAA_GET_MAX mode. Not used in %WMAA_SET mode.
> + * @ignored: Padding; not used. The ACPI method expects a 24 byte params struct.
> + *
> + * This is the parameters structure for the ACPI WMAA method as wrapped by WMI.
> + * The value passed in to @val or returned by @ret will be a brightness value
> + * when the WMI method ID is %WMAA_LEVEL, or an &enum wmaa_source value when
> + * the WMI method ID is %WMAA_SOURCE.
> + */
> +struct wmaa_args {
> +	u32 set;
> +	u32 val;
> +	u32 ret;
> +	u32 ignored[3];
> +};
> +
> +static int wmi_call_wmaa(struct wmi_device *w, enum wmaa_method method, enum wmaa_get_or_set set, u32 *val)
> +{
> +	struct wmaa_args args = {
> +		.set = set,
> +		.val = 0,
> +		.ret = 0,
> +	};
> +	struct acpi_buffer buf = { (acpi_size)sizeof(args), &args };
> +	acpi_status status;
> +
> +	if (set == WMAA_SET)
> +		args.val = *val;
> +
> +	status = wmidev_evaluate_method(w, 0, method, &buf, &buf);
> +	if (ACPI_FAILURE(status)) {
> +		dev_err(&w->dev, "ACPI WMAA failed with %s\n",
> +			acpi_format_exception(status));
> +		return -EIO;
> +	}
> +
> +	if (set != WMAA_SET)
> +		*val = args.ret;
> +
> +	return 0;
> +}
> +
> +static int wmaa_backlight_update_status(struct backlight_device *bd)
> +{
> +	struct wmi_device *wdev = bl_get_data(bd);
> +
> +	return wmi_call_wmaa(wdev, WMAA_LEVEL, WMAA_SET, &bd->props.brightness);
> +}
> +
> +static int wmaa_backlight_get_brightness(struct backlight_device *bd)
> +{
> +	struct wmi_device *wdev = bl_get_data(bd);
> +	u32 level = 0;
> +	int ret;
> +
> +	ret = wmi_call_wmaa(wdev, WMAA_LEVEL, WMAA_GET, &level);
> +
> +	if (ret)
> +		dev_err(&bd->dev, "ACPI WMAA failed to get backlight level.\n");
> +
> +	return level;
> +}
> +
> +static const struct backlight_ops wmaa_backlight_ops = {
> +	.update_status = wmaa_backlight_update_status,
> +	.get_brightness = wmaa_backlight_get_brightness
> +};
> +
> +static int wmaa_backlight_wmi_probe(struct wmi_device *w, const void *ctx)
> +{
> +	struct backlight_properties props = {};
> +	struct backlight_device *backlight;
> +	u32 source;
> +	int ret;
> +
> +	ret = wmi_call_wmaa(w, WMAA_SOURCE, WMAA_GET, &source);
> +	if (ret)
> +		return ret;
> +
> +	if (source != WMAA_SOURCE_EC) {
> +		/* This driver is only to be used when brightness control is
> +		 * handled by the EC; otherwise, the GPU driver(s) should handle
> +		 * brightness control. */
> +		return -ENODEV;
> +	}
> +
> +	/* Identify this backlight device as a platform device so that it can
> +	 * be prioritized over any exposed GPU-driven raw device(s). */
> +	props.type = BACKLIGHT_PLATFORM;
> +
> +	ret = wmi_call_wmaa(w, WMAA_LEVEL, WMAA_GET_MAX, &props.max_brightness);
> +	if (ret)
> +		return ret;
> +
> +	ret = wmi_call_wmaa(w, WMAA_LEVEL, WMAA_GET, &props.brightness);
> +	if (ret)
> +		return ret;
> +
> +	backlight = devm_backlight_device_register(
> +		&w->dev, "wmaa_backlight",
> +		&w->dev, w, &wmaa_backlight_ops, &props);
> +	if (IS_ERR(backlight))
> +		return PTR_ERR(backlight);
> +
> +	return 0;
> +}
> +
> +#define WMAA_WMI_GUID "603E9613-EF25-4338-A3D0-C46177516DB7"
> +
> +static const struct wmi_device_id wmaa_backlight_wmi_id_table[] = {
> +	{ .guid_string = WMAA_WMI_GUID },
> +	{ }
> +};
> +MODULE_DEVICE_TABLE(wmi, wmaa_backlight_wmi_id_table);
> +
> +static struct wmi_driver wmaa_backlight_wmi_driver = {
> +	.driver = {
> +		.name = "wmaa-backlight"
> +	},
> +	.probe = wmaa_backlight_wmi_probe,
> +	.id_table = wmaa_backlight_wmi_id_table
> +};
> +module_wmi_driver(wmaa_backlight_wmi_driver);
> +
> +MODULE_AUTHOR("Aaron Plattner <aplattner@nvidia.com>");
> +MODULE_AUTHOR("Daniel Dadap <ddadap@nvidia.com>");
> +MODULE_DESCRIPTION("WMAA Backlight WMI driver");
> +MODULE_LICENSE("GPL v2");
>