Documentation for naming LEDs was Re: [PATCH net-next 5/5] igc: Export LEDs

Commit Message

Pavel Machek Aug. 10, 2021, 5:22 p.m. UTC

Hi!

> > > The last time we discussed this (Andrew, Pavel and I), we've decided
> > > that for ethernet PHY controlled LEDs we want the devicename part
> > > should be something like
> > >    phyN  or  ethphyN  or  ethernet-phyN
> > > with N a number unique for every PHY (a simple atomically increased
> > > integer for every ethernet PHY).  
> > 
> > We might want to rethink this. PHYs typically have 2 or 3 LEDs. So we
> > want a way to indicate which LED of a PHY it is. So i suspect we will
> > want something like
> > 
> > ethphyN-led0, ethphyN-led1, ethphyN-led2.
> 
> But... there is still color and function and possibly function-numerator
> to differentiate them. I was talking only about the devicename part. So
> for three LEDs you can have, for example:
>   ethphyN:green:link
>   ethphyN:yellow:activity

For the record, this is the solution I'd like to see. Plus, we do want
it consistent between drivers, and I believe we need more than
list of functions provided by dt-bindings/leds/common.h -- we want
people to set something reasonable for "device" part, too.

Thus, I'm proposing this:

Rules will be simple -- when new type of LED is added to the
system, it will need to come with documentation explaining what the
LED does, and people will be expected to use existing names when
possible.

We'll also want to list "known bad" names in the file, so that there's
central place to search for aliases.

Thoughts?

Best regards,
								Pavel

Patch

--- /dev/null	2021-08-08 09:30:15.272028621 +0200
+++ Documentation/leds/well-known-leds.txt	2021-07-03 14:33:45.573718655 +0200
@@ -0,0 +1,57 @@ 
+-*- org -*-
+
+It is somehow important to provide consistent interface to the
+userland. LED devices have one problem there, and that is naming of
+directories in /sys/class/leds. It would be nice if userland would
+just know right "name" for given LED function, but situation got more
+complex.
+
+Anyway, if backwards compatibility is not an issue, new code should
+use one of the "good" names from this list, and you should extend the
+list where applicable.
+
+Bad names are listed, too; in case you are writing application that
+wants to use particular feature, you should probe for good name, first,
+but then try the bad ones, too.
+
+* Keyboards
+  
+Good: "input*:*:capslock"
+Good: "input*:*:scrolllock"
+Good: "input*:*:numlock"
+Bad: "shift-key-light" (Motorola Droid 4, capslock)
+
+Set of common keyboard LEDs, going back to PC AT or so.
+
+Good: "platform::kbd_backlight"
+Bad: "tpacpi::thinklight" (IBM/Lenovo Thinkpads)
+Bad: "lp5523:kb{1,2,3,4,5,6}" (Nokia N900)
+
+Frontlight/backlight of main keyboard.
+
+Bad: "button-backlight" (Motorola Droid 4)
+
+Some phones have touch buttons below screen; it is different from main
+keyboard. And this is their backlight.
+
+* Sound subsystem
+
+Good: "platform:*:mute"
+Good: "platform:*:micmute"
+
+LEDs on notebook body, indicating that sound input / output is muted.
+
+* System notification
+
+Good: "status-led:{red,green,blue}" (Motorola Droid 4)
+Bad: "lp5523:{r,g,b}" (Nokia N900)
+
+Phones usually have multi-color status LED.
+
+* Power management
+
+Good: "platform:*:charging" (allwinner sun50i)
+
+* Screen
+
+Good: ":backlight" (Motorola Droid 4)