Am 20.03.24 um 12:16 schrieb Werner Sembach:
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.
Is this what I have been searching for? https://docs.kernel.org/usb/gadget_hid.html
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
