diff options
Diffstat (limited to 'Documentation/leds')
| -rw-r--r-- | Documentation/leds/00-INDEX | 8 | ||||
| -rw-r--r-- | Documentation/leds/leds-class.txt | 97 | ||||
| -rw-r--r-- | Documentation/leds/leds-lp3944.txt | 50 | ||||
| -rw-r--r-- | Documentation/leds/leds-lp5521.txt | 151 | ||||
| -rw-r--r-- | Documentation/leds/leds-lp5523.txt | 83 |
5 files changed, 389 insertions, 0 deletions
diff --git a/Documentation/leds/00-INDEX b/Documentation/leds/00-INDEX new file mode 100644 index 00000000..29f481df --- /dev/null +++ b/Documentation/leds/00-INDEX @@ -0,0 +1,8 @@ +leds-class.txt + - documents LED handling under Linux. +leds-lp3944.txt + - notes on how to use the leds-lp3944 driver. +leds-lp5521.txt + - notes on how to use the leds-lp5521 driver. +leds-lp5523.txt + - notes on how to use the leds-lp5523 driver. diff --git a/Documentation/leds/leds-class.txt b/Documentation/leds/leds-class.txt new file mode 100644 index 00000000..79699c20 --- /dev/null +++ b/Documentation/leds/leds-class.txt @@ -0,0 +1,97 @@ + +LED handling under Linux +======================== + +If you're reading this and thinking about keyboard leds, these are +handled by the input subsystem and the led class is *not* needed. + +In its simplest form, the LED class just allows control of LEDs from +userspace. LEDs appear in /sys/class/leds/. The maximum brightness of the +LED is defined in max_brightness file. The brightness file will set the brightness +of the LED (taking a value 0-max_brightness). Most LEDs don't have hardware +brightness support so will just be turned on for non-zero brightness settings. + +The class also introduces the optional concept of an LED trigger. A trigger +is a kernel based source of led events. Triggers can either be simple or +complex. A simple trigger isn't configurable and is designed to slot into +existing subsystems with minimal additional code. Examples are the ide-disk, +nand-disk and sharpsl-charge triggers. With led triggers disabled, the code +optimises away. + +Complex triggers whilst available to all LEDs have LED specific +parameters and work on a per LED basis. The timer trigger is an example. +The timer trigger will periodically change the LED brightness between +LED_OFF and the current brightness setting. The "on" and "off" time can +be specified via /sys/class/leds/<device>/delay_{on,off} in milliseconds. +You can change the brightness value of a LED independently of the timer +trigger. However, if you set the brightness value to LED_OFF it will +also disable the timer trigger. + +You can change triggers in a similar manner to the way an IO scheduler +is chosen (via /sys/class/leds/<device>/trigger). Trigger specific +parameters can appear in /sys/class/leds/<device> once a given trigger is +selected. + + +Design Philosophy +================= + +The underlying design philosophy is simplicity. LEDs are simple devices +and the aim is to keep a small amount of code giving as much functionality +as possible. Please keep this in mind when suggesting enhancements. + + +LED Device Naming +================= + +Is currently of the form: + +"devicename:colour:function" + +There have been calls for LED properties such as colour to be exported as +individual led class attributes. As a solution which doesn't incur as much +overhead, I suggest these become part of the device name. The naming scheme +above leaves scope for further attributes should they be needed. If sections +of the name don't apply, just leave that section blank. + + +Hardware accelerated blink of LEDs +================================== + +Some LEDs can be programmed to blink without any CPU interaction. To +support this feature, a LED driver can optionally implement the +blink_set() function (see <linux/leds.h>). To set an LED to blinking, +however, it is better to use the API function led_blink_set(), as it +will check and implement software fallback if necessary. + +To turn off blinking again, use the API function led_brightness_set() +as that will not just set the LED brightness but also stop any software +timers that may have been required for blinking. + +The blink_set() function should choose a user friendly blinking value +if it is called with *delay_on==0 && *delay_off==0 parameters. In this +case the driver should give back the chosen value through delay_on and +delay_off parameters to the leds subsystem. + +Setting the brightness to zero with brightness_set() callback function +should completely turn off the LED and cancel the previously programmed +hardware blinking function, if any. + + +Known Issues +============ + +The LED Trigger core cannot be a module as the simple trigger functions +would cause nightmare dependency issues. I see this as a minor issue +compared to the benefits the simple trigger functionality brings. The +rest of the LED subsystem can be modular. + + +Future Development +================== + +At the moment, a trigger can't be created specifically for a single LED. +There are a number of cases where a trigger might only be mappable to a +particular LED (ACPI?). The addition of triggers provided by the LED driver +should cover this option and be possible to add without breaking the +current interface. diff --git a/Documentation/leds/leds-lp3944.txt b/Documentation/leds/leds-lp3944.txt new file mode 100644 index 00000000..c6eda18b --- /dev/null +++ b/Documentation/leds/leds-lp3944.txt @@ -0,0 +1,50 @@ +Kernel driver lp3944 +==================== + + * National Semiconductor LP3944 Fun-light Chip + Prefix: 'lp3944' + Addresses scanned: None (see the Notes section below) + Datasheet: Publicly available at the National Semiconductor website + http://www.national.com/pf/LP/LP3944.html + +Authors: + Antonio Ospite <ospite@studenti.unina.it> + + +Description +----------- +The LP3944 is a helper chip that can drive up to 8 leds, with two programmable +DIM modes; it could even be used as a gpio expander but this driver assumes it +is used as a led controller. + +The DIM modes are used to set _blink_ patterns for leds, the pattern is +specified supplying two parameters: + - period: from 0s to 1.6s + - duty cycle: percentage of the period the led is on, from 0 to 100 + +Setting a led in DIM0 or DIM1 mode makes it blink according to the pattern. +See the datasheet for details. + +LP3944 can be found on Motorola A910 smartphone, where it drives the rgb +leds, the camera flash light and the lcds power. + + +Notes +----- +The chip is used mainly in embedded contexts, so this driver expects it is +registered using the i2c_board_info mechanism. + +To register the chip at address 0x60 on adapter 0, set the platform data +according to include/linux/leds-lp3944.h, set the i2c board info: + + static struct i2c_board_info __initdata a910_i2c_board_info[] = { + { + I2C_BOARD_INFO("lp3944", 0x60), + .platform_data = &a910_lp3944_leds, + }, + }; + +and register it in the platform init function + + i2c_register_board_info(0, a910_i2c_board_info, + ARRAY_SIZE(a910_i2c_board_info)); diff --git a/Documentation/leds/leds-lp5521.txt b/Documentation/leds/leds-lp5521.txt new file mode 100644 index 00000000..0e542ab3 --- /dev/null +++ b/Documentation/leds/leds-lp5521.txt @@ -0,0 +1,151 @@ +Kernel driver for lp5521 +======================== + +* National Semiconductor LP5521 led driver chip +* Datasheet: http://www.national.com/pf/LP/LP5521.html + +Authors: Mathias Nyman, Yuri Zaporozhets, Samu Onkalo +Contact: Samu Onkalo (samu.p.onkalo-at-nokia.com) + +Description +----------- + +LP5521 can drive up to 3 channels. Leds can be controlled directly via +the led class control interface. Channels have generic names: +lp5521:channelx, where x is 0 .. 2 + +All three channels can be also controlled using the engine micro programs. +More details of the instructions can be found from the public data sheet. + +Control interface for the engines: +x is 1 .. 3 +enginex_mode : disabled, load, run +enginex_load : store program (visible only in engine load mode) + +Example (start to blink the channel 2 led): +cd /sys/class/leds/lp5521:channel2/device +echo "load" > engine3_mode +echo "037f4d0003ff6000" > engine3_load +echo "run" > engine3_mode + +stop the engine: +echo "disabled" > engine3_mode + +sysfs contains a selftest entry. +The test communicates with the chip and checks that +the clock mode is automatically set to the requested one. + +Each channel has its own led current settings. +/sys/class/leds/lp5521:channel0/led_current - RW +/sys/class/leds/lp5521:channel0/max_current - RO +Format: 10x mA i.e 10 means 1.0 mA + +example platform data: + +Note: chan_nr can have values between 0 and 2. +The name of each channel can be configurable. +If the name field is not defined, the default name will be set to 'xxxx:channelN' +(XXXX : pdata->label or i2c client name, N : channel number) + +static struct lp5521_led_config lp5521_led_config[] = { + { + .name = "red", + .chan_nr = 0, + .led_current = 50, + .max_current = 130, + }, { + .name = "green", + .chan_nr = 1, + .led_current = 0, + .max_current = 130, + }, { + .name = "blue", + .chan_nr = 2, + .led_current = 0, + .max_current = 130, + } +}; + +static int lp5521_setup(void) +{ + /* setup HW resources */ +} + +static void lp5521_release(void) +{ + /* Release HW resources */ +} + +static void lp5521_enable(bool state) +{ + /* Control of chip enable signal */ +} + +static struct lp5521_platform_data lp5521_platform_data = { + .led_config = lp5521_led_config, + .num_channels = ARRAY_SIZE(lp5521_led_config), + .clock_mode = LP5521_CLOCK_EXT, + .setup_resources = lp5521_setup, + .release_resources = lp5521_release, + .enable = lp5521_enable, +}; + +If the current is set to 0 in the platform data, that channel is +disabled and it is not visible in the sysfs. + +The 'update_config' : CONFIG register (ADDR 08h) +This value is platform-specific data. +If update_config is not defined, the CONFIG register is set with +'LP5521_PWRSAVE_EN | LP5521_CP_MODE_AUTO | LP5521_R_TO_BATT'. +(Enable auto-powersave, set charge pump to auto, red to battery) + +example of update_config : + +#define LP5521_CONFIGS (LP5521_PWM_HF | LP5521_PWRSAVE_EN | \ + LP5521_CP_MODE_AUTO | LP5521_R_TO_BATT | \ + LP5521_CLK_INT) + +static struct lp5521_platform_data lp5521_pdata = { + .led_config = lp5521_led_config, + .num_channels = ARRAY_SIZE(lp5521_led_config), + .clock_mode = LP5521_CLOCK_INT, + .update_config = LP5521_CONFIGS, +}; + +LED patterns : LP5521 has autonomous operation without external control. +Pattern data can be defined in the platform data. + +example of led pattern data : + +/* RGB(50,5,0) 500ms on, 500ms off, infinite loop */ +static u8 pattern_red[] = { + 0x40, 0x32, 0x60, 0x00, 0x40, 0x00, 0x60, 0x00, + }; + +static u8 pattern_green[] = { + 0x40, 0x05, 0x60, 0x00, 0x40, 0x00, 0x60, 0x00, + }; + +static struct lp5521_led_pattern board_led_patterns[] = { + { + .r = pattern_red, + .g = pattern_green, + .size_r = ARRAY_SIZE(pattern_red), + .size_g = ARRAY_SIZE(pattern_green), + }, +}; + +static struct lp5521_platform_data lp5521_platform_data = { + .led_config = lp5521_led_config, + .num_channels = ARRAY_SIZE(lp5521_led_config), + .clock_mode = LP5521_CLOCK_EXT, + .patterns = board_led_patterns, + .num_patterns = ARRAY_SIZE(board_led_patterns), +}; + +Then predefined led pattern(s) can be executed via the sysfs. +To start the pattern #1, +# echo 1 > /sys/bus/i2c/devices/xxxx/led_pattern +(xxxx : i2c bus & slave address) +To end the pattern, +# echo 0 > /sys/bus/i2c/devices/xxxx/led_pattern diff --git a/Documentation/leds/leds-lp5523.txt b/Documentation/leds/leds-lp5523.txt new file mode 100644 index 00000000..fad2feb8 --- /dev/null +++ b/Documentation/leds/leds-lp5523.txt @@ -0,0 +1,83 @@ +Kernel driver for lp5523 +======================== + +* National Semiconductor LP5523 led driver chip +* Datasheet: http://www.national.com/pf/LP/LP5523.html + +Authors: Mathias Nyman, Yuri Zaporozhets, Samu Onkalo +Contact: Samu Onkalo (samu.p.onkalo-at-nokia.com) + +Description +----------- +LP5523 can drive up to 9 channels. Leds can be controlled directly via +the led class control interface. Channels have generic names: +lp5523:channelx where x is 0...8 + +The chip provides 3 engines. Each engine can control channels without +interaction from the main CPU. Details of the micro engine code can be found +from the public data sheet. Leds can be muxed to different channels. + +Control interface for the engines: +x is 1 .. 3 +enginex_mode : disabled, load, run +enginex_load : microcode load (visible only in load mode) +enginex_leds : led mux control (visible only in load mode) + +cd /sys/class/leds/lp5523:channel2/device +echo "load" > engine3_mode +echo "9d80400004ff05ff437f0000" > engine3_load +echo "111111111" > engine3_leds +echo "run" > engine3_mode + +sysfs contains a selftest entry. It measures each channel +voltage level and checks if it looks reasonable. If the level is too high, +the led is missing; if the level is too low, there is a short circuit. + +Selftest uses always the current from the platform data. + +Each channel contains led current settings. +/sys/class/leds/lp5523:channel2/led_current - RW +/sys/class/leds/lp5523:channel2/max_current - RO +Format: 10x mA i.e 10 means 1.0 mA + +Example platform data: + +Note - chan_nr can have values between 0 and 8. + +static struct lp5523_led_config lp5523_led_config[] = { + { + .chan_nr = 0, + .led_current = 50, + .max_current = 130, + }, +... + }, { + .chan_nr = 8, + .led_current = 50, + .max_current = 130, + } +}; + +static int lp5523_setup(void) +{ + /* Setup HW resources */ +} + +static void lp5523_release(void) +{ + /* Release HW resources */ +} + +static void lp5523_enable(bool state) +{ + /* Control chip enable signal */ +} + +static struct lp5523_platform_data lp5523_platform_data = { + .led_config = lp5523_led_config, + .num_channels = ARRAY_SIZE(lp5523_led_config), + .clock_mode = LP5523_CLOCK_EXT, + .setup_resources = lp5523_setup, + .release_resources = lp5523_release, + .enable = lp5523_enable, +}; |