1 /* SPDX-License-Identifier: GPL-2.0-only */ 2 /* 3 * Driver model for leds and led triggers 4 * 5 * Copyright (C) 2005 John Lenz <[email protected]> 6 * Copyright (C) 2005 Richard Purdie <[email protected]> 7 */ 8 #ifndef __LINUX_LEDS_H_INCLUDED 9 #define __LINUX_LEDS_H_INCLUDED 10 11 #include <dt-bindings/leds/common.h> 12 #include <linux/device.h> 13 #include <linux/kernfs.h> 14 #include <linux/list.h> 15 #include <linux/mutex.h> 16 #include <linux/rwsem.h> 17 #include <linux/spinlock.h> 18 #include <linux/timer.h> 19 #include <linux/workqueue.h> 20 21 struct device; 22 struct led_pattern; 23 struct device_node; 24 /* 25 * LED Core 26 */ 27 28 /* This is obsolete/useless. We now support variable maximum brightness. */ 29 enum led_brightness { 30 LED_OFF = 0, 31 LED_ON = 1, 32 LED_HALF = 127, 33 LED_FULL = 255, 34 }; 35 36 enum led_default_state { 37 LEDS_DEFSTATE_OFF = 0, 38 LEDS_DEFSTATE_ON = 1, 39 LEDS_DEFSTATE_KEEP = 2, 40 }; 41 42 /** 43 * struct led_lookup_data - represents a single LED lookup entry 44 * 45 * @list: internal list of all LED lookup entries 46 * @provider: name of led_classdev providing the LED 47 * @dev_id: name of the device associated with this LED 48 * @con_id: name of the LED from the device's point of view 49 */ 50 struct led_lookup_data { 51 struct list_head list; 52 const char *provider; 53 const char *dev_id; 54 const char *con_id; 55 }; 56 57 struct led_init_data { 58 /* device fwnode handle */ 59 struct fwnode_handle *fwnode; 60 /* 61 * default <color:function> tuple, for backward compatibility 62 * with in-driver hard-coded LED names used as a fallback when 63 * DT "label" property is absent; it should be set to NULL 64 * in new LED class drivers. 65 */ 66 const char *default_label; 67 /* 68 * string to be used for devicename section of LED class device 69 * either for label based LED name composition path or for fwnode 70 * based when devname_mandatory is true 71 */ 72 const char *devicename; 73 /* 74 * indicates if LED name should always comprise devicename section; 75 * only LEDs exposed by drivers of hot-pluggable devices should 76 * set it to true 77 */ 78 bool devname_mandatory; 79 }; 80 81 struct led_hw_trigger_type { 82 int dummy; 83 }; 84 85 struct led_classdev { 86 const char *name; 87 unsigned int brightness; 88 unsigned int max_brightness; 89 int flags; 90 91 /* Lower 16 bits reflect status */ 92 #define LED_SUSPENDED BIT(0) 93 #define LED_UNREGISTERING BIT(1) 94 /* Upper 16 bits reflect control information */ 95 #define LED_CORE_SUSPENDRESUME BIT(16) 96 #define LED_SYSFS_DISABLE BIT(17) 97 #define LED_DEV_CAP_FLASH BIT(18) 98 #define LED_HW_PLUGGABLE BIT(19) 99 #define LED_PANIC_INDICATOR BIT(20) 100 #define LED_BRIGHT_HW_CHANGED BIT(21) 101 #define LED_RETAIN_AT_SHUTDOWN BIT(22) 102 #define LED_INIT_DEFAULT_TRIGGER BIT(23) 103 104 /* set_brightness_work / blink_timer flags, atomic, private. */ 105 unsigned long work_flags; 106 107 #define LED_BLINK_SW 0 108 #define LED_BLINK_ONESHOT 1 109 #define LED_BLINK_ONESHOT_STOP 2 110 #define LED_BLINK_INVERT 3 111 #define LED_BLINK_BRIGHTNESS_CHANGE 4 112 #define LED_BLINK_DISABLE 5 113 114 /* Set LED brightness level 115 * Must not sleep. Use brightness_set_blocking for drivers 116 * that can sleep while setting brightness. 117 */ 118 void (*brightness_set)(struct led_classdev *led_cdev, 119 enum led_brightness brightness); 120 /* 121 * Set LED brightness level immediately - it can block the caller for 122 * the time required for accessing a LED device register. 123 */ 124 int (*brightness_set_blocking)(struct led_classdev *led_cdev, 125 enum led_brightness brightness); 126 /* Get LED brightness level */ 127 enum led_brightness (*brightness_get)(struct led_classdev *led_cdev); 128 129 /* 130 * Activate hardware accelerated blink, delays are in milliseconds 131 * and if both are zero then a sensible default should be chosen. 132 * The call should adjust the timings in that case and if it can't 133 * match the values specified exactly. 134 * Deactivate blinking again when the brightness is set to LED_OFF 135 * via the brightness_set() callback. 136 */ 137 int (*blink_set)(struct led_classdev *led_cdev, 138 unsigned long *delay_on, 139 unsigned long *delay_off); 140 141 int (*pattern_set)(struct led_classdev *led_cdev, 142 struct led_pattern *pattern, u32 len, int repeat); 143 int (*pattern_clear)(struct led_classdev *led_cdev); 144 145 struct device *dev; 146 const struct attribute_group **groups; 147 148 struct list_head node; /* LED Device list */ 149 const char *default_trigger; /* Trigger to use */ 150 151 unsigned long blink_delay_on, blink_delay_off; 152 struct timer_list blink_timer; 153 int blink_brightness; 154 int new_blink_brightness; 155 void (*flash_resume)(struct led_classdev *led_cdev); 156 157 struct work_struct set_brightness_work; 158 int delayed_set_value; 159 160 #ifdef CONFIG_LEDS_TRIGGERS 161 /* Protects the trigger data below */ 162 struct rw_semaphore trigger_lock; 163 164 struct led_trigger *trigger; 165 struct list_head trig_list; 166 void *trigger_data; 167 /* true if activated - deactivate routine uses it to do cleanup */ 168 bool activated; 169 170 /* LEDs that have private triggers have this set */ 171 struct led_hw_trigger_type *trigger_type; 172 #endif 173 174 #ifdef CONFIG_LEDS_BRIGHTNESS_HW_CHANGED 175 int brightness_hw_changed; 176 struct kernfs_node *brightness_hw_changed_kn; 177 #endif 178 179 /* Ensures consistent access to the LED Flash Class device */ 180 struct mutex led_access; 181 }; 182 183 /** 184 * led_classdev_register_ext - register a new object of LED class with 185 * init data 186 * @parent: LED controller device this LED is driven by 187 * @led_cdev: the led_classdev structure for this device 188 * @init_data: the LED class device initialization data 189 * 190 * Register a new object of LED class, with name derived from init_data. 191 * 192 * Returns: 0 on success or negative error value on failure 193 */ 194 int led_classdev_register_ext(struct device *parent, 195 struct led_classdev *led_cdev, 196 struct led_init_data *init_data); 197 198 /** 199 * led_classdev_register - register a new object of LED class 200 * @parent: LED controller device this LED is driven by 201 * @led_cdev: the led_classdev structure for this device 202 * 203 * Register a new object of LED class, with name derived from the name property 204 * of passed led_cdev argument. 205 * 206 * Returns: 0 on success or negative error value on failure 207 */ 208 static inline int led_classdev_register(struct device *parent, 209 struct led_classdev *led_cdev) 210 { 211 return led_classdev_register_ext(parent, led_cdev, NULL); 212 } 213 214 int devm_led_classdev_register_ext(struct device *parent, 215 struct led_classdev *led_cdev, 216 struct led_init_data *init_data); 217 218 static inline int devm_led_classdev_register(struct device *parent, 219 struct led_classdev *led_cdev) 220 { 221 return devm_led_classdev_register_ext(parent, led_cdev, NULL); 222 } 223 void led_classdev_unregister(struct led_classdev *led_cdev); 224 void devm_led_classdev_unregister(struct device *parent, 225 struct led_classdev *led_cdev); 226 void led_classdev_suspend(struct led_classdev *led_cdev); 227 void led_classdev_resume(struct led_classdev *led_cdev); 228 229 void led_add_lookup(struct led_lookup_data *led_lookup); 230 void led_remove_lookup(struct led_lookup_data *led_lookup); 231 232 struct led_classdev *__must_check led_get(struct device *dev, char *con_id); 233 struct led_classdev *__must_check devm_led_get(struct device *dev, char *con_id); 234 235 extern struct led_classdev *of_led_get(struct device_node *np, int index); 236 extern void led_put(struct led_classdev *led_cdev); 237 struct led_classdev *__must_check devm_of_led_get(struct device *dev, 238 int index); 239 240 /** 241 * led_blink_set - set blinking with software fallback 242 * @led_cdev: the LED to start blinking 243 * @delay_on: the time it should be on (in ms) 244 * @delay_off: the time it should ble off (in ms) 245 * 246 * This function makes the LED blink, attempting to use the 247 * hardware acceleration if possible, but falling back to 248 * software blinking if there is no hardware blinking or if 249 * the LED refuses the passed values. 250 * 251 * Note that if software blinking is active, simply calling 252 * led_cdev->brightness_set() will not stop the blinking, 253 * use led_classdev_brightness_set() instead. 254 */ 255 void led_blink_set(struct led_classdev *led_cdev, unsigned long *delay_on, 256 unsigned long *delay_off); 257 /** 258 * led_blink_set_oneshot - do a oneshot software blink 259 * @led_cdev: the LED to start blinking 260 * @delay_on: the time it should be on (in ms) 261 * @delay_off: the time it should ble off (in ms) 262 * @invert: blink off, then on, leaving the led on 263 * 264 * This function makes the LED blink one time for delay_on + 265 * delay_off time, ignoring the request if another one-shot 266 * blink is already in progress. 267 * 268 * If invert is set, led blinks for delay_off first, then for 269 * delay_on and leave the led on after the on-off cycle. 270 */ 271 void led_blink_set_oneshot(struct led_classdev *led_cdev, 272 unsigned long *delay_on, unsigned long *delay_off, 273 int invert); 274 /** 275 * led_set_brightness - set LED brightness 276 * @led_cdev: the LED to set 277 * @brightness: the brightness to set it to 278 * 279 * Set an LED's brightness, and, if necessary, cancel the 280 * software blink timer that implements blinking when the 281 * hardware doesn't. This function is guaranteed not to sleep. 282 */ 283 void led_set_brightness(struct led_classdev *led_cdev, unsigned int brightness); 284 285 /** 286 * led_set_brightness_sync - set LED brightness synchronously 287 * @led_cdev: the LED to set 288 * @value: the brightness to set it to 289 * 290 * Set an LED's brightness immediately. This function will block 291 * the caller for the time required for accessing device registers, 292 * and it can sleep. 293 * 294 * Returns: 0 on success or negative error value on failure 295 */ 296 int led_set_brightness_sync(struct led_classdev *led_cdev, unsigned int value); 297 298 /** 299 * led_update_brightness - update LED brightness 300 * @led_cdev: the LED to query 301 * 302 * Get an LED's current brightness and update led_cdev->brightness 303 * member with the obtained value. 304 * 305 * Returns: 0 on success or negative error value on failure 306 */ 307 int led_update_brightness(struct led_classdev *led_cdev); 308 309 /** 310 * led_get_default_pattern - return default pattern 311 * 312 * @led_cdev: the LED to get default pattern for 313 * @size: pointer for storing the number of elements in returned array, 314 * modified only if return != NULL 315 * 316 * Return: Allocated array of integers with default pattern from device tree 317 * or NULL. Caller is responsible for kfree(). 318 */ 319 u32 *led_get_default_pattern(struct led_classdev *led_cdev, unsigned int *size); 320 321 /** 322 * led_sysfs_disable - disable LED sysfs interface 323 * @led_cdev: the LED to set 324 * 325 * Disable the led_cdev's sysfs interface. 326 */ 327 void led_sysfs_disable(struct led_classdev *led_cdev); 328 329 /** 330 * led_sysfs_enable - enable LED sysfs interface 331 * @led_cdev: the LED to set 332 * 333 * Enable the led_cdev's sysfs interface. 334 */ 335 void led_sysfs_enable(struct led_classdev *led_cdev); 336 337 /** 338 * led_compose_name - compose LED class device name 339 * @dev: LED controller device object 340 * @init_data: the LED class device initialization data 341 * @led_classdev_name: composed LED class device name 342 * 343 * Create LED class device name basing on the provided init_data argument. 344 * The name can have <devicename:color:function> or <color:function>. 345 * form, depending on the init_data configuration. 346 * 347 * Returns: 0 on success or negative error value on failure 348 */ 349 int led_compose_name(struct device *dev, struct led_init_data *init_data, 350 char *led_classdev_name); 351 352 /** 353 * led_sysfs_is_disabled - check if LED sysfs interface is disabled 354 * @led_cdev: the LED to query 355 * 356 * Returns: true if the led_cdev's sysfs interface is disabled. 357 */ 358 static inline bool led_sysfs_is_disabled(struct led_classdev *led_cdev) 359 { 360 return led_cdev->flags & LED_SYSFS_DISABLE; 361 } 362 363 /* 364 * LED Triggers 365 */ 366 /* Registration functions for simple triggers */ 367 #define DEFINE_LED_TRIGGER(x) static struct led_trigger *x; 368 #define DEFINE_LED_TRIGGER_GLOBAL(x) struct led_trigger *x; 369 370 #ifdef CONFIG_LEDS_TRIGGERS 371 372 #define TRIG_NAME_MAX 50 373 374 struct led_trigger { 375 /* Trigger Properties */ 376 const char *name; 377 int (*activate)(struct led_classdev *led_cdev); 378 void (*deactivate)(struct led_classdev *led_cdev); 379 380 /* LED-private triggers have this set */ 381 struct led_hw_trigger_type *trigger_type; 382 383 /* LEDs under control by this trigger (for simple triggers) */ 384 spinlock_t leddev_list_lock; 385 struct list_head led_cdevs; 386 387 /* Link to next registered trigger */ 388 struct list_head next_trig; 389 390 const struct attribute_group **groups; 391 }; 392 393 /* 394 * Currently the attributes in struct led_trigger::groups are added directly to 395 * the LED device. As this might change in the future, the following 396 * macros abstract getting the LED device and its trigger_data from the dev 397 * parameter passed to the attribute accessor functions. 398 */ 399 #define led_trigger_get_led(dev) ((struct led_classdev *)dev_get_drvdata((dev))) 400 #define led_trigger_get_drvdata(dev) (led_get_trigger_data(led_trigger_get_led(dev))) 401 402 /* Registration functions for complex triggers */ 403 int led_trigger_register(struct led_trigger *trigger); 404 void led_trigger_unregister(struct led_trigger *trigger); 405 int devm_led_trigger_register(struct device *dev, 406 struct led_trigger *trigger); 407 408 void led_trigger_register_simple(const char *name, 409 struct led_trigger **trigger); 410 void led_trigger_unregister_simple(struct led_trigger *trigger); 411 void led_trigger_event(struct led_trigger *trigger, enum led_brightness event); 412 void led_trigger_blink(struct led_trigger *trigger, unsigned long *delay_on, 413 unsigned long *delay_off); 414 void led_trigger_blink_oneshot(struct led_trigger *trigger, 415 unsigned long *delay_on, 416 unsigned long *delay_off, 417 int invert); 418 void led_trigger_set_default(struct led_classdev *led_cdev); 419 int led_trigger_set(struct led_classdev *led_cdev, struct led_trigger *trigger); 420 void led_trigger_remove(struct led_classdev *led_cdev); 421 422 static inline void led_set_trigger_data(struct led_classdev *led_cdev, 423 void *trigger_data) 424 { 425 led_cdev->trigger_data = trigger_data; 426 } 427 428 static inline void *led_get_trigger_data(struct led_classdev *led_cdev) 429 { 430 return led_cdev->trigger_data; 431 } 432 433 /** 434 * led_trigger_rename_static - rename a trigger 435 * @name: the new trigger name 436 * @trig: the LED trigger to rename 437 * 438 * Change a LED trigger name by copying the string passed in 439 * name into current trigger name, which MUST be large 440 * enough for the new string. 441 * 442 * Note that name must NOT point to the same string used 443 * during LED registration, as that could lead to races. 444 * 445 * This is meant to be used on triggers with statically 446 * allocated name. 447 */ 448 void led_trigger_rename_static(const char *name, struct led_trigger *trig); 449 450 #define module_led_trigger(__led_trigger) \ 451 module_driver(__led_trigger, led_trigger_register, \ 452 led_trigger_unregister) 453 454 #else 455 456 /* Trigger has no members */ 457 struct led_trigger {}; 458 459 /* Trigger inline empty functions */ 460 static inline void led_trigger_register_simple(const char *name, 461 struct led_trigger **trigger) {} 462 static inline void led_trigger_unregister_simple(struct led_trigger *trigger) {} 463 static inline void led_trigger_event(struct led_trigger *trigger, 464 enum led_brightness event) {} 465 static inline void led_trigger_blink(struct led_trigger *trigger, 466 unsigned long *delay_on, 467 unsigned long *delay_off) {} 468 static inline void led_trigger_blink_oneshot(struct led_trigger *trigger, 469 unsigned long *delay_on, 470 unsigned long *delay_off, 471 int invert) {} 472 static inline void led_trigger_set_default(struct led_classdev *led_cdev) {} 473 static inline int led_trigger_set(struct led_classdev *led_cdev, 474 struct led_trigger *trigger) 475 { 476 return 0; 477 } 478 479 static inline void led_trigger_remove(struct led_classdev *led_cdev) {} 480 static inline void led_set_trigger_data(struct led_classdev *led_cdev) {} 481 static inline void *led_get_trigger_data(struct led_classdev *led_cdev) 482 { 483 return NULL; 484 } 485 486 #endif /* CONFIG_LEDS_TRIGGERS */ 487 488 /* Trigger specific functions */ 489 #ifdef CONFIG_LEDS_TRIGGER_DISK 490 void ledtrig_disk_activity(bool write); 491 #else 492 static inline void ledtrig_disk_activity(bool write) {} 493 #endif 494 495 #ifdef CONFIG_LEDS_TRIGGER_MTD 496 void ledtrig_mtd_activity(void); 497 #else 498 static inline void ledtrig_mtd_activity(void) {} 499 #endif 500 501 #if defined(CONFIG_LEDS_TRIGGER_CAMERA) || defined(CONFIG_LEDS_TRIGGER_CAMERA_MODULE) 502 void ledtrig_flash_ctrl(bool on); 503 void ledtrig_torch_ctrl(bool on); 504 #else 505 static inline void ledtrig_flash_ctrl(bool on) {} 506 static inline void ledtrig_torch_ctrl(bool on) {} 507 #endif 508 509 /* 510 * Generic LED platform data for describing LED names and default triggers. 511 */ 512 struct led_info { 513 const char *name; 514 const char *default_trigger; 515 int flags; 516 }; 517 518 struct led_platform_data { 519 int num_leds; 520 struct led_info *leds; 521 }; 522 523 struct led_properties { 524 u32 color; 525 bool color_present; 526 const char *function; 527 u32 func_enum; 528 bool func_enum_present; 529 const char *label; 530 }; 531 532 struct gpio_desc; 533 typedef int (*gpio_blink_set_t)(struct gpio_desc *desc, int state, 534 unsigned long *delay_on, 535 unsigned long *delay_off); 536 537 /* For the leds-gpio driver */ 538 struct gpio_led { 539 const char *name; 540 const char *default_trigger; 541 unsigned gpio; 542 unsigned active_low : 1; 543 unsigned retain_state_suspended : 1; 544 unsigned panic_indicator : 1; 545 unsigned default_state : 2; 546 unsigned retain_state_shutdown : 1; 547 /* default_state should be one of LEDS_GPIO_DEFSTATE_(ON|OFF|KEEP) */ 548 struct gpio_desc *gpiod; 549 }; 550 #define LEDS_GPIO_DEFSTATE_OFF LEDS_DEFSTATE_OFF 551 #define LEDS_GPIO_DEFSTATE_ON LEDS_DEFSTATE_ON 552 #define LEDS_GPIO_DEFSTATE_KEEP LEDS_DEFSTATE_KEEP 553 554 struct gpio_led_platform_data { 555 int num_leds; 556 const struct gpio_led *leds; 557 558 #define GPIO_LED_NO_BLINK_LOW 0 /* No blink GPIO state low */ 559 #define GPIO_LED_NO_BLINK_HIGH 1 /* No blink GPIO state high */ 560 #define GPIO_LED_BLINK 2 /* Please, blink */ 561 gpio_blink_set_t gpio_blink_set; 562 }; 563 564 #ifdef CONFIG_NEW_LEDS 565 struct platform_device *gpio_led_register_device( 566 int id, const struct gpio_led_platform_data *pdata); 567 #else 568 static inline struct platform_device *gpio_led_register_device( 569 int id, const struct gpio_led_platform_data *pdata) 570 { 571 return 0; 572 } 573 #endif 574 575 enum cpu_led_event { 576 CPU_LED_IDLE_START, /* CPU enters idle */ 577 CPU_LED_IDLE_END, /* CPU idle ends */ 578 CPU_LED_START, /* Machine starts, especially resume */ 579 CPU_LED_STOP, /* Machine stops, especially suspend */ 580 CPU_LED_HALTED, /* Machine shutdown */ 581 }; 582 #ifdef CONFIG_LEDS_TRIGGER_CPU 583 void ledtrig_cpu(enum cpu_led_event evt); 584 #else 585 static inline void ledtrig_cpu(enum cpu_led_event evt) 586 { 587 return; 588 } 589 #endif 590 591 #ifdef CONFIG_LEDS_BRIGHTNESS_HW_CHANGED 592 void led_classdev_notify_brightness_hw_changed( 593 struct led_classdev *led_cdev, unsigned int brightness); 594 #else 595 static inline void led_classdev_notify_brightness_hw_changed( 596 struct led_classdev *led_cdev, enum led_brightness brightness) { } 597 #endif 598 599 /** 600 * struct led_pattern - pattern interval settings 601 * @delta_t: pattern interval delay, in milliseconds 602 * @brightness: pattern interval brightness 603 */ 604 struct led_pattern { 605 u32 delta_t; 606 int brightness; 607 }; 608 609 enum led_audio { 610 LED_AUDIO_MUTE, /* master mute LED */ 611 LED_AUDIO_MICMUTE, /* mic mute LED */ 612 NUM_AUDIO_LEDS 613 }; 614 615 #if IS_ENABLED(CONFIG_LEDS_TRIGGER_AUDIO) 616 enum led_brightness ledtrig_audio_get(enum led_audio type); 617 void ledtrig_audio_set(enum led_audio type, enum led_brightness state); 618 #else 619 static inline enum led_brightness ledtrig_audio_get(enum led_audio type) 620 { 621 return LED_OFF; 622 } 623 static inline void ledtrig_audio_set(enum led_audio type, 624 enum led_brightness state) 625 { 626 } 627 #endif 628 629 #endif /* __LINUX_LEDS_H_INCLUDED */ 630