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