Re: Future handling of complex RGB devices on Linux v3

From: Werner Sembach
Date: Wed Mar 20 2024 - 07:17:56 EST


Hi Hans and the others,

Am 22.02.24 um 14:14 schrieb Werner Sembach:
Hi,

Thanks everyone for the exhaustive feedback. And at least this thread is a good comprehesive reference for the future ^^.

To recap the hopefully final UAPI for complex RGB lighting devices:

- By default there is a singular /sys/class/leds/* entry that treats the device as if it was a single zone RGB keyboard backlight with no special effects.

- There is an accompanying misc device with the sysfs attributes "name", "device_type",  "firmware_version_string", "serial_number" for device identification and "use_leds_uapi" that defaults to 1.

    - If set to 0 the /sys/class/leds/* entry disappears. The driver should keep the last state the backlight was in active if possible.

    - If set 1 it appears again. The driver should bring it back to a static 1 zone setting while avoiding flicker if possible.

- If the device is not controllable by for example hidraw, the misc device might also implement additional ioctls or sysfs attributes to allow a more complex low level control for the keyboard backlight. This is will be a highly vendor specific UAPI.
So in the OpenRGB issue thread https://learn.microsoft.com/en-us/windows-hardware/design/component-guidelines/dynamic-lighting-devices aka HID LampArray was mentioned. I did dismiss it because I thought that is only relevant for firmware, but I now stumbled upon the Virtual HID Framework (VHF) https://learn.microsoft.com/en-us/windows-hardware/drivers/hid/virtual-hid-framework--vhf- and now I wonder if an equivalent exists for Linux? A quick search did not yield any results for me.

If a virtual HID device is possible and the WMI interface can reasonably be mapped to the LampArray API this might be the best starting point:

- Implement a Virtual HID device with LampArray

- Implement LampArray in OpenRGB

- (Optional) Implement a generic LampArray leds subsystem driver that maps to the single zone control and ads the use_leds_uapi sysfs switch to the virtual HID device

- (Optional) Implement vendor specific controls for AutonomousMode/built-in-firmware-effects via custom HID commands

- (Optional) Implement Virtual HID devices for actual HID devices that don't support LampArray in firmware (Open question: How to prevent userspace/OpenRGB from interacting with original HID when the virtual HID device is not in AutonomousMode? How to associate the original and virtual HID device to each other that userspace can easily recognize this relation? Or is it possible to add virtual HID commands on top of a real HID device, making it look exactly like the pure virtual devices for userspace?)

The LampArray API hereby is made with the intention to be used for multi leds devices, like per-key-backlight keyboards, unlike the leds UAPI. And it is coming anyway with new RGB devices soon. So it would not conflict with a "don't introduce unnecessary UAPI interfaces" principle. Are there any plans already of Wrapping LampArray in some kind ioctl/sysfs API? Or just have it used via hidraw? Or was there no discussion about it till now?

Regards,

Werner


    - The actual logic interacting with this low level UAPI is implemented by a userspace driver

Implementation wise: For the creation of the misc device with the use_leds_uapi switch a helper function/macro might be useful? Wonder if it should go into leds.h, led-class-multicolor.h, or a new header file?

- Out of my head it would look something like this:

led_classdev_add_optional_misc_control(
    struct led_classdev *led_cdev,
    char* name,
    char* device_type,
    char* firmware_version_string,
    char* serial_number,
    void (*deregister_led)(struct led_classdev *led_cdev),
    void (*reregister_led)(struct led_classdev *led_cdev))

Let me know your thoughts and hopefully I can start implementing it soon for one of our devices.

Kind regards,

Werner Sembach