include/led.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * Copyright (c) 2015 Google, Inc
   4  * Written by Simon Glass <[email protected]>
   5  */
   6
   7 #ifndef __LED_H
   8 #define __LED_H
   9
  10 #include <stdbool.h>
  11 #include <cyclic.h>
  12 #include <dm/ofnode.h>
  13
  14 /**
  15  * DOC: Overview
  16  *
  17  * Generic LED API provided when a supported compatible is defined in DeviceTree.
  18  *
  19  * To enable support for LEDs, enable the `CONFIG_LED` Kconfig option.
  20  *
  21  * The most common implementation is for GPIO-connected LEDs. If using GPIO-connected LEDs,
  22  * enable the `LED_GPIO` Kconfig option.
  23  *
  24  * `LED_BLINK` support requires LED driver support and is therefore optional. If LED blink
  25  * functionality is needed, enable the `LED_BLINK` Kconfig option. If LED driver doesn't
  26  * support HW Blink, SW Blink can be used with the Cyclic framework by enabling the
  27  * CONFIG_LED_SW_BLINK.
  28  *
  29  * Boot and Activity LEDs are also supported. These LEDs can signal various system operations
  30  * during runtime, such as boot initialization, file transfers, and flash write/erase operations.
  31  *
  32  * To enable a Boot LED, enable `CONFIG_LED_BOOT` and define in `/options/u-boot` root node the
  33  * property `boot-led`. This will enable the specified LED to blink and turn ON when
  34  * the bootloader initializes correctly.
  35  *
  36  * To enable an Activity LED, enable `CONFIG_LED_ACTIVITY` and define in `/options/u-boot` root
  37  * node the property `activity-led`.
  38  * This will enable the specified LED to blink and turn ON during file transfers or flash
  39  * write/erase operations.
  40  *
  41  * Both Boot and Activity LEDs provide a simple API to turn the LED ON or OFF:
  42  * `led_boot_on()`, `led_boot_off()`, `led_activity_on()`, and `led_activity_off()`.
  43  *
  44  * Both configurations can optionally define a `boot/activity-led-period` property
  45  * if `CONFIG_LED_BLINK` or `CONFIG_LED_SW_BLINK` is enabled for LED blink operations, which
  46  * is usually used by the Activity LED. If not defined the default value of 250 (ms) is used.
  47  *
  48  * When `CONFIG_LED_BLINK` or `CONFIG_LED_SW_BLINK` is enabled, additional APIs are exposed:
  49  * `led_boot_blink()` and `led_activity_blink()`. Note that if `CONFIG_LED_BLINK` or
  50  * `CONFIG_LED_SW_BLINK` is disabled, these APIs will behave like the `led_boot_on()` and
  51  * `led_activity_on()` APIs, respectively.
  52  */
  53
  54 struct udevice;
  55
  56 enum led_state_t {
  57         LEDST_OFF = 0,
  58         LEDST_ON = 1,
  59         LEDST_TOGGLE,
  60         LEDST_BLINK,
  61
  62         LEDST_COUNT,
  63 };
  64
  65 enum led_sw_blink_state_t {
  66         LED_SW_BLINK_ST_DISABLED,
  67         LED_SW_BLINK_ST_NOT_READY,
  68         LED_SW_BLINK_ST_OFF,
  69         LED_SW_BLINK_ST_ON,
  70 };
  71
  72 struct led_sw_blink {
  73         enum led_sw_blink_state_t state;
  74         struct udevice *dev;
  75         struct cyclic_info cyclic;
  76         const char cyclic_name[0];
  77 };
  78
  79 /**
  80  * struct led_uc_plat - Platform data the uclass stores about each device
  81  *
  82  * @label:      LED label
  83  * @default_state:      LED default state
  84  * @sw_blink:   LED software blink struct
  85  */
  86 struct led_uc_plat {
  87         const char *label;
  88         enum led_state_t default_state;
  89 #ifdef CONFIG_LED_SW_BLINK
  90         struct led_sw_blink *sw_blink;
  91 #endif
  92 };
  93
  94 /**
  95  * struct led_uc_priv - Private data the uclass stores about each device
  96  *
  97  * @boot_led_label:     Boot LED label
  98  * @activity_led_label: Activity LED label
  99  * @boot_led_dev:       Boot LED dev
 100  * @activity_led_dev:   Activity LED dev
 101  * @boot_led_period:    Boot LED blink period
 102  * @activity_led_period: Activity LED blink period
 103  */
 104 struct led_uc_priv {
 105 #ifdef CONFIG_LED_BOOT
 106         const char *boot_led_label;
 107         int boot_led_period;
 108 #endif
 109 #ifdef CONFIG_LED_ACTIVITY
 110         const char *activity_led_label;
 111         int activity_led_period;
 112 #endif
 113 };
 114
 115 struct led_ops {
 116         /**
 117          * set_state() - set the state of an LED
 118          *
 119          * @dev:        LED device to change
 120          * @state:      LED state to set
 121          * @return 0 if OK, -ve on error
 122          */
 123         int (*set_state)(struct udevice *dev, enum led_state_t state);
 124
 125         /**
 126          * led_get_state() - get the state of an LED
 127          *
 128          * @dev:        LED device to change
 129          * @return LED state led_state_t, or -ve on error
 130          */
 131         enum led_state_t (*get_state)(struct udevice *dev);
 132
 133 #ifdef CONFIG_LED_BLINK
 134         /**
 135          * led_set_period() - set the blink period of an LED
 136          *
 137          * Thie records the period if supported, or returns -ENOSYS if not.
 138          * To start the LED blinking, use set_state().
 139          *
 140          * @dev:        LED device to change
 141          * @period_ms:  LED blink period in milliseconds
 142          * @return 0 if OK, -ve on error
 143          */
 144         int (*set_period)(struct udevice *dev, int period_ms);
 145 #endif
 146 };
 147
 148 #define led_get_ops(dev)        ((struct led_ops *)(dev)->driver->ops)
 149
 150 /**
 151  * led_get_by_label() - Find an LED device by label
 152  *
 153  * @label:      LED label to look up
 154  * @devp:       Returns the associated device, if found
 155  * Return: 0 if found, -ENODEV if not found, other -ve on error
 156  */
 157 int led_get_by_label(const char *label, struct udevice **devp);
 158
 159 /**
 160  * led_set_state() - set the state of an LED
 161  *
 162  * @dev:        LED device to change
 163  * @state:      LED state to set
 164  * Return: 0 if OK, -ve on error
 165  */
 166 int led_set_state(struct udevice *dev, enum led_state_t state);
 167
 168 /**
 169  * led_get_state() - get the state of an LED
 170  *
 171  * @dev:        LED device to change
 172  * Return: LED state led_state_t, or -ve on error
 173  */
 174 enum led_state_t led_get_state(struct udevice *dev);
 175
 176 /**
 177  * led_set_period() - set the blink period of an LED
 178  *
 179  * @dev:        LED device to change
 180  * @period_ms:  LED blink period in milliseconds
 181  * Return: 0 if OK, -ve on error
 182  */
 183 int led_set_period(struct udevice *dev, int period_ms);
 184
 185 /**
 186  * led_bind_generic() - bind children of parent to given driver
 187  *
 188  * @parent:      Top-level LED device
 189  * @driver_name: Driver for handling individual child nodes
 190  */
 191 int led_bind_generic(struct udevice *parent, const char *driver_name);
 192
 193 /* Internal functions for software blinking. Do not use them in your code */
 194 int led_sw_set_period(struct udevice *dev, int period_ms);
 195 bool led_sw_is_blinking(struct udevice *dev);
 196 bool led_sw_on_state_change(struct udevice *dev, enum led_state_t state);
 197
 198 #ifdef CONFIG_LED_BOOT
 199
 200 /**
 201  * led_boot_on() - turn ON the designated LED for booting
 202  *
 203  * Return: 0 if OK, -ve on error
 204  */
 205 int led_boot_on(void);
 206
 207 /**
 208  * led_boot_off() - turn OFF the designated LED for booting
 209  *
 210  * Return: 0 if OK, -ve on error
 211  */
 212 int led_boot_off(void);
 213
 214 #if defined(CONFIG_LED_BLINK) || defined(CONFIG_LED_SW_BLINK)
 215 /**
 216  * led_boot_blink() - turn ON the designated LED for booting
 217  *
 218  * Return: 0 if OK, -ve on error
 219  */
 220 int led_boot_blink(void);
 221
 222 #else
 223 /* If LED BLINK is not supported/enabled, fallback to LED ON */
 224 #define led_boot_blink led_boot_on
 225 #endif
 226 #else
 227 static inline int led_boot_on(void)
 228 {
 229         return -ENOSYS;
 230 }
 231
 232 static inline int led_boot_off(void)
 233 {
 234         return -ENOSYS;
 235 }
 236
 237 static inline int led_boot_blink(void)
 238 {
 239         return -ENOSYS;
 240 }
 241 #endif
 242
 243 #ifdef CONFIG_LED_ACTIVITY
 244
 245 /**
 246  * led_activity_on() - turn ON the designated LED for activity
 247  *
 248  * Return: 0 if OK, -ve on error
 249  */
 250 int led_activity_on(void);
 251
 252 /**
 253  * led_activity_off() - turn OFF the designated LED for activity
 254  *
 255  * Return: 0 if OK, -ve on error
 256  */
 257 int led_activity_off(void);
 258
 259 #if defined(CONFIG_LED_BLINK) || defined(CONFIG_LED_SW_BLINK)
 260 /**
 261  * led_activity_blink() - turn ON the designated LED for activity
 262  *
 263  * Return: 0 if OK, -ve on error
 264  */
 265 int led_activity_blink(void);
 266 #else
 267 /* If LED BLINK is not supported/enabled, fallback to LED ON */
 268 #define led_activity_blink led_activity_on
 269 #endif
 270 #else
 271 static inline int led_activity_on(void)
 272 {
 273         return -ENOSYS;
 274 }
 275
 276 static inline int led_activity_off(void)
 277 {
 278         return -ENOSYS;
 279 }
 280
 281 static inline int led_activity_blink(void)
 282 {
 283         return -ENOSYS;
 284 }
 285 #endif
 286
 287 #endif