summaryrefslogtreecommitdiff
path: root/Documentation/leds/leds-lp55xx.rst
blob: 632e41cec0b5914908f96f348ca1fb11dceda97e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
=================================================
LP5521/LP5523/LP55231/LP5562/LP8501 Common Driver
=================================================

Authors: Milo(Woogyom) Kim <milo.kim@ti.com>

Description
-----------
LP5521, LP5523/55231, LP5562 and LP8501 have common features as below.

  Register access via the I2C
  Device initialization/deinitialization
  Create LED class devices for multiple output channels
  Device attributes for user-space interface
  Program memory for running LED patterns

The LP55xx common driver provides these features using exported functions.

  lp55xx_init_device() / lp55xx_deinit_device()
  lp55xx_register_leds() / lp55xx_unregister_leds()
  lp55xx_regsister_sysfs() / lp55xx_unregister_sysfs()

( Driver Structure Data )

In lp55xx common driver, two different data structure is used.

* lp55xx_led
    control multi output LED channels such as led current, channel index.
* lp55xx_chip
    general chip control such like the I2C and platform data.

For example, LP5521 has maximum 3 LED channels.
LP5523/55231 has 9 output channels::

  lp55xx_chip for LP5521 ... lp55xx_led #1
			     lp55xx_led #2
			     lp55xx_led #3

  lp55xx_chip for LP5523 ... lp55xx_led #1
			     lp55xx_led #2
				   .
				   .
			     lp55xx_led #9

( Chip Dependent Code )

To support device specific configurations, special structure
'lpxx_device_config' is used.

  - Maximum number of channels
  - Reset command, chip enable command
  - Chip specific initialization
  - Brightness control register access
  - Setting LED output current
  - Program memory address access for running patterns
  - Additional device specific attributes

( Firmware Interface )

LP55xx family devices have the internal program memory for running
various LED patterns.

This pattern data is saved as a file in the user-land or
hex byte string is written into the memory through the I2C.

LP55xx common driver supports the firmware interface.

LP55xx chips have three program engines.

To load and run the pattern, the programming sequence is following.

  (1) Select an engine number (1/2/3)
  (2) Mode change to load
  (3) Write pattern data into selected area
  (4) Mode change to run

The LP55xx common driver provides simple interfaces as below.

select_engine:
	Select which engine is used for running program
run_engine:
	Start program which is loaded via the firmware interface
firmware:
	Load program data

In case of LP5523, one more command is required, 'enginex_leds'.
It is used for selecting LED output(s) at each engine number.
In more details, please refer to 'leds-lp5523.txt'.

For example, run blinking pattern in engine #1 of LP5521::

	echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
	echo 1 > /sys/class/firmware/lp5521/loading
	echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
	echo 0 > /sys/class/firmware/lp5521/loading
	echo 1 > /sys/bus/i2c/devices/xxxx/run_engine

For example, run blinking pattern in engine #3 of LP55231

Two LEDs are configured as pattern output channels::

	echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
	echo 1 > /sys/class/firmware/lp55231/loading
	echo "9d0740ff7e0040007e00a0010000" > /sys/class/firmware/lp55231/data
	echo 0 > /sys/class/firmware/lp55231/loading
	echo "000001100" > /sys/bus/i2c/devices/xxxx/engine3_leds
	echo 1 > /sys/bus/i2c/devices/xxxx/run_engine

To start blinking patterns in engine #2 and #3 simultaneously::

	for idx in 2 3
	do
	echo $idx > /sys/class/leds/red/device/select_engine
	sleep 0.1
	echo 1 > /sys/class/firmware/lp5521/loading
	echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
	echo 0 > /sys/class/firmware/lp5521/loading
	done
	echo 1 > /sys/class/leds/red/device/run_engine

Here is another example for LP5523.

Full LED strings are selected by 'engine2_leds'::

	echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
	echo 1 > /sys/class/firmware/lp5523/loading
	echo "9d80400004ff05ff437f0000" > /sys/class/firmware/lp5523/data
	echo 0 > /sys/class/firmware/lp5523/loading
	echo "111111111" > /sys/bus/i2c/devices/xxxx/engine2_leds
	echo 1 > /sys/bus/i2c/devices/xxxx/run_engine

As soon as 'loading' is set to 0, registered callback is called.
Inside the callback, the selected engine is loaded and memory is updated.
To run programmed pattern, 'run_engine' attribute should be enabled.

The pattern sequence of LP8501 is similar to LP5523.

However pattern data is specific.

Ex 1) Engine 1 is used::

	echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
	echo 1 > /sys/class/firmware/lp8501/loading
	echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
	echo 0 > /sys/class/firmware/lp8501/loading
	echo 1 > /sys/bus/i2c/devices/xxxx/run_engine

Ex 2) Engine 2 and 3 are used at the same time::

	echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
	sleep 1
	echo 1 > /sys/class/firmware/lp8501/loading
	echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
	echo 0 > /sys/class/firmware/lp8501/loading
	sleep 1
	echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
	sleep 1
	echo 1 > /sys/class/firmware/lp8501/loading
	echo "9d0340ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
	echo 0 > /sys/class/firmware/lp8501/loading
	sleep 1
	echo 1 > /sys/class/leds/d1/device/run_engine

( 'run_engine' and 'firmware_cb' )

The sequence of running the program data is common.

But each device has own specific register addresses for commands.

To support this, 'run_engine' and 'firmware_cb' are configurable in each driver.

run_engine:
	Control the selected engine
firmware_cb:
	The callback function after loading the firmware is done.

	Chip specific commands for loading and updating program memory.

( Predefined pattern data )

Without the firmware interface, LP55xx driver provides another method for
loading a LED pattern. That is 'predefined' pattern.

A predefined pattern is defined in the platform data and load it(or them)
via the sysfs if needed.

To use the predefined pattern concept, 'patterns' and 'num_patterns' should be
configured.

Example of predefined pattern data::

  /* mode_1: blinking data */
  static const u8 mode_1[] = {
		0x40, 0x00, 0x60, 0x00, 0x40, 0xFF, 0x60, 0x00,
		};

  /* mode_2: always on */
  static const u8 mode_2[] = { 0x40, 0xFF, };

  struct lp55xx_predef_pattern board_led_patterns[] = {
	{
		.r = mode_1,
		.size_r = ARRAY_SIZE(mode_1),
	},
	{
		.b = mode_2,
		.size_b = ARRAY_SIZE(mode_2),
	},
  }

  struct lp55xx_platform_data lp5562_pdata = {
  ...
	.patterns      = board_led_patterns,
	.num_patterns  = ARRAY_SIZE(board_led_patterns),
  };

Then, mode_1 and mode_2 can be run via through the sysfs::

  echo 1 > /sys/bus/i2c/devices/xxxx/led_pattern    # red blinking LED pattern
  echo 2 > /sys/bus/i2c/devices/xxxx/led_pattern    # blue LED always on

To stop running pattern::

  echo 0 > /sys/bus/i2c/devices/xxxx/led_pattern