Commit | Line | Data |
---|---|---|
5f634c65 | 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 | |
14 | existing subsystems with minimal additional code. Examples are the ide-disk, | |
15 | nand-disk and sharpsl-charge triggers. With led triggers disabled, the code | |
16 | optimises away. | |
17 | ||
18 | Complex triggers whilst available to all LEDs have LED specific | |
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 | ||
6c152bee | 46 | "devicename:colour:function" |
75c1d31d RP |
47 | |
48 | There have been calls for LED properties such as colour to be exported as | |
49 | individual led class attributes. As a solution which doesn't incur as much | |
50 | overhead, I suggest these become part of the device name. The naming scheme | |
6c152bee RP |
51 | above leaves scope for further attributes should they be needed. If sections |
52 | of the name don't apply, just leave that section blank. | |
75c1d31d RP |
53 | |
54 | ||
4c79141d MN |
55 | Hardware accelerated blink of LEDs |
56 | ================================== | |
57 | ||
58 | Some LEDs can be programmed to blink without any CPU interaction. To | |
59 | support this feature, a LED driver can optionally implement the | |
5ada28bf | 60 | blink_set() function (see <linux/leds.h>). To set an LED to blinking, |
ee31892a BW |
61 | however, it is better to use the API function led_blink_set(), as it |
62 | will check and implement software fallback if necessary. | |
5ada28bf JB |
63 | |
64 | To turn off blinking again, use the API function led_brightness_set() | |
65 | as that will not just set the LED brightness but also stop any software | |
66 | timers that may have been required for blinking. | |
67 | ||
68 | The blink_set() function should choose a user friendly blinking value | |
69 | if it is called with *delay_on==0 && *delay_off==0 parameters. In this | |
70 | case the driver should give back the chosen value through delay_on and | |
71 | delay_off parameters to the leds subsystem. | |
4c79141d | 72 | |
0013b23d NM |
73 | Setting the brightness to zero with brightness_set() callback function |
74 | should completely turn off the LED and cancel the previously programmed | |
75 | hardware blinking function, if any. | |
4c79141d MN |
76 | |
77 | ||
75c1d31d RP |
78 | Known Issues |
79 | ============ | |
80 | ||
81 | The LED Trigger core cannot be a module as the simple trigger functions | |
82 | would cause nightmare dependency issues. I see this as a minor issue | |
83 | compared to the benefits the simple trigger functionality brings. The | |
84 | rest of the LED subsystem can be modular. | |
85 | ||
75c1d31d RP |
86 | |
87 | Future Development | |
88 | ================== | |
89 | ||
90 | At the moment, a trigger can't be created specifically for a single LED. | |
91 | There are a number of cases where a trigger might only be mappable to a | |
92 | particular LED (ACPI?). The addition of triggers provided by the LED driver | |
93 | should cover this option and be possible to add without breaking the | |
94 | current interface. |