1-*- org -*-
  2
  3It is somehow important to provide consistent interface to the
  4userland. LED devices have one problem there, and that is naming of
  5directories in /sys/class/leds. It would be nice if userland would
  6just know right "name" for given LED function, but situation got more
  7complex.
  8
  9Anyway, if backwards compatibility is not an issue, new code should
 10use one of the "good" names from this list, and you should extend the
 11list where applicable.
 12
 13Legacy names are listed, too; in case you are writing application that
 14wants to use particular feature, you should probe for good name, first,
 15but then try the legacy ones, too.
 16
 17Notice there's a list of functions in include/dt-bindings/leds/common.h .
 18
 19* Gamepads and joysticks
 20
 21Game controllers may feature LEDs to indicate a player number. This is commonly
 22used on game consoles in which multiple controllers can be connected to a system.
 23The "player LEDs" are then programmed with a pattern to indicate a particular
 24player. For example, a game controller with 4 LEDs, may be programmed with "x---"
 25to indicate player 1, "-x--" to indicate player 2 etcetera where "x" means on.
 26Input drivers can utilize the LED class to expose the individual player LEDs
 27of a game controller using the function "player".
 28Note: tracking and management of Player IDs is the responsibility of user space,
 29though drivers may pick a default value.
 30
 31Good: "input*:*:player-{1,2,3,4,5}
 32
 33* Keyboards
 34  
 35Good: "input*:*:capslock"
 36Good: "input*:*:scrolllock"
 37Good: "input*:*:numlock"
 38Legacy: "shift-key-light" (Motorola Droid 4, capslock)
 39
 40Set of common keyboard LEDs, going back to PC AT or so.
 41
 42Legacy: "tpacpi::thinklight" (IBM/Lenovo Thinkpads)
 43Legacy: "lp5523:kb{1,2,3,4,5,6}" (Nokia N900)
 44
 45Frontlight/backlight of main keyboard.
 46
 47Legacy: "button-backlight" (Motorola Droid 4)
 48
 49Some phones have touch buttons below screen; it is different from main
 50keyboard. And this is their backlight.
 51
 52* Sound subsystem
 53
 54Good: "platform:*:mute"
 55Good: "platform:*:micmute"
 56
 57LEDs on notebook body, indicating that sound input / output is muted.
 58
 59* System notification
 60
 61Good: "rgb:status"
 62Legacy: "status-led:{red,green,blue}" (Motorola Droid 4)
 63Legacy: "lp5523:{r,g,b}" (Nokia N900)
 64
 65Phones usually have multi-color status LED.
 66
 67* Power management
 68
 69Good: "platform:*:charging" (allwinner sun50i, leds-cht-wcove)
 70
 71* Screen
 72
 73Good: ":backlight" (Motorola Droid 4)
 74
 75* Indicators
 76
 77Good: ":indicator" (Blinkm)
 78
 79* RGB
 80
 81Good: ":rgb" (Blinkm)
 82
 83* Ethernet LEDs
 84
 85Currently two types of Network LEDs are support, those controlled by
 86the PHY and those by the MAC. In theory both can be present at the
 87same time for one Linux netdev, hence the names need to differ between
 88MAC and PHY.
 89
 90Do not use the netdev name, such as eth0, enp1s0. These are not stable
 91and are not unique. They also don't differentiate between MAC and PHY.
 92
 93** MAC LEDs
 94
 95Good: f1070000.ethernet:white:WAN
 96Good: mdio_mux-0.1:00:green:left
 97Good: 0000:02:00.0:yellow:top
 98
 99The first part must uniquely name the MAC controller. Then follows the
100colour.  WAN/LAN should be used for a single LED. If there are
101multiple LEDs, use left/right, or top/bottom to indicate their
102position on the RJ45 socket.
103
104** PHY LEDs
105
106Good: f1072004.mdio-mii:00: white:WAN
107Good: !mdio-mux!mdio@2!switch@0!mdio:01:green:right
108Good: r8169-0-200:00:yellow:bottom
109
110The first part must uniquely name the PHY. This often means uniquely
111identifying the MDIO bus controller, and the address on the bus.