Commit | Line | Data |
---|---|---|
75c1d31d RP |
1 | LED handling under Linux |
2 | ======================== | |
3 | ||
4 | If you're reading this and thinking about keyboard leds, these are | |
5 | handled by the input subsystem and the led class is *not* needed. | |
6 | ||
7 | In its simplest form, the LED class just allows control of LEDs from | |
8 | userspace. LEDs appear in /sys/class/leds/. The brightness file will | |
9 | set the brightness of the LED (taking a value 0-255). Most LEDs don't | |
10 | have hardware brightness support so will just be turned on for non-zero | |
11 | brightness settings. | |
12 | ||
13 | The class also introduces the optional concept of an LED trigger. A trigger | |
14 | is a kernel based source of led events. Triggers can either be simple or | |
15 | complex. A simple trigger isn't configurable and is designed to slot into | |
16 | existing subsystems with minimal additional code. Examples are the ide-disk, | |
17 | nand-disk and sharpsl-charge triggers. With led triggers disabled, the code | |
18 | optimises away. | |
19 | ||
20 | Complex triggers whilst available to all LEDs have LED specific | |
21 | parameters and work on a per LED basis. The timer trigger is an example. | |
22 | ||
23 | You can change triggers in a similar manner to the way an IO scheduler | |
24 | is chosen (via /sys/class/leds/<device>/trigger). Trigger specific | |
25 | parameters can appear in /sys/class/leds/<device> once a given trigger is | |
26 | selected. | |
27 | ||
28 | ||
29 | Design Philosophy | |
30 | ================= | |
31 | ||
32 | The underlying design philosophy is simplicity. LEDs are simple devices | |
33 | and the aim is to keep a small amount of code giving as much functionality | |
34 | as possible. Please keep this in mind when suggesting enhancements. | |
35 | ||
36 | ||
37 | LED Device Naming | |
38 | ================= | |
39 | ||
40 | Is currently of the form: | |
41 | ||
6c152bee | 42 | "devicename:colour:function" |
75c1d31d RP |
43 | |
44 | There have been calls for LED properties such as colour to be exported as | |
45 | individual led class attributes. As a solution which doesn't incur as much | |
46 | overhead, I suggest these become part of the device name. The naming scheme | |
6c152bee RP |
47 | above leaves scope for further attributes should they be needed. If sections |
48 | of the name don't apply, just leave that section blank. | |
75c1d31d RP |
49 | |
50 | ||
4c79141d MN |
51 | Hardware accelerated blink of LEDs |
52 | ================================== | |
53 | ||
54 | Some LEDs can be programmed to blink without any CPU interaction. To | |
55 | support this feature, a LED driver can optionally implement the | |
56 | blink_set() function (see <linux/leds.h>). If implemeted, triggers can | |
57 | attempt to use it before falling back to software timers. The blink_set() | |
58 | function should return 0 if the blink setting is supported, or -EINVAL | |
59 | otherwise, which means that LED blinking will be handled by software. | |
60 | ||
61 | The blink_set() function should choose a user friendly blinking | |
62 | value if it is called with *delay_on==0 && *delay_off==0 parameters. In | |
63 | this case the driver should give back the chosen value through delay_on | |
64 | and delay_off parameters to the leds subsystem. | |
65 | ||
66 | Any call to the brightness_set() callback function should cancel the | |
67 | previously programmed hardware blinking function so setting the brightness | |
68 | to 0 can also cancel the blinking of the LED. | |
69 | ||
70 | ||
75c1d31d RP |
71 | Known Issues |
72 | ============ | |
73 | ||
74 | The LED Trigger core cannot be a module as the simple trigger functions | |
75 | would cause nightmare dependency issues. I see this as a minor issue | |
76 | compared to the benefits the simple trigger functionality brings. The | |
77 | rest of the LED subsystem can be modular. | |
78 | ||
75c1d31d RP |
79 | |
80 | Future Development | |
81 | ================== | |
82 | ||
83 | At the moment, a trigger can't be created specifically for a single LED. | |
84 | There are a number of cases where a trigger might only be mappable to a | |
85 | particular LED (ACPI?). The addition of triggers provided by the LED driver | |
86 | should cover this option and be possible to add without breaking the | |
87 | current interface. | |
88 |