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

[Lee Jones <lee@kernel.org>]

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

-- 
Lee Jones [李琼斯]