PebbleOS v4.47.0-512-g5285d4236
Loading...
Searching...
No Matches
Display

Display class. More...

Modules

 QEMU display
 Display driver for the QEMU framebuffer display peripheral.
 
 SDL display
 Display driver showing the framebuffer in an SDL window on the host.
 
 SF32LB57 LCD controller
 Display driver for the SF32LB57 LCD controller, sending frames to a panel with frame memory over quad SPI.
 
 SF32LB LCD controller
 Display driver for the SF32LB LCD controller scanning out to a panel.
 
 Sharp LS013B7DH01
 Display driver for the Sharp LS013B7DH01 memory LCD, an SPI device.
 

Data Structures

struct  pbl_display_props
 Properties of a display. More...
 
struct  pbl_display_buffer
 Framebuffer handed to an update. More...
 
struct  pbl_display_ops
 Display driver operations. More...
 
struct  pbl_display
 A display. More...
 

Macros

#define PBL_DISPLAY_STATE_DEFINE(sym)
 Define the class state of display sym, for the PBL_*_DEFINE() macro of a driver.
 
#define PBL_DISPLAY_INIT_FRAMEBUFFER(sym, _name, _parent, _ops, _width, _height, _format, _rotated, _fb, _fb_size, _fb_ram, ...)
 Initializer for the struct pbl_display of display sym, with the memory the board reserves for its framebuffer.
 
#define PBL_DISPLAY_INIT(sym, _name, _parent, _ops, _width, _height, _format, _rotated, ...)
 Initializer for the struct pbl_display of display sym.
 

Typedefs

typedef void(* pbl_display_callback_t) (int status, void *arg)
 Completion callback of pbl_display_update().
 

Enumerations

enum  pbl_display_format { PBL_DISPLAY_FORMAT_MONO , PBL_DISPLAY_FORMAT_ARGB2222 , PBL_DISPLAY_FORMAT_RGB565 }
 Pixel formats of the framebuffer. More...
 

Functions

static const struct pbl_display_props * pbl_display_get_props (const struct pbl_display *disp)
 Get the properties of a display.
 
static uint16_t pbl_display_round_inset (const struct pbl_display *disp, uint16_t y)
 Get the pixels hidden at each end of a row of a round panel.
 
int pbl_display_dev_init (const struct pbl_device *dev)
 Device init of every display: sets the class state up, then calls the driver's init.
 
void pbl_display_complete (const struct pbl_display *disp, int status)
 Report the end of the update in flight.
 
int pbl_display_enable (const struct pbl_display *disp)
 Turn the panel on.
 
int pbl_display_disable (const struct pbl_display *disp)
 Turn the panel off.
 
int pbl_display_set_rotated (const struct pbl_display *disp, bool rotated)
 Turn the image by 180 degrees, on top of the mounting rotation, from the next update.
 
int pbl_display_clear (const struct pbl_display *disp)
 Clear the image held by the panel, if the display supports it.
 
int pbl_display_update (const struct pbl_display *disp, const struct pbl_display_buffer *buf, uint16_t y0, uint16_t y1, pbl_display_callback_t cb, void *arg)
 Send rows of a framebuffer to the panel, returning once the update has started.
 
int pbl_display_get_framebuffer (const struct pbl_display *disp, struct pbl_display_buffer *buf)
 Get the framebuffer the board reserves for a display.
 
int pbl_display_update_sync (const struct pbl_display *disp, const struct pbl_display_buffer *buf, uint16_t y0, uint16_t y1)
 Send rows of a framebuffer to the panel and wait for the update to end.
 
bool pbl_display_update_in_progress (const struct pbl_display *disp)
 Check whether an update is in progress.
 

Variables

const struct pbl_device_class pbl_display_class
 Class of the displays.
 
const struct pbl_display *const DISPLAY
 The display, defined by the board.
 

Detailed Description

Display class.

A display is a struct pbl_display device that scans a framebuffer out to a panel: a controller driving its panel, or a panel with its own memory on a bus. The framebuffer is owned by the caller and has the display's size and pbl_display_format; an update sends a range of its rows. As in Linux, a panel's mounting rotation is part of the display, and the image is turned by a further 180 degrees on request, e.g. for left-hand wear.

A board may also reserve memory for the display's framebuffer, as the devicetree memory-region of the controller, for frames too large for the heap: pbl_display_get_framebuffer() gives it. Memory in a RAM device, only powered while it has users, is kept powered by the display.

static void prv_done(int status, void *arg) {
// Runs from the display's interrupt
}
struct pbl_display_buffer buf = {.data = fb, .pitch = FB_PITCH};
ret = pbl_display_update(DISPLAY, &buf, y0, y1, prv_done, nullptr);
uint8_t * data
First row.
Definition display.h:78
Framebuffer handed to an update.
Definition display.h:76
const struct pbl_display *const DISPLAY
The display, defined by the board.
int pbl_display_update(const struct pbl_display *disp, const struct pbl_display_buffer *buf, uint16_t y0, uint16_t y1, pbl_display_callback_t cb, void *arg)
Send rows of a framebuffer to the panel, returning once the update has started.

