Commit | Line | Data |
---|---|---|
8dab9197 | 1 | ======================== |
75c1d31d RP |
2 | LED handling under Linux |
3 | ======================== | |
4 | ||
75c1d31d | 5 | In its simplest form, the LED class just allows control of LEDs from |
5f634c65 CC |
6 | userspace. LEDs appear in /sys/class/leds/. The maximum brightness of the |
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. | |
75c1d31d RP |
10 | |
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 | |
13 | complex. A simple trigger isn't configurable and is designed to slot into | |
86ab1686 | 14 | existing subsystems with minimal additional code. Examples are the disk-activity, |
75c1d31d RP |
15 | nand-disk and sharpsl-charge triggers. With led triggers disabled, the code |
16 | optimises away. | |
17 | ||
806654a9 | 18 | Complex triggers while available to all LEDs have LED specific |
75c1d31d | 19 | parameters and work on a per LED basis. The timer trigger is an example. |
0013b23d NM |
20 | The timer trigger will periodically change the LED brightness between |
21 | LED_OFF and the current brightness setting. The "on" and "off" time can | |
22 | be specified via /sys/class/leds/<device>/delay_{on,off} in milliseconds. | |
23 | You can change the brightness value of a LED independently of the timer | |
24 | trigger. However, if you set the brightness value to LED_OFF it will | |
25 | also disable the timer trigger. | |
75c1d31d RP |
26 | |
27 | You can change triggers in a similar manner to the way an IO scheduler | |
28 | is chosen (via /sys/class/leds/<device>/trigger). Trigger specific | |
29 | parameters can appear in /sys/class/leds/<device> once a given trigger is | |
30 | selected. | |
31 | ||
32 | ||
33 | Design Philosophy | |
34 | ================= | |
35 | ||
36 | The underlying design philosophy is simplicity. LEDs are simple devices | |
37 | and the aim is to keep a small amount of code giving as much functionality | |
38 | as possible. Please keep this in mind when suggesting enhancements. | |
39 | ||
40 | ||
41 | LED Device Naming | |
42 | ================= | |
43 | ||
44 | Is currently of the form: | |
45 | ||
bb4e9af0 | 46 | "devicename:color:function" |
75c1d31d | 47 | |
bb4e9af0 JA |
48 | - devicename: |
49 | it should refer to a unique identifier created by the kernel, | |
50 | like e.g. phyN for network devices or inputN for input devices, rather | |
51 | than to the hardware; the information related to the product and the bus | |
52 | to which given device is hooked is available in sysfs and can be | |
53 | retrieved using get_led_device_info.sh script from tools/leds; generally | |
54 | this section is expected mostly for LEDs that are somehow associated with | |
55 | other devices. | |
56 | ||
57 | - color: | |
58 | one of LED_COLOR_ID_* definitions from the header | |
59 | include/dt-bindings/leds/common.h. | |
60 | ||
61 | - function: | |
62 | one of LED_FUNCTION_* definitions from the header | |
63 | include/dt-bindings/leds/common.h. | |
64 | ||
65 | If required color or function is missing, please submit a patch | |
66 | to linux-leds@vger.kernel.org. | |
67 | ||
68 | It is possible that more than one LED with the same color and function will | |
69 | be required for given platform, differing only with an ordinal number. | |
70 | In this case it is preferable to just concatenate the predefined LED_FUNCTION_* | |
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. | |
74 | ||
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 | |
77 | it doesn't provide unique devicename section. In this case numerical | |
78 | suffix (e.g. "_1", "_2", "_3" etc.) is added to the requested LED class | |
79 | device name. | |
80 | ||
81 | There might be still LED class drivers around using vendor or product name | |
82 | for devicename, but this approach is now deprecated as it doesn't convey | |
83 | any added value. Product information can be found in other places in sysfs | |
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 verifying if the LED name | |
102 | meets the requirements pointed out here. It performs validation of the LED class | |
103 | devicename sections and gives hints on expected value for a section in case | |
104 | the validation fails for it. So far the script supports validation | |
105 | of associations between LEDs and following types of devices: | |
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 as color to be exported as | |
75c1d31d RP |
113 | individual led class attributes. As a solution which doesn't incur as much |
114 | overhead, I suggest these become part of the device name. The naming scheme | |
6c152bee RP |
115 | above leaves scope for further attributes should they be needed. If sections |
116 | of the name don't apply, just leave that section blank. | |
75c1d31d RP |
117 | |
118 | ||
648da8ff JA |
119 | Brightness setting API |
120 | ====================== | |
121 | ||
122 | LED subsystem core exposes following API for setting brightness: | |
123 | ||
8dab9197 MCC |
124 | - led_set_brightness: |
125 | it is guaranteed not to sleep, passing LED_OFF stops | |
648da8ff | 126 | blinking, |
8dab9197 MCC |
127 | |
128 | - led_set_brightness_sync: | |
129 | for use cases when immediate effect is desired - | |
648da8ff JA |
130 | it can block the caller for the time required for accessing |
131 | device registers and can sleep, passing LED_OFF stops hardware | |
132 | blinking, returns -EBUSY if software blink fallback is enabled. | |
133 | ||
134 | ||
0cb8eb30 HG |
135 | LED registration API |
136 | ==================== | |
137 | ||
138 | A driver wanting to register a LED classdev for use by other drivers / | |
139 | userspace needs to allocate and fill a led_classdev struct and then call | |
8dab9197 | 140 | `[devm_]led_classdev_register`. If the non devm version is used the driver |
0cb8eb30 HG |
141 | must call led_classdev_unregister from its remove function before |
142 | free-ing the led_classdev struct. | |
143 | ||
144 | If the driver can detect hardware initiated brightness changes and thus | |
145 | wants to have a brightness_hw_changed attribute then the LED_BRIGHT_HW_CHANGED | |
146 | flag must be set in flags before registering. Calling | |
147 | led_classdev_notify_brightness_hw_changed on a classdev not registered with | |
148 | the LED_BRIGHT_HW_CHANGED flag is a bug and will trigger a WARN_ON. | |
149 | ||
4c79141d MN |
150 | Hardware accelerated blink of LEDs |
151 | ================================== | |
152 | ||
153 | Some LEDs can be programmed to blink without any CPU interaction. To | |
154 | support this feature, a LED driver can optionally implement the | |
5ada28bf | 155 | blink_set() function (see <linux/leds.h>). To set an LED to blinking, |
ee31892a BW |
156 | however, it is better to use the API function led_blink_set(), as it |
157 | will check and implement software fallback if necessary. | |
5ada28bf | 158 | |
7cfe749f TM |
159 | To turn off blinking, use the API function led_brightness_set() |
160 | with brightness value LED_OFF, which should stop any software | |
5ada28bf JB |
161 | timers that may have been required for blinking. |
162 | ||
163 | The blink_set() function should choose a user friendly blinking value | |
8dab9197 | 164 | if it is called with `*delay_on==0` && `*delay_off==0` parameters. In this |
5ada28bf JB |
165 | case the driver should give back the chosen value through delay_on and |
166 | delay_off parameters to the leds subsystem. | |
4c79141d | 167 | |
0013b23d NM |
168 | Setting the brightness to zero with brightness_set() callback function |
169 | should completely turn off the LED and cancel the previously programmed | |
170 | hardware blinking function, if any. | |
4c79141d | 171 | |
8aa2fd7b CM |
172 | Hardware driven LEDs |
173 | ==================== | |
174 | ||
175 | Some LEDs can be programmed to be driven by hardware. This is not | |
176 | limited to blink but also to turn off or on autonomously. | |
177 | To support this feature, a LED needs to implement various additional | |
178 | ops and needs to declare specific support for the supported triggers. | |
179 | ||
180 | With hw control we refer to the LED driven by hardware. | |
181 | ||
182 | LED driver must define the following value to support hw control: | |
183 | ||
184 | - hw_control_trigger: | |
185 | unique trigger name supported by the LED in hw control | |
186 | mode. | |
187 | ||
188 | LED driver must implement the following API to support hw control: | |
189 | - hw_control_is_supported: | |
190 | check if the flags passed by the supported trigger can | |
191 | be parsed and activate hw control on the LED. | |
192 | ||
193 | Return 0 if the passed flags mask is supported and | |
194 | can be set with hw_control_set(). | |
195 | ||
196 | If the passed flags mask is not supported -EOPNOTSUPP | |
197 | must be returned, the LED trigger will use software | |
198 | fallback in this case. | |
199 | ||
200 | Return a negative error in case of any other error like | |
201 | device not ready or timeouts. | |
202 | ||
203 | - hw_control_set: | |
204 | activate hw control. LED driver will use the provided | |
205 | flags passed from the supported trigger, parse them to | |
206 | a set of mode and setup the LED to be driven by hardware | |
207 | following the requested modes. | |
208 | ||
209 | Set LED_OFF via the brightness_set to deactivate hw control. | |
210 | ||
211 | Return 0 on success, a negative error number on failing to | |
212 | apply flags. | |
213 | ||
214 | - hw_control_get: | |
215 | get active modes from a LED already in hw control, parse | |
216 | them and set in flags the current active flags for the | |
217 | supported trigger. | |
218 | ||
219 | Return 0 on success, a negative error number on failing | |
220 | parsing the initial mode. | |
221 | Error from this function is NOT FATAL as the device may | |
222 | be in a not supported initial state by the attached LED | |
223 | trigger. | |
224 | ||
225 | - hw_control_get_device: | |
226 | return the device associated with the LED driver in | |
227 | hw control. A trigger might use this to match the | |
228 | returned device from this function with a configured | |
229 | device for the trigger as the source for blinking | |
230 | events and correctly enable hw control. | |
231 | (example a netdev trigger configured to blink for a | |
232 | particular dev match the returned dev from get_device | |
233 | to set hw control) | |
234 | ||
235 | Returns a pointer to a struct device or NULL if nothing | |
236 | is currently attached. | |
237 | ||
238 | LED driver can activate additional modes by default to workaround the | |
239 | impossibility of supporting each different mode on the supported trigger. | |
240 | Examples are hardcoding the blink speed to a set interval, enable special | |
241 | feature like bypassing blink if some requirements are not met. | |
242 | ||
243 | A trigger should first check if the hw control API are supported by the LED | |
244 | driver and check if the trigger is supported to verify if hw control is possible, | |
245 | use hw_control_is_supported to check if the flags are supported and only at | |
246 | the end use hw_control_set to activate hw control. | |
247 | ||
248 | A trigger can use hw_control_get to check if a LED is already in hw control | |
249 | and init their flags. | |
250 | ||
251 | When the LED is in hw control, no software blink is possible and doing so | |
252 | will effectively disable hw control. | |
4c79141d | 253 | |
75c1d31d RP |
254 | Known Issues |
255 | ============ | |
256 | ||
257 | The LED Trigger core cannot be a module as the simple trigger functions | |
258 | would cause nightmare dependency issues. I see this as a minor issue | |
259 | compared to the benefits the simple trigger functionality brings. The | |
260 | rest of the LED subsystem can be modular. |