[linux-block.git] / Documentation / leds / well-known-leds.txt

-*- 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.

Legacy 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 legacy ones, too.

Notice there's a list of functions in include/dt-bindings/leds/common.h .

* Gamepads and joysticks

Game controllers may feature LEDs to indicate a player number. This is commonly
used on game consoles in which multiple controllers can be connected to a system.
The "player LEDs" are then programmed with a pattern to indicate a particular
player. For example, a game controller with 4 LEDs, may be programmed with "x---"
to indicate player 1, "-x--" to indicate player 2 etcetera where "x" means on.
Input drivers can utilize the LED class to expose the individual player LEDs
of a game controller using the function "player".
Note: tracking and management of Player IDs is the responsibility of user space,
though drivers may pick a default value.

Good: "input*:*:player-{1,2,3,4,5}

* Keyboards
  
Good: "input*:*:capslock"
Good: "input*:*:scrolllock"
Good: "input*:*:numlock"
Legacy: "shift-key-light" (Motorola Droid 4, capslock)

Set of common keyboard LEDs, going back to PC AT or so.

Legacy: "tpacpi::thinklight" (IBM/Lenovo Thinkpads)
Legacy: "lp5523:kb{1,2,3,4,5,6}" (Nokia N900)

Frontlight/backlight of main keyboard.

Legacy: "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: "rgb:status"
Legacy: "status-led:{red,green,blue}" (Motorola Droid 4)
Legacy: "lp5523:{r,g,b}" (Nokia N900)

Phones usually have multi-color status LED.

* Power management

Good: "platform:*:charging" (allwinner sun50i, leds-cht-wcove)

* Screen

Good: ":backlight" (Motorola Droid 4)

* Indicators

Good: ":indicator" (Blinkm)

* RGB

Good: ":rgb" (Blinkm)

* Ethernet LEDs

Currently two types of Network LEDs are support, those controlled by
the PHY and those by the MAC. In theory both can be present at the
same time for one Linux netdev, hence the names need to differ between
MAC and PHY.

Do not use the netdev name, such as eth0, enp1s0. These are not stable
and are not unique. They also don't differentiate between MAC and PHY.

** MAC LEDs

Good: f1070000.ethernet:white:WAN
Good: mdio_mux-0.1:00:green:left
Good: 0000:02:00.0:yellow:top

The first part must uniquely name the MAC controller. Then follows the
colour.  WAN/LAN should be used for a single LED. If there are
multiple LEDs, use left/right, or top/bottom to indicate their
position on the RJ45 socket.

** PHY LEDs

Good: f1072004.mdio-mii:00: white:WAN
Good: !mdio-mux!mdio@2!switch@0!mdio:01:green:right
Good: r8169-0-200:00:yellow:bottom

The first part must uniquely name the PHY. This often means uniquely
identifying the MDIO bus controller, and the address on the bus.
Commit	Line	Data
09f12730 PM	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
61177c08 RC	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
09f12730 PM	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
ece1f480	61	Good: "rgb:status"
09f12730 PM	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
047da762	69	Good: "platform:*:charging" (allwinner sun50i, leds-cht-wcove)
09f12730 PM	70
	71	* Screen
	72
	73	Good: ":backlight" (Motorola Droid 4)
c693ea2f	74
56e8c56c JS	75	* Indicators
	76
	77	Good: ":indicator" (Blinkm)
	78
	79	* RGB
	80
	81	Good: ":rgb" (Blinkm)
	82
c693ea2f AL	83	* Ethernet LEDs
	84
	85	Currently two types of Network LEDs are support, those controlled by
	86	the PHY and those by the MAC. In theory both can be present at the
	87	same time for one Linux netdev, hence the names need to differ between
	88	MAC and PHY.
	89
	90	Do not use the netdev name, such as eth0, enp1s0. These are not stable
	91	and are not unique. They also don't differentiate between MAC and PHY.
	92
	93	** MAC LEDs
	94
	95	Good: f1070000.ethernet:white:WAN
	96	Good: mdio_mux-0.1:00:green:left
	97	Good: 0000:02:00.0:yellow:top
	98
	99	The first part must uniquely name the MAC controller. Then follows the
	100	colour. WAN/LAN should be used for a single LED. If there are
	101	multiple LEDs, use left/right, or top/bottom to indicate their
	102	position on the RJ45 socket.
	103
	104	** PHY LEDs
	105
	106	Good: f1072004.mdio-mii:00: white:WAN
	107	Good: !mdio-mux!mdio@2!switch@0!mdio:01:green:right
	108	Good: r8169-0-200:00:yellow:bottom
	109
	110	The first part must uniquely name the PHY. This often means uniquely
	111	identifying the MDIO bus controller, and the address on the bus.