1 /*
2 * Copyright (c) 2022-2023 Jamie McCrae
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /**
8 * @file
9 * @brief Public API for auxiliary (textual/non-graphical) display drivers
10 */
11
12 #ifndef ZEPHYR_INCLUDE_DRIVERS_AUXDISPLAY_H_
13 #define ZEPHYR_INCLUDE_DRIVERS_AUXDISPLAY_H_
14
15 /**
16 * @brief Auxiliary (Text) Display Interface
17 * @defgroup auxdisplay_interface Text Display Interface
18 * @ingroup io_interfaces
19 * @{
20 */
21
22 #include <stdint.h>
23 #include <stddef.h>
24 #include <zephyr/kernel.h>
25 #include <zephyr/device.h>
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 /** @brief Used for minimum and maximum brightness/backlight values if not supported */
32 #define AUXDISPLAY_LIGHT_NOT_SUPPORTED 0
33
34 /** @brief Used to describe the mode of an auxiliary (text) display */
35 typedef uint32_t auxdisplay_mode_t;
36
37 /** @brief Used for moving the cursor or display position */
38 enum auxdisplay_position {
39 /** Moves to specified X,Y position */
40 AUXDISPLAY_POSITION_ABSOLUTE = 0,
41
42 /** Shifts current position by +/- X,Y position, does not take display direction into
43 * consideration
44 */
45 AUXDISPLAY_POSITION_RELATIVE,
46
47 /** Shifts current position by +/- X,Y position, takes display direction into
48 * consideration
49 */
50 AUXDISPLAY_POSITION_RELATIVE_DIRECTION,
51
52 AUXDISPLAY_POSITION_COUNT,
53 };
54
55 /** @brief Used for setting character append position */
56 enum auxdisplay_direction {
57 /** Each character will be placed to the right of existing characters */
58 AUXDISPLAY_DIRECTION_RIGHT = 0,
59
60 /** Each character will be placed to the left of existing characters */
61 AUXDISPLAY_DIRECTION_LEFT,
62
63 AUXDISPLAY_DIRECTION_COUNT,
64 };
65
66 /** @brief Light levels for brightness and/or backlight. If not supported by a
67 * display/driver, both minimum and maximum will be AUXDISPLAY_LIGHT_NOT_SUPPORTED.
68 */
69 struct auxdisplay_light {
70 /** Minimum light level supported */
71 uint8_t minimum;
72
73 /** Maximum light level supported */
74 uint8_t maximum;
75 };
76
77 /** @brief Structure holding display capabilities. */
78 struct auxdisplay_capabilities {
79 /** Number of character columns */
80 uint16_t columns;
81
82 /** Number of character rows */
83 uint16_t rows;
84
85 /** Display-specific data (e.g. 4-bit or 8-bit mode for HD44780-based displays) */
86 auxdisplay_mode_t mode;
87
88 /** Brightness details for display (if supported) */
89 struct auxdisplay_light brightness;
90
91 /** Backlight details for display (if supported) */
92 struct auxdisplay_light backlight;
93
94 /** Number of custom characters supported by display (0 if unsupported) */
95 uint8_t custom_characters;
96
97 /** Width (in pixels) of a custom character, supplied custom characters should match. */
98 uint8_t custom_character_width;
99
100 /** Height (in pixels) of a custom character, supplied custom characters should match. */
101 uint8_t custom_character_height;
102 };
103
104 /** @brief Structure for a custom command. This may be extended by specific drivers. */
105 struct auxdisplay_custom_data {
106 /** Raw command data to be sent */
107 uint8_t *data;
108
109 /** Length of supplied data */
110 uint16_t len;
111
112 /** Display-driver specific options for command */
113 uint32_t options;
114 };
115
116 /** @brief Structure for a custom character. */
117 struct auxdisplay_character {
118 /** Custom character index on the display */
119 uint8_t index;
120
121 /** Custom character pixel data, a character must be valid for a display consisting
122 * of a uint8 array of size character width by character height, values should be
123 * 0x00 for pixel off or 0xff for pixel on, if a display supports shades then values
124 * between 0x00 and 0xff may be used (display driver dependent).
125 */
126 uint8_t *data;
127
128 /** Will be updated with custom character index to use in the display write function to
129 * disaplay this custom character
130 */
131 uint8_t character_code;
132 };
133
134 /**
135 * @cond INTERNAL_HIDDEN
136 *
137 * For internal use only, skip these in public documentation.
138 */
139
140 /**
141 * @typedef auxdisplay_display_on_t
142 * @brief Callback API to turn display on
143 * See auxdisplay_display_on() for argument description
144 */
145 typedef int (*auxdisplay_display_on_t)(const struct device *dev);
146
147 /**
148 * @typedef auxdisplay_display_off_t
149 * @brief Callback API to turn display off
150 * See auxdisplay_display_off() for argument description
151 */
152 typedef int (*auxdisplay_display_off_t)(const struct device *dev);
153
154 /**
155 * @typedef auxdisplay_cursor_set_enabled_t
156 * @brief Callback API to turn display cursor visibility on or off
157 * See auxdisplay_cursor_set_enabled() for argument description
158 */
159 typedef int (*auxdisplay_cursor_set_enabled_t)(const struct device *dev, bool enabled);
160
161 /**
162 * @typedef auxdisplay_position_blinking_set_enabled_t
163 * @brief Callback API to turn the current position blinking on or off
164 * See auxdisplay_position_blinking_set_enabled() for argument description
165 */
166 typedef int (*auxdisplay_position_blinking_set_enabled_t)(const struct device *dev,
167 bool enabled);
168
169 /**
170 * @typedef auxdisplay_cursor_shift_set_t
171 * @brief Callback API to set how the cursor shifts after a character is written
172 * See auxdisplay_cursor_shift_set() for argument description
173 */
174 typedef int (*auxdisplay_cursor_shift_set_t)(const struct device *dev, uint8_t direction,
175 bool display_shift);
176
177 /**
178 * @typedef auxdisplay_cursor_position_set_t
179 * @brief Callback API to set the cursor position
180 * See auxdisplay_cursor_position_set() for argument description
181 */
182 typedef int (*auxdisplay_cursor_position_set_t)(const struct device *dev,
183 enum auxdisplay_position type,
184 int16_t x, int16_t y);
185
186 /**
187 * @typedef auxdisplay_cursor_position_get_t
188 * @brief Callback API to get the cursor position
189 * See auxdisplay_cursor_position_get() for argument description
190 */
191 typedef int (*auxdisplay_cursor_position_get_t)(const struct device *dev, int16_t *x,
192 int16_t *y);
193
194 /**
195 * @typedef auxdisplay_display_position_set_t
196 * @brief Callback API to set the current position of the display
197 * See auxdisplay_display_position_set() for argument description
198 */
199 typedef int (*auxdisplay_display_position_set_t)(const struct device *dev,
200 enum auxdisplay_position type,
201 int16_t x, int16_t y);
202
203 /**
204 * @typedef auxdisplay_display_position_get_t
205 * @brief Callback API to get the current position of the display
206 * See auxdisplay_display_position_get() for argument description
207 */
208 typedef int (*auxdisplay_display_position_get_t)(const struct device *dev, int16_t *x,
209 int16_t *y);
210
211 /**
212 * @typedef auxdisplay_capabilities_get_t
213 * @brief Callback API to get details on the display
214 * See auxdisplay_capabilities_get() for argument description
215 */
216 typedef int (*auxdisplay_capabilities_get_t)(const struct device *dev,
217 struct auxdisplay_capabilities *capabilities);
218
219 /**
220 * @typedef auxdisplay_clear_t
221 * @brief Callback API to clear the contents of the display
222 * See auxdisplay_clear() for argument description
223 */
224 typedef int (*auxdisplay_clear_t)(const struct device *dev);
225
226 /**
227 * @typedef auxdisplay_brightness_get_t
228 * @brief Callback API to get the current and minimum/maximum supported
229 * brightness settings of the display
230 * See auxdisplay_brightness_get_api() for argument description
231 */
232 typedef int (*auxdisplay_brightness_get_t)(const struct device *dev, uint8_t *brightness);
233
234 /**
235 * @typedef auxdisplay_brightness_set_t
236 * @brief Callback API to set the brightness of the display
237 * See auxdisplay_brightness_set_api() for argument description
238 */
239 typedef int (*auxdisplay_brightness_set_t)(const struct device *dev, uint8_t brightness);
240
241 /**
242 * @typedef auxdisplay_backlight_get_t
243 * @brief Callback API to get the current and minimum/maximum supported
244 * backlight settings of the display
245 * See auxdisplay_backlight_set() for argument description
246 */
247 typedef int (*auxdisplay_backlight_get_t)(const struct device *dev, uint8_t *backlight);
248
249 /**
250 * @typedef auxdisplay_backlight_set_t
251 * @brief Callback API to set the backlight status
252 * See auxdisplay_backlight_set() for argument description
253 */
254 typedef int (*auxdisplay_backlight_set_t)(const struct device *dev, uint8_t backlight);
255
256 /**
257 * @typedef auxdisplay_is_busy_t
258 * @brief Callback API to check if the display is busy with an operation
259 * See auxdisplay_is_busy() for argument description
260 */
261 typedef int (*auxdisplay_is_busy_t)(const struct device *dev);
262
263 /**
264 * @typedef auxdisplay_custom_character_set_t
265 * @brief Callback API to set a customer character on the display for usage
266 * See auxdisplay_custom_character_set() for argument description
267 */
268 typedef int (*auxdisplay_custom_character_set_t)(const struct device *dev,
269 struct auxdisplay_character *character);
270
271 /**
272 * @typedef auxdisplay_write_t
273 * @brief Callback API to write text to the display
274 * See auxdisplay_write() for argument description
275 */
276 typedef int (*auxdisplay_write_t)(const struct device *dev, const uint8_t *data, uint16_t len);
277
278 /**
279 * @typedef auxdisplay_custom_command_t
280 * @brief Callback API to send a custom command to the display
281 * See auxdisplay_custom_command() for argument description
282 */
283 typedef int (*auxdisplay_custom_command_t)(const struct device *dev,
284 struct auxdisplay_custom_data *command);
285
286 struct auxdisplay_driver_api {
287 auxdisplay_display_on_t display_on;
288 auxdisplay_display_off_t display_off;
289 auxdisplay_cursor_set_enabled_t cursor_set_enabled;
290 auxdisplay_position_blinking_set_enabled_t position_blinking_set_enabled;
291 auxdisplay_cursor_shift_set_t cursor_shift_set;
292 auxdisplay_cursor_position_set_t cursor_position_set;
293 auxdisplay_cursor_position_get_t cursor_position_get;
294 auxdisplay_display_position_set_t display_position_set;
295 auxdisplay_display_position_get_t display_position_get;
296 auxdisplay_capabilities_get_t capabilities_get;
297 auxdisplay_clear_t clear;
298 auxdisplay_brightness_get_t brightness_get;
299 auxdisplay_brightness_set_t brightness_set;
300 auxdisplay_backlight_get_t backlight_get;
301 auxdisplay_backlight_set_t backlight_set;
302 auxdisplay_is_busy_t is_busy;
303 auxdisplay_custom_character_set_t custom_character_set;
304 auxdisplay_write_t write;
305 auxdisplay_custom_command_t custom_command;
306 };
307
308 /**
309 * @endcond
310 */
311
312 /**
313 * @brief Turn display on.
314 *
315 * @param dev Auxiliary display device instance
316 *
317 * @retval 0 on success.
318 * @retval -ENOSYS if not supported/implemented.
319 * @retval -errno Negative errno code on other failure.
320 */
321 __syscall int auxdisplay_display_on(const struct device *dev);
322
z_impl_auxdisplay_display_on(const struct device * dev)323 static inline int z_impl_auxdisplay_display_on(const struct device *dev)
324 {
325 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
326
327 if (!api->display_on) {
328 return -ENOSYS;
329 }
330
331 return api->display_on(dev);
332 }
333
334 /**
335 * @brief Turn display off.
336 *
337 * @param dev Auxiliary display device instance
338 *
339 * @retval 0 on success.
340 * @retval -ENOSYS if not supported/implemented.
341 * @retval -errno Negative errno code on other failure.
342 */
343 __syscall int auxdisplay_display_off(const struct device *dev);
344
z_impl_auxdisplay_display_off(const struct device * dev)345 static inline int z_impl_auxdisplay_display_off(const struct device *dev)
346 {
347 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
348
349 if (!api->display_off) {
350 return -ENOSYS;
351 }
352
353 return api->display_off(dev);
354 }
355
356 /**
357 * @brief Set cursor enabled status on an auxiliary display
358 *
359 * @param dev Auxiliary display device instance
360 * @param enabled True to enable cursor, false to disable
361 *
362 * @retval 0 on success.
363 * @retval -ENOSYS if not supported/implemented.
364 * @retval -errno Negative errno code on other failure.
365 */
366 __syscall int auxdisplay_cursor_set_enabled(const struct device *dev,
367 bool enabled);
368
z_impl_auxdisplay_cursor_set_enabled(const struct device * dev,bool enabled)369 static inline int z_impl_auxdisplay_cursor_set_enabled(const struct device *dev,
370 bool enabled)
371 {
372 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
373
374 if (!api->cursor_set_enabled) {
375 return -ENOSYS;
376 }
377
378 return api->cursor_set_enabled(dev, enabled);
379 }
380
381 /**
382 * @brief Set cursor blinking status on an auxiliary display
383 *
384 * @param dev Auxiliary display device instance
385 * @param enabled Set to true to enable blinking position, false to disable
386 *
387 * @retval 0 on success.
388 * @retval -ENOSYS if not supported/implemented.
389 * @retval -errno Negative errno code on other failure.
390 */
391 __syscall int auxdisplay_position_blinking_set_enabled(const struct device *dev,
392 bool enabled);
393
z_impl_auxdisplay_position_blinking_set_enabled(const struct device * dev,bool enabled)394 static inline int z_impl_auxdisplay_position_blinking_set_enabled(const struct device *dev,
395 bool enabled)
396 {
397 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
398
399 if (!api->position_blinking_set_enabled) {
400 return -ENOSYS;
401 }
402
403 return api->position_blinking_set_enabled(dev, enabled);
404 }
405
406 /**
407 * @brief Set cursor shift after character write and display shift
408 *
409 * @param dev Auxiliary display device instance
410 * @param direction Sets the direction of the display when characters are written
411 * @param display_shift If true, will shift the display when characters are written
412 * (which makes it look like the display is moving, not the cursor)
413 *
414 * @retval 0 on success.
415 * @retval -ENOSYS if not supported/implemented.
416 * @retval -EINVAL if provided argument is invalid.
417 * @retval -errno Negative errno code on other failure.
418 */
419 __syscall int auxdisplay_cursor_shift_set(const struct device *dev,
420 uint8_t direction, bool display_shift);
421
z_impl_auxdisplay_cursor_shift_set(const struct device * dev,uint8_t direction,bool display_shift)422 static inline int z_impl_auxdisplay_cursor_shift_set(const struct device *dev,
423 uint8_t direction,
424 bool display_shift)
425 {
426 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
427
428 if (!api->cursor_shift_set) {
429 return -ENOSYS;
430 }
431
432 if (direction >= AUXDISPLAY_DIRECTION_COUNT) {
433 return -EINVAL;
434 }
435
436 return api->cursor_shift_set(dev, direction, display_shift);
437 }
438
439 /**
440 * @brief Set cursor (and write position) on an auxiliary display
441 *
442 * @param dev Auxiliary display device instance
443 * @param type Type of move, absolute or offset
444 * @param x Exact or offset X position
445 * @param y Exact or offset Y position
446 *
447 * @retval 0 on success.
448 * @retval -ENOSYS if not supported/implemented.
449 * @retval -EINVAL if provided argument is invalid.
450 * @retval -errno Negative errno code on other failure.
451 */
452 __syscall int auxdisplay_cursor_position_set(const struct device *dev,
453 enum auxdisplay_position type,
454 int16_t x, int16_t y);
455
z_impl_auxdisplay_cursor_position_set(const struct device * dev,enum auxdisplay_position type,int16_t x,int16_t y)456 static inline int z_impl_auxdisplay_cursor_position_set(const struct device *dev,
457 enum auxdisplay_position type,
458 int16_t x, int16_t y)
459 {
460 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
461
462 if (!api->cursor_position_set) {
463 return -ENOSYS;
464 } else if (type >= AUXDISPLAY_POSITION_COUNT) {
465 return -EINVAL;
466 } else if (type == AUXDISPLAY_POSITION_ABSOLUTE && (x < 0 || y < 0)) {
467 return -EINVAL;
468 }
469
470 return api->cursor_position_set(dev, type, x, y);
471 }
472
473 /**
474 * @brief Get current cursor on an auxiliary display
475 *
476 * @param dev Auxiliary display device instance
477 * @param x Will be updated with the exact X position
478 * @param y Will be updated with the exact Y position
479 *
480 * @retval 0 on success.
481 * @retval -ENOSYS if not supported/implemented.
482 * @retval -EINVAL if provided argument is invalid.
483 * @retval -errno Negative errno code on other failure.
484 */
485 __syscall int auxdisplay_cursor_position_get(const struct device *dev,
486 int16_t *x, int16_t *y);
487
z_impl_auxdisplay_cursor_position_get(const struct device * dev,int16_t * x,int16_t * y)488 static inline int z_impl_auxdisplay_cursor_position_get(const struct device *dev,
489 int16_t *x, int16_t *y)
490 {
491 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
492
493 if (!api->cursor_position_get) {
494 return -ENOSYS;
495 }
496
497 return api->cursor_position_get(dev, x, y);
498 }
499
500 /**
501 * @brief Set display position on an auxiliary display
502 *
503 * @param dev Auxiliary display device instance
504 * @param type Type of move, absolute or offset
505 * @param x Exact or offset X position
506 * @param y Exact or offset Y position
507 *
508 * @retval 0 on success.
509 * @retval -ENOSYS if not supported/implemented.
510 * @retval -EINVAL if provided argument is invalid.
511 * @retval -errno Negative errno code on other failure.
512 */
513 __syscall int auxdisplay_display_position_set(const struct device *dev,
514 enum auxdisplay_position type,
515 int16_t x, int16_t y);
516
z_impl_auxdisplay_display_position_set(const struct device * dev,enum auxdisplay_position type,int16_t x,int16_t y)517 static inline int z_impl_auxdisplay_display_position_set(const struct device *dev,
518 enum auxdisplay_position type,
519 int16_t x, int16_t y)
520 {
521 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
522
523 if (!api->display_position_set) {
524 return -ENOSYS;
525 } else if (type >= AUXDISPLAY_POSITION_COUNT) {
526 return -EINVAL;
527 } else if (type == AUXDISPLAY_POSITION_ABSOLUTE && (x < 0 || y < 0)) {
528 return -EINVAL;
529 }
530
531 return api->display_position_set(dev, type, x, y);
532 }
533
534 /**
535 * @brief Get current display position on an auxiliary display
536 *
537 * @param dev Auxiliary display device instance
538 * @param x Will be updated with the exact X position
539 * @param y Will be updated with the exact Y position
540 *
541 * @retval 0 on success.
542 * @retval -ENOSYS if not supported/implemented.
543 * @retval -EINVAL if provided argument is invalid.
544 * @retval -errno Negative errno code on other failure.
545 */
546 __syscall int auxdisplay_display_position_get(const struct device *dev,
547 int16_t *x, int16_t *y);
548
z_impl_auxdisplay_display_position_get(const struct device * dev,int16_t * x,int16_t * y)549 static inline int z_impl_auxdisplay_display_position_get(const struct device *dev,
550 int16_t *x, int16_t *y)
551 {
552 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
553
554 if (!api->display_position_get) {
555 return -ENOSYS;
556 }
557
558 return api->display_position_get(dev, x, y);
559 }
560
561 /**
562 * @brief Fetch capabilities (and details) of auxiliary display
563 *
564 * @param dev Auxiliary display device instance
565 * @param capabilities Will be updated with the details of the auxiliary display
566 *
567 * @retval 0 on success.
568 * @retval -errno Negative errno code on other failure.
569 */
570 __syscall int auxdisplay_capabilities_get(const struct device *dev,
571 struct auxdisplay_capabilities *capabilities);
572
z_impl_auxdisplay_capabilities_get(const struct device * dev,struct auxdisplay_capabilities * capabilities)573 static inline int z_impl_auxdisplay_capabilities_get(const struct device *dev,
574 struct auxdisplay_capabilities *capabilities)
575 {
576 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
577
578 return api->capabilities_get(dev, capabilities);
579 }
580
581 /**
582 * @brief Clear display of auxiliary display and return to home position (note that
583 * this does not reset the display configuration, e.g. custom characters and
584 * display mode will persist).
585 *
586 * @param dev Auxiliary display device instance
587 *
588 * @retval 0 on success.
589 * @retval -errno Negative errno code on other failure.
590 */
591 __syscall int auxdisplay_clear(const struct device *dev);
592
z_impl_auxdisplay_clear(const struct device * dev)593 static inline int z_impl_auxdisplay_clear(const struct device *dev)
594 {
595 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
596
597 return api->clear(dev);
598 }
599
600 /**
601 * @brief Get the current brightness level of an auxiliary display
602 *
603 * @param dev Auxiliary display device instance
604 * @param brightness Will be updated with the current brightness
605 *
606 * @retval 0 on success.
607 * @retval -ENOSYS if not supported/implemented.
608 * @retval -errno Negative errno code on other failure.
609 */
610 __syscall int auxdisplay_brightness_get(const struct device *dev,
611 uint8_t *brightness);
612
z_impl_auxdisplay_brightness_get(const struct device * dev,uint8_t * brightness)613 static inline int z_impl_auxdisplay_brightness_get(const struct device *dev,
614 uint8_t *brightness)
615 {
616 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
617
618 if (!api->brightness_get) {
619 return -ENOSYS;
620 }
621
622 return api->brightness_get(dev, brightness);
623 }
624
625 /**
626 * @brief Update the brightness level of an auxiliary display
627 *
628 * @param dev Auxiliary display device instance
629 * @param brightness The brightness level to set
630 *
631 * @retval 0 on success.
632 * @retval -ENOSYS if not supported/implemented.
633 * @retval -EINVAL if provided argument is invalid.
634 * @retval -errno Negative errno code on other failure.
635 */
636 __syscall int auxdisplay_brightness_set(const struct device *dev,
637 uint8_t brightness);
638
z_impl_auxdisplay_brightness_set(const struct device * dev,uint8_t brightness)639 static inline int z_impl_auxdisplay_brightness_set(const struct device *dev,
640 uint8_t brightness)
641 {
642 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
643
644 if (!api->brightness_set) {
645 return -ENOSYS;
646 }
647
648 return api->brightness_set(dev, brightness);
649 }
650
651 /**
652 * @brief Get the backlight level details of an auxiliary display
653 *
654 * @param dev Auxiliary display device instance
655 * @param backlight Will be updated with the current backlight level
656 *
657 * @retval 0 on success.
658 * @retval -ENOSYS if not supported/implemented.
659 * @retval -errno Negative errno code on other failure.
660 */
661 __syscall int auxdisplay_backlight_get(const struct device *dev,
662 uint8_t *backlight);
663
z_impl_auxdisplay_backlight_get(const struct device * dev,uint8_t * backlight)664 static inline int z_impl_auxdisplay_backlight_get(const struct device *dev,
665 uint8_t *backlight)
666 {
667 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
668
669 if (!api->backlight_get) {
670 return -ENOSYS;
671 }
672
673 return api->backlight_get(dev, backlight);
674 }
675
676 /**
677 * @brief Update the backlight level of an auxiliary display
678 *
679 * @param dev Auxiliary display device instance
680 * @param backlight The backlight level to set
681 *
682 * @retval 0 on success.
683 * @retval -ENOSYS if not supported/implemented.
684 * @retval -EINVAL if provided argument is invalid.
685 * @retval -errno Negative errno code on other failure.
686 */
687 __syscall int auxdisplay_backlight_set(const struct device *dev,
688 uint8_t backlight);
689
z_impl_auxdisplay_backlight_set(const struct device * dev,uint8_t backlight)690 static inline int z_impl_auxdisplay_backlight_set(const struct device *dev,
691 uint8_t backlight)
692 {
693 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
694
695 if (!api->backlight_set) {
696 return -ENOSYS;
697 }
698
699 return api->backlight_set(dev, backlight);
700 }
701
702 /**
703 * @brief Check if an auxiliary display driver is busy
704 *
705 * @param dev Auxiliary display device instance
706 *
707 * @retval 1 on success and display busy.
708 * @retval 0 on success and display not busy.
709 * @retval -ENOSYS if not supported/implemented.
710 * @retval -errno Negative errno code on other failure.
711 */
712 __syscall int auxdisplay_is_busy(const struct device *dev);
713
z_impl_auxdisplay_is_busy(const struct device * dev)714 static inline int z_impl_auxdisplay_is_busy(const struct device *dev)
715 {
716 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
717
718 if (!api->is_busy) {
719 return -ENOSYS;
720 }
721
722 return api->is_busy(dev);
723 }
724
725 /**
726 * @brief Sets a custom character in the display, the custom character struct
727 * must contain the pixel data for the custom character to add and valid
728 * custom character index, if successful then the character_code variable
729 * in the struct will be set to the character code that can be used with
730 * the auxdisplay_write() function to show it.
731 *
732 * A character must be valid for a display consisting of a uint8 array of
733 * size character width by character height, values should be 0x00 for
734 * pixel off or 0xff for pixel on, if a display supports shades then
735 * values between 0x00 and 0xff may be used (display driver dependent).
736 *
737 * @param dev Auxiliary display device instance
738 * @param character Pointer to custom character structure
739 *
740 * @retval 0 on success.
741 * @retval -ENOSYS if not supported/implemented.
742 * @retval -EINVAL if provided argument is invalid.
743 * @retval -errno Negative errno code on other failure.
744 */
745 __syscall int auxdisplay_custom_character_set(const struct device *dev,
746 struct auxdisplay_character *character);
747
z_impl_auxdisplay_custom_character_set(const struct device * dev,struct auxdisplay_character * character)748 static inline int z_impl_auxdisplay_custom_character_set(const struct device *dev,
749 struct auxdisplay_character *character)
750 {
751 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
752
753 if (!api->custom_character_set) {
754 return -ENOSYS;
755 }
756
757 return api->custom_character_set(dev, character);
758 }
759
760 /**
761 * @brief Write data to auxiliary display screen at current position
762 *
763 * @param dev Auxiliary display device instance
764 * @param data Text data to write
765 * @param len Length of text data to write
766 *
767 * @retval 0 on success.
768 * @retval -EINVAL if provided argument is invalid.
769 * @retval -errno Negative errno code on other failure.
770 */
771 __syscall int auxdisplay_write(const struct device *dev, const uint8_t *data,
772 uint16_t len);
773
z_impl_auxdisplay_write(const struct device * dev,const uint8_t * data,uint16_t len)774 static inline int z_impl_auxdisplay_write(const struct device *dev,
775 const uint8_t *data, uint16_t len)
776 {
777 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
778
779 return api->write(dev, data, len);
780 }
781
782 /**
783 * @brief Send a custom command to the display (if supported by driver)
784 *
785 * @param dev Auxiliary display device instance
786 * @param data Custom command structure (this may be extended by specific drivers)
787 *
788 * @retval 0 on success.
789 * @retval -ENOSYS if not supported/implemented.
790 * @retval -EINVAL if provided argument is invalid.
791 * @retval -errno Negative errno code on other failure.
792 */
793 __syscall int auxdisplay_custom_command(const struct device *dev,
794 struct auxdisplay_custom_data *data);
795
z_impl_auxdisplay_custom_command(const struct device * dev,struct auxdisplay_custom_data * data)796 static inline int z_impl_auxdisplay_custom_command(const struct device *dev,
797 struct auxdisplay_custom_data *data)
798 {
799 struct auxdisplay_driver_api *api = (struct auxdisplay_driver_api *)dev->api;
800
801 if (!api->custom_command) {
802 return -ENOSYS;
803 }
804
805 return api->custom_command(dev, data);
806 }
807
808 #ifdef __cplusplus
809 }
810 #endif
811
812 /**
813 * @}
814 */
815
816 #include <syscalls/auxdisplay.h>
817
818 #endif /* ZEPHYR_INCLUDE_DRIVERS_AUXDISPLAY_H_ */
819
