leds: dynamic: Add Dynamic Lighting class interface and Aura (hid-asus) support by scardracs · Pull Request #17 · OpenGamingCollective/linux-unstable

scardracs · 2026-09-04T19:39:14Z

Summary

This pull request introduces the Dynamic Lighting LED class to the kernel and adds driver support in hid-asus for ASUS ROG Aura keyboards and chassis lightbars.
It provides a standard sysfs ABI for devices that expose multi-zone effects, palette programming, direct RGB frame streaming, and lighting power-state persistence, without requiring individual drivers to invent ad-hoc sysfs layouts.

NOTE: due to heavy work on both here and linux the text on that OP can or cannot be accurate

Commits Overview

leds: Add LED_DYNAMIC_LIGHTING flag to LED core
- Defines LED_DYNAMIC_LIGHTING in struct led_classdev to enable runtime identification of Dynamic Lighting class devices, following the pattern of LED_MULTI_COLOR.
leds: dynamic: Add Dynamic Lighting core class interface
- Implements the new class (drivers/leds/led-class-dynamic.c, include/linux/led-dynamic-lighting.h) extending led_classdev.
- Exposes common effect, speed, direction, and power-state controls, plus binary direct-buffer and frame write interfaces.
- Serializes writes using led_access and the class mutex to ensure thread safety alongside LED triggers.
docs: leds: Document the Dynamic Lighting class ABI
- Documents the user-facing sysfs interface in Documentation/ABI/testing/sysfs-class-leds-dynamic and Documentation/leds/leds-class-dynamic.rst.
- Updates Documentation/leds/index.rst and registers the subsystem files in MAINTAINERS.
HID: asus: Add Dynamic Lighting support for Aura devices
- Integrates Dynamic Lighting support into hid-asus.
- Discovers keyboard layout and chassis lightbar zones via the Aura probe report.
- Implements zone power unmasking (0xbd), zone activation (0xc0), and hardware effect engine programming (0xb3) with the firmware latch commit sequence (0xb5 SET -> 0xb4 COMMIT -> 0xb5 SET).
- Supports direct per-key/lightbar packed RGB frame writes through the class direct-buffer streaming interface.
- Fully preserves backward compatibility with the existing asus::kbd_backlight brightness control.

scardracs · 2026-09-05T20:40:50Z

I've moved the patch to 7.2 in order to have some stability (7.3 is way too bugged as for now). When the situation will be better I'll move it back to 7.3. I leave that draft open for now

scardracs · 2026-09-08T18:31:31Z

Added an aura:global that controls both keyboard and lightbar for those devices that don't have the ability to control them separately

cifs.idmap key descriptions carry authority-bearing fields (owner and group SIDs and uid/gid values in "os:"/"gs:"/"oi:"/"gi:" form) that the cifs.idmap upcall helper treats as kernel-originating inputs. Unlike its sibling cifs.spnego, the cifs.idmap key type has no vet_description hook, so userspace can create keys of this type through request_key(2)/add_key(2) and supply those fields without CIFS origin. A request_key(2) call with a non-NULL callout then drives a root usermodehelper upcall (/sbin/request-key -> cifs.idmap) that consumes the unvetted description in root context. Only accept cifs.idmap descriptions while CIFS is using its private root_cred to request the key. id_to_sid()/sid_to_id() already run under override_creds(root_cred), so the kernel-originated path is unaffected. This mirrors commit 3da1fdf ("smb: client: reject userspace cifs.spnego descriptions"), which applied the same restriction to cifs.spnego. Fixes: 4d79dba ("cifs: Add idmap key and related data structures and functions (try OpenGamingCollective#17 repost)") Reported-by: TencentOS Corvus AI <corvus@tencent.com> Cc: stable@vger.kernel.org Assisted-by: CodeBuddy:Kimi-K3 Signed-off-by: Aohan Mei <henrymei@tencent.com> Acked-by: David Howells <dhowells@redhat.com> Signed-off-by: Paulo Alcantara <pc@manguebit.org>

