Display

Interfaces for display controllers. More...

Topics
	AC057TC1 display controller
	AC057TC1 7-color e-ink display controller device-specific API extension.
	Device-specific Display API extensions
	Devicetree Display API
	Display Driver Backend API
	LCD Interface
	LCD Interface.
	MIPI Display interface
	MIPI Display definitions.
	MIPI-DBI
	Interfaces for MIPI-DBI (Display Bus Interface).
	MIPI-DSI
	Interfaces for MIPI-DSI (Display Serial Interface).
	Monochrome Character Framebuffer
	Public Monochrome Character Framebuffer API.

Files
file	display.h
	Main header file for display driver API.
file	ac057tc1.h
	Public API for AC057TC1 7-color e-ink display.

Data Structures
struct	display_capabilities
	Structure holding display capabilities. More...
struct	display_buffer_descriptor
	Structure to describe display data buffer layout. More...
struct	display_event_data
	Display event payload. More...

Macros
#define	DISPLAY_BITS_PER_PIXEL(fmt)
	Bits required per pixel for display format.

Typedefs
typedef enum display_event_result(*	display_event_cb_t) (const struct device *dev, uint32_t evt, const struct display_event_data *data, void *user_data)
	Called either in ISR context (if arg in_isr=true at register time, see display_register_event_cb ) or in thread context (if in_isr=false, driver will schedule work to call it).

Enumerations
enum	display_pixel_format {   PIXEL_FORMAT_RGB_888 = BIT(0) , PIXEL_FORMAT_MONO01 = BIT(1) , PIXEL_FORMAT_MONO10 = BIT(2) , PIXEL_FORMAT_ARGB_8888 = BIT(3) ,   PIXEL_FORMAT_RGB_565 = BIT(4) , PIXEL_FORMAT_RGB_565X = BIT(5) , PIXEL_FORMAT_L_8 = BIT(6) , PIXEL_FORMAT_AL_88 = BIT(7) ,   PIXEL_FORMAT_XRGB_8888 = BIT(8) , PIXEL_FORMAT_BGR_888 = BIT(9) , PIXEL_FORMAT_ABGR_8888 = BIT(10) , PIXEL_FORMAT_RGBA_8888 = BIT(11) ,   PIXEL_FORMAT_BGRA_8888 = BIT(12) , PIXEL_FORMAT_PRIV_START = (PIXEL_FORMAT_BGRA_8888 << 1) }
	Display pixel formats. More...
enum	display_screen_info {   SCREEN_INFO_MONO_VTILED = BIT(0) , SCREEN_INFO_MONO_MSB_FIRST = BIT(1) , SCREEN_INFO_EPD = BIT(2) , SCREEN_INFO_DOUBLE_BUFFER = BIT(3) ,   SCREEN_INFO_X_ALIGNMENT_WIDTH = BIT(4) }
	Display screen information. More...
enum	display_orientation { DISPLAY_ORIENTATION_NORMAL , DISPLAY_ORIENTATION_ROTATED_90 , DISPLAY_ORIENTATION_ROTATED_180 , DISPLAY_ORIENTATION_ROTATED_270 }
	Enumeration with possible display orientation. More...
enum	display_event { DISPLAY_EVENT_LINE_INT = BIT(0) , DISPLAY_EVENT_VSYNC = BIT(1) , DISPLAY_EVENT_FRAME_DONE = BIT(2) }
	Display event types. More...
enum	display_event_result { DISPLAY_EVENT_RESULT_CONTINUE = 0 , DISPLAY_EVENT_RESULT_HANDLED = 1 }
	Display event callback return flags. More...

Functions
static int	display_write (const struct device *dev, const uint16_t x, const uint16_t y, const struct display_buffer_descriptor *desc, const void *buf)
	Write data to display.
static int	display_read (const struct device *dev, const uint16_t x, const uint16_t y, const struct display_buffer_descriptor *desc, void *buf)
	Read data from display.
static int	display_clear (const struct device *dev)
	Clear the screen of the display device.
