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 */ 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 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 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 */ 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 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 */ 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 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 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 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 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 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