blob: bcea12a0c5847e12211a14d43f356d0f1a1e77f0 [file] [log] [blame]
Kim, Milo33b3a562013-07-09 02:11:37 -07001LP5521/LP5523/LP55231/LP5562/LP8501 Common Driver
2=================================================
Milo(Woogyom) Kimc0285f82013-02-05 20:22:48 +09003
4Authors: Milo(Woogyom) Kim <milo.kim@ti.com>
5
6Description
7-----------
Kim, Milo33b3a562013-07-09 02:11:37 -07008LP5521, LP5523/55231, LP5562 and LP8501 have common features as below.
Milo(Woogyom) Kimc0285f82013-02-05 20:22:48 +09009
10 Register access via the I2C
11 Device initialization/deinitialization
12 Create LED class devices for multiple output channels
13 Device attributes for user-space interface
14 Program memory for running LED patterns
15
16The LP55xx common driver provides these features using exported functions.
17 lp55xx_init_device() / lp55xx_deinit_device()
18 lp55xx_register_leds() / lp55xx_unregister_leds()
19 lp55xx_regsister_sysfs() / lp55xx_unregister_sysfs()
20
21( Driver Structure Data )
22
23In lp55xx common driver, two different data structure is used.
24
25o lp55xx_led
26 control multi output LED channels such as led current, channel index.
27o lp55xx_chip
28 general chip control such like the I2C and platform data.
29
30For example, LP5521 has maximum 3 LED channels.
31LP5523/55231 has 9 output channels.
32
33lp55xx_chip for LP5521 ... lp55xx_led #1
34 lp55xx_led #2
35 lp55xx_led #3
36
37lp55xx_chip for LP5523 ... lp55xx_led #1
38 lp55xx_led #2
39 .
40 .
41 lp55xx_led #9
42
43( Chip Dependent Code )
44
45To support device specific configurations, special structure
46'lpxx_device_config' is used.
47
48 Maximum number of channels
49 Reset command, chip enable command
50 Chip specific initialization
51 Brightness control register access
52 Setting LED output current
53 Program memory address access for running patterns
54 Additional device specific attributes
55
56( Firmware Interface )
57
58LP55xx family devices have the internal program memory for running
59various LED patterns.
60This pattern data is saved as a file in the user-land or
61hex byte string is written into the memory through the I2C.
62LP55xx common driver supports the firmware interface.
63
64LP55xx chips have three program engines.
65To load and run the pattern, the programming sequence is following.
66 (1) Select an engine number (1/2/3)
67 (2) Mode change to load
68 (3) Write pattern data into selected area
69 (4) Mode change to run
70
71The LP55xx common driver provides simple interfaces as below.
72select_engine : Select which engine is used for running program
73run_engine : Start program which is loaded via the firmware interface
74firmware : Load program data
75
Milo Kim93ad8a12013-11-20 22:14:34 -080076In case of LP5523, one more command is required, 'enginex_leds'.
77It is used for selecting LED output(s) at each engine number.
78In more details, please refer to 'leds-lp5523.txt'.
79
Milo(Woogyom) Kimc0285f82013-02-05 20:22:48 +090080For example, run blinking pattern in engine #1 of LP5521
81echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
82echo 1 > /sys/class/firmware/lp5521/loading
83echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
84echo 0 > /sys/class/firmware/lp5521/loading
85echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
86
87For example, run blinking pattern in engine #3 of LP55231
Milo Kim93ad8a12013-11-20 22:14:34 -080088Two LEDs are configured as pattern output channels.
Milo(Woogyom) Kimc0285f82013-02-05 20:22:48 +090089echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
90echo 1 > /sys/class/firmware/lp55231/loading
91echo "9d0740ff7e0040007e00a0010000" > /sys/class/firmware/lp55231/data
92echo 0 > /sys/class/firmware/lp55231/loading
Milo Kim93ad8a12013-11-20 22:14:34 -080093echo "000001100" > /sys/bus/i2c/devices/xxxx/engine3_leds
Milo(Woogyom) Kimc0285f82013-02-05 20:22:48 +090094echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
95
96To start blinking patterns in engine #2 and #3 simultaneously,
97for idx in 2 3
98do
99 echo $idx > /sys/class/leds/red/device/select_engine
100 sleep 0.1
101 echo 1 > /sys/class/firmware/lp5521/loading
102 echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
103 echo 0 > /sys/class/firmware/lp5521/loading
104done
105echo 1 > /sys/class/leds/red/device/run_engine
106
107Here is another example for LP5523.
Milo Kim93ad8a12013-11-20 22:14:34 -0800108Full LED strings are selected by 'engine2_leds'.
Milo(Woogyom) Kimc0285f82013-02-05 20:22:48 +0900109echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
110echo 1 > /sys/class/firmware/lp5523/loading
111echo "9d80400004ff05ff437f0000" > /sys/class/firmware/lp5523/data
112echo 0 > /sys/class/firmware/lp5523/loading
Milo Kim93ad8a12013-11-20 22:14:34 -0800113echo "111111111" > /sys/bus/i2c/devices/xxxx/engine2_leds
Milo(Woogyom) Kimc0285f82013-02-05 20:22:48 +0900114echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
115
116As soon as 'loading' is set to 0, registered callback is called.
117Inside the callback, the selected engine is loaded and memory is updated.
118To run programmed pattern, 'run_engine' attribute should be enabled.
119
Milo Kim93ad8a12013-11-20 22:14:34 -0800120The pattern sqeuence of LP8501 is similar to LP5523.
Kim, Milo33b3a562013-07-09 02:11:37 -0700121However pattern data is specific.
122Ex 1) Engine 1 is used
123echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
124echo 1 > /sys/class/firmware/lp8501/loading
125echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
126echo 0 > /sys/class/firmware/lp8501/loading
127echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
128
129Ex 2) Engine 2 and 3 are used at the same time
130echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
131sleep 1
132echo 1 > /sys/class/firmware/lp8501/loading
133echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
134echo 0 > /sys/class/firmware/lp8501/loading
135sleep 1
136echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
137sleep 1
138echo 1 > /sys/class/firmware/lp8501/loading
139echo "9d0340ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
140echo 0 > /sys/class/firmware/lp8501/loading
141sleep 1
142echo 1 > /sys/class/leds/d1/device/run_engine
143
Milo(Woogyom) Kimc0285f82013-02-05 20:22:48 +0900144( 'run_engine' and 'firmware_cb' )
145The sequence of running the program data is common.
146But each device has own specific register addresses for commands.
147To support this, 'run_engine' and 'firmware_cb' are configurable in each driver.
148run_engine : Control the selected engine
149firmware_cb : The callback function after loading the firmware is done.
150 Chip specific commands for loading and updating program memory.
Kim, Miloff45262a2013-02-18 21:10:14 -0800151
152( Predefined pattern data )
153
154Without the firmware interface, LP55xx driver provides another method for
155loading a LED pattern. That is 'predefined' pattern.
156A predefined pattern is defined in the platform data and load it(or them)
157via the sysfs if needed.
158To use the predefined pattern concept, 'patterns' and 'num_patterns' should be
159configured.
160
161 Example of predefined pattern data:
162
163 /* mode_1: blinking data */
164 static const u8 mode_1[] = {
165 0x40, 0x00, 0x60, 0x00, 0x40, 0xFF, 0x60, 0x00,
166 };
167
168 /* mode_2: always on */
169 static const u8 mode_2[] = { 0x40, 0xFF, };
170
171 struct lp55xx_predef_pattern board_led_patterns[] = {
172 {
173 .r = mode_1,
174 .size_r = ARRAY_SIZE(mode_1),
175 },
176 {
177 .b = mode_2,
178 .size_b = ARRAY_SIZE(mode_2),
179 },
180 }
181
182 struct lp55xx_platform_data lp5562_pdata = {
183 ...
184 .patterns = board_led_patterns,
185 .num_patterns = ARRAY_SIZE(board_led_patterns),
186 };
187
188Then, mode_1 and mode_2 can be run via through the sysfs.
189
190 echo 1 > /sys/bus/i2c/devices/xxxx/led_pattern # red blinking LED pattern
191 echo 2 > /sys/bus/i2c/devices/xxxx/led_pattern # blue LED always on
192
193To stop running pattern,
194 echo 0 > /sys/bus/i2c/devices/xxxx/led_pattern