Documentation/leds/leds-class.rst

2 LED handling under Linux
5 In its simplest form, the LED class just allows control of LEDs from
7 LED is defined in max_brightness file. The brightness file will set the brightness
8 of the LED (taking a value 0-max_brightness). Most LEDs don't have hardware
9 brightness support so will just be turned on for non-zero brightness settings.
11 The class also introduces the optional concept of an LED trigger. A trigger
12 is a kernel based source of led events. Triggers can either be simple or
14 existing subsystems with minimal additional code. Examples are the disk-activity,
15 nand-disk and sharpsl-charge triggers. With led triggers disabled, the code
18 Complex triggers while available to all LEDs have LED specific
19 parameters and work on a per LED basis. The timer trigger is an example.
20 The timer trigger will periodically change the LED brightness between
23 You can change the brightness value of a LED independently of the timer
41 LED Device Naming
48 - devicename:
57 - color:
59         include/dt-bindings/leds/common.h.
61 - function:
63         include/dt-bindings/leds/common.h.
66 to linux-leds@vger.kernel.org.
68 It is possible that more than one LED with the same color and function will
71 name with required "-N" suffix in the driver. fwnode based drivers can use
72 function-enumerator property for that and then the concatenation will be handled
73 automatically by the LED core upon LED class device registration.
75 LED subsystem has also a protection against name clash, that may occur
76 when LED class device is created by a driver of hot-pluggable device and
78 suffix (e.g. "_1", "_2", "_3" etc.) is added to the requested LED class
81 There might be still LED class drivers around using vendor or product name
86 Examples of proper LED names:
88   - "red:disk"
89   - "white:flash"
90   - "red:indicator"
91   - "phy1:green:wlan"
92   - "phy3::wlan"
93   - ":kbd_backlight"
94   - "input5::kbd_backlight"
95   - "input3::numlock"
96   - "input3::scrolllock"
97   - "input3::capslock"
98   - "mmc1::status"
99   - "white:status"
101 get_led_device_info.sh script can be used for verifying if the LED name
102 meets the requirements pointed out here. It performs validation of the LED class
107         - input devices
108         - ieee80211 compliant USB devices
112 There have been calls for LED properties such as color to be exported as
113 individual led class attributes. As a solution which doesn't incur as much
122 LED subsystem core exposes following API for setting brightness:
124     - led_set_brightness:
128     - led_set_brightness_sync:
129 		for use cases when immediate effect is desired -
132 		blinking, returns -EBUSY if software blink fallback is enabled.
135 LED registration API
138 A driver wanting to register a LED classdev for use by other drivers /
142 free-ing the led_classdev struct.
154 support this feature, a LED driver can optionally implement the
155 blink_set() function (see <linux/leds.h>). To set an LED to blinking,
169 should completely turn off the LED and cancel the previously programmed
177 To support this feature, a LED needs to implement various additional
180 With hw control we refer to the LED driven by hardware.
182 LED driver must define the following value to support hw control:
184     - hw_control_trigger:
185                unique trigger name supported by the LED in hw control
188 LED driver must implement the following API to support hw control:
189     - hw_control_is_supported:
191                 be parsed and activate hw control on the LED.
196                 If the passed flags mask is not supported -EOPNOTSUPP
197                 must be returned, the LED trigger will use software
203      - hw_control_set:
204                 activate hw control. LED driver will use the provided
206                 a set of mode and setup the LED to be driven by hardware
214     - hw_control_get:
215                 get active modes from a LED already in hw control, parse
222                 be in a not supported initial state by the attached LED
225     - hw_control_get_device:
226                 return the device associated with the LED driver in
238 LED driver can activate additional modes by default to workaround the
243 A trigger should first check if the hw control API are supported by the LED
248 A trigger can use hw_control_get to check if a LED is already in hw control
251 When the LED is in hw control, no software blink is possible and doing so
257 The LED Trigger core cannot be a module as the simple trigger functions
260 rest of the LED subsystem can be modular.