1 ========================
2 LED handling under Linux
3 ========================
4
5 In its simplest form, the LED class just allow
6 userspace. LEDs appear in /sys/class/leds/. Th
7 LED is defined in max_brightness file. The bri
8 of the LED (taking a value 0-max_brightness).
9 brightness support so will just be turned on f
10
11 The class also introduces the optional concept
12 is a kernel based source of led events. Trigge
13 complex. A simple trigger isn't configurable a
14 existing subsystems with minimal additional co
15 nand-disk and sharpsl-charge triggers. With le
16 optimises away.
17
18 Complex triggers while available to all LEDs h
19 parameters and work on a per LED basis. The ti
20 The timer trigger will periodically change the
21 LED_OFF and the current brightness setting. Th
22 be specified via /sys/class/leds/<device>/dela
23 You can change the brightness value of a LED i
24 trigger. However, if you set the brightness va
25 also disable the timer trigger.
26
27 You can change triggers in a similar manner to
28 is chosen (via /sys/class/leds/<device>/trigge
29 parameters can appear in /sys/class/leds/<devi
30 selected.
31
32
33 Design Philosophy
34 =================
35
36 The underlying design philosophy is simplicity
37 and the aim is to keep a small amount of code
38 as possible. Please keep this in mind when su
39
40
41 LED Device Naming
42 =================
43
44 Is currently of the form:
45
46 "devicename:color:function"
47
48 - devicename:
49 it should refer to a unique identifier
50 like e.g. phyN for network devices or
51 than to the hardware; the information
52 to which given device is hooked is ava
53 retrieved using get_led_device_info.sh
54 this section is expected mostly for LE
55 other devices.
56
57 - color:
58 one of LED_COLOR_ID_* definitions from
59 include/dt-bindings/leds/common.h.
60
61 - function:
62 one of LED_FUNCTION_* definitions from
63 include/dt-bindings/leds/common.h.
64
65 If required color or function is missing, plea
66 to linux-leds@vger.kernel.org.
67
68 It is possible that more than one LED with the
69 be required for given platform, differing only
70 In this case it is preferable to just concaten
71 name with required "-N" suffix in the driver.
72 function-enumerator property for that and then
73 automatically by the LED core upon LED class d
74
75 LED subsystem has also a protection against na
76 when LED class device is created by a driver o
77 it doesn't provide unique devicename section.
78 suffix (e.g. "_1", "_2", "_3" etc.) is added t
79 device name.
80
81 There might be still LED class drivers around
82 for devicename, but this approach is now depre
83 any added value. Product information can be fo
84 (see tools/leds/get_led_device_info.sh).
85
86 Examples of proper LED names:
87
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"
100
101 get_led_device_info.sh script can be used for
102 meets the requirements pointed out here. It pe
103 devicename sections and gives hints on expecte
104 the validation fails for it. So far the script
105 of associations between LEDs and following typ
106
107 - input devices
108 - ieee80211 compliant USB devices
109
110 The script is open to extensions.
111
112 There have been calls for LED properties such
113 individual led class attributes. As a solution
114 overhead, I suggest these become part of the d
115 above leaves scope for further attributes shou
116 of the name don't apply, just leave that secti
117
118
119 Brightness setting API
120 ======================
121
122 LED subsystem core exposes following API for s
123
124 - led_set_brightness:
125 it is guaranteed not to sleep,
126 blinking,
127
128 - led_set_brightness_sync:
129 for use cases when immediate e
130 it can block the caller for th
131 device registers and can sleep
132 blinking, returns -EBUSY if so
133
134
135 LED registration API
136 ====================
137
138 A driver wanting to register a LED classdev fo
139 userspace needs to allocate and fill a led_cla
140 `[devm_]led_classdev_register`. If the non dev
141 must call led_classdev_unregister from its rem
142 free-ing the led_classdev struct.
143
144 If the driver can detect hardware initiated br
145 wants to have a brightness_hw_changed attribut
146 flag must be set in flags before registering.
147 led_classdev_notify_brightness_hw_changed on a
148 the LED_BRIGHT_HW_CHANGED flag is a bug and wi
149
150 Hardware accelerated blink of LEDs
151 ==================================
152
153 Some LEDs can be programmed to blink without a
154 support this feature, a LED driver can optiona
155 blink_set() function (see <linux/leds.h>). To
156 however, it is better to use the API function
157 will check and implement software fallback if
158
159 To turn off blinking, use the API function led
160 with brightness value LED_OFF, which should st
161 timers that may have been required for blinkin
162
163 The blink_set() function should choose a user
164 if it is called with `*delay_on==0` && `*delay
165 case the driver should give back the chosen va
166 delay_off parameters to the leds subsystem.
167
168 Setting the brightness to zero with brightness
169 should completely turn off the LED and cancel
170 hardware blinking function, if any.
171
172 Hardware driven LEDs
173 ====================
174
175 Some LEDs can be programmed to be driven by ha
176 limited to blink but also to turn off or on au
177 To support this feature, a LED needs to implem
178 ops and needs to declare specific support for
179
180 With hw control we refer to the LED driven by
181
182 LED driver must define the following value to
183
184 - hw_control_trigger:
185 unique trigger name supported b
186 mode.
187
188 LED driver must implement the following API to
189 - hw_control_is_supported:
190 check if the flags passed by t
191 be parsed and activate hw cont
192
193 Return 0 if the passed flags m
194 can be set with hw_control_set
195
196 If the passed flags mask is no
197 must be returned, the LED trig
198 fallback in this case.
199
200 Return a negative error in cas
201 device not ready or timeouts.
202
203 - hw_control_set:
204 activate hw control. LED drive
205 flags passed from the supporte
206 a set of mode and setup the LE
207 following the requested modes.
208
209 Set LED_OFF via the brightness
210
211 Return 0 on success, a negativ
212 apply flags.
213
214 - hw_control_get:
215 get active modes from a LED al
216 them and set in flags the curr
217 supported trigger.
218
219 Return 0 on success, a negativ
220 parsing the initial mode.
221 Error from this function is NO
222 be in a not supported initial
223 trigger.
224
225 - hw_control_get_device:
226 return the device associated w
227 hw control. A trigger might us
228 returned device from this func
229 device for the trigger as the
230 events and correctly enable hw
231 (example a netdev trigger conf
232 particular dev match the retur
233 to set hw control)
234
235 Returns a pointer to a struct
236 is currently attached.
237
238 LED driver can activate additional modes by de
239 impossibility of supporting each different mod
240 Examples are hardcoding the blink speed to a s
241 feature like bypassing blink if some requireme
242
243 A trigger should first check if the hw control
244 driver and check if the trigger is supported t
245 use hw_control_is_supported to check if the fl
246 the end use hw_control_set to activate hw cont
247
248 A trigger can use hw_control_get to check if a
249 and init their flags.
250
251 When the LED is in hw control, no software bli
252 will effectively disable hw control.
253
254 Known Issues
255 ============
256
257 The LED Trigger core cannot be a module as the
258 would cause nightmare dependency issues. I see
259 compared to the benefits the simple trigger fu
260 rest of the LED subsystem can be modular.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.