static void *	display_get_framebuffer (const struct device *dev)
	Get pointer to framebuffer for direct access.
static int	display_blanking_on (const struct device *dev)
	Turn display blanking on.
static int	display_blanking_off (const struct device *dev)
	Turn display blanking off.
static int	display_set_brightness (const struct device *dev, uint8_t brightness)
	Set the brightness of the display.
static int	display_set_contrast (const struct device *dev, uint8_t contrast)
	Set the contrast of the display.
static void	display_get_capabilities (const struct device *dev, struct display_capabilities *capabilities)
	Get display capabilities.
static int	display_set_pixel_format (const struct device *dev, const enum display_pixel_format pixel_format)
	Set pixel format used by the display.
static int	display_set_orientation (const struct device *dev, const enum display_orientation orientation)
	Set display orientation.
static int	display_register_event_cb (const struct device *dev, display_event_cb_t cb, void *user_data, uint32_t event_mask, bool in_isr, uint32_t *out_reg_handle)
	Register event callback for a display device.
static int	display_unregister_event_cb (const struct device *dev, uint32_t reg_handle)
	Unregister event callback for a display device.

Detailed Description

Interfaces for display controllers.

Since

1.14

Version

0.9.0

Macro Definition Documentation

DISPLAY_BITS_PER_PIXEL

#define DISPLAY_BITS_PER_PIXEL

(

fmt

)

#include <zephyr/drivers/display.h>

Value:

((((fmt & PIXEL_FORMAT_RGB_888) >> 0) * 24U) +                          \
(((fmt & PIXEL_FORMAT_MONO01) >> 1) * 1U) +                             \
(((fmt & PIXEL_FORMAT_MONO10) >> 2) * 1U) +                             \
(((fmt & PIXEL_FORMAT_ARGB_8888) >> 3) * 32U) +                         \
(((fmt & PIXEL_FORMAT_RGB_565) >> 4) * 16U) +                           \
(((fmt & PIXEL_FORMAT_RGB_565X) >> 5) * 16U) +                          \
(((fmt & PIXEL_FORMAT_L_8) >> 6) * 8U) +                                \
(((fmt & PIXEL_FORMAT_AL_88) >> 7) * 16U) +                             \
(((fmt & PIXEL_FORMAT_XRGB_8888) >> 8) * 32U) +                         \
(((fmt & PIXEL_FORMAT_BGR_888) >> 9) * 24U) +                           \
(((fmt & PIXEL_FORMAT_ABGR_8888) >> 10) * 32U) +                        \
(((fmt & PIXEL_FORMAT_RGBA_8888) >> 11) * 32U) +                        \
(((fmt & PIXEL_FORMAT_BGRA_8888) >> 12) * 32U))

Bits required per pixel for display format.

This macro expands to the number of bits required for a given display format. It can be used to allocate a framebuffer based on a given display format type. This does not work with any private pixel formats.

Typedef Documentation

display_event_cb_t

typedef enum display_event_result(* display_event_cb_t) (const struct device *dev, uint32_t evt, const struct display_event_data *data, void *user_data)

#include <zephyr/drivers/display.h>

Called either in ISR context (if arg in_isr=true at register time, see display_register_event_cb ) or in thread context (if in_isr=false, driver will schedule work to call it).

When called from ISR context the callback must be extremely fast and must not call blocking APIs or sleep.

Parameters

dev	Pointer to device structure
evt	'enum display_event' bit of event to handle
data	Driver data passed to callback
user_data	User data passed by driver to callback

Returns

An 'enum display_event_result' flag, see its description for details.

Enumeration Type Documentation

display_event

enum display_event

#include <zephyr/drivers/display.h>

Display event types.

Enumerator
DISPLAY_EVENT_LINE_INT	Fired when controller reaches a configured scanline.
DISPLAY_EVENT_VSYNC	Fired at vertical sync / start of new frame.
DISPLAY_EVENT_FRAME_DONE	Fired when a frame transfer to the panel or frame buffer update completes.

