| Message ID | 20200920162625.14754-1-jacek.anaszewski@gmail.com |
|---|---|
| State | New |
| Headers | show |
| Series | leds: Document standard LED functions | expand |
On Sun, 20 Sep 2020 18:26:25 +0200 Jacek Anaszewski <jacek.anaszewski@gmail.com> wrote: > Add a documentation for standard LED functions with regard > to differences in meaning between cases when devicename section > of an LED name is present or not. > > Signed-off-by: Jacek Anaszewski <jacek.anaszewski@gmail.com> > --- > Documentation/leds/led-functions.rst | 226 +++++++++++++++++++++++++++++++++++ > 1 file changed, 226 insertions(+) > create mode 100644 Documentation/leds/led-functions.rst > > diff --git a/Documentation/leds/led-functions.rst b/Documentation/leds/led-functions.rst > new file mode 100644 > index 000000000000..42621dd81235 > --- /dev/null > +++ b/Documentation/leds/led-functions.rst > @@ -0,0 +1,226 @@ > +============================================ > +Standardized LED functions and their meaning > +============================================ > + > +Each LED function is described using below template: > + > +LED function name > +----------------- > + > + NDEV : <function meaning when LED devicename section is absent> > + DEV : <function meaning when LED devicename section is present> > + DEVICENAME : <expected LED devicename for DEV case> > + TRIGGER: <matching LED trigger> > + > +LED functions with corresponding LED trigger support > +---------------------------------------------------- > + > +- activity > + NDEV : system activity > + DEV : n/a > + TRIGGER : "activity" > + Hi Jacek, as I wrote in another discussion, but maybe we should discuss this here. Are your opinions on this matter final or are you open for discussion? For activity: the thing is that activity is sometimes interpreted as the union of rx and tx, or read and write. I think the pair (device,function) could be used better to infer the actual trigger and its settings, than just (function,). For example: device function trigger ------ -------- ------- system activity cpu activity (empty) activity cpu activity eth0 activity netdev rx/tx sda activity disk read/write on sda wlan0 activity phy rx/tx > +- backlight > + NDEV : when there is a single one on the platform > + DEV : backlight of a frame buffer device > + DEVICENAME : associated frame buffer device, e.g. fb0 > + TRIGGER: "backlight" > + > +- disk > + NDEV : rw activity on any disk in the system > + DEV : rw activity on specified disk > + DEVICENAME : associated disk, e.g.: hda, sdb > + TRIGGER : "disk-activity", applies only to NDEV case > + > +- disk-read / disk-write > + NDEV : read / write activity on any disk in the system > + DEV : read / write activity on specified disk > + DEVICENAME : associted disk, e.g.: hda, sdb > + TRIGGER : "disk-read" / "disk-write" , applies only to NDEV case > + Currently the disk trigger blinks on events for any device, user cannot specify just one. If we implemented this, I think the trigger name should be just "disk", and whether it is read/write/both should be decided by sysfs files "read" and "write" as is in netdev trigger files "rx" and "tx". Moreover I think it would make more sense (but other people can of course disagree) if the LED function for LED associated with a disk could be "activity", "read" or "write", device function trigger ------ -------- ------- sda activity disk read/write on sda sda read disk read on sda sda write disk write on sda Marek > +- flash > + NDEV : flash LED (if there is single available on the platform) > + DEV : flash LED related to the specified video device > + DEVICENAME : associated video device, e.g. v4l2-subdev3 > + TRIGGER : "flash"; this LED can be also controlled by v4l2-flash framework > + > +- flash-front > + NDEV : n/a > + DEV : front flash LED related to the specified video device > + DEVICENAME : associated video device, e.g. v4l2-subdev3 > + TRIGGER : "flash"; this LED can be also controlled by v4l2-flash framework > + > +- flash-rear > + NDEV : n/a > + DEV : rear flash LED related to the specified video device > + DEVICENAME : associated video device, e.g. v4l2-subdev3 > + TRIGGER : "flash"; this LED can be also controlled by v4l2-flash framework > + > +- heartbeat > + NDEV : cpu load average expressed as heartbeat-fashion blink frequency > + DEV : n/a > + TRIGGER : "heartbeat" > + > +- lan > + NDEV : n/a > + DEV : network traffic on selected network device > + DEVICENAME : associated phy, e.g. phy1 > + TRIGGER : "netdev" > > +- wlan > + NDEV : activity on any wlan device > + DEV : activity on a specified wlan device > + DEVICENAME: associated phy, e.g. phy1 > + TRIGGER: wlan device drivers may implement their own triggers > + using phyN-function naming > + > +- mute > + NDEV : platform audio output mute state > + DEV : mute state of specified audio device output > + DEVICENAME : associated audio device > + TRIGGER : "audio-mute" > + > +- micmute > + NDEV : plaform microphone input mute state > + DEV : mute state of a microphone belonging to the specified device > + DEVICENAME : associated audio device > + TRIGGER : "audio-micmute" > + > +- mtd > + NDEV : rw actvity on any mtd device in the system > + DEV : rw actvity on specified mtd device > + DEVICENAME : associated mtd device, e.g mtdN > + TRIGGER : "mtd" > + > +- panic > + NDEV : signals kernel panic > + DEV : n/a > + TRIGGER : "panic" > + > +- torch > + NDEV : torch LED (if there is single available on the platform) > + DEV : torch LED related to the specified video device > + DEVICENAME : associated video device, e.g. video1, v4l2-subdev3 > + TRIGGER : "torch"; this LED can be also controlled by v4l2-flash framework > + > +- usb > + NDEV : activity on any USB port > + DEV : activity on a specified USB port > + DEVICENAME: associated USB device identifier > + TRIGGER : "usbport" > + > +- numlock > + NDEV : n/a > + DEV : keyboard numlock state related to the specified input device > + DEVICENAME : associated input device, e.g. input1 > + TRIGGER : "kbd-numlock" > + > +- capslock > + NDEV : n/a > + DEV : keyboard capslock state related to the specified input device > + DEVICENAME : associated input device, e.g. input1 > + TRIGGER : "kbd-capslock" > + > +- scrolllock > + NDEV : n/a > + DEV : keyboard scrollock state related to the specified input device > + DEVICENAME : associated input device, e.g. input1 > + TRIGGER : "kbd-scrolllock" > + > + > +LED functions without corresponding trigger support > +--------------------------------------------------- > + > +- alarm > + NDEV : system wide alarm > + DEV : n/a > + > +- bluetooth > + NDEV : activity on platform bluetooth adapter > + DEV : activity on bluetooth adapter related to the specified device > + DEVICENAME : associated device > + > +- boot > + NDEV : when lit indicates system boot > + DEV : n/a > + > +- charging > + NDEV : battery charging status > + DEV : n/a > + > +- debug > + NDEV : signals if device runs in debug mode > + DEV : n/a > + > +- disk-err > + NDEV : failure on any disk in the system > + DEV : failure on specified disk > + DEVICENAME : associted disk, e.g.: hda, sdb > + > +- fault > + NDEV : general system fault > + DEV : fault on specified system device > + DEVICENAME : related device name > + > +- indicator > + NDEV : signals if platform camera sensor is active > + DEV : signals if camera sensor related to the specified video device is active > + DEVICENAME : associated video device, e.g.: v4l2-subdev3 > + > +- kbd_backlight > + NDEV : platform keyboard backlight state > + DEV : backlight state related to the specified device > + DEVICENAME : associated device, e.g. input1 > + > +- mail > + NDEV : signals a new massage in mailbox > + DEV : n/a > + > +- programming > + NDEV : platform firmware update is in progress > + DEV : n/a > + > +- power > + NDEV : power plug presence indicator > + DEV : n/a > + > +- rx > + NDEV : n/a > + DEV : activity on rx line of serial port related to the specified tty device > + DEVICENAME: associated tty device, e.g.: tty1, ttyUSB2 > + > +- tx > + NDEV : n/a > + DEV : activity on tx line of serial port related to the specified tty device > + DEVICENAME: associated tty device, e.g.: tty1, ttyUSB2 > + > +- sd > + NDEV : n/a > + DEV : activity on sd card related to the specified device > + DEVICENAME: associated disk, e.g. sdb > + > +- sleep > + NDEV : signals any variant of system hibernation or suspend state > + DEV : n/a > + > +- standby > + NDEV : device standby status > + DEV : n/a > + > +- status > + NDEV : system wide status LED > + DEV : n/a > + > +- system > + NDEV : system is fully operating > + DEV : n/a > + > +- wan > + NDEV : activity on any WAN device > + DEV : activity on a specified WAN device > + DEVICENAME: associated WAN device identifier > + > +- wps > + NDEV : n/a > + DEV : wps functionality activation state related to the specified device > + DEVICENAME : associated device name
On 9/20/20 6:44 PM, Marek Behun wrote: > On Sun, 20 Sep 2020 18:26:25 +0200 > Jacek Anaszewski <jacek.anaszewski@gmail.com> wrote: > >> Add a documentation for standard LED functions with regard >> to differences in meaning between cases when devicename section >> of an LED name is present or not. >> >> Signed-off-by: Jacek Anaszewski <jacek.anaszewski@gmail.com> >> --- >> Documentation/leds/led-functions.rst | 226 +++++++++++++++++++++++++++++++++++ >> 1 file changed, 226 insertions(+) >> create mode 100644 Documentation/leds/led-functions.rst >> >> diff --git a/Documentation/leds/led-functions.rst b/Documentation/leds/led-functions.rst >> new file mode 100644 >> index 000000000000..42621dd81235 >> --- /dev/null >> +++ b/Documentation/leds/led-functions.rst >> @@ -0,0 +1,226 @@ >> +============================================ >> +Standardized LED functions and their meaning >> +============================================ >> + >> +Each LED function is described using below template: >> + >> +LED function name >> +----------------- >> + >> + NDEV : <function meaning when LED devicename section is absent> >> + DEV : <function meaning when LED devicename section is present> >> + DEVICENAME : <expected LED devicename for DEV case> >> + TRIGGER: <matching LED trigger> >> + >> +LED functions with corresponding LED trigger support >> +---------------------------------------------------- >> + >> +- activity >> + NDEV : system activity >> + DEV : n/a >> + TRIGGER : "activity" >> + > > Hi Jacek, > as I wrote in another discussion, but maybe we should discuss this here. > Are your opinions on this matter final or are you open for discussion? I am certainly open for discussion, especially that now this is not me who is in charge here :-) > For activity: the thing is that activity is sometimes interpreted as > the union of rx and tx, or read and write. I think the pair (device,function) > could be used better to infer the actual trigger and its settings, than > just (function,). For example: > device function trigger > ------ -------- ------- > system activity cpu activity > (empty) activity cpu activity > eth0 activity netdev rx/tx > sda activity disk read/write on sda > wlan0 activity phy rx/tx As you may have seen Rob proposed that LED functions immediately implied default trigger. That was in discussion over a year ago while my LED naming patch set was floating around. Thus this proposal looks how it looks. If we are not going to infer default LED trigger from LED name, then other options are open. But if we compare your above proposals with contents of this patch, we will see that for eth0 activity we will have lan, for sda activity we will have "disk-read"/"disk-write" and for wlan activity we will have wlan, and more precise function can be inferred referring to particular phyN-function trigger. >> +- backlight >> + NDEV : when there is a single one on the platform >> + DEV : backlight of a frame buffer device >> + DEVICENAME : associated frame buffer device, e.g. fb0 >> + TRIGGER: "backlight" >> + >> +- disk >> + NDEV : rw activity on any disk in the system >> + DEV : rw activity on specified disk >> + DEVICENAME : associated disk, e.g.: hda, sdb >> + TRIGGER : "disk-activity", applies only to NDEV case >> + >> +- disk-read / disk-write >> + NDEV : read / write activity on any disk in the system >> + DEV : read / write activity on specified disk >> + DEVICENAME : associted disk, e.g.: hda, sdb >> + TRIGGER : "disk-read" / "disk-write" , applies only to NDEV case >> + > > Currently the disk trigger blinks on events for any device, user cannot > specify just one. If we implemented this, I think the trigger name This is already implemented, see drivers/leds/trigger/ledtrig-disk.c. And for blinking on specific device there was block device trigger proposal, probably someone already works (or soon will start working) on it. > should be just "disk", and whether it is read/write/both should be > decided by sysfs files "read" and "write" as is in netdev trigger files > "rx" and "tx". > > Moreover I think it would make more sense (but other people can of > course disagree) if the LED function for LED associated with a disk > could be "activity", "read" or "write", > > device function trigger > ------ -------- ------- > sda activity disk read/write on sda > sda read disk read on sda > sda write disk write on sda We have currently more meaningful functions: #define LED_FUNCTION_DISK_ACTIVITY "disk-activity" #define LED_FUNCTION_DISK_ERR "disk-err" #define LED_FUNCTION_DISK_READ "disk-read" #define LED_FUNCTION_DISK_WRITE "disk-write"
diff --git a/Documentation/leds/led-functions.rst b/Documentation/leds/led-functions.rst new file mode 100644 index 000000000000..42621dd81235 --- /dev/null +++ b/Documentation/leds/led-functions.rst @@ -0,0 +1,226 @@ +============================================ +Standardized LED functions and their meaning +============================================ + +Each LED function is described using below template: + +LED function name +----------------- + + NDEV : <function meaning when LED devicename section is absent> + DEV : <function meaning when LED devicename section is present> + DEVICENAME : <expected LED devicename for DEV case> + TRIGGER: <matching LED trigger> + +LED functions with corresponding LED trigger support +---------------------------------------------------- + +- activity + NDEV : system activity + DEV : n/a + TRIGGER : "activity" + +- backlight + NDEV : when there is a single one on the platform + DEV : backlight of a frame buffer device + DEVICENAME : associated frame buffer device, e.g. fb0 + TRIGGER: "backlight" + +- disk + NDEV : rw activity on any disk in the system + DEV : rw activity on specified disk + DEVICENAME : associated disk, e.g.: hda, sdb + TRIGGER : "disk-activity", applies only to NDEV case + +- disk-read / disk-write + NDEV : read / write activity on any disk in the system + DEV : read / write activity on specified disk + DEVICENAME : associted disk, e.g.: hda, sdb + TRIGGER : "disk-read" / "disk-write" , applies only to NDEV case + +- flash + NDEV : flash LED (if there is single available on the platform) + DEV : flash LED related to the specified video device + DEVICENAME : associated video device, e.g. v4l2-subdev3 + TRIGGER : "flash"; this LED can be also controlled by v4l2-flash framework + +- flash-front + NDEV : n/a + DEV : front flash LED related to the specified video device + DEVICENAME : associated video device, e.g. v4l2-subdev3 + TRIGGER : "flash"; this LED can be also controlled by v4l2-flash framework + +- flash-rear + NDEV : n/a + DEV : rear flash LED related to the specified video device + DEVICENAME : associated video device, e.g. v4l2-subdev3 + TRIGGER : "flash"; this LED can be also controlled by v4l2-flash framework + +- heartbeat + NDEV : cpu load average expressed as heartbeat-fashion blink frequency + DEV : n/a + TRIGGER : "heartbeat" + +- lan + NDEV : n/a + DEV : network traffic on selected network device + DEVICENAME : associated phy, e.g. phy1 + TRIGGER : "netdev" + +- wlan + NDEV : activity on any wlan device + DEV : activity on a specified wlan device + DEVICENAME: associated phy, e.g. phy1 + TRIGGER: wlan device drivers may implement their own triggers + using phyN-function naming + +- mute + NDEV : platform audio output mute state + DEV : mute state of specified audio device output + DEVICENAME : associated audio device + TRIGGER : "audio-mute" + +- micmute + NDEV : plaform microphone input mute state + DEV : mute state of a microphone belonging to the specified device + DEVICENAME : associated audio device + TRIGGER : "audio-micmute" + +- mtd + NDEV : rw actvity on any mtd device in the system + DEV : rw actvity on specified mtd device + DEVICENAME : associated mtd device, e.g mtdN + TRIGGER : "mtd" + +- panic + NDEV : signals kernel panic + DEV : n/a + TRIGGER : "panic" + +- torch + NDEV : torch LED (if there is single available on the platform) + DEV : torch LED related to the specified video device + DEVICENAME : associated video device, e.g. video1, v4l2-subdev3 + TRIGGER : "torch"; this LED can be also controlled by v4l2-flash framework + +- usb + NDEV : activity on any USB port + DEV : activity on a specified USB port + DEVICENAME: associated USB device identifier + TRIGGER : "usbport" + +- numlock + NDEV : n/a + DEV : keyboard numlock state related to the specified input device + DEVICENAME : associated input device, e.g. input1 + TRIGGER : "kbd-numlock" + +- capslock + NDEV : n/a + DEV : keyboard capslock state related to the specified input device + DEVICENAME : associated input device, e.g. input1 + TRIGGER : "kbd-capslock" + +- scrolllock + NDEV : n/a + DEV : keyboard scrollock state related to the specified input device + DEVICENAME : associated input device, e.g. input1 + TRIGGER : "kbd-scrolllock" + + +LED functions without corresponding trigger support +--------------------------------------------------- + +- alarm + NDEV : system wide alarm + DEV : n/a + +- bluetooth + NDEV : activity on platform bluetooth adapter + DEV : activity on bluetooth adapter related to the specified device + DEVICENAME : associated device + +- boot + NDEV : when lit indicates system boot + DEV : n/a + +- charging + NDEV : battery charging status + DEV : n/a + +- debug + NDEV : signals if device runs in debug mode + DEV : n/a + +- disk-err + NDEV : failure on any disk in the system + DEV : failure on specified disk + DEVICENAME : associted disk, e.g.: hda, sdb + +- fault + NDEV : general system fault + DEV : fault on specified system device + DEVICENAME : related device name + +- indicator + NDEV : signals if platform camera sensor is active + DEV : signals if camera sensor related to the specified video device is active + DEVICENAME : associated video device, e.g.: v4l2-subdev3 + +- kbd_backlight + NDEV : platform keyboard backlight state + DEV : backlight state related to the specified device + DEVICENAME : associated device, e.g. input1 + +- mail + NDEV : signals a new massage in mailbox + DEV : n/a + +- programming + NDEV : platform firmware update is in progress + DEV : n/a + +- power + NDEV : power plug presence indicator + DEV : n/a + +- rx + NDEV : n/a + DEV : activity on rx line of serial port related to the specified tty device + DEVICENAME: associated tty device, e.g.: tty1, ttyUSB2 + +- tx + NDEV : n/a + DEV : activity on tx line of serial port related to the specified tty device + DEVICENAME: associated tty device, e.g.: tty1, ttyUSB2 + +- sd + NDEV : n/a + DEV : activity on sd card related to the specified device + DEVICENAME: associated disk, e.g. sdb + +- sleep + NDEV : signals any variant of system hibernation or suspend state + DEV : n/a + +- standby + NDEV : device standby status + DEV : n/a + +- status + NDEV : system wide status LED + DEV : n/a + +- system + NDEV : system is fully operating + DEV : n/a + +- wan + NDEV : activity on any WAN device + DEV : activity on a specified WAN device + DEVICENAME: associated WAN device identifier + +- wps + NDEV : n/a + DEV : wps functionality activation state related to the specified device + DEVICENAME : associated device name
Add a documentation for standard LED functions with regard to differences in meaning between cases when devicename section of an LED name is present or not. Signed-off-by: Jacek Anaszewski <jacek.anaszewski@gmail.com> --- Documentation/leds/led-functions.rst | 226 +++++++++++++++++++++++++++++++++++ 1 file changed, 226 insertions(+) create mode 100644 Documentation/leds/led-functions.rst