[PATCH v3 0/5] platform/x86: asus-wmi: TUF keyboard shutdown naming and RGB readback

[Bartu Alev <bartualev@gmail.com>]

This series fixes the name of the fourth TUF keyboard power state and
makes the TUF keyboard RGB attributes readable.

The fourth flag of kbd_rgb_state was labelled "keyboard" and treated as
a no-op since it was introduced.  In hardware it gates the backlight
during the ACPI S5 power-off sequence: with the bit set the keyboard
lights up white while the machine powers off, with the bit clear the
machine powers off dark.  Patch 2 renames the field and carries a Fixes
tag for stable.

The remaining patches prepare and add readback.  DSTS device 0x0010005B
evaluates the DSDT method EC0.KBLS(), which returns a 16-byte snapshot
of the EC's keyboard state: lighting mode, red, green and blue levels,
animation speed, and the four power flags.  Both kbd_rgb_mode and
kbd_rgb_state become readable and report the write format with the
command word fixed at 1.

Responses to the v2 review:

Ilpo:
- Documentation: patch 5 adds the missing ABI entries.
- Errno: the helper already separates the cases.
  asus_wmi_evaluate_method_buf() returns -EIO for a failed evaluation
  and -ENODEV for an unsupported DEVID.  The readback keeps the
  err < 0 ? err : -ENODEV normalization for the positive ACPI integers
  that leak through, and the AML signature check returns -ENODEV as
  well.
- Named defines: patch 3 names the three speed codes and the four state
  bits, and the decoding comments are gone.
- Struct: patch 4 parses the status buffer through a packed struct.

Denis:
- DEVID naming: the write DEVID is now ASUS_WMI_DEVID_TUF_RGB_CMD
  (patch 1) and the read DEVID is ASUS_WMI_DEVID_TUF_RGB_READ_STATUS,
  as you suggested.
- -ENODATA: asus_wmi_evaluate_method_buf() already returns -ENODATA for
  empty buffers, so no extra handling was added.

Provenance: the KBLS buffer layout and the speed-code semantics were
recovered by static analysis of the EC firmware (ITE IT5570VG),
assisted by an LLM-driven toolchain; the readback patch carries an
Assisted-by tag.  Tested on a TUF Gaming A15 (FA507NV): the v2
readback on kernel 7.2.6, and the S5 behaviour of the shutdown flag by
A/B testing both values.

Changes in v3, relative to v2:
- split into five patches, one logical change each
- renamed the write DEVID to ASUS_WMI_DEVID_TUF_RGB_CMD and the new one
  to ASUS_WMI_DEVID_TUF_RGB_READ_STATUS, per Denis Benato
- named the speed codes and the power state bits and dropped the
  decoding comments
- parse the status buffer through a packed struct
- added the ABI documentation, with the attributes documented at their
  real location under /sys/class/leds/asus::kbd_backlight/ and worded
  for all laptops that expose the zonal RGB devices, not only TUF
  models
- added linux-api to Cc, which the earlier versions missed

v2: https://lore.kernel.org/all/20260926005625.171560-1-bartualev@gmail.com/
v1: https://lore.kernel.org/all/20260925200744.129714-1-bartualev@gmail.com/

Bartu Alev (5):
  platform/x86: asus-wmi: rename TUF RGB state DEVID to _CMD
  platform/x86: asus-wmi: fix TUF keyboard power state shutdown naming
  platform/x86: asus-wmi: name the TUF keyboard RGB state and speed
    codes
  platform/x86: asus-wmi: add TUF keyboard RGB readback support
  Documentation/ABI: asus-wmi: document TUF keyboard RGB attributes

 .../ABI/testing/sysfs-platform-asus-wmi       |  42 ++++++
 drivers/platform/x86/asus-wmi.c               | 123 +++++++++++++++---
 include/linux/platform_data/x86/asus-wmi.h    |   5 +-
 3 files changed, 153 insertions(+), 17 deletions(-)


base-commit: af32da41b0327b9c6a37856ba82b6760d6c8d10e
-- 
2.56.0