Root/
1 | |
2 | LED handling under Linux |
3 | ======================== |
4 | |
5 | If you're reading this and thinking about keyboard leds, these are |
6 | handled by the input subsystem and the led class is *not* needed. |
7 | |
8 | In its simplest form, the LED class just allows control of LEDs from |
9 | userspace. LEDs appear in /sys/class/leds/. The maximum brightness of the |
10 | LED is defined in max_brightness file. The brightness file will set the brightness |
11 | of the LED (taking a value 0-max_brightness). Most LEDs don't have hardware |
12 | brightness support so will just be turned on for non-zero brightness settings. |
13 | |
14 | The class also introduces the optional concept of an LED trigger. A trigger |
15 | is a kernel based source of led events. Triggers can either be simple or |
16 | complex. A simple trigger isn't configurable and is designed to slot into |
17 | existing subsystems with minimal additional code. Examples are the ide-disk, |
18 | nand-disk and sharpsl-charge triggers. With led triggers disabled, the code |
19 | optimises away. |
20 | |
21 | Complex triggers whilst available to all LEDs have LED specific |
22 | parameters and work on a per LED basis. The timer trigger is an example. |
23 | The timer trigger will periodically change the LED brightness between |
24 | LED_OFF and the current brightness setting. The "on" and "off" time can |
25 | be specified via /sys/class/leds/<device>/delay_{on,off} in milliseconds. |
26 | You can change the brightness value of a LED independently of the timer |
27 | trigger. However, if you set the brightness value to LED_OFF it will |
28 | also disable the timer trigger. |
29 | |
30 | You can change triggers in a similar manner to the way an IO scheduler |
31 | is chosen (via /sys/class/leds/<device>/trigger). Trigger specific |
32 | parameters can appear in /sys/class/leds/<device> once a given trigger is |
33 | selected. |
34 | |
35 | |
36 | Design Philosophy |
37 | ================= |
38 | |
39 | The underlying design philosophy is simplicity. LEDs are simple devices |
40 | and the aim is to keep a small amount of code giving as much functionality |
41 | as possible. Please keep this in mind when suggesting enhancements. |
42 | |
43 | |
44 | LED Device Naming |
45 | ================= |
46 | |
47 | Is currently of the form: |
48 | |
49 | "devicename:colour:function" |
50 | |
51 | There have been calls for LED properties such as colour to be exported as |
52 | individual led class attributes. As a solution which doesn't incur as much |
53 | overhead, I suggest these become part of the device name. The naming scheme |
54 | above leaves scope for further attributes should they be needed. If sections |
55 | of the name don't apply, just leave that section blank. |
56 | |
57 | |
58 | Hardware accelerated blink of LEDs |
59 | ================================== |
60 | |
61 | Some LEDs can be programmed to blink without any CPU interaction. To |
62 | support this feature, a LED driver can optionally implement the |
63 | blink_set() function (see <linux/leds.h>). To set an LED to blinking, |
64 | however, it is better to use use the API function led_blink_set(), |
65 | as it will check and implement software fallback if necessary. |
66 | |
67 | To turn off blinking again, use the API function led_brightness_set() |
68 | as that will not just set the LED brightness but also stop any software |
69 | timers that may have been required for blinking. |
70 | |
71 | The blink_set() function should choose a user friendly blinking value |
72 | if it is called with *delay_on==0 && *delay_off==0 parameters. In this |
73 | case the driver should give back the chosen value through delay_on and |
74 | delay_off parameters to the leds subsystem. |
75 | |
76 | Setting the brightness to zero with brightness_set() callback function |
77 | should completely turn off the LED and cancel the previously programmed |
78 | hardware blinking function, if any. |
79 | |
80 | |
81 | Known Issues |
82 | ============ |
83 | |
84 | The LED Trigger core cannot be a module as the simple trigger functions |
85 | would cause nightmare dependency issues. I see this as a minor issue |
86 | compared to the benefits the simple trigger functionality brings. The |
87 | rest of the LED subsystem can be modular. |
88 | |
89 | |
90 | Future Development |
91 | ================== |
92 | |
93 | At the moment, a trigger can't be created specifically for a single LED. |
94 | There are a number of cases where a trigger might only be mappable to a |
95 | particular LED (ACPI?). The addition of triggers provided by the LED driver |
96 | should cover this option and be possible to add without breaking the |
97 | current interface. |
98 | |
99 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9