An update runs in the background and reports its outcome to a callback run from the display's interrupt, or before pbl_display_update() returns for displays that update synchronously. The display may modify the updated rows while it runs, but restores them before the callback. Calls are made from task context and return 0 or a negative errno: -EBUSY while an update is in progress, -EINVAL for an invalid row range and -ENODEV if the display is not ready.


Data Structure Documentation

◆ pbl_display_props

struct pbl_display_props

Properties of a display.

Data Fields
enum pbl_display_format format Framebuffer format.
uint16_t height Height, in pixels.
bool rotated Panel mounted upside down.
const uint8_t * round_mask Pixels hidden at each end of the rows of the top half of a round panel, mirrored in the bottom half, or NULL.
uint16_t width Width, in pixels.

◆ pbl_display_buffer

struct pbl_display_buffer

Framebuffer handed to an update.

Data Fields
uint8_t * data First row.
uint32_t pitch Bytes from one row to the next.

◆ pbl_display

struct pbl_display

A display.

Data Fields
struct pbl_device dev Device.
uint8_t * framebuffer Memory the board reserves for the framebuffer, or NULL.
const struct pbl_ram * framebuffer_ram RAM device the memory is in, or NULL when it is always powered.
size_t framebuffer_size Its size, in bytes.
const struct pbl_display_ops * ops Driver operations.
struct pbl_display_props props Properties.
struct pbl_display_state * state Runtime state.

Macro Definition Documentation

◆ PBL_DISPLAY_INIT

#define PBL_DISPLAY_INIT (   sym,
  _name,
  _parent,
  _ops,
  _width,
  _height,
  _format,
  _rotated,
  ... 
)
Value:
PBL_DISPLAY_INIT_FRAMEBUFFER(sym, _name, _parent, _ops, _width, _height, _format, _rotated, 0U, \
0U, nullptr, __VA_ARGS__)
#define PBL_DISPLAY_INIT_FRAMEBUFFER(sym, _name, _parent, _ops, _width, _height, _format, _rotated, _fb, _fb_size, _fb_ram,...)
Initializer for the struct pbl_display of display sym, with the memory the board reserves for its fra...
Definition display.h:205

Initializer for the struct pbl_display of display sym.

Parameters
symSymbol of the display instance, with its state defined by PBL_DISPLAY_STATE_DEFINE().
_nameName.
_parentParent device, or NULL.
_opsDriver operations.
_widthWidth, in pixels.
_heightHeight, in pixels.
_formatFramebuffer format.
_rotatedPanel mounted upside down.
...Other properties, designated initializers of struct pbl_display_props.

◆ PBL_DISPLAY_INIT_FRAMEBUFFER

#define PBL_DISPLAY_INIT_FRAMEBUFFER (   sym,
  _name,
  _parent,
  _ops,
  _width,
  _height,
  _format,
  _rotated,
  _fb,
  _fb_size,
  _fb_ram,
  ... 
)
Value:
{ \
.ops = (_ops), \
.state = &sym##_display_state, \
.props = \
{.width = (_width), \
.height = (_height), \
.format = (_format), \
.rotated = (_rotated), \
__VA_ARGS__}, \
.framebuffer = (uint8_t *)(uintptr_t)(_fb), \
.framebuffer_size = (_fb_size), \
.framebuffer_ram = (_fb_ram), \
}
#define PBL_DEVICE_INIT_CLASS(sym, _name, _init, _parent, _cls)
Initializer for the struct pbl_device of device instance sym, in class _cls.
Definition device.h:153
int pbl_display_dev_init(const struct pbl_device *dev)
Device init of every display: sets the class state up, then calls the driver's init.
const struct pbl_device_class pbl_display_class
Class of the displays.

Initializer for the struct pbl_display of display sym, with the memory the board reserves for its framebuffer.

Parameters
symSymbol of the display instance, with its state defined by PBL_DISPLAY_STATE_DEFINE().
_nameName.
_parentParent device, or NULL.
_opsDriver operations.
_widthWidth, in pixels.
_heightHeight, in pixels.
_formatFramebuffer format.
_rotatedPanel mounted upside down.
_fbMemory reserved for the framebuffer, or 0.
_fb_sizeIts size, in bytes, at least a frame.
_fb_ramRAM device the memory is in, kept powered by the display, or NULL.
...Other properties, designated initializers of struct pbl_display_props.

◆ PBL_DISPLAY_STATE_DEFINE

#define PBL_DISPLAY_STATE_DEFINE (   sym)
Value:
static struct pbl_display_state sym##_display_state
#define PBL_DEVICE_STATE_DEFINE(sym)
Define the runtime state of device instance sym.
Definition device.h:132

