CC Benjamin On Sat, 29 Oct 2022 at 21:18, Andreas Bergmeier <abergmeier@xxxxxxx> wrote: > > On Sat, 29 Oct 2022 at 20:32, Pavel Machek <pavel@xxxxxx> wrote: > > Hmm, and there are likely to be more lights like this, right? > Indeed > > > I guess it makes sense to support this in LED subsystem. I believe it > > should be only supported for "white" LEDs. I believe first step is > > defining an userspace API in Documentation. > > RFC: I refined the RFC a bit more (was missing hw changes before): diff --git a/Documentation/leds/leds-class.rst b/Documentation/leds/leds-class.rst index cd155ead8703..c3645adfe12d 100644 --- a/Documentation/leds/leds-class.rst +++ b/Documentation/leds/leds-class.rst @@ -3,10 +3,13 @@ LED handling under Linux ======================== In its simplest form, the LED class just allows control of LEDs from -userspace. LEDs appear in /sys/class/leds/. The maximum brightness of the -LED is defined in max_brightness file. The brightness file will set the brightness +userspace. LEDs appear in ``/sys/class/leds/``. The maximum brightness of the +LED is defined in ``max_brightness`` file. The ``brightness`` file will set the brightness of the LED (taking a value 0-max_brightness). Most LEDs don't have hardware brightness support so will just be turned on for non-zero brightness settings. +If setting Color Temperature is supported there will be three files: ``color_temp``, +``lower_color_temp`` and ``upper_color_temp``. The acceptable values for ``color_temp`` are in the +range of (lower_color_temp-upper_color_temp). The class also introduces the optional concept of an LED trigger. A trigger is a kernel based source of led events. Triggers can either be simple or @@ -121,16 +124,29 @@ Brightness setting API LED subsystem core exposes following API for setting brightness: - - led_set_brightness: + - ``led_set_brightness``: it is guaranteed not to sleep, passing LED_OFF stops blinking, - - led_set_brightness_sync: + - ``led_set_brightness_sync``: for use cases when immediate effect is desired - it can block the caller for the time required for accessing device registers and can sleep, passing LED_OFF stops hardware blinking, returns -EBUSY if software blink fallback is enabled. +Color Temperature setting API +============================= + +LED subsystem core exposes following API for setting Color Temperature: + + - ``led_set_color_temp``: + it is guaranteed not to sleep + + - ``led_set_color_temp_sync``: + for use cases when immediate effect is desired - + it can block the caller for the time required for accessing + device registers and can sleep. It returns -EBUSY if + software blink fallback is enabled. LED registration API ==================== @@ -138,14 +154,20 @@ LED registration API A driver wanting to register a LED classdev for use by other drivers / userspace needs to allocate and fill a led_classdev struct and then call `[devm_]led_classdev_register`. If the non devm version is used the driver -must call led_classdev_unregister from its remove function before -free-ing the led_classdev struct. +must call ``led_classdev_unregister`` from its remove function before +free-ing the ``led_classdev`` struct. If the driver can detect hardware initiated brightness changes and thus -wants to have a brightness_hw_changed attribute then the LED_BRIGHT_HW_CHANGED +wants to have a ``brightness_hw_changed`` attribute then the ``LED_BRIGHT_HW_CHANGED`` +flag must be set in flags before registering. Calling +``led_classdev_notify_brightness_hw_changed`` on a classdev not registered with +the ``LED_BRIGHT_HW_CHANGED`` flag is a bug and will trigger a WARN_ON. + +If the driver can detect hardware initiated color temperature changes and thus +wants to have a ``color_temp_hw_changed`` attribute then the ``LED_COLOR_TEMP_HW_CHANGED`` flag must be set in flags before registering. Calling -led_classdev_notify_brightness_hw_changed on a classdev not registered with -the LED_BRIGHT_HW_CHANGED flag is a bug and will trigger a WARN_ON. +``led_classdev_notify_color_temp_hw_changed`` on a classdev not registered with +the ``LED_COLOR_TEMP_HW_CHANGED`` flag is a bug and will trigger a WARN_ON. Hardware accelerated blink of LEDs ==================================
