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