Add a dedicated Dynamic Lighting LED class for devices that expose multi-LED effects, palette programming, direct frame streaming or lighting state persistence through sysfs. Define LED_DYNAMIC_LIGHTING on struct led_classdev for runtime type identification, matching the established LED_MULTI_COLOR pattern. The new class extends struct led_classdev with common effect, speed, direction and power-state controls, plus binary write interfaces for packed RGB frames and device-specific frame payloads. Registration validates the exported capabilities, exposes only the attributes implemented by the driver, and serializes writes under led_access and the class-private lock so drivers can coexist safely with LED triggers. After a successful direct_write the class sets current_effect to DIRECT when that effect is advertised, so drivers must not mutate it before the HID/USB write succeeds. This provides a common kernel ABI for complex lighting devices without requiring each driver to invent its own sysfs layout. Signed-off-by: Marco Scardovi <scardracs@disroot.org>

Document the Dynamic Lighting LED class ABI and user-facing sysfs interface. Describe the common attributes, the visibility rules for optional controls, the discoverability attributes used by programmable devices, and the write semantics for the direct and frame binary interfaces. Writing power_states replaces the active bitmask (an empty list clears all enabled states). Also add the new document to the LED documentation index and register it in MAINTAINERS. Signed-off-by: Marco Scardovi <scardracs@disroot.org>

…osures ASUS ROG external NVMe enclosures (such as the ROG STRIX Arion, USB ID 0b05:1932) are USB mass-storage devices with no HID interface. Their addressable Aura RGB LEDs hang off an onboard ENE microcontroller driven via 16-byte vendor SCSI commands on the same LUN as the storage. Add the leds-asus-aura-scsi driver using a class_interface registered with the SCSI class. Its add callback matches INQUIRY vendor "ROG" and model "ESD-S1C", retains the SCSI device while the LED is registered, and leaves disk ownership and access untouched for the sd driver. Each matching enclosure exposes a uniquely named Dynamic Lighting device: asus-aura-scsi-<H_C_T_L>:rgb:indicator. Hardware animation offloads (Off, Static, Breathing, Strobe, Spectrum Cycle, Rainbow, Direct streaming), speed (0..4), direction (right/left), palette, and direct RGB frame streaming via direct_buffer are fully integrated. direct_write updates current_mode after a successful apply. Enable CONFIG_LEDS_ASUS_AURA_SCSI=m in the OGC packaging fragment so the driver ships in linux-unstable-ogc. Signed-off-by: Marco Scardovi <scardracs@disroot.org>

USB ID 0x193b is shared by standalone Slash MCUs and AniMe Matrix panels. Bind it only when the interface exposes Aura/Slash LED reports (0x5d/0x5e) or a sibling HID LampArray lighting interface. Detect LampArray by report IDs on usage page 0x59 and start that interface without hidraw so lighting is not exported to userspace. Firmware animations stay on the Aura 0x5d interface; Aura 0xBC remains the fallback when LampArray is absent. Signed-off-by: Marco Scardovi <scardracs@disroot.org>

Add Dynamic Lighting class support to hid-asus for Aura-capable ROG keyboards and chassis lightbars. Discover Aura layout, lightbar, and per-key/direct RGB from HID feature reports rather than DMI board lists. Register aura:global, aura:keyboard and aura:lightbar with aura_mode (auto/unified/split). auto resolves to split so keyboard and lightbar stay independently writable. Advertise DIRECT when the keyboard path supports direct RGB. Drive firmware effects with Aura 0xb3/0xb4/0xb5 and solid/direct frames with Aura 0xBC. Map boot/awake/sleep/shutdown via power_states to AURA_CMD_POWER (0xbd) without rewriting zone power from brightness or resume. Keep asus::kbd_backlight brightness behaviour unchanged. Signed-off-by: Marco Scardovi <scardracs@disroot.org>

On N-KEY devices where Aura 0xBC cannot drive the chassis lightbar independently, use the sibling HID LampArray interface as the in-kernel direct-RGB backend and drop the owner reference on unbind. Linux Dynamic Lighting sysfs remains the userspace ABI. Fall back to Aura 0xBC when LampArray is absent. Firmware animations stay on Aura 0xb3. Signed-off-by: Marco Scardovi <scardracs@disroot.org>