display_event_result

enum display_event_result

#include <zephyr/drivers/display.h>

Display event callback return flags.

Enumerator
DISPLAY_EVENT_RESULT_CONTINUE	Let the driver execute its default handling.
DISPLAY_EVENT_RESULT_HANDLED	The callback handled the event and the driver should skip its default processing for that event.

display_orientation

enum display_orientation

#include <zephyr/drivers/display.h>

Enumeration with possible display orientation.

Enumerator
DISPLAY_ORIENTATION_NORMAL	No rotation.
DISPLAY_ORIENTATION_ROTATED_90	Rotated 90 degrees clockwise.
DISPLAY_ORIENTATION_ROTATED_180	Rotated 180 degrees clockwise.
DISPLAY_ORIENTATION_ROTATED_270	Rotated 270 degrees clockwise.

display_pixel_format

enum display_pixel_format

#include <zephyr/drivers/display.h>

Display pixel formats.

Display pixel format enumeration.

In case a pixel format consists out of multiple bytes the byte order is big endian.

Enumerator
PIXEL_FORMAT_RGB_888	24-bit RGB format with 8 bits per component. Below shows how data are organized in memory. Byte 0 Byte 1 Byte 2 7......0 15.....8 23....16 | Bbbbbbbb Gggggggg Rrrrrrrr | ... 24-bit RGB
PIXEL_FORMAT_MONO01	1-bit monochrome format with 1 bit per pixel, thus each byte represent 8 pixels Two variants, with black being either represented by 0 or 1 Below shows how data are organized in memory. Byte 0 | Byte 1 | 7......0 7......0 | MMMMMMMM | MMMMMMMM | ... Monochrome (0=Black 1=White)
PIXEL_FORMAT_MONO10	Monochrome (1=Black 0=White).
PIXEL_FORMAT_ARGB_8888	32-bit RGB format with 8 bits per component and 8 bits for alpha. Below shows how data are organized in memory. Byte 0 Byte 1 Byte 2 Byte 3 7......0 15.....8 23....16 31....24 | Bbbbbbbb Gggggggg Rrrrrrrr Aaaaaaaa | ... 32-bit ARGB
PIXEL_FORMAT_RGB_565	16-bit RGB format packed into two bytes: 5 red bits [15:11], 6 green bits [10:5], 5 blue bits [4:0]. Below shows how data are organized in memory. Byte 0 Byte 1 | 7......0 15.....8 | gggBbbbb RrrrrGgg | ...
PIXEL_FORMAT_RGB_565X	16-bit RGB format packed into two bytes. Byte swapped version of the PIXEL_FORMAT_RGB_565 format. 7......0 15.....8 | RrrrrGgg gggBbbbb | ...
PIXEL_FORMAT_L_8	8-bit Greyscale format Below shows how data are organized in memory. Byte 0 | Byte 1 | 7......0 7......0 | Gggggggg | Gggggggg | ... 8-bit Grayscale/Luminance, equivalent to GRAY, GREY, GRAY8, Y8, R8, etc...
PIXEL_FORMAT_AL_88	16-bit Greyscale format with 8-bit luminance and 8-bit for alpha Below shows how data are organized in memory. Byte 0 Byte 1 | 7......0 15.....8 | Gggggggg Aaaaaaaa | ... 8-bit Grayscale/Luminance with alpha
PIXEL_FORMAT_XRGB_8888	32-bit RGB format with 8 bits per component and 8 bits unused. Below shows how data are organized in memory. Byte 0 Byte 1 Byte 2 Byte 3 7......0 15.....8 23....16 31....24 | Bbbbbbbb Gggggggg Rrrrrrrr Xxxxxxxx | ... 32-bit XRGB
PIXEL_FORMAT_BGR_888	24-bit BGR format with 8 bits per component. Below shows how data are organized in memory. Byte 0 Byte 1 Byte 2 7......0 15.....8 23....16 | Rrrrrrrr Gggggggg Bbbbbbbb | ... 24-bit BGR
PIXEL_FORMAT_ABGR_8888	32-bit BGR format with 8 bits per component and 8 bits for alpha. Below shows how data are organized in memory. Byte 0 Byte 1 Byte 2 Byte 3 7......0 15.....8 23....16 31....24 | Rrrrrrrr Gggggggg Bbbbbbbb Aaaaaaaa | ... 32-bit ABGR
PIXEL_FORMAT_RGBA_8888	32-bit RGB format with 8 bits per component and 8 bits for alpha. Below shows how data are organized in memory. Byte 0 Byte 1 Byte 2 Byte 3 7......0 15.....8 23....16 31....24 | Aaaaaaaa Bbbbbbbb Gggggggg Rrrrrrrr | ... 32-bit RGBA
PIXEL_FORMAT_BGRA_8888	32-bit BGR format with 8 bits per component and 8 bits for alpha. Below shows how data are organized in memory. Byte 0 Byte 1 Byte 2 Byte 3 7......0 15.....8 23....16 31....24 | Aaaaaaaa Rrrrrrrr Gggggggg Bbbbbbbb | ... 32-bit BGRA
PIXEL_FORMAT_PRIV_START	This and higher values are display specific. Refer to the display header file.

