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