Register Slash when feature report 0x5e is present, or on USB 0x193b when Aura LED report 0x5d exists. Identify Slash from HID reports, never from DMI board lists. Expose asus::slash with mode, interval and brightness controls using the Aura feature-report path already used for keyboard lighting. Signed-off-by: Marco Scardovi <scardracs@disroot.org>

Expose Dynamic Lighting class attributes on asus::kbd_backlight when TUF RGB control is supported (kbd_rgb_dev). Register via devm_led_classdev_dynamic_register with effects, speed, palette, and power-state persistence through ACPI WMI methods. Map DL_POWER_STATE_* bits directly; they are already BIT(n) values. Always initialize the keyboard LED cdev name before queuing registration work so HID listener registration cannot oops on a NULL name when WMI kbd backlight setup was skipped. Preserve legacy kbd_rgb_mode and kbd_rgb_state sysfs attributes for backward compatibility. Signed-off-by: Marco Scardovi <scardracs@disroot.org>

pastaq

I'm concerned that this implementation is too restrictive. I was under the impression that the classdev would outline the shape of the ABI, and a generic implementation would also exist that would implement them. Currently I don't see how I can transition the existing hid-[lenovo-go*|oxp|msi] drivers to this which need more dynamic ability to describe built in effects. Ideally this could be a drop in replacement where I just need to define the index/range for each and assign function pointers like I do with brightness/multi_intensity.

pastaq · 2026-09-18T17:16:19Z

+Description:	read
+		Space-separated list of animation effect names supported by
+		the hardware or driver (not numeric indices). Possible names
+		include: "off", "static", "breathing", "strobe",


hid-oxp has a lot more than this. IMO the specific effects should be arbitrarily assignable as different devices will have different needs

pastaq · 2026-09-18T17:16:51Z

+		effect. Any active trigger is automatically detached upon
+		switching effects to prevent lock conflicts.
+
+What:		/sys/class/leds/<led>/speed_range


sort attrs alphabetically, this should be below speed

Same for others in this file

pastaq · 2026-09-18T17:20:19Z

+6. Release outer mutex: ``mutex_unlock(&cdev->led_access)``.
+
+Driver callbacks must not persist class-owned fields (``current_effect``,
+``speed``, palette, ``active_power_states``) on failure; the core writes those


missing `` on palette

pastaq · 2026-09-18T17:22:34Z

+
+``effect_index`` (read-only)
+    Space-separated list of animation effect names supported by the hardware
+    (not numeric indices). Names include: ``off``, ``static``, ``breathing``,


current ABI uses monocolor and breathe, and a separate enabled (true/false) attr for "off"

pastaq · 2026-09-18T17:23:12Z

 #define USB_DEVICE_ID_ASUSTEK_ROG_KEYBOARD2 0x1837
 #define USB_DEVICE_ID_ASUSTEK_ROG_KEYBOARD3 0x1822
 #define USB_DEVICE_ID_ASUSTEK_ROG_NKEY_KEYBOARD	0x1866
+/* 0x193b is also AniMe Matrix; hid-asus binds it only when Aura/Slash LED reports exist. */


It's a led stripe on the back of certain asus laptops

scardracs · 2026-09-18T18:01:55Z

I'm concerned that this implementation is too restrictive. I was under the impression that the classdev would outline the shape of the ABI, and a generic implementation would also exist that would implement them. Currently I don't see how I can transition the existing hid-[lenovo-go*|oxp|msi] drivers to this which need more dynamic ability to describe built in effects. Ideally this could be a drop in replacement where I just need to define the index/range for each and assign function pointers like I do with brightness/multi_intensity.

I totally get your point: I tried to make it working for ASUS as it is the only machine I own but I understand that it needs to work on all the OEMs without the need to bend the drivers. I'll look into it and see if I can follow a way that can be agnostic for everyone as much as possible

scardracs force-pushed the leds/dynamic-lighting branch 4 times, most recently from 005fb1f to c6ee973 Compare September 5, 2026 12:09