display_screen_info

enum display_screen_info

#include <zephyr/drivers/display.h>

Display screen information.

Enumerator
SCREEN_INFO_MONO_VTILED	If selected, one octet represents 8 pixels ordered vertically, otherwise ordered horizontally.
SCREEN_INFO_MONO_MSB_FIRST	If selected, the MSB represents the first pixel, otherwise MSB represents the last pixel.
SCREEN_INFO_EPD	Electrophoretic Display.
SCREEN_INFO_DOUBLE_BUFFER	Screen has two alternating ram buffers.
SCREEN_INFO_X_ALIGNMENT_WIDTH	Screen has x alignment constrained to width.

Function Documentation

display_blanking_off()

int display_blanking_off ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/display.h>

Turn display blanking off.

Restore the frame buffer content to the display. In case backlight control is supported by the driver the backlight configuration is restored.

Parameters

dev	Pointer to device structure

Returns

0 on success else negative errno code.

Return values

-ENOSYS

if not implemented.

display_blanking_on()

int display_blanking_on ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/display.h>

Turn display blanking on.

This function blanks the complete display. The content of the frame buffer will be retained while blanking is enabled and the frame buffer will be accessible for read and write operations.

In case backlight control is supported by the driver the backlight is turned off. The backlight configuration is retained and accessible for configuration.

In case the driver supports display blanking the initial state of the driver would be the same as if this function was called.

Parameters

dev	Pointer to device structure

Returns

0 on success else negative errno code.

Return values

-ENOSYS

if not implemented.

display_clear()

int display_clear ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/display.h>

Clear the screen of the display device.

Parameters

dev	Pointer to device structure

Returns

0 on success else negative errno code.

Return values

-ENOSYS

if not implemented.

display_get_capabilities()

void display_get_capabilities ( const struct device * dev, struct display_capabilities * capabilities )

inlinestatic

#include <zephyr/drivers/display.h>

Get display capabilities.

Parameters

dev	Pointer to device structure
capabilities	Pointer to capabilities structure to populate

display_get_framebuffer()

void * display_get_framebuffer ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/display.h>

Get pointer to framebuffer for direct access.

Parameters

dev	Pointer to device structure

Returns

Pointer to frame buffer or NULL if direct framebuffer access is not supported

display_read()

int display_read ( const struct device * dev, const uint16_t x, const uint16_t y, const struct display_buffer_descriptor * desc, void * buf )

inlinestatic

#include <zephyr/drivers/display.h>

Read data from display.

Parameters

dev	Pointer to device structure
x	x Coordinate of the upper left corner where to read from
y	y Coordinate of the upper left corner where to read from
desc	Pointer to a structure describing the buffer layout
buf	Pointer to buffer array

Returns

