Corentin Chary | 5f634c6 | 2009-08-28 12:56:45 +0000 | [diff] [blame] | 1 | |
Richard Purdie | 75c1d31 | 2006-03-31 02:31:03 -0800 | [diff] [blame] | 2 | LED handling under Linux |
| 3 | ======================== |
| 4 | |
Richard Purdie | 75c1d31 | 2006-03-31 02:31:03 -0800 | [diff] [blame] | 5 | In its simplest form, the LED class just allows control of LEDs from |
Corentin Chary | 5f634c6 | 2009-08-28 12:56:45 +0000 | [diff] [blame] | 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. |
Richard Purdie | 75c1d31 | 2006-03-31 02:31:03 -0800 | [diff] [blame] | 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. |
Németh Márton | 0013b23 | 2008-03-09 20:54:37 +0000 | [diff] [blame] | 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. |
Richard Purdie | 75c1d31 | 2006-03-31 02:31:03 -0800 | [diff] [blame] | 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 | |
Richard Purdie | 6c152be | 2007-10-31 15:00:07 +0100 | [diff] [blame] | 46 | "devicename:colour:function" |
Richard Purdie | 75c1d31 | 2006-03-31 02:31:03 -0800 | [diff] [blame] | 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 |
Richard Purdie | 6c152be | 2007-10-31 15:00:07 +0100 | [diff] [blame] | 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. |
Richard Purdie | 75c1d31 | 2006-03-31 02:31:03 -0800 | [diff] [blame] | 53 | |
| 54 | |
Márton Németh | 4c79141 | 2007-10-31 15:07:12 +0100 | [diff] [blame] | 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 |
Johannes Berg | 5ada28b | 2010-11-11 14:05:21 -0800 | [diff] [blame] | 60 | blink_set() function (see <linux/leds.h>). To set an LED to blinking, |
Bryan Wu | ee31892 | 2011-11-04 11:22:29 -0700 | [diff] [blame] | 61 | however, it is better to use the API function led_blink_set(), as it |
| 62 | will check and implement software fallback if necessary. |
Márton Németh | 4c79141 | 2007-10-31 15:07:12 +0100 | [diff] [blame] | 63 | |
Johannes Berg | 5ada28b | 2010-11-11 14:05:21 -0800 | [diff] [blame] | 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. |
Márton Németh | 4c79141 | 2007-10-31 15:07:12 +0100 | [diff] [blame] | 72 | |
Németh Márton | 0013b23 | 2008-03-09 20:54:37 +0000 | [diff] [blame] | 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. |
Márton Németh | 4c79141 | 2007-10-31 15:07:12 +0100 | [diff] [blame] | 76 | |
| 77 | |
Richard Purdie | 75c1d31 | 2006-03-31 02:31:03 -0800 | [diff] [blame] | 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 | |
Richard Purdie | 75c1d31 | 2006-03-31 02:31:03 -0800 | [diff] [blame] | 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. |