NeroReflex reviewed Sep 5, 2026

View reviewed changes

Comment thread drivers/leds/led-class-dynamic.c Outdated

scardracs force-pushed the leds/dynamic-lighting branch from c6ee973 to 2ce82cc Compare September 5, 2026 14:23

pastaq reviewed Sep 7, 2026

View reviewed changes

Comment thread Documentation/ABI/testing/sysfs-class-leds-dynamic Outdated

scardracs force-pushed the leds/dynamic-lighting branch 2 times, most recently from 45f6a76 to 1a38a2e Compare September 8, 2026 14:19

scardracs changed the title ~~Leds/dynamic lighting~~ leds: dynamic: Add Dynamic Lighting class interface and Aura (hid-asus) support Sep 8, 2026

scardracs force-pushed the leds/dynamic-lighting branch from 1a38a2e to 4e550e9 Compare September 8, 2026 18:30

scardracs mentioned this pull request Sep 8, 2026

feat(aura): support Dynamic Lighting sysfs interface with hidraw fallback OpenGamingCollective/asusctl#369

Draft

7 tasks

scardracs force-pushed the leds/dynamic-lighting branch 4 times, most recently from 3a706b9 to a4d18f6 Compare September 9, 2026 07:42

scardracs force-pushed the leds/dynamic-lighting branch 4 times, most recently from fb74985 to 907aeed Compare September 13, 2026 10:23

scardracs force-pushed the leds/dynamic-lighting branch 2 times, most recently from 99b29b1 to 9b2b6fd Compare September 18, 2026 13:55

scardracs added 2 commits September 18, 2026 15:59

scardracs force-pushed the leds/dynamic-lighting branch 2 times, most recently from 7d4bd15 to 3b75011 Compare September 18, 2026 14:12

scardracs marked this pull request as ready for review September 18, 2026 14:13

scardracs added 6 commits September 18, 2026 16:20

scardracs force-pushed the leds/dynamic-lighting branch from 3b75011 to 5a77b23 Compare September 18, 2026 14:21

pastaq reviewed Sep 18, 2026

View reviewed changes

Navigation Menu

leds: dynamic: Add Dynamic Lighting class interface and Aura (hid-asus) support - #17

leds: dynamic: Add Dynamic Lighting class interface and Aura (hid-asus) support#17
scardracs wants to merge 8 commits into
OpenGamingCollective:masterfrom
scardracs:leds/dynamic-lighting

scardracs commented Sep 4, 2026 •

edited

Loading

Uh oh!

Uh oh!

scardracs commented Sep 5, 2026

Uh oh!

Uh oh!

scardracs commented Sep 8, 2026

Uh oh!

pastaq left a comment

Uh oh!

pastaq Sep 18, 2026

Uh oh!

pastaq Sep 18, 2026

Uh oh!

pastaq Sep 18, 2026

Uh oh!

pastaq Sep 18, 2026

Uh oh!

pastaq Sep 18, 2026

Uh oh!

NeroReflex Sep 18, 2026

Uh oh!

scardracs commented Sep 18, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

scardracs commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Commits Overview

Uh oh!

Uh oh!

scardracs commented Sep 5, 2026

Uh oh!

Uh oh!

scardracs commented Sep 8, 2026

Uh oh!

pastaq left a comment

Choose a reason for hiding this comment

Uh oh!

pastaq Sep 18, 2026

Choose a reason for hiding this comment

Uh oh!

pastaq Sep 18, 2026

Choose a reason for hiding this comment

Uh oh!

pastaq Sep 18, 2026

Choose a reason for hiding this comment

Uh oh!

pastaq Sep 18, 2026

Choose a reason for hiding this comment

Uh oh!

pastaq Sep 18, 2026

Choose a reason for hiding this comment

Uh oh!

NeroReflex Sep 18, 2026

Choose a reason for hiding this comment

Uh oh!

scardracs commented Sep 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

scardracs commented Sep 4, 2026 •

edited

Loading

scardracs commented Sep 18, 2026 •

edited

Loading