1 /*
2 * Copyright (c) 2018 Linaro Limited
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /**
8 * @file
9 * @brief Public LED driver APIs
10 */
11
12 #ifndef ZEPHYR_INCLUDE_DRIVERS_LED_H_
13 #define ZEPHYR_INCLUDE_DRIVERS_LED_H_
14
15 /**
16 * @brief LED Interface
17 * @defgroup led_interface LED Interface
18 * @since 1.12
19 * @version 1.0.0
20 * @ingroup io_interfaces
21 * @{
22 */
23
24 #include <errno.h>
25
26 #include <zephyr/types.h>
27 #include <zephyr/device.h>
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33 /**
34 * @brief LED information structure
35 *
36 * This structure gathers useful information about LED controller.
37 */
38 struct led_info {
39 /** LED label */
40 const char *label;
41 /** Index of the LED on the controller */
42 uint32_t index;
43 /** Number of colors per LED */
44 uint8_t num_colors;
45 /** Mapping of the LED colors */
46 const uint8_t *color_mapping;
47 };
48
49 /**
50 * @typedef led_api_blink()
51 * @brief Callback API for blinking an LED
52 *
53 * @see led_blink() for argument descriptions.
54 */
55 typedef int (*led_api_blink)(const struct device *dev, uint32_t led,
56 uint32_t delay_on, uint32_t delay_off);
57
58 /**
59 * @typedef led_api_get_info()
60 * @brief Optional API callback to get LED information
61 *
62 * @see led_get_info() for argument descriptions.
63 */
64 typedef int (*led_api_get_info)(const struct device *dev, uint32_t led,
65 const struct led_info **info);
66
67 /**
68 * @typedef led_api_set_brightness()
69 * @brief Callback API for setting brightness of an LED
70 *
71 * @see led_set_brightness() for argument descriptions.
72 */
73 typedef int (*led_api_set_brightness)(const struct device *dev, uint32_t led,
74 uint8_t value);
75 /**
76 * @typedef led_api_set_color()
77 * @brief Optional API callback to set the colors of a LED.
78 *
79 * @see led_set_color() for argument descriptions.
80 */
81 typedef int (*led_api_set_color)(const struct device *dev, uint32_t led,
82 uint8_t num_colors, const uint8_t *color);
83
84 /**
85 * @typedef led_api_on()
86 * @brief Callback API for turning on an LED
87 *
88 * @see led_on() for argument descriptions.
89 */
90 typedef int (*led_api_on)(const struct device *dev, uint32_t led);
91
92 /**
93 * @typedef led_api_off()
94 * @brief Callback API for turning off an LED
95 *
96 * @see led_off() for argument descriptions.
97 */
98 typedef int (*led_api_off)(const struct device *dev, uint32_t led);
99
100 /**
101 * @typedef led_api_write_channels()
102 * @brief Callback API for writing a strip of LED channels
103 *
104 * @see led_api_write_channels() for arguments descriptions.
105 */
106 typedef int (*led_api_write_channels)(const struct device *dev,
107 uint32_t start_channel,
108 uint32_t num_channels,
109 const uint8_t *buf);
110
111 /**
112 * @brief LED driver API
113 */
114 __subsystem struct led_driver_api {
115 /* Mandatory callbacks. */
116 led_api_on on;
117 led_api_off off;
118 /* Optional callbacks. */
119 led_api_blink blink;
120 led_api_get_info get_info;
121 led_api_set_brightness set_brightness;
122 led_api_set_color set_color;
123 led_api_write_channels write_channels;
124 };
125
126 /**
127 * @brief Blink an LED
128 *
129 * This optional routine starts blinking a LED forever with the given time
130 * period.
131 *
132 * @param dev LED device
133 * @param led LED number
134 * @param delay_on Time period (in milliseconds) an LED should be ON
135 * @param delay_off Time period (in milliseconds) an LED should be OFF
136 * @return 0 on success, negative on error
137 */
138 __syscall int led_blink(const struct device *dev, uint32_t led,
139 uint32_t delay_on, uint32_t delay_off);
140
z_impl_led_blink(const struct device * dev,uint32_t led,uint32_t delay_on,uint32_t delay_off)141 static inline int z_impl_led_blink(const struct device *dev, uint32_t led,
142 uint32_t delay_on, uint32_t delay_off)
143 {
144 const struct led_driver_api *api =
145 (const struct led_driver_api *)dev->api;
146
147 if (api->blink == NULL) {
148 return -ENOSYS;
149 }
150 return api->blink(dev, led, delay_on, delay_off);
151 }
152
153 /**
154 * @brief Get LED information
155 *
156 * This optional routine provides information about a LED.
157 *
158 * @param dev LED device
159 * @param led LED number
160 * @param info Pointer to a pointer filled with LED information
161 * @return 0 on success, negative on error
162 */
163 __syscall int led_get_info(const struct device *dev, uint32_t led,
164 const struct led_info **info);
165
z_impl_led_get_info(const struct device * dev,uint32_t led,const struct led_info ** info)166 static inline int z_impl_led_get_info(const struct device *dev, uint32_t led,
167 const struct led_info **info)
168 {
169 const struct led_driver_api *api =
170 (const struct led_driver_api *)dev->api;
171
172 if (api->get_info == NULL) {
173 *info = NULL;
174 return -ENOSYS;
175 }
176 return api->get_info(dev, led, info);
177 }
178
179 /**
180 * @brief Set LED brightness
181 *
182 * This optional routine sets the brightness of a LED to the given value.
183 * Calling this function after led_blink() won't affect blinking.
184 *
185 * LEDs which can only be turned on or off may provide this function.
186 * These should simply turn the LED on if @p value is nonzero, and off
187 * if @p value is zero.
188 *
189 * @param dev LED device
190 * @param led LED number
191 * @param value Brightness value to set in percent
192 * @return 0 on success, negative on error
193 */
194 __syscall int led_set_brightness(const struct device *dev, uint32_t led,
195 uint8_t value);
196
z_impl_led_set_brightness(const struct device * dev,uint32_t led,uint8_t value)197 static inline int z_impl_led_set_brightness(const struct device *dev,
198 uint32_t led,
199 uint8_t value)
200 {
201 const struct led_driver_api *api =
202 (const struct led_driver_api *)dev->api;
203
204 if (api->set_brightness == NULL) {
205 return -ENOSYS;
206 }
207 return api->set_brightness(dev, led, value);
208 }
209
210 /**
211 * @brief Write/update a strip of LED channels
212 *
213 * This optional routine writes a strip of LED channels to the given array of
214 * levels. Therefore it can be used to configure several LEDs at the same time.
215 *
216 * Calling this function after led_blink() won't affect blinking.
217 *
218 * @param dev LED device
219 * @param start_channel Absolute number (i.e. not relative to a LED) of the
220 * first channel to update.
221 * @param num_channels The number of channels to write/update.
222 * @param buf array of values to configure the channels with. num_channels
223 * entries must be provided.
224 * @return 0 on success, negative on error
225 */
226 __syscall int led_write_channels(const struct device *dev,
227 uint32_t start_channel,
228 uint32_t num_channels, const uint8_t *buf);
229
230 static inline int
z_impl_led_write_channels(const struct device * dev,uint32_t start_channel,uint32_t num_channels,const uint8_t * buf)231 z_impl_led_write_channels(const struct device *dev, uint32_t start_channel,
232 uint32_t num_channels, const uint8_t *buf)
233 {
234 const struct led_driver_api *api =
235 (const struct led_driver_api *)dev->api;
236
237 if (api->write_channels == NULL) {
238 return -ENOSYS;
239 }
240 return api->write_channels(dev, start_channel, num_channels, buf);
241 }
242
243 /**
244 * @brief Set a single LED channel
245 *
246 * This optional routine sets a single LED channel to the given value.
247 *
248 * Calling this function after led_blink() won't affect blinking.
249 *
250 * @param dev LED device
251 * @param channel Absolute channel number (i.e. not relative to a LED)
252 * @param value Value to configure the channel with
253 * @return 0 on success, negative on error
254 */
255 __syscall int led_set_channel(const struct device *dev,
256 uint32_t channel, uint8_t value);
257
z_impl_led_set_channel(const struct device * dev,uint32_t channel,uint8_t value)258 static inline int z_impl_led_set_channel(const struct device *dev,
259 uint32_t channel, uint8_t value)
260 {
261 return z_impl_led_write_channels(dev, channel, 1, &value);
262 }
263
264 /**
265 * @brief Set LED color
266 *
267 * This routine configures all the color channels of a LED with the given
268 * color array.
269 *
270 * Calling this function after led_blink() won't affect blinking.
271 *
272 * @param dev LED device
273 * @param led LED number
274 * @param num_colors Number of colors in the array.
275 * @param color Array of colors. It must be ordered following the color
276 * mapping of the LED controller. See the color_mapping member
277 * in struct led_info.
278 * @return 0 on success, negative on error
279 */
280 __syscall int led_set_color(const struct device *dev, uint32_t led,
281 uint8_t num_colors, const uint8_t *color);
282
z_impl_led_set_color(const struct device * dev,uint32_t led,uint8_t num_colors,const uint8_t * color)283 static inline int z_impl_led_set_color(const struct device *dev, uint32_t led,
284 uint8_t num_colors, const uint8_t *color)
285 {
286 const struct led_driver_api *api =
287 (const struct led_driver_api *)dev->api;
288
289 if (api->set_color == NULL) {
290 return -ENOSYS;
291 }
292 return api->set_color(dev, led, num_colors, color);
293 }
294
295 /**
296 * @brief Turn on an LED
297 *
298 * This routine turns on an LED
299 *
300 * @param dev LED device
301 * @param led LED number
302 * @return 0 on success, negative on error
303 */
304 __syscall int led_on(const struct device *dev, uint32_t led);
305
z_impl_led_on(const struct device * dev,uint32_t led)306 static inline int z_impl_led_on(const struct device *dev, uint32_t led)
307 {
308 const struct led_driver_api *api =
309 (const struct led_driver_api *)dev->api;
310
311 return api->on(dev, led);
312 }
313
314 /**
315 * @brief Turn off an LED
316 *
317 * This routine turns off an LED
318 *
319 * @param dev LED device
320 * @param led LED number
321 * @return 0 on success, negative on error
322 */
323 __syscall int led_off(const struct device *dev, uint32_t led);
324
z_impl_led_off(const struct device * dev,uint32_t led)325 static inline int z_impl_led_off(const struct device *dev, uint32_t led)
326 {
327 const struct led_driver_api *api =
328 (const struct led_driver_api *)dev->api;
329
330 return api->off(dev, led);
331 }
332
333 /*
334 * LED DT helpers.
335 */
336
337 /**
338 * @brief Container for an LED information specified in devicetree.
339 *
340 * This type contains a pointer to and LED device and an LED index.
341 *
342 * @see LED_DT_SPEC_GET
343 * @see LED_DT_SPEC_GET_OR
344 */
345 struct led_dt_spec {
346 /** LED device instance. */
347 const struct device *dev;
348 /** Index of the LED on the controller. */
349 uint32_t index;
350 };
351
352 /**
353 * @brief Set LED brightness from a led_dt_spec.
354 *
355 * @param spec LED device specification from devicetree.
356 * @param value Brightness value to set in percent.
357 * @return 0 on success, negative on error.
358 *
359 * @see led_set_brightness()
360 */
led_set_brightness_dt(const struct led_dt_spec * spec,uint8_t value)361 static inline int led_set_brightness_dt(const struct led_dt_spec *spec,
362 uint8_t value)
363 {
364 return led_set_brightness(spec->dev, spec->index, value);
365 }
366
367 /**
368 * @brief Turn on an LED from a struct led_dt_spec.
369 *
370 * @param spec LED device specification from devicetree.
371 * @return 0 on success, negative on error.
372 *
373 * @see led_on()
374 */
led_on_dt(const struct led_dt_spec * spec)375 static inline int led_on_dt(const struct led_dt_spec *spec)
376 {
377 return led_on(spec->dev, spec->index);
378 }
379
380 /**
381 * @brief Turn off an LED from a struct led_dt_spec.
382 *
383 * @param spec LED device specification from devicetree.
384 * @return 0 on success, negative on error.
385 *
386 * @see led_off()
387 */
led_off_dt(const struct led_dt_spec * spec)388 static inline int led_off_dt(const struct led_dt_spec *spec)
389 {
390 return led_off(spec->dev, spec->index);
391 }
392
393 /**
394 * @brief Validate that the LED device is ready.
395 *
396 * @param spec LED specification from devicetree.
397 *
398 * @retval true If the LED device is ready for use.
399 * @retval false If the LED device is not ready for use.
400 */
led_is_ready_dt(const struct led_dt_spec * spec)401 static inline bool led_is_ready_dt(const struct led_dt_spec *spec)
402 {
403 return device_is_ready(spec->dev);
404 }
405
406 /**
407 * @brief Static initializer for a struct led_dt_spec
408 *
409 * This returns a static initializer for a struct led_dt_spec given a devicetree
410 * node identifier.
411 *
412 * Example devicetree fragment:
413 *
414 * @code{.dts}
415 * leds {
416 * compatible = "gpio-leds";
417 * led0: led_0 {
418 * ...
419 * };
420 * };
421 * @endcode
422 *
423 * Example usage:
424 *
425 * @code{.c}
426 * const struct led_dt_spec spec = LED_DT_SPEC_GET(DT_NODELABEL(led0));
427 *
428 * // Initializes 'spec' to:
429 * // {
430 * // .dev = DEVICE_DT_GET(DT_PARENT(led0)),
431 * // .index = 0,
432 * // }
433 * @endcode
434 *
435 * The device (dev) must still be checked for readiness, e.g. using
436 * device_is_ready().
437 *
438 * @param node_id Devicetree node identifier.
439 *
440 * @return Static initializer for a struct led_dt_spec for the property.
441 */
442 #define LED_DT_SPEC_GET(node_id) \
443 { \
444 .dev = DEVICE_DT_GET(DT_PARENT(node_id)), \
445 .index = DT_NODE_CHILD_IDX(node_id), \
446 }
447
448 /**
449 * @brief Like LED_DT_SPEC_GET(), with a fallback value if the node does not exist.
450 *
451 * @param node_id Devicetree node identifier.
452 *
453 * @return Static initializer for a struct led_dt_spec for the property.
454 *
455 * @see LED_DT_SPEC_GET
456 */
457 #define LED_DT_SPEC_GET_OR(node_id, default_value) \
458 COND_CODE_1(DT_NODE_EXISTS(node_id), \
459 (LED_DT_SPEC_GET(node_id)), \
460 (default_value))
461
462 /**
463 * @}
464 */
465
466 #ifdef __cplusplus
467 }
468 #endif
469
470 #include <zephyr/syscalls/led.h>
471
472 #endif /* ZEPHYR_INCLUDE_DRIVERS_LED_H_ */
473
