1 // SPDX-License-Identifier: GPL-2.0
2 /*
3 * LTC3220 18-Channel LED Driver
4 *
5 * Copyright 2026 Analog Devices Inc.
6 *
7 * Author: Edelweise Escala <edelweise.escala@analog.com>
8 */
9
10 #include <linux/bitfield.h>
11 #include <linux/delay.h>
12 #include <linux/device.h>
13 #include <linux/gpio/consumer.h>
14 #include <linux/i2c.h>
15 #include <linux/leds.h>
16 #include <linux/module.h>
17 #include <linux/property.h>
18 #include <linux/regmap.h>
19 #include <linux/types.h>
20
21 /* LTC3220 Registers */
22 #define LTC3220_COMMAND_REG 0x00
23 #define LTC3220_QUICK_WRITE_MASK BIT(0)
24 #define LTC3220_SHUTDOWN_MASK BIT(3)
25
26 #define LTC3220_ULED_REG(x) (0x01 + (x))
27 #define LTC3220_LED_CURRENT_MASK GENMASK(5, 0)
28 #define LTC3220_LED_MODE_MASK GENMASK(7, 6)
29
30 #define LTC3220_GRAD_BLINK_REG 0x13
31 #define LTC3220_GRADATION_MASK GENMASK(2, 0)
32 #define LTC3220_GRADATION_DIRECTION_MASK BIT(0)
33 #define LTC3220_GRADATION_PERIOD_MASK GENMASK(2, 1)
34 #define LTC3220_BLINK_MASK GENMASK(4, 3)
35
36 #define LTC3220_NUM_LEDS 18
37 #define LTC3220_MAX_BRIGHTNESS 63
38
39 #define LTC3220_GRADATION_RAMP_TIME_240MS 240
40 #define LTC3220_GRADATION_RAMP_TIME_480MS 480
41
42 #define LTC3220_BLINK_ON_156MS 156
43 #define LTC3220_BLINK_ON_625MS 625
44 #define LTC3220_BLINK_PERIOD_1250MS 1250
45 #define LTC3220_BLINK_PERIOD_2500MS 2500
46
47 #define LTC3220_BLINK_SHORT_ON_TIME BIT(0)
48 #define LTC3220_BLINK_LONG_PERIOD BIT(1)
49
50 enum ltc3220_led_mode {
51 LTC3220_NORMAL_MODE,
52 LTC3220_BLINK_MODE,
53 LTC3220_GRADATION_MODE,
54 };
55
56 enum ltc3220_blink_mode {
57 LTC3220_BLINK_MODE_625MS_1250MS,
58 LTC3220_BLINK_MODE_156MS_1250MS,
59 LTC3220_BLINK_MODE_625MS_2500MS,
60 LTC3220_BLINK_MODE_156MS_2500MS
61 };
62
63 enum ltc3220_gradation_mode {
64 LTC3220_GRADATION_MODE_DISABLED,
65 LTC3220_GRADATION_MODE_240MS_RAMP_TIME,
66 LTC3220_GRADATION_MODE_480MS_RAMP_TIME,
67 LTC3220_GRADATION_MODE_960MS_RAMP_TIME
68 };
69
70 static const struct regmap_config ltc3220_regmap_config = {
71 .reg_bits = 8,
72 .val_bits = 8,
73 .max_register = LTC3220_GRAD_BLINK_REG,
74 .cache_type = REGCACHE_FLAT_S,
75 };
76
77 struct ltc3220_uled_cfg {
78 struct led_classdev led_cdev;
79 u8 reg_value;
80 u8 led_index;
81 bool registered;
82 };
83
84 struct ltc3220 {
85 struct ltc3220_uled_cfg uled_cfg[LTC3220_NUM_LEDS];
86 struct regmap *regmap;
87 struct mutex lock;
88 };
89
90 /*
91 * Set LED brightness. Hardware supports 0-63 brightness levels.
92 * Mode switching (blink/gradation) is handled through dedicated callbacks.
93 *
94 * In aggregated mode only a single LED (reg = 1) is registered and the
95 * hardware quick-write feature propagates the write to all 18 channels, so
96 * there is no need to update the other registers explicitly.
97 */
__ltc3220_set_led_data(struct ltc3220 * ltc3220,struct ltc3220_uled_cfg * uled_cfg,enum led_brightness brightness)98 static int __ltc3220_set_led_data(struct ltc3220 *ltc3220,
99 struct ltc3220_uled_cfg *uled_cfg,
100 enum led_brightness brightness)
101 {
102 int ret;
103
104 brightness &= LTC3220_LED_CURRENT_MASK;
105
106 ret = regmap_write(ltc3220->regmap, LTC3220_ULED_REG(uled_cfg->led_index),
107 brightness);
108 if (ret)
109 return ret;
110
111 uled_cfg->reg_value = brightness;
112
113 return 0;
114 }
115
ltc3220_set_led_data(struct led_classdev * led_cdev,enum led_brightness brightness)116 static int ltc3220_set_led_data(struct led_classdev *led_cdev,
117 enum led_brightness brightness)
118 {
119 struct ltc3220_uled_cfg *uled_cfg = container_of(led_cdev, struct ltc3220_uled_cfg,
120 led_cdev);
121 struct ltc3220 *ltc3220 = container_of(uled_cfg - uled_cfg->led_index, struct ltc3220,
122 uled_cfg[0]);
123 int ret;
124
125 mutex_lock(<c3220->lock);
126 ret = __ltc3220_set_led_data(ltc3220, uled_cfg, brightness);
127 mutex_unlock(<c3220->lock);
128
129 return ret;
130 }
131
ltc3220_get_led_data(struct led_classdev * led_cdev)132 static enum led_brightness ltc3220_get_led_data(struct led_classdev *led_cdev)
133 {
134 struct ltc3220_uled_cfg *uled_cfg = container_of(led_cdev, struct ltc3220_uled_cfg,
135 led_cdev);
136
137 return uled_cfg->reg_value;
138 }
139
140 /*
141 * LTC3220 pattern support for hardware-assisted breathing/gradation.
142 * The hardware supports 3 gradation ramp times (240ms, 480ms, 960ms)
143 * and can ramp up or down. The gradation period and direction are chip-global
144 * registers (LTC3220_GRAD_BLINK_REG), affecting all 18 channels simultaneously.
145 * This is a hardware limitation, not a driver bug.
146 *
147 * Pattern array interpretation:
148 * pattern[0].brightness = start brightness (0-63)
149 * pattern[0].delta_t = ramp time in milliseconds
150 * pattern[1].brightness = end brightness (0-63)
151 * pattern[1].delta_t = (optional, can be 0 or same as pattern[0].delta_t)
152 */
ltc3220_pattern_set(struct led_classdev * led_cdev,struct led_pattern * pattern,u32 len,int repeat)153 static int ltc3220_pattern_set(struct led_classdev *led_cdev,
154 struct led_pattern *pattern,
155 u32 len, int repeat)
156 {
157 struct ltc3220_uled_cfg *uled_cfg = container_of(led_cdev, struct ltc3220_uled_cfg,
158 led_cdev);
159 struct ltc3220 *ltc3220 = container_of(uled_cfg - uled_cfg->led_index, struct ltc3220,
160 uled_cfg[0]);
161 u8 gradation_period;
162 u8 start_brightness;
163 u8 end_brightness;
164 u8 gradation_val;
165 u8 led_mode;
166 bool is_increasing;
167 int ret;
168
169 if (len != 2)
170 return -EINVAL;
171
172 start_brightness = clamp_val(pattern[0].brightness, 0, LTC3220_LED_CURRENT_MASK);
173 end_brightness = clamp_val(pattern[1].brightness, 0, LTC3220_LED_CURRENT_MASK);
174
175 is_increasing = end_brightness > start_brightness;
176
177 if (pattern[0].delta_t == 0)
178 gradation_period = LTC3220_GRADATION_MODE_DISABLED;
179 else if (pattern[0].delta_t <= LTC3220_GRADATION_RAMP_TIME_240MS)
180 gradation_period = LTC3220_GRADATION_MODE_240MS_RAMP_TIME;
181 else if (pattern[0].delta_t <= LTC3220_GRADATION_RAMP_TIME_480MS)
182 gradation_period = LTC3220_GRADATION_MODE_480MS_RAMP_TIME;
183 else
184 gradation_period = LTC3220_GRADATION_MODE_960MS_RAMP_TIME;
185
186 gradation_val = FIELD_PREP(LTC3220_GRADATION_PERIOD_MASK, gradation_period);
187 gradation_val |= FIELD_PREP(LTC3220_GRADATION_DIRECTION_MASK, is_increasing);
188
189 /*
190 * With the ramp disabled (delta_t == 0) there is no gradation to run,
191 * so apply the end brightness directly in NORMAL mode instead of
192 * leaving the channel in gradation mode with a disabled ramp.
193 */
194 led_mode = gradation_period == LTC3220_GRADATION_MODE_DISABLED ?
195 LTC3220_NORMAL_MODE : LTC3220_GRADATION_MODE;
196
197 mutex_lock(<c3220->lock);
198
199 ret = regmap_update_bits(ltc3220->regmap, LTC3220_GRAD_BLINK_REG,
200 LTC3220_GRADATION_MASK, gradation_val);
201 if (ret)
202 goto unlock;
203
204 if (led_mode == LTC3220_GRADATION_MODE) {
205 ret = regmap_write(ltc3220->regmap, LTC3220_ULED_REG(uled_cfg->led_index),
206 start_brightness & LTC3220_LED_CURRENT_MASK);
207 if (ret)
208 goto unlock;
209
210 ret = regmap_write(ltc3220->regmap, LTC3220_ULED_REG(uled_cfg->led_index),
211 FIELD_PREP(LTC3220_LED_MODE_MASK, led_mode) |
212 (end_brightness & LTC3220_LED_CURRENT_MASK));
213 if (ret)
214 goto unlock;
215
216 uled_cfg->reg_value = end_brightness;
217 } else {
218 ret = __ltc3220_set_led_data(ltc3220, uled_cfg, end_brightness);
219 if (ret)
220 goto unlock;
221 }
222
223 unlock:
224 mutex_unlock(<c3220->lock);
225 return ret;
226 }
227
ltc3220_pattern_clear(struct led_classdev * led_cdev)228 static int ltc3220_pattern_clear(struct led_classdev *led_cdev)
229 {
230 struct ltc3220_uled_cfg *uled_cfg = container_of(led_cdev, struct ltc3220_uled_cfg,
231 led_cdev);
232 struct ltc3220 *ltc3220 = container_of(uled_cfg - uled_cfg->led_index, struct ltc3220,
233 uled_cfg[0]);
234 int ret;
235
236 mutex_lock(<c3220->lock);
237
238 ret = regmap_update_bits(ltc3220->regmap, LTC3220_ULED_REG(uled_cfg->led_index),
239 LTC3220_LED_MODE_MASK, LTC3220_NORMAL_MODE);
240 if (ret)
241 goto unlock;
242
243 ret = __ltc3220_set_led_data(ltc3220, uled_cfg, LED_OFF);
244
245 unlock:
246 mutex_unlock(<c3220->lock);
247 return ret;
248 }
249
250 /*
251 * LTC3220 has a global blink configuration that affects all LEDs.
252 * This implementation allows per-LED blink requests via sysfs, but setting
253 * blink on any LED reprograms the timing for all 18 channels simultaneously.
254 * The delay values are mapped to the hardware's discrete blink rates.
255 *
256 * HARDWARE LIMITATION: This is not a driver bug. Per-LED blink timing control
257 * is not possible with this hardware due to the global blink register.
258 */
ltc3220_blink_set(struct led_classdev * led_cdev,unsigned long * delay_on,unsigned long * delay_off)259 static int ltc3220_blink_set(struct led_classdev *led_cdev,
260 unsigned long *delay_on,
261 unsigned long *delay_off)
262 {
263 struct ltc3220_uled_cfg *uled_cfg = container_of(led_cdev, struct ltc3220_uled_cfg,
264 led_cdev);
265 struct ltc3220 *ltc3220 = container_of(uled_cfg - uled_cfg->led_index, struct ltc3220,
266 uled_cfg[0]);
267 u8 blink_brightness;
268 u8 blink_mode = 0;
269 int ret;
270
271 if (*delay_on <= LTC3220_BLINK_ON_156MS)
272 blink_mode = LTC3220_BLINK_SHORT_ON_TIME;
273
274 if (*delay_on + *delay_off > LTC3220_BLINK_PERIOD_1250MS)
275 blink_mode |= LTC3220_BLINK_LONG_PERIOD;
276
277 switch (blink_mode) {
278 case LTC3220_BLINK_MODE_625MS_1250MS:
279 *delay_on = LTC3220_BLINK_ON_625MS;
280 *delay_off = LTC3220_BLINK_PERIOD_1250MS - LTC3220_BLINK_ON_625MS;
281 break;
282 case LTC3220_BLINK_MODE_156MS_1250MS:
283 *delay_on = LTC3220_BLINK_ON_156MS;
284 *delay_off = LTC3220_BLINK_PERIOD_1250MS - LTC3220_BLINK_ON_156MS;
285 break;
286 case LTC3220_BLINK_MODE_625MS_2500MS:
287 *delay_on = LTC3220_BLINK_ON_625MS;
288 *delay_off = LTC3220_BLINK_PERIOD_2500MS - LTC3220_BLINK_ON_625MS;
289 break;
290 case LTC3220_BLINK_MODE_156MS_2500MS:
291 *delay_on = LTC3220_BLINK_ON_156MS;
292 *delay_off = LTC3220_BLINK_PERIOD_2500MS - LTC3220_BLINK_ON_156MS;
293 break;
294 }
295
296 mutex_lock(<c3220->lock);
297
298 ret = regmap_update_bits(ltc3220->regmap, LTC3220_GRAD_BLINK_REG,
299 LTC3220_BLINK_MASK, FIELD_PREP(LTC3220_BLINK_MASK, blink_mode));
300 if (ret)
301 goto unlock;
302
303 blink_brightness = uled_cfg->reg_value ? : led_cdev->max_brightness;
304
305 ret = regmap_write(ltc3220->regmap, LTC3220_ULED_REG(uled_cfg->led_index),
306 FIELD_PREP(LTC3220_LED_MODE_MASK, LTC3220_BLINK_MODE) |
307 (blink_brightness & LTC3220_LED_CURRENT_MASK));
308 if (ret)
309 goto unlock;
310
311 uled_cfg->reg_value = blink_brightness;
312
313 unlock:
314 mutex_unlock(<c3220->lock);
315 return ret;
316 }
317
ltc3220_reset_gpio_action(void * data)318 static void ltc3220_reset_gpio_action(void *data)
319 {
320 struct gpio_desc *reset_gpio = data;
321
322 gpiod_set_value_cansleep(reset_gpio, 1);
323 }
324
ltc3220_reset(struct ltc3220 * ltc3220,struct i2c_client * client)325 static int ltc3220_reset(struct ltc3220 *ltc3220, struct i2c_client *client)
326 {
327 struct gpio_desc *reset_gpio;
328 int ret;
329
330 reset_gpio = devm_gpiod_get_optional(&client->dev, "reset", GPIOD_OUT_HIGH);
331 if (IS_ERR(reset_gpio))
332 return dev_err_probe(&client->dev, PTR_ERR(reset_gpio), "Failed on reset GPIO\n");
333
334 if (reset_gpio) {
335 usleep_range(10000, 12000);
336 gpiod_set_value_cansleep(reset_gpio, 0);
337 usleep_range(10000, 12000);
338
339 ret = devm_add_action_or_reset(&client->dev, ltc3220_reset_gpio_action,
340 reset_gpio);
341 if (ret)
342 return ret;
343 }
344
345 ret = regmap_write(ltc3220->regmap, LTC3220_COMMAND_REG, 0);
346 if (ret)
347 return ret;
348
349 for (int i = 0; i < LTC3220_NUM_LEDS; i++) {
350 ret = regmap_write(ltc3220->regmap, LTC3220_ULED_REG(i), 0);
351 if (ret)
352 return ret;
353 }
354
355 return regmap_write(ltc3220->regmap, LTC3220_GRAD_BLINK_REG, 0);
356 }
357
ltc3220_suspend(struct device * dev)358 static int ltc3220_suspend(struct device *dev)
359 {
360 struct ltc3220 *ltc3220 = i2c_get_clientdata(to_i2c_client(dev));
361 int ret;
362
363 ret = regmap_update_bits(ltc3220->regmap, LTC3220_COMMAND_REG,
364 LTC3220_SHUTDOWN_MASK, LTC3220_SHUTDOWN_MASK);
365 if (ret)
366 return ret;
367
368 regcache_mark_dirty(ltc3220->regmap);
369
370 return 0;
371 }
372
ltc3220_resume(struct device * dev)373 static int ltc3220_resume(struct device *dev)
374 {
375 struct ltc3220 *ltc3220 = i2c_get_clientdata(to_i2c_client(dev));
376 bool quick_write_enabled;
377 unsigned int command_reg;
378 int ret;
379
380 ret = regmap_read(ltc3220->regmap, LTC3220_COMMAND_REG, &command_reg);
381 if (ret)
382 return ret;
383
384 quick_write_enabled = command_reg & LTC3220_QUICK_WRITE_MASK;
385
386 if (quick_write_enabled) {
387 ret = regmap_update_bits(ltc3220->regmap, LTC3220_COMMAND_REG,
388 LTC3220_QUICK_WRITE_MASK, 0);
389 if (ret)
390 return ret;
391 }
392
393 ret = regmap_update_bits(ltc3220->regmap, LTC3220_COMMAND_REG,
394 LTC3220_SHUTDOWN_MASK, 0);
395 if (ret)
396 return ret;
397
398 usleep_range(10000, 12000);
399
400 ret = regcache_sync(ltc3220->regmap);
401 if (ret)
402 return ret;
403
404 if (quick_write_enabled) {
405 ret = regmap_update_bits(ltc3220->regmap, LTC3220_COMMAND_REG,
406 LTC3220_QUICK_WRITE_MASK,
407 LTC3220_QUICK_WRITE_MASK);
408 if (ret)
409 return ret;
410 }
411
412 return 0;
413 }
414
415 static DEFINE_SIMPLE_DEV_PM_OPS(ltc3220_pm_ops, ltc3220_suspend, ltc3220_resume);
416
ltc3220_probe(struct i2c_client * client)417 static int ltc3220_probe(struct i2c_client *client)
418 {
419 struct ltc3220 *ltc3220;
420 bool aggregated_led_found = false;
421 int num_leds = 0;
422 u8 led_index = 0;
423 int ret;
424
425 ltc3220 = devm_kzalloc(&client->dev, sizeof(*ltc3220), GFP_KERNEL);
426 if (!ltc3220)
427 return -ENOMEM;
428
429 ltc3220->regmap = devm_regmap_init_i2c(client, <c3220_regmap_config);
430 if (IS_ERR(ltc3220->regmap))
431 return dev_err_probe(&client->dev, PTR_ERR(ltc3220->regmap),
432 "Failed to initialize regmap\n");
433
434 ret = devm_mutex_init(&client->dev, <c3220->lock);
435 if (ret)
436 return ret;
437
438 i2c_set_clientdata(client, ltc3220);
439
440 ret = ltc3220_reset(ltc3220, client);
441 if (ret)
442 return dev_err_probe(&client->dev, ret, "Failed to reset device\n");
443
444 /* First pass: validate configuration and set up LED structures */
445 device_for_each_child_node_scoped(&client->dev, child) {
446 struct ltc3220_uled_cfg *led;
447 u32 source;
448
449 ret = fwnode_property_read_u32(child, "reg", &source);
450 if (ret)
451 return dev_err_probe(&client->dev, ret, "Couldn't read LED address\n");
452
453 if (!source || source > LTC3220_NUM_LEDS)
454 return dev_err_probe(&client->dev, -EINVAL, "LED address out of range\n");
455
456 if (fwnode_property_present(child, "led-sources")) {
457 u32 led_sources[LTC3220_NUM_LEDS];
458 int count;
459
460 if (source != 1)
461 return dev_err_probe(&client->dev, -EINVAL,
462 "Aggregated LED out of range\n");
463
464 if (aggregated_led_found)
465 return dev_err_probe(&client->dev, -EINVAL,
466 "One Aggregated LED only\n");
467
468 count = fwnode_property_count_u32(child, "led-sources");
469 if (count != LTC3220_NUM_LEDS)
470 return dev_err_probe(&client->dev, -EINVAL,
471 "Aggregated mode requires all %d outputs in led-sources, got %d\n",
472 LTC3220_NUM_LEDS, count);
473
474 ret = fwnode_property_read_u32_array(child, "led-sources",
475 led_sources, LTC3220_NUM_LEDS);
476 if (ret)
477 return dev_err_probe(&client->dev, ret,
478 "Failed to read led-sources array\n");
479
480 /*
481 * Validate array contents for DT correctness. The hardware
482 * quick-write broadcasts to all 18 channels regardless of
483 * array contents, but checking helps catch DT mistakes.
484 */
485 for (int i = 0; i < LTC3220_NUM_LEDS; i++) {
486 if (led_sources[i] < 1 || led_sources[i] > LTC3220_NUM_LEDS)
487 return dev_err_probe(&client->dev, -EINVAL,
488 "Invalid output %u in led-sources\n",
489 led_sources[i]);
490 }
491
492 aggregated_led_found = true;
493 }
494
495 num_leds++;
496
497 /* LED node reg/index/address goes from 1 to 18 */
498 led_index = source - 1;
499 led = <c3220->uled_cfg[led_index];
500
501 if (led->registered)
502 return dev_err_probe(&client->dev, -EINVAL,
503 "Duplicate LED reg %u found\n", source);
504
505 led->registered = true;
506 led->led_index = led_index;
507 led->reg_value = 0;
508 led->led_cdev.brightness_set_blocking = ltc3220_set_led_data;
509 led->led_cdev.brightness_get = ltc3220_get_led_data;
510 led->led_cdev.max_brightness = LTC3220_MAX_BRIGHTNESS;
511 led->led_cdev.blink_set = ltc3220_blink_set;
512 led->led_cdev.pattern_set = ltc3220_pattern_set;
513 led->led_cdev.pattern_clear = ltc3220_pattern_clear;
514 }
515
516 /*
517 * Aggregated LED mode uses hardware quick-write to control all 18 LEDs
518 * simultaneously. This is mutually exclusive with individual LED control.
519 * See Documentation/devicetree/bindings/leds/adi,ltc3220.yaml for details
520 * on how to configure aggregated LED mode.
521 */
522 if (aggregated_led_found && num_leds > 1)
523 return dev_err_probe(&client->dev, -EINVAL,
524 "Aggregated LED must be the only LED node\n");
525
526 if (num_leds == 0)
527 return dev_err_probe(&client->dev, -EINVAL,
528 "No LED nodes found in device tree\n");
529
530 if (aggregated_led_found) {
531 ret = regmap_update_bits(ltc3220->regmap,
532 LTC3220_COMMAND_REG,
533 LTC3220_QUICK_WRITE_MASK,
534 LTC3220_QUICK_WRITE_MASK);
535 if (ret)
536 return dev_err_probe(&client->dev, ret,
537 "Failed to set quick write mode\n");
538 }
539
540 /* Second pass: register LEDs after validation */
541 device_for_each_child_node_scoped(&client->dev, child) {
542 struct led_init_data init_data = {};
543 struct ltc3220_uled_cfg *led;
544 u32 source;
545
546 ret = fwnode_property_read_u32(child, "reg", &source);
547 if (ret)
548 return ret;
549
550 if (!source || source > LTC3220_NUM_LEDS)
551 return dev_err_probe(&client->dev, -EINVAL,
552 "LED address out of range in second pass\n");
553
554 init_data.fwnode = child;
555 init_data.devicename = "ltc3220";
556
557 led_index = source - 1;
558 led = <c3220->uled_cfg[led_index];
559
560 ret = devm_led_classdev_register_ext(&client->dev, &led->led_cdev, &init_data);
561 if (ret)
562 return dev_err_probe(&client->dev, ret, "Failed to register LED class\n");
563 }
564
565 return 0;
566 }
567
568 static const struct of_device_id ltc3220_of_match[] = {
569 { .compatible = "adi,ltc3220" },
570 { }
571 };
572 MODULE_DEVICE_TABLE(of, ltc3220_of_match);
573
574 static struct i2c_driver ltc3220_led_driver = {
575 .driver = {
576 .name = "ltc3220",
577 .of_match_table = ltc3220_of_match,
578 .pm = pm_sleep_ptr(<c3220_pm_ops),
579 },
580 .probe = ltc3220_probe,
581 };
582 module_i2c_driver(ltc3220_led_driver);
583
584 MODULE_AUTHOR("Edelweise Escala <edelweise.escala@analog.com>");
585 MODULE_DESCRIPTION("LED driver for LTC3220 controllers");
586 MODULE_LICENSE("GPL");
587