| Message ID | 20240719100011.16656-3-carlosmiguelferreira.2003@gmail.com (mailing list archive) |
|---|---|
| State | Changes Requested, archived |
| Headers | show |
| Series | HP: wmi: added support for 4 zone keyboard rgb | expand |
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 > ====================== >
On Mon, 12 Aug 2024, Hans de Goede wrote: > 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. Please use get_maintainer.pl when submitting patches: % ./scripts/get_maintainer.pl -f Documentation/leds/leds-class.rst Pavel Machek <pavel@ucw.cz> (maintainer:LED SUBSYSTEM) Lee Jones <lee@kernel.org> (maintainer:LED SUBSYSTEM) Jonathan Corbet <corbet@lwn.net> (maintainer:DOCUMENTATION) linux-leds@vger.kernel.org (open list:LED SUBSYSTEM) linux-doc@vger.kernel.org (open list:DOCUMENTATION) linux-kernel@vger.kernel.org (open list) I'll review the patch once it's been submitted properly, thanks. > 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 > > ====================== > > >
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 +<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 ======================
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(+)