Re: [PATCH 1/1] Documentation: leds: leds-class: Document keyboard backlight LED class naming

[Hans de Goede <johannes.goede@oss.qualcomm.com>]

Hi Lee,

On 30-Apr-26 11:25 AM, Lee Jones wrote:
> On Mon, 06 Apr 2026, Hans de Goede wrote:
> 
>> From: Carlos Ferreira <carlosmiguelferreira.2003@gmail.com>
>>
>> Document the existing practice of always using 'kbd_backlight' for
>> the function part of LED class device names for LED class devices which
>> control single-zone keyboard backlights.
>>
>> Also extend this existing practice with a new naming scheme for keyboards
>> with zoned backlight control. There are several drivers in the works (see
>> the Link:tags below) which offer backlight control for keyboards where
>> the keyboard backlight is divided in a limited number of zones, e.g.
>> "main", "cursor" and "numpad" zones.
>>
>> It is important to agree on a consistent naming scheme for these now,
>> so that userspace can support multiple different models / vendors through
>> a single unified naming scheme.
>>
>> Link: https://lore.kernel.org/platform-driver-x86/20230131235027.36304-1-rishitbansal0@gmail.com/
>> Link: https://lore.kernel.org/platform-driver-x86/20240719100011.16656-1-carlosmiguelferreira.2003@gmail.com/
>> Link: https://lore.kernel.org/platform-driver-x86/20260304105831.119349-3-edip@medip.dev/
>> Link: https://lore.kernel.org/platform-driver-x86/20240806205001.191551-2-mustafa.eskieksi@gmail.com/
>> Link: https://lore.kernel.org/linux-input/20260402075239.3829699-1-xav@bes.tel/
>> Signed-off-by: Carlos Ferreira <carlosmiguelferreira.2003@gmail.com>
>> Co-authored-by: Hans de Goede <johannes.goede@oss.qualcomm.com>
>> Signed-off-by: Hans de Goede <johannes.goede@oss.qualcomm.com>
> 
> The premise is fine I think.

Great, thank you for taking a look.

>> ---
>>  Documentation/leds/leds-class.rst | 63 +++++++++++++++++++++++++++++++
>>  1 file changed, 63 insertions(+)
>>
>> diff --git a/Documentation/leds/leds-class.rst b/Documentation/leds/leds-class.rst
>> index 5db620ed27aa..d2b042519a66 100644
>> --- a/Documentation/leds/leds-class.rst
>> +++ b/Documentation/leds/leds-class.rst
>> @@ -116,6 +116,69 @@ 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 LED Device Naming
>> +============================================
>> +
>> +For backlit keyboards with a single brightness / color settings a single
>> +(multicolor) LED class device should be used to allow userspace to change
>> +the backlight brightness (and if possible the color). This LED class device
>> +must use "kbd_backlight" for the function part of the LED class device name.
>> +IOW the name must end with ":kbd_backlight".
>> +
>> +For backlit keyboards with multiple control zones, one (multicolor) LED class
>> +device should be used per zone. These LED class devices' name must follow:
>> +
>> +	"<devicename>:<color>:kbd_zoned_backlight-<zone_name>"
>> +
>> +and <devicename> must be the same for all zones of the same keyboard.
>> +
>> +<zone_name> should be descriptive of which part of the keyboard backlight
>> +the zone covers and should be suitable for userspace to show to an end user
>> +in an UI for controlling the zones.
>> +
>> +Where possible <zone_name> should be a value already used by other
>> +zoned keyboards with a similar or identical zone layout, e.g.:
>> +
>> +<devicename>:<color>:kbd_zoned_backlight-right
>> +<devicename>:<color>:kbd_zoned_backlight-middle
>> +<devicename>:<color>:kbd_zoned_backlight-left
>> +<devicename>:<color>:kbd_zoned_backlight-corners
>> +<devicename>:<color>:kbd_zoned_backlight-wasd
>> +
>> +or:
>> +
>> +<devicename>:<color>:kbd_zoned_backlight-main
>> +<devicename>:<color>:kbd_zoned_backlight-cursor
>> +<devicename>:<color>:kbd_zoned_backlight-numpad
>> +<devicename>:<color>:kbd_zoned_backlight-corners
>> +<devicename>:<color>: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.
>> +
>> +An exception to the rule that all zones must follow:
>> +
>> +	"<devicename>:<color>:kbd_zoned_backlight-<zone_name>"
>> +
>> +is made for the special case where there is a single big zone which controls
>> +the backlighting of almost all of the keyboard and there are some small areas
>> +with separate control, like just the 4 cursor keys, or the WASD keys. In this
>> +case the main zone should use 'kbd_backlight' for the function part of the name
>> +for compatiblity with (older) userspace code which is not aware of
> 
> Nit: compatibility
> 
> There may be others.  Please run it through a spell checker.

Ack, I'll send a v2 fixing this. I've run the patch through hunspell and this
was the only spelling issue it found.

Regards,

Hans


> 
>> +the "kbd_zoned_backlight-<zone_name>" function naming scheme.
>> +
>> +While the smaller zones should use the new zoned naming scheme. Such a setup
>> +would result in e.g.:
>> +
>> +<devicename>:<color>:kbd_backlight
>> +<devicename>:<color>:kbd_zoned_backlight-wasd
>> +
>> +"kbd_zoned_backlight-<zone_name>" aware userspace should be aware of this
>> +exception and check for a main zone with a "kbd_backlight" function-name.
>> +
>> +
>>  Brightness setting API
>>  ======================
>>  
>> -- 
>> 2.53.0
>>
>