Line data Source code
1 1 : /*
2 : * Copyright (c) 2017 Jan Van Winkel <jan.van_winkel@dxplore.eu>
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @ingroup display_interface
10 : * @brief Main header file for display driver API.
11 : */
12 :
13 : #ifndef ZEPHYR_INCLUDE_DRIVERS_DISPLAY_H_
14 : #define ZEPHYR_INCLUDE_DRIVERS_DISPLAY_H_
15 :
16 : /**
17 : * @brief Interfaces for display controllers.
18 : * @defgroup display_interface Display
19 : * @since 1.14
20 : * @version 0.8.0
21 : * @ingroup io_interfaces
22 : * @{
23 : */
24 :
25 : #include <zephyr/device.h>
26 : #include <errno.h>
27 : #include <stddef.h>
28 : #include <zephyr/types.h>
29 : #include <zephyr/dt-bindings/display/panel.h>
30 :
31 : #ifdef __cplusplus
32 : extern "C" {
33 : #endif
34 :
35 : /**
36 : * @brief Display pixel formats
37 : *
38 : * Display pixel format enumeration.
39 : *
40 : * In case a pixel format consists out of multiple bytes the byte order is
41 : * big endian.
42 : */
43 1 : enum display_pixel_format {
44 : PIXEL_FORMAT_RGB_888 = BIT(0), /**< 24-bit RGB */
45 : PIXEL_FORMAT_MONO01 = BIT(1), /**< Monochrome (0=Black 1=White) */
46 : PIXEL_FORMAT_MONO10 = BIT(2), /**< Monochrome (1=Black 0=White) */
47 : PIXEL_FORMAT_ARGB_8888 = BIT(3), /**< 32-bit ARGB */
48 : /**
49 : * 16-bit RGB format packed into two bytes: 5 red bits [15:11], 6
50 : * green bits [10:5], 5 blue bits [4:0]. For example, in little-endian machine:
51 : *
52 : * @code{.unparsed}
53 : * 7......0 15.....8
54 : * | gggBbbbb RrrrrGgg | ...
55 : * @endcode
56 : *
57 : */
58 : PIXEL_FORMAT_RGB_565 = BIT(4),
59 : /**
60 : * 16-bit RGB format packed into two bytes: 5 blue bits [15:11], 6
61 : * green bits [10:5], 5 red bits [4:0]. For example, in little-endian machine:
62 : *
63 : * @code{.unparsed}
64 : * 7......0 15.....8
65 : * | gggRrrrr BbbbbGgg | ...
66 : * @endcode
67 : *
68 : */
69 : PIXEL_FORMAT_BGR_565 = BIT(5),
70 : PIXEL_FORMAT_L_8 = BIT(6), /**< 8-bit Grayscale/Luminance, equivalent to */
71 : /**< GRAY, GREY, GRAY8, Y8, R8, etc... */
72 : PIXEL_FORMAT_AL_88 = BIT(7), /**< 8-bit Grayscale/Luminance with alpha */
73 : };
74 :
75 : /**
76 : * @brief Bits required per pixel for display format
77 : *
78 : * This macro expands to the number of bits required for a given display
79 : * format. It can be used to allocate a framebuffer based on a given
80 : * display format type
81 : */
82 1 : #define DISPLAY_BITS_PER_PIXEL(fmt) \
83 : ((((fmt & PIXEL_FORMAT_RGB_888) >> 0) * 24U) + \
84 : (((fmt & PIXEL_FORMAT_MONO01) >> 1) * 1U) + \
85 : (((fmt & PIXEL_FORMAT_MONO10) >> 2) * 1U) + \
86 : (((fmt & PIXEL_FORMAT_ARGB_8888) >> 3) * 32U) + \
87 : (((fmt & PIXEL_FORMAT_RGB_565) >> 4) * 16U) + \
88 : (((fmt & PIXEL_FORMAT_BGR_565) >> 5) * 16U) + \
89 : (((fmt & PIXEL_FORMAT_L_8) >> 6) * 8U) + \
90 : (((fmt & PIXEL_FORMAT_AL_88) >> 7) * 16U))
91 :
92 : /**
93 : * @brief Display screen information
94 : */
95 1 : enum display_screen_info {
96 : /**
97 : * If selected, one octet represents 8 pixels ordered vertically,
98 : * otherwise ordered horizontally.
99 : */
100 : SCREEN_INFO_MONO_VTILED = BIT(0),
101 : /**
102 : * If selected, the MSB represents the first pixel,
103 : * otherwise MSB represents the last pixel.
104 : */
105 : SCREEN_INFO_MONO_MSB_FIRST = BIT(1),
106 : /**
107 : * Electrophoretic Display.
108 : */
109 : SCREEN_INFO_EPD = BIT(2),
110 : /**
111 : * Screen has two alternating ram buffers
112 : */
113 : SCREEN_INFO_DOUBLE_BUFFER = BIT(3),
114 : /**
115 : * Screen has x alignment constrained to width.
116 : */
117 : SCREEN_INFO_X_ALIGNMENT_WIDTH = BIT(4),
118 : };
119 :
120 : /**
121 : * @brief Enumeration with possible display orientation
122 : */
123 1 : enum display_orientation {
124 : DISPLAY_ORIENTATION_NORMAL, /**< No rotation */
125 : DISPLAY_ORIENTATION_ROTATED_90, /**< Rotated 90 degrees clockwise */
126 : DISPLAY_ORIENTATION_ROTATED_180, /**< Rotated 180 degrees clockwise */
127 : DISPLAY_ORIENTATION_ROTATED_270, /**< Rotated 270 degrees clockwise */
128 : };
129 :
130 : /** @brief Structure holding display capabilities. */
131 1 : struct display_capabilities {
132 : /** Display resolution in the X direction */
133 1 : uint16_t x_resolution;
134 : /** Display resolution in the Y direction */
135 1 : uint16_t y_resolution;
136 : /** Bitwise or of pixel formats supported by the display */
137 1 : uint32_t supported_pixel_formats;
138 : /** Information about display panel */
139 1 : uint32_t screen_info;
140 : /** Currently active pixel format for the display */
141 1 : enum display_pixel_format current_pixel_format;
142 : /** Current display orientation */
143 1 : enum display_orientation current_orientation;
144 : };
145 :
146 : /** @brief Structure to describe display data buffer layout */
147 1 : struct display_buffer_descriptor {
148 : /** Data buffer size in bytes */
149 1 : uint32_t buf_size;
150 : /** Data buffer row width in pixels */
151 1 : uint16_t width;
152 : /** Data buffer column height in pixels */
153 1 : uint16_t height;
154 : /** Number of pixels between consecutive rows in the data buffer */
155 1 : uint16_t pitch;
156 : /** Indicates that this is not the last write buffer of the frame */
157 1 : bool frame_incomplete;
158 : };
159 :
160 : /**
161 : * @typedef display_blanking_on_api
162 : * @brief Callback API to turn on display blanking
163 : * See display_blanking_on() for argument description
164 : */
165 1 : typedef int (*display_blanking_on_api)(const struct device *dev);
166 :
167 : /**
168 : * @typedef display_blanking_off_api
169 : * @brief Callback API to turn off display blanking
170 : * See display_blanking_off() for argument description
171 : */
172 1 : typedef int (*display_blanking_off_api)(const struct device *dev);
173 :
174 : /**
175 : * @typedef display_write_api
176 : * @brief Callback API for writing data to the display
177 : * See display_write() for argument description
178 : */
179 1 : typedef int (*display_write_api)(const struct device *dev, const uint16_t x,
180 : const uint16_t y,
181 : const struct display_buffer_descriptor *desc,
182 : const void *buf);
183 :
184 : /**
185 : * @typedef display_read_api
186 : * @brief Callback API for reading data from the display
187 : * See display_read() for argument description
188 : */
189 1 : typedef int (*display_read_api)(const struct device *dev, const uint16_t x,
190 : const uint16_t y,
191 : const struct display_buffer_descriptor *desc,
192 : void *buf);
193 :
194 : /**
195 : * @typedef display_clear
196 : * @brief Callback API for clearing the screen of the display
197 : * See display_clear() for argument description
198 : */
199 0 : typedef int (*display_clear_api)(const struct device *dev);
200 :
201 : /**
202 : * @typedef display_get_framebuffer_api
203 : * @brief Callback API to get framebuffer pointer
204 : * See display_get_framebuffer() for argument description
205 : */
206 1 : typedef void *(*display_get_framebuffer_api)(const struct device *dev);
207 :
208 : /**
209 : * @typedef display_set_brightness_api
210 : * @brief Callback API to set display brightness
211 : * See display_set_brightness() for argument description
212 : */
213 1 : typedef int (*display_set_brightness_api)(const struct device *dev,
214 : const uint8_t brightness);
215 :
216 : /**
217 : * @typedef display_set_contrast_api
218 : * @brief Callback API to set display contrast
219 : * See display_set_contrast() for argument description
220 : */
221 1 : typedef int (*display_set_contrast_api)(const struct device *dev,
222 : const uint8_t contrast);
223 :
224 : /**
225 : * @typedef display_get_capabilities_api
226 : * @brief Callback API to get display capabilities
227 : * See display_get_capabilities() for argument description
228 : */
229 1 : typedef void (*display_get_capabilities_api)(const struct device *dev,
230 : struct display_capabilities *
231 : capabilities);
232 :
233 : /**
234 : * @typedef display_set_pixel_format_api
235 : * @brief Callback API to set pixel format used by the display
236 : * See display_set_pixel_format() for argument description
237 : */
238 1 : typedef int (*display_set_pixel_format_api)(const struct device *dev,
239 : const enum display_pixel_format
240 : pixel_format);
241 :
242 : /**
243 : * @typedef display_set_orientation_api
244 : * @brief Callback API to set orientation used by the display
245 : * See display_set_orientation() for argument description
246 : */
247 1 : typedef int (*display_set_orientation_api)(const struct device *dev,
248 : const enum display_orientation
249 : orientation);
250 :
251 : /**
252 : * @brief Display driver API
253 : * API which a display driver should expose
254 : */
255 1 : __subsystem struct display_driver_api {
256 0 : display_blanking_on_api blanking_on;
257 0 : display_blanking_off_api blanking_off;
258 0 : display_write_api write;
259 0 : display_read_api read;
260 0 : display_clear_api clear;
261 0 : display_get_framebuffer_api get_framebuffer;
262 0 : display_set_brightness_api set_brightness;
263 0 : display_set_contrast_api set_contrast;
264 0 : display_get_capabilities_api get_capabilities;
265 0 : display_set_pixel_format_api set_pixel_format;
266 0 : display_set_orientation_api set_orientation;
267 : };
268 :
269 : /**
270 : * @brief Write data to display
271 : *
272 : * @param dev Pointer to device structure
273 : * @param x x Coordinate of the upper left corner where to write the buffer
274 : * @param y y Coordinate of the upper left corner where to write the buffer
275 : * @param desc Pointer to a structure describing the buffer layout
276 : * @param buf Pointer to buffer array
277 : *
278 : * @retval 0 on success else negative errno code.
279 : */
280 1 : static inline int display_write(const struct device *dev, const uint16_t x,
281 : const uint16_t y,
282 : const struct display_buffer_descriptor *desc,
283 : const void *buf)
284 : {
285 : struct display_driver_api *api =
286 : (struct display_driver_api *)dev->api;
287 :
288 : return api->write(dev, x, y, desc, buf);
289 : }
290 :
291 : /**
292 : * @brief Read data from display
293 : *
294 : * @param dev Pointer to device structure
295 : * @param x x Coordinate of the upper left corner where to read from
296 : * @param y y Coordinate of the upper left corner where to read from
297 : * @param desc Pointer to a structure describing the buffer layout
298 : * @param buf Pointer to buffer array
299 : *
300 : * @retval 0 on success else negative errno code.
301 : * @retval -ENOSYS if not implemented.
302 : */
303 1 : static inline int display_read(const struct device *dev, const uint16_t x,
304 : const uint16_t y,
305 : const struct display_buffer_descriptor *desc,
306 : void *buf)
307 : {
308 : struct display_driver_api *api =
309 : (struct display_driver_api *)dev->api;
310 :
311 : if (api->read == NULL) {
312 : return -ENOSYS;
313 : }
314 :
315 : return api->read(dev, x, y, desc, buf);
316 : }
317 :
318 : /**
319 : * @brief Clear the screen of the display device
320 : *
321 : * @param dev Pointer to device structure
322 : *
323 : * @retval 0 on success else negative errno code.
324 : * @retval -ENOSYS if not implemented.
325 : */
326 1 : static inline int display_clear(const struct device *dev)
327 : {
328 : struct display_driver_api *api =
329 : (struct display_driver_api *)dev->api;
330 :
331 : if (api->clear == NULL) {
332 : return -ENOSYS;
333 : }
334 :
335 : return api->clear(dev);
336 : }
337 :
338 : /**
339 : * @brief Get pointer to framebuffer for direct access
340 : *
341 : * @param dev Pointer to device structure
342 : *
343 : * @retval Pointer to frame buffer or NULL if direct framebuffer access
344 : * is not supported
345 : *
346 : */
347 1 : static inline void *display_get_framebuffer(const struct device *dev)
348 : {
349 : struct display_driver_api *api =
350 : (struct display_driver_api *)dev->api;
351 :
352 : if (api->get_framebuffer == NULL) {
353 : return NULL;
354 : }
355 :
356 : return api->get_framebuffer(dev);
357 : }
358 :
359 : /**
360 : * @brief Turn display blanking on
361 : *
362 : * This function blanks the complete display.
363 : * The content of the frame buffer will be retained while blanking is enabled
364 : * and the frame buffer will be accessible for read and write operations.
365 : *
366 : * In case backlight control is supported by the driver the backlight is
367 : * turned off. The backlight configuration is retained and accessible for
368 : * configuration.
369 : *
370 : * In case the driver supports display blanking the initial state of the driver
371 : * would be the same as if this function was called.
372 : *
373 : * @param dev Pointer to device structure
374 : *
375 : * @retval 0 on success else negative errno code.
376 : * @retval -ENOSYS if not implemented.
377 : */
378 1 : static inline int display_blanking_on(const struct device *dev)
379 : {
380 : struct display_driver_api *api =
381 : (struct display_driver_api *)dev->api;
382 :
383 : if (api->blanking_on == NULL) {
384 : return -ENOSYS;
385 : }
386 :
387 : return api->blanking_on(dev);
388 : }
389 :
390 : /**
391 : * @brief Turn display blanking off
392 : *
393 : * Restore the frame buffer content to the display.
394 : * In case backlight control is supported by the driver the backlight
395 : * configuration is restored.
396 : *
397 : * @param dev Pointer to device structure
398 : *
399 : * @retval 0 on success else negative errno code.
400 : * @retval -ENOSYS if not implemented.
401 : */
402 1 : static inline int display_blanking_off(const struct device *dev)
403 : {
404 : struct display_driver_api *api =
405 : (struct display_driver_api *)dev->api;
406 :
407 : if (api->blanking_off == NULL) {
408 : return -ENOSYS;
409 : }
410 :
411 : return api->blanking_off(dev);
412 : }
413 :
414 : /**
415 : * @brief Set the brightness of the display
416 : *
417 : * Set the brightness of the display in steps of 1/256, where 255 is full
418 : * brightness and 0 is minimal.
419 : *
420 : * @param dev Pointer to device structure
421 : * @param brightness Brightness in steps of 1/256
422 : *
423 : * @retval 0 on success else negative errno code.
424 : * @retval -ENOSYS if not implemented.
425 : */
426 1 : static inline int display_set_brightness(const struct device *dev,
427 : uint8_t brightness)
428 : {
429 : struct display_driver_api *api =
430 : (struct display_driver_api *)dev->api;
431 :
432 : if (api->set_brightness == NULL) {
433 : return -ENOSYS;
434 : }
435 :
436 : return api->set_brightness(dev, brightness);
437 : }
438 :
439 : /**
440 : * @brief Set the contrast of the display
441 : *
442 : * Set the contrast of the display in steps of 1/256, where 255 is maximum
443 : * difference and 0 is minimal.
444 : *
445 : * @param dev Pointer to device structure
446 : * @param contrast Contrast in steps of 1/256
447 : *
448 : * @retval 0 on success else negative errno code.
449 : * @retval -ENOSYS if not implemented.
450 : */
451 1 : static inline int display_set_contrast(const struct device *dev, uint8_t contrast)
452 : {
453 : struct display_driver_api *api =
454 : (struct display_driver_api *)dev->api;
455 :
456 : if (api->set_contrast == NULL) {
457 : return -ENOSYS;
458 : }
459 :
460 : return api->set_contrast(dev, contrast);
461 : }
462 :
463 : /**
464 : * @brief Get display capabilities
465 : *
466 : * @param dev Pointer to device structure
467 : * @param capabilities Pointer to capabilities structure to populate
468 : */
469 1 : static inline void display_get_capabilities(const struct device *dev,
470 : struct display_capabilities *
471 : capabilities)
472 : {
473 : struct display_driver_api *api =
474 : (struct display_driver_api *)dev->api;
475 :
476 : api->get_capabilities(dev, capabilities);
477 : }
478 :
479 : /**
480 : * @brief Set pixel format used by the display
481 : *
482 : * @param dev Pointer to device structure
483 : * @param pixel_format Pixel format to be used by display
484 : *
485 : * @retval 0 on success else negative errno code.
486 : * @retval -ENOSYS if not implemented.
487 : */
488 : static inline int
489 1 : display_set_pixel_format(const struct device *dev,
490 : const enum display_pixel_format pixel_format)
491 : {
492 : struct display_driver_api *api =
493 : (struct display_driver_api *)dev->api;
494 :
495 : if (api->set_pixel_format == NULL) {
496 : return -ENOSYS;
497 : }
498 :
499 : return api->set_pixel_format(dev, pixel_format);
500 : }
501 :
502 : /**
503 : * @brief Set display orientation
504 : *
505 : * @param dev Pointer to device structure
506 : * @param orientation Orientation to be used by display
507 : *
508 : * @retval 0 on success else negative errno code.
509 : * @retval -ENOSYS if not implemented.
510 : */
511 1 : static inline int display_set_orientation(const struct device *dev,
512 : const enum display_orientation
513 : orientation)
514 : {
515 : struct display_driver_api *api =
516 : (struct display_driver_api *)dev->api;
517 :
518 : if (api->set_orientation == NULL) {
519 : return -ENOSYS;
520 : }
521 :
522 : return api->set_orientation(dev, orientation);
523 : }
524 :
525 : #ifdef __cplusplus
526 : }
527 : #endif
528 :
529 : /**
530 : * @}
531 : */
532 :
533 : #endif /* ZEPHYR_INCLUDE_DRIVERS_DISPLAY_H_ */
|
