Documentation/leds/well-known-leds.txt

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