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

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

[Hans de Goede]

Hi All,

Over the last couple of years there have been several attempts to add
upstream kernel support for controlling keyboard backlights consisting of
a small number of backlight zones, think e.g. : "main", "cursor" and
"keypad" zones.

All of these attempts have gotten or are stuck on the lack of consensus on
a userspace API (1) for controlling such zoned keyboard backlights.

Previous discussion can be summarized as there being consensus that
these backlights should be represented as (multi-color) LED class devices
with one LED class device per zone, mirroring the existing use of
a LED class device for controlling single zone keyboard backlights.

The only thing which really still needs to be agreed upon is a naming
scheme for the per zone LED class devices so that userspace can detect:

1. That the function of these is to control a zoned keyboard backlight.
2. How to group the per zone devices together for a single keyboard.

The single patch in this series documents the currently undocumented naming
scheme for single zone keyboard backlights and extends this with a naming
scheme to use for multi-zone keyboard backlights.

This is send out as a separate patch rather then as part of a series
implementing this in the hope to get multiple drivers which are in
the process of being upstreamed unstuck wrt the LED class naming problem.

Drivers which need this are:

1. HP WMI laptop driver Omen gaming keyboards backlight control support:
First 2023 attempt:
https://lore.kernel.org/platform-driver-x86/20230131235027.36304-1-rishitbansal0@gmail.com/
Later 2024 attempt which includes an earlier version of this doc patch:
https://lore.kernel.org/platform-driver-x86/20240719100011.16656-1-carlosmiguelferreira.2003@gmail.com/
Current ongoing 2026 attempt:
https://lore.kernel.org/platform-driver-x86/20260304105831.119349-3-edip@medip.dev/

2. Casper Excalibur laptop driver (inc. multi-zone kbd backlight control):
https://lore.kernel.org/platform-driver-x86/20240806205001.191551-2-mustafa.eskieksi@gmail.com/
This one unfortunately seems to have stalled.

3. Logitech G710/G710+ gaming keyboards HID driver:
https://lore.kernel.org/linux-input/20260402075239.3829699-1-xav@bes.tel/
Posted a week ago, needs an agreement on the LED class dev naming scheme
to continue.

Regards,

Hans


1) The lack of such an API may not always have been the sole reason these
drivers have gotten stuck, but it was always a factor.


Carlos Ferreira (1):
  Documentation: leds: leds-class: Document keyboard backlight LED class
    naming

 Documentation/leds/leds-class.rst | 63 +++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

-- 
2.53.0

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

[Hans de Goede]

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>
---
 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
+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

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

[Lee Jones]

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.

> ---
>  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.

> +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
> 

-- 
Lee Jones

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

[Hans de Goede]

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
>>
> 

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

[Xavier Bestel]

Le lundi 06 avril 2026 à 19:46 +0200, Hans de Goede a écrit :
> Drivers which need this are:
> [...]
> 3. Logitech G710/G710+ gaming keyboards HID driver:
> https://lore.kernel.org/linux-input/20260402075239.3829699-1-xav@bes.tel/
> Posted a week ago, needs an agreement on the LED class dev naming scheme
> to continue.

Indeed. I referenced Documentation/leds/leds-class.rst as if your patch
was already merged. Thank you for tackling this !

Regards,

	Xavier

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

[Kate Hsuan]

Hi Hans,

On 4/7/26 1:46 AM, Hans de Goede wrote:
> Hi All,
>
> Over the last couple of years there have been several attempts to add
> upstream kernel support for controlling keyboard backlights consisting of
> a small number of backlight zones, think e.g. : "main", "cursor" and
> "keypad" zones.
>
> All of these attempts have gotten or are stuck on the lack of consensus on
> a userspace API (1) for controlling such zoned keyboard backlights.
>
> Previous discussion can be summarized as there being consensus that
> these backlights should be represented as (multi-color) LED class devices
> with one LED class device per zone, mirroring the existing use of
> a LED class device for controlling single zone keyboard backlights.
>
> The only thing which really still needs to be agreed upon is a naming
> scheme for the per zone LED class devices so that userspace can detect:
>
> 1. That the function of these is to control a zoned keyboard backlight.
> 2. How to group the per zone devices together for a single keyboard.
>
> The single patch in this series documents the currently undocumented naming
> scheme for single zone keyboard backlights and extends this with a naming
> scheme to use for multi-zone keyboard backlights.
>
> This is send out as a separate patch rather then as part of a series
> implementing this in the hope to get multiple drivers which are in
> the process of being upstreamed unstuck wrt the LED class naming problem.
>
> Drivers which need this are:
>
> 1. HP WMI laptop driver Omen gaming keyboards backlight control support:
> First 2023 attempt:
> https://lore.kernel.org/platform-driver-x86/20230131235027.36304-1-rishitbansal0@gmail.com/
> Later 2024 attempt which includes an earlier version of this doc patch:
> https://lore.kernel.org/platform-driver-x86/20240719100011.16656-1-carlosmiguelferreira.2003@gmail.com/
> Current ongoing 2026 attempt:
> https://lore.kernel.org/platform-driver-x86/20260304105831.119349-3-edip@medip.dev/
>
> 2. Casper Excalibur laptop driver (inc. multi-zone kbd backlight control):
> https://lore.kernel.org/platform-driver-x86/20240806205001.191551-2-mustafa.eskieksi@gmail.com/
> This one unfortunately seems to have stalled.
>
> 3. Logitech G710/G710+ gaming keyboards HID driver:
> https://lore.kernel.org/linux-input/20260402075239.3829699-1-xav@bes.tel/
> Posted a week ago, needs an agreement on the LED class dev naming scheme
> to continue.
>
> Regards,
>
> Hans
>
>
> 1) The lack of such an API may not always have been the sole reason these
> drivers have gotten stuck, but it was always a factor.
>
>
> Carlos Ferreira (1):
>    Documentation: leds: leds-class: Document keyboard backlight LED class
>      naming
>
>   Documentation/leds/leds-class.rst | 63 +++++++++++++++++++++++++++++++
>   1 file changed, 63 insertions(+)
>
Thank you for your work.

The kbd_zoned_backlight is pretty useful for the upper-layer apps, such 
as upower.
This gives additional information about the location of the keyboard 
backlight LED and allows the upower to expose the APIs with the zone 
information to the user space. It also improves the user experience of 
the keyboard backlight control.

Acked-by: Kate Hsuan <hpa@redhat.com>