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