diff options
Diffstat (limited to 'Documentation/leds/leds-class.txt')
-rw-r--r-- | Documentation/leds/leds-class.txt | 97 |
1 files changed, 97 insertions, 0 deletions
diff --git a/Documentation/leds/leds-class.txt b/Documentation/leds/leds-class.txt new file mode 100644 index 000000000000..4996586e27e8 --- /dev/null +++ b/Documentation/leds/leds-class.txt | |||
@@ -0,0 +1,97 @@ | |||
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. | ||