0 on success else negative errno code.

Return values

-ENOSYS

if not implemented.

display_register_event_cb()

int display_register_event_cb ( const struct device * dev, display_event_cb_t cb, void * user_data, uint32_t event_mask, bool in_isr, uint32_t * out_reg_handle )

inlinestatic

#include <zephyr/drivers/display.h>

Register event callback for a display device.

Parameters

dev	Pointer to device structure
cb	User callback function pointer, see display_event_cb_t description
user_data	User data to be passed by driver to event callback
event_mask	Mask of 'enum display_event' events upon which the callback will be called
in_isr	If true, callback will be invoked in ISR context (shall be fast, non-blocking). If false, callback will be invoked in thread/workqueue context. A driver is allowed to implement just one of the invocation contexts.
out_reg_handle	Lets the caller prove ownership of the registration, and allows for safe unregistration

Note

Thread-context delivery should be preferred for non-critical work; keep ISR fast and optionally only set flags and schedule work, avoid scheduler APIs, mutexes, prints.

Returns

0 and a non-zero out_reg_handle value on success, otherwise a negative errno code.

Return values

-EBUSY	A callback is already registered.
-ENOTSUP	One of the events is not supported, or the requested invocation context is not supported.
-ENOSYS	Not implemented.
-EINVAL	Invalid argument.

display_set_brightness()

int display_set_brightness ( const struct device * dev, uint8_t brightness )

inlinestatic

#include <zephyr/drivers/display.h>

Set the brightness of the display.

Set the brightness of the display in steps of 1/256, where 255 is full brightness and 0 is minimal.

Parameters

dev	Pointer to device structure
brightness	Brightness in steps of 1/256

Returns

0 on success else negative errno code.

Return values

-ENOSYS

if not implemented.

display_set_contrast()

int display_set_contrast ( const struct device * dev, uint8_t contrast )

inlinestatic

#include <zephyr/drivers/display.h>

Set the contrast of the display.

Set the contrast of the display in steps of 1/256, where 255 is maximum difference and 0 is minimal.

Parameters

dev	Pointer to device structure
contrast	Contrast in steps of 1/256

Returns

0 on success else negative errno code.

Return values

-ENOSYS

if not implemented.

display_set_orientation()

int display_set_orientation ( const struct device * dev, const enum display_orientation orientation )

inlinestatic

#include <zephyr/drivers/display.h>

Set display orientation.

Parameters

dev	Pointer to device structure
orientation	Orientation to be used by display

Returns

0 on success else negative errno code.

Return values

-ENOSYS

if not implemented.

display_set_pixel_format()

int display_set_pixel_format ( const struct device * dev, const enum display_pixel_format pixel_format )

inlinestatic

#include <zephyr/drivers/display.h>

Set pixel format used by the display.

Parameters

dev	Pointer to device structure
pixel_format	Pixel format to be used by display

Returns

0 on success else negative errno code.

Return values

-ENOSYS

if not implemented.

display_unregister_event_cb()

int display_unregister_event_cb ( const struct device * dev, uint32_t reg_handle )

inlinestatic

#include <zephyr/drivers/display.h>

Unregister event callback for a display device.

Parameters

dev	Pointer to device structure
reg_handle	Handle used to register the callback.

Returns

0 on success, otherwise a negative errno code.

Return values

-EINVAL	If 'reg_handle == 0'.
-EPERM	Not the owner, or already unregistered.
-ENOSYS	If it, or register_event_cb, is not implemented.

display_write()

int display_write ( const struct device * dev, const uint16_t x, const uint16_t y, const struct display_buffer_descriptor * desc, const void * buf )

inlinestatic

#include <zephyr/drivers/display.h>

Write data to display.

Parameters

dev	Pointer to device structure
x	x Coordinate of the upper left corner where to write the buffer
y	y Coordinate of the upper left corner where to write the buffer
desc	Pointer to a structure describing the buffer layout
buf	Pointer to buffer array

Returns

0 on success else negative errno code.