diff options
| author | Carlos Ferreira <carlosmiguelferreira.2003@gmail.com> | 2026-05-04 16:54:34 +0200 |
|---|---|---|
| committer | Lee Jones <lee@kernel.org> | 2026-06-17 11:28:25 +0100 |
| commit | 79ac28f175e02c8ca6216d5df1c83885f30b4c3b (patch) | |
| tree | e2affb2a3386b712f1af77b62eee58805999ed42 /Documentation | |
| parent | a03484e1e42893e2b219d9d780ce6933d319ef46 (diff) | |
| download | ath-79ac28f175e02c8ca6216d5df1c83885f30b4c3b.tar.gz | |
Documentation: leds: leds-class: Document keyboard backlight LED class naming
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-developed-by: Hans de Goede <johannes.goede@oss.qualcomm.com>
Signed-off-by: Hans de Goede <johannes.goede@oss.qualcomm.com>
Acked-by: Kate Hsuan <hpa@redhat.com>
Link: https://patch.msgid.link/20260504145434.12746-1-johannes.goede@oss.qualcomm.com
Signed-off-by: Lee Jones <lee@kernel.org>
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/leds/leds-class.rst | 63 |
1 files changed, 63 insertions, 0 deletions
diff --git a/Documentation/leds/leds-class.rst b/Documentation/leds/leds-class.rst index 5db620ed27aa2..3913966cfdac0 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 compatibility 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 ====================== |