Re: [PATCH v4 2/2] HP: wmi: Add documentation for the LED API naming scheme

[Hans de Goede <hdegoede@redhat.com>]

Hi all,

+Cc Pavel, Lee, linux-leds for review by the linux LED subsystem folks.

Pavel, Lee there are 2 pdx86 drivers for control of zoned (3/4 zones)
RGB backlit laptop keyboards pending:

https://lore.kernel.org/platform-driver-x86/20240719100011.16656-2-carlosmiguelferreira.2003@gmail.com/
https://lore.kernel.org/platform-driver-x86/20240806205001.191551-2-mustafa.eskieksi@gmail.com/

both of these will use 1 multicolor LED class device per keyboard zone,
using the naming convention documented in this patch.

It would be good if we can get feedback or an ack from you for this
userspace API before merging these drivers.

Note the first part of the patch documents the already existing naming
scheme for single zone (RGB or mono color) backlight keyboards. This
scheme is already used by many drivers and by userspace consumers like
upower. So this is just documenting existing userspace API which so far
was not documented.


Carlos, Thank you for writing this patch.

For v2 please change the patch subject to:

"Documentation: leds: leds-class: Add documentation for keyboard backlight LED device names"

and this should also be merged through the LED subsystem tree, so for v2
please send this to Pavel + Lee with linux-leds + platform-driver-x86
in the Cc.


On 7/19/24 11:59 AM, Carlos Ferreira wrote:
> This patch adds documentation for the LED API class-device naming
> scheme practice.
>
> Signed-off-by: Carlos Ferreira <carlosmiguelferreira.2003@gmail.com>
> ---
>  Documentation/leds/leds-class.rst | 40 +++++++++++++++++++++++++++++++
>  1 file changed, 40 insertions(+)
> 
> diff --git a/Documentation/leds/leds-class.rst b/Documentation/leds/leds-class.rst
> index 5db620ed27aa..8e74a436ca9b 100644
> --- a/Documentation/leds/leds-class.rst
> +++ b/Documentation/leds/leds-class.rst
> @@ -116,6 +116,46 @@ above leaves scope for further attributes should they be needed. If sections
>  of the name don't apply, just leave that section blank.
>  
>  
> +Keyboard backlight control
> +==========================
> +
> +For backlit keyboards with a single brightness / color settings a
> +single (multicolor) LED device should be used to allow userspace
> +to change the backlight brightness (and if possible the color).
> +This LED device must have a name ending in ':kbd_backlight'.
> +
> +For RGB backlit keyboards with multiple control zones, one multicolor
> +LED device should be used per zone. These LED devices' name
> +must follow the following form:
> +
> +	"<devicename>:rgb:kbd_zoned_backlight-<zone_name>"
> +
> +and <devicename> must be the same for all zones of the same keyboard.
> +
> +Where possible <zone_name> should be a value already used by other
> +zoned keyboards with a similar or identical zone layout, e.g.:
> +
> +<devicename>:rgb:kbd_zoned_backlight-right
> +<devicename>:rgb:kbd_zoned_backlight-middle
> +<devicename>:rgb:kbd_zoned_backlight-left
> +<devicename>:rgb:kbd_zoned_backlight-corners

The -corners zone was based on a misunderstanding about
the Excaliber laptop's functionality, please drop
the "<devicename>:rgb:kbd_zoned_backlight-corners"
line here as well as below.

Regards,

Hans



> +<devicename>:rgb:kbd_zoned_backlight-wasd
> +
> +or:
> +
> +<devicename>:rgb:kbd_zoned_backlight-main
> +<devicename>:rgb:kbd_zoned_backlight-cursor
> +<devicename>:rgb:kbd_zoned_backlight-numpad
> +<devicename>:rgb:kbd_zoned_backlight-corners
> +<devicename>:rgb:kbd_zoned_backlight-wasd
> +
> +Note that this is intended for keyboards with a limited number of zones,
> +keyboards with per key addressable backlighting must not use LED
> +class devices since the sysfs API is not suitable for rapidly change
> +multiple LEDs in one "commit" as is necessary to do animations /
> +special effects on such keyboards.
> +
> +
>  Brightness setting API
>  ======================
>