Merge branch 'etnaviv/fixes' of https://git.pengutronix.de/git/lst/linux into drm...
[sfrench/cifs-2.6.git] / Documentation / leds / leds-lp55xx.txt
1 LP5521/LP5523/LP55231/LP5562/LP8501 Common Driver
2 =================================================
3
4 Authors: Milo(Woogyom) Kim <milo.kim@ti.com>
5
6 Description
7 -----------
8 LP5521, LP5523/55231, LP5562 and LP8501 have common features as below.
9
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
16 The 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
23 In lp55xx common driver, two different data structure is used.
24
25 o lp55xx_led
26   control multi output LED channels such as led current, channel index.
27 o lp55xx_chip
28   general chip control such like the I2C and platform data.
29
30 For example, LP5521 has maximum 3 LED channels.
31 LP5523/55231 has 9 output channels.
32
33 lp55xx_chip for LP5521 ... lp55xx_led #1
34                            lp55xx_led #2
35                            lp55xx_led #3
36
37 lp55xx_chip for LP5523 ... lp55xx_led #1
38                            lp55xx_led #2
39                                  .
40                                  .
41                            lp55xx_led #9
42
43 ( Chip Dependent Code )
44
45 To 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
58 LP55xx family devices have the internal program memory for running
59 various LED patterns.
60 This pattern data is saved as a file in the user-land or
61 hex byte string is written into the memory through the I2C.
62 LP55xx common driver supports the firmware interface.
63
64 LP55xx chips have three program engines.
65 To 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
71 The LP55xx common driver provides simple interfaces as below.
72 select_engine : Select which engine is used for running program
73 run_engine    : Start program which is loaded via the firmware interface
74 firmware      : Load program data
75
76 In case of LP5523, one more command is required, 'enginex_leds'.
77 It is used for selecting LED output(s) at each engine number.
78 In more details, please refer to 'leds-lp5523.txt'.
79
80 For example, run blinking pattern in engine #1 of LP5521
81 echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
82 echo 1 > /sys/class/firmware/lp5521/loading
83 echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
84 echo 0 > /sys/class/firmware/lp5521/loading
85 echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
86
87 For example, run blinking pattern in engine #3 of LP55231
88 Two LEDs are configured as pattern output channels.
89 echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
90 echo 1 > /sys/class/firmware/lp55231/loading
91 echo "9d0740ff7e0040007e00a0010000" > /sys/class/firmware/lp55231/data
92 echo 0 > /sys/class/firmware/lp55231/loading
93 echo "000001100" > /sys/bus/i2c/devices/xxxx/engine3_leds
94 echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
95
96 To start blinking patterns in engine #2 and #3 simultaneously,
97 for idx in 2 3
98 do
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
104 done
105 echo 1 > /sys/class/leds/red/device/run_engine
106
107 Here is another example for LP5523.
108 Full LED strings are selected by 'engine2_leds'.
109 echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
110 echo 1 > /sys/class/firmware/lp5523/loading
111 echo "9d80400004ff05ff437f0000" > /sys/class/firmware/lp5523/data
112 echo 0 > /sys/class/firmware/lp5523/loading
113 echo "111111111" > /sys/bus/i2c/devices/xxxx/engine2_leds
114 echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
115
116 As soon as 'loading' is set to 0, registered callback is called.
117 Inside the callback, the selected engine is loaded and memory is updated.
118 To run programmed pattern, 'run_engine' attribute should be enabled.
119
120 The pattern sequence of LP8501 is similar to LP5523.
121 However pattern data is specific.
122 Ex 1) Engine 1 is used
123 echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
124 echo 1 > /sys/class/firmware/lp8501/loading
125 echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
126 echo 0 > /sys/class/firmware/lp8501/loading
127 echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
128
129 Ex 2) Engine 2 and 3 are used at the same time
130 echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
131 sleep 1
132 echo 1 > /sys/class/firmware/lp8501/loading
133 echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
134 echo 0 > /sys/class/firmware/lp8501/loading
135 sleep 1
136 echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
137 sleep 1
138 echo 1 > /sys/class/firmware/lp8501/loading
139 echo "9d0340ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
140 echo 0 > /sys/class/firmware/lp8501/loading
141 sleep 1
142 echo 1 > /sys/class/leds/d1/device/run_engine
143
144 ( 'run_engine' and 'firmware_cb' )
145 The sequence of running the program data is common.
146 But each device has own specific register addresses for commands.
147 To support this, 'run_engine' and 'firmware_cb' are configurable in each driver.
148 run_engine  : Control the selected engine
149 firmware_cb : The callback function after loading the firmware is done.
150               Chip specific commands for loading and updating program memory.
151
152 ( Predefined pattern data )
153
154 Without the firmware interface, LP55xx driver provides another method for
155 loading a LED pattern. That is 'predefined' pattern.
156 A predefined pattern is defined in the platform data and load it(or them)
157 via the sysfs if needed.
158 To use the predefined pattern concept, 'patterns' and 'num_patterns' should be
159 configured.
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
188 Then, 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
193 To stop running pattern,
194   echo 0 > /sys/bus/i2c/devices/xxxx/led_pattern