Define the class state of display sym, for the PBL_*_DEFINE() macro of a driver.

Parameters
symSymbol of the display instance.

Typedef Documentation

◆ pbl_display_callback_t

typedef void(* pbl_display_callback_t) (int status, void *arg)

Completion callback of pbl_display_update().

Parameters
status0 or a negative errno.
argCallback argument.

Enumeration Type Documentation

◆ pbl_display_format

Pixel formats of the framebuffer.

Enumerator
PBL_DISPLAY_FORMAT_MONO 

1 bit per pixel, leftmost pixel in the least significant bit, set for white.

PBL_DISPLAY_FORMAT_ARGB2222 

8 bits per pixel, 2 bits per alpha, red, green and blue, from the most significant bit.

PBL_DISPLAY_FORMAT_RGB565 

16 bits per pixel, little-endian, 5 bits of red, 6 of green and 5 of blue, from the most significant bit.

Function Documentation

◆ pbl_display_clear()

int pbl_display_clear ( const struct pbl_display *  disp)

Clear the image held by the panel, if the display supports it.

Parameters
dispDisplay.
Returns
0, -ENOTSUP if the display cannot, or another negative errno.

◆ pbl_display_complete()

void pbl_display_complete ( const struct pbl_display *  disp,
int  status 
)

Report the end of the update in flight.

Called by the display driver, typically from its interrupt handler.

Parameters
dispDisplay.
status0 or a negative errno.

◆ pbl_display_dev_init()

int pbl_display_dev_init ( const struct pbl_device *  dev)

Device init of every display: sets the class state up, then calls the driver's init.

Parameters
devDisplay device.
Returns
0 or a negative errno.

◆ pbl_display_disable()

int pbl_display_disable ( const struct pbl_display *  disp)

Turn the panel off.

Parameters
dispDisplay.
Returns
0 or a negative errno.

◆ pbl_display_enable()

int pbl_display_enable ( const struct pbl_display *  disp)

Turn the panel on.

Parameters
dispDisplay.
Returns
0 or a negative errno.

◆ pbl_display_get_framebuffer()

int pbl_display_get_framebuffer ( const struct pbl_display *  disp,
struct pbl_display_buffer *  buf 
)

Get the framebuffer the board reserves for a display.

It has the display's size and format, and is cleared to 0 when the display comes up.

Parameters
dispDisplay.
[out]bufFramebuffer.
Returns
0, -ENOENT if the board reserves none, or -ENODEV if the display is not ready.

◆ pbl_display_get_props()

static const struct pbl_display_props * pbl_display_get_props ( const struct pbl_display *  disp)
inlinestatic

Get the properties of a display.

Parameters
dispDisplay.
Returns
Its properties.

References pbl_display::props.

◆ pbl_display_round_inset()

static uint16_t pbl_display_round_inset ( const struct pbl_display *  disp,
uint16_t  y 
)
inlinestatic

Get the pixels hidden at each end of a row of a round panel.

Parameters
dispDisplay, with a pbl_display_props::round_mask.
yRow.
Returns
Pixels hidden at each end of the row.

References pbl_display_props::height, pbl_display::props, and pbl_display_props::round_mask.

◆ pbl_display_set_rotated()

int pbl_display_set_rotated ( const struct pbl_display *  disp,
bool  rotated 
)

Turn the image by 180 degrees, on top of the mounting rotation, from the next update.

Parameters
dispDisplay.
rotatedTurn the image.
Returns
0 or a negative errno.

◆ pbl_display_update()

int pbl_display_update ( const struct pbl_display *  disp,
const struct pbl_display_buffer *  buf,
uint16_t  y0,
uint16_t  y1,
pbl_display_callback_t  cb,
void *  arg 
)

Send rows of a framebuffer to the panel, returning once the update has started.

Parameters
dispDisplay.
bufFramebuffer, valid until cb is called.
y0First row.
y1Last row.
cbCompletion callback.
argCallback argument.
Returns
0 if cb will be called, or a negative errno.

◆ pbl_display_update_in_progress()

bool pbl_display_update_in_progress ( const struct pbl_display *  disp)

Check whether an update is in progress.

Parameters
dispDisplay.
Returns
True from pbl_display_update() until the callback.

◆ pbl_display_update_sync()

int pbl_display_update_sync ( const struct pbl_display *  disp,
const struct pbl_display_buffer *  buf,
uint16_t  y0,
uint16_t  y1 
)

Send rows of a framebuffer to the panel and wait for the update to end.

Parameters
dispDisplay.
bufFramebuffer.
y0First row.
y1Last row.
Returns
0 or a negative errno.

Variable Documentation

◆ DISPLAY

const struct pbl_display* const DISPLAY
extern

The display, defined by the board.

◆ pbl_display_class

const struct pbl_device_class pbl_display_class
extern

Class of the displays.