Display Platform Abstraction Layer for the RA8D2. More...

#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for ra8_display_pal.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	display_caps_t
	Capabilities a backend reports after display_init. More...
struct	display_fb_t
	Framebuffer descriptor returned by display_get_framebuffer. More...
struct	display_rect_t
	Rectangle in framebuffer coordinates passed into display_flush. More...
struct	display_cfg_t
	Configuration descriptor passed into display_init. More...

Typedefs
typedef struct display_backend_iface	display_backend_iface_t
typedef struct display_handle	display_handle_t

Enumerations
enum	display_pixfmt_t : uint8_t { k_display_pixfmt_rgb565 = 0U , k_display_pixfmt_rgb888 = 1U , k_display_pixfmt_grey4 = 2U , k_display_pixfmt_grey1 = 3U }
	Canonical pixel formats the PAL understands. More...
enum	display_refresh_hint_t : uint8_t { k_display_refresh_fast = 0U , k_display_refresh_quality = 1U , k_display_refresh_init = 2U }
	Intent passed into display_flush; backends map this onto whatever waveform/mode their controller offers. More...

Functions
ra8_err_t	display_init (const display_cfg_t cfg, display_handle_t *out_handle)
	Initialise the display PAL and bring the selected backend up to a state where display_flush succeeds.
ra8_err_t	display_get_caps (const display_handle_t d, display_caps_t out)
	Query the bound backend's runtime capabilities.
ra8_err_t	display_get_framebuffer (const display_handle_t d, display_fb_t out)
	Return the framebuffer descriptor the backend is targeting.
ra8_err_t	display_flush (const display_handle_t *d, display_rect_t rect, display_refresh_hint_t hint)
	Commit pending framebuffer changes to the panel.
ra8_err_t	display_clear (const display_handle_t *d, uint32_t color)
	Clear the entire framebuffer to color.
ra8_err_t	display_deinit (const display_handle_t *d)
	Release the backend and invalidate the PAL handle.
display_rect_t	display_full_rect (const display_handle_t *d)
	Convenience helper returning the rect covering the whole framebuffer.

Detailed Description

Display Platform Abstraction Layer for the RA8D2.

Tag: [Ring 4 / PAL] {World: NS}

Backend-agnostic API that lets applications draw into a framebuffer and push it to a panel without knowing which display controller is on the other end. Today there are three backends:

k_display_backend_lcd_ra8_glcdc – thin wrapper over libs/ra8_hal/src/ra8_glcdc.c driving the EK-RA8D2 1024x600 parallel-RGB TFT.
k_display_backend_eink_it8951 – stub for the future IT8951-compatible e-ink panel. Compiles and presents the same API surface, but returns k_ra8_err_not_supported from display_flush / display_get_framebuffer until the hardware-side driver lands.

Apps swap backends by changing the iface field of their display_cfg_t – no other code touches the underlying controller, so a future e-ink port is a single-line change in the app's config.

Layering

+-----------------------------+ display_init / get_framebuffer
| application code            | display_flush(rect, hint)
| (ra8_gfx / ra8_box chrome)    |
+--------------+--------------+
               |
               v
+-----------------------------+   one vtable per backend.
| ra8_display_pal (this file)  |<- dispatches via display_backend_iface_t
+--------------+--------------+
               |
      +--------+---------+
      |                  |
      v                  v
+------------+    +-------------+
| LCD (glcdc)|    | e-ink stub  |
+------------+    +-------------+

Framebuffer ownership

The caller owns the framebuffer storage and points the PAL at it through cfg->framebuffer. RGB565 is the canonical app-side format; backends that want a different native depth (e.g. e-ink's 4bpp greyscale) convert during display_flush. This keeps app code portable across backends.

Refresh model

LCD panels scan continuously, so display_flush is essentially a no-op (it commits any pending DMA writes and returns).
E-ink panels are bistable, so display_flush is where the real work happens: write the FB to the controller, then trigger an update with the chosen display_refresh_hint_t.

Applications that need to control speed-vs-quality on e-ink pass the hint; LCD backends ignore it.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file ra8_display_pal.h.

Typedef Documentation

◆ display_backend_iface_t

typedef struct display_backend_iface display_backend_iface_t

Definition at line 208 of file ra8_display_pal.h.

◆ display_handle_t

typedef struct display_handle display_handle_t

Definition at line 222 of file ra8_display_pal.h.

Enumeration Type Documentation

◆ display_pixfmt_t

enum display_pixfmt_t : uint8_t

Canonical pixel formats the PAL understands.

RGB565 is the only format LCD apps need today and is the canonical choice for portable code. Greyscale formats are reserved for e-ink backends that paint natively at lower depth – the LCD backend rejects them with k_ra8_err_not_supported.

Since: 0.1.0

Enumerator
k_display_pixfmt_rgb565	16 bpp, 5/6/5 packed.
k_display_pixfmt_rgb888	24 bpp, 8/8/8 packed.
k_display_pixfmt_grey4	4 bpp greyscale (2 px / byte).
k_display_pixfmt_grey1	1 bpp greyscale (8 px / byte).

Definition at line 98 of file ra8_display_pal.h.

◆ display_refresh_hint_t

enum display_refresh_hint_t : uint8_t

Intent passed into display_flush; backends map this onto whatever waveform/mode their controller offers.

Hint values describe the trade-off the caller wants – not a specific waveform name. On LCD backends every hint behaves the same (flush is effectively a no-op). On e-ink the mapping is:

k_display_refresh_fast -> A2-like waveform (fast, ghosting OK).
k_display_refresh_quality -> GC16-like waveform (slow, clean).
k_display_refresh_init -> full INIT clear (once at boot).

Since: 0.1.0

Enumerator
k_display_refresh_fast	Prioritise latency.
k_display_refresh_quality	Prioritise final quality.
k_display_refresh_init	Full reset of the panel.

Definition at line 121 of file ra8_display_pal.h.

Function Documentation

◆ display_clear()

ra8_err_t display_clear	(	const display_handle_t *	d,
		uint32_t	color )

nodiscard

Clear the entire framebuffer to color.

Writes color into every pixel of the framebuffer using the backend's native paint loop. Does NOT call display_flush – callers that want the cleared frame visible on e-ink must follow up with a display_flush(d, display_full_rect(d), k_display_refresh_quality).

Parameters

[in]	d	PAL handle.
[in]	color	Pixel value to write (interpretation depends on caps.pixfmt).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Buffer cleared.
k_ra8_err_null_ptr	d was NULL.

Precondition: display_init has succeeded.; The framebuffer pointer is reachable.

Postcondition: Every pixel of the framebuffer equals color.; Panel state is unchanged until the next display_flush.

Note: Not thread-safe with concurrent paint loops.

Since: 0.1.0

Definition at line 148 of file ra8_display_pal.c.

References internal_validate_handle(), k_ra8_ok, and s_handle.

Referenced by main().

◆ display_deinit()

ra8_err_t display_deinit ( const display_handle_t * d )

nodiscard

Release the backend and invalidate the PAL handle.

Mirrors display_init: tears down the controller, releases the static handle, and leaves the PAL ready to be re-initialised with a different backend.

Parameters

[in] d PAL handle to release.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Backend released; d is now stale.
k_ra8_err_null_ptr	d was NULL.

Precondition: display_init has succeeded.; No paint loop is in flight.

Postcondition: Subsequent calls through d return k_ra8_err_invalid_arg.; A fresh display_init will succeed.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 157 of file ra8_display_pal.c.

References internal_validate_handle(), k_ra8_ok, s_handle, and s_initialized.

Referenced by main().

◆ display_flush()

ra8_err_t display_flush	(	const display_handle_t *	d,
		display_rect_t	rect,
		display_refresh_hint_t	hint )

nodiscard

Commit pending framebuffer changes to the panel.

On scan-out backends (LCD) this is a memory barrier plus an optional cache clean. On e-ink backends this is the real work step: copy rect from the framebuffer into the controller's internal buffer, then trigger a display update with the waveform mapped from hint.

Parameters

[in]	d	PAL handle.
[in]	rect	Region of the framebuffer to push. Use display_full_rect(d) for a whole-screen update.
[in]	hint	Intent driving the waveform/mode selection.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Flush completed (or queued for the next scan on continuous-refresh panels).
k_ra8_err_null_ptr	d was NULL.
k_ra8_err_invalid_arg	rect extends outside the framebuffer.
k_ra8_err_not_supported	Backend does not implement flush yet (e-ink stub returns this).

Precondition: display_init has succeeded.; rect.x + rect.w <= caps.width_px and likewise for y / h.

Postcondition: On success rect of the panel reflects framebuffer state.; On non-ok return the panel is unchanged.

Note: Thread-safe relative to PAL state; the underlying controller is single-threaded.

Since: 0.1.0

Definition at line 139 of file ra8_display_pal.c.

References internal_validate_handle(), k_ra8_ok, and s_handle.

Referenced by cm_present(), ep_run_refresh_cycle(), er_flush_event(), ez_flush(), internal_tc_apply_and_measure(), internal_tc_draw_target(), ls_present(), main(), mg_present(), sh_loading_overlay(), sh_present(), sh_present_loupe(), wc_flush_rect(), wd_flush_full(), wd_flush_rect(), and wk_flush_rect().

◆ display_full_rect()

display_rect_t display_full_rect ( const display_handle_t * d )

Convenience helper returning the rect covering the whole framebuffer.

Short-hand for the common case where the caller wants to flush the entire framebuffer. Equivalent to {0, 0, caps.width_px, caps.height_px} if the handle is valid, or an all-zero rectangle if it is not.

Parameters

[in] d PAL handle.

Returns: display_rect_t {0, 0, caps.width_px, caps.height_px} on success, or an all-zero rectangle if d is NULL.

Return values

Full-screen	rect when d is a live handle.
All-zero	rect when d is NULL or stale.

Precondition: display_init has succeeded.; d is non-NULL.

Postcondition: No state is mutated.; Returned rectangle has w/h equal to current caps.

Note: Thread-safe.

Since: 0.1.0

Definition at line 173 of file ra8_display_pal.c.

References display_caps_t::height_px, internal_validate_handle(), k_ra8_ok, s_handle, and display_caps_t::width_px.

Referenced by cm_present(), ep_run_refresh_cycle(), er_flush_event(), internal_tc_apply_and_measure(), internal_tc_draw_target(), ls_present(), main(), mg_present(), and wd_flush_full().

◆ display_get_caps()

ra8_err_t display_get_caps	(	const display_handle_t *	d,
		display_caps_t *	out )

nodiscard

Query the bound backend's runtime capabilities.

Parameters

[in]	d	PAL handle returned by display_init.
[out]	out	Capabilities snapshot.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Capabilities written to *out.
k_ra8_err_null_ptr	Either argument was NULL.

Precondition: display_init has succeeded.; out is writable.

Postcondition: On success *out mirrors what the backend reported at init time.; No internal state is mutated.

Note: Thread-safe (pure read of immutable state).

Since: 0.1.0

Definition at line 119 of file ra8_display_pal.c.

References internal_validate_handle(), k_ra8_ok, RA8_CHECK_NULL_PTR, s_handle, and s_tag.

Referenced by app_bringup_display(), and main().

◆ display_get_framebuffer()

ra8_err_t display_get_framebuffer	(	const display_handle_t *	d,
		display_fb_t *	out )

nodiscard

Return the framebuffer descriptor the backend is targeting.

The pointer in out->pixels is the same buffer the caller passed via cfg->framebuffer. The width / height / stride may differ from the values the caller passed if the backend rounded them up to satisfy an alignment requirement.

Parameters

[in]	d	PAL handle.
[out]	out	Filled with the framebuffer descriptor.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Descriptor written.
k_ra8_err_null_ptr	Either argument was NULL.
k_ra8_err_not_supported	Backend does not expose a CPU-writable framebuffer (e.g. the e-ink stub before it is wired up).

Precondition: display_init has succeeded.; out is writable.

Postcondition: On success the caller may write out->width_px * out->stride_bytes bytes starting at out->pixels.

Note: Thread-safe relative to other PAL calls; not safe to call in parallel with display_deinit.

Since: 0.1.0

Definition at line 129 of file ra8_display_pal.c.

References internal_validate_handle(), k_ra8_ok, RA8_CHECK_NULL_PTR, s_handle, and s_tag.

Referenced by app_bringup_display(), app_bringup_panel(), cm_bringup_panel(), ez_bringup_panel(), gh_glcdc_programmed(), internal_tc_glcdc_bringup(), main(), mg_bringup_panel(), sfr_bringup_panel(), sh_panel_or_halt(), wc_panel_up(), wd_panel_up(), and wk_panel_up().

◆ display_init()

ra8_err_t display_init	(	const display_cfg_t *	cfg,
		display_handle_t **	out_handle )

nodiscard

Initialise the display PAL and bring the selected backend up to a state where display_flush succeeds.

Validates cfg, dispatches into the backend's init function (which on the LCD path runs the full GLCDC bring-up sequence: panel power-on, GLCDC pin/clock setup, settle delay, controller init, BG colour clear, start(true), layer1_show), then stores the resulting context inside the module-static handle and returns its address through out_handle.

Parameters

[in]	cfg	Backend + geometry descriptor (see struct).
[out]	out_handle	Filled with the PAL handle on success.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Backend ready; out_handle populated.
k_ra8_err_null_ptr	cfg / cfg->iface / cfg->framebuffer / out_handle NULL.
k_ra8_err_invalid_arg	Width / height / pixfmt rejected by backend.
k_ra8_err_busy	PAL already initialised; deinit first.
k_ra8_err_not_supported	Pixel format unsupported by chosen backend.

Precondition: Power to the underlying controller is on (true at reset).; The caller's framebuffer buffer is alive and aligned.

Postcondition: On success the handle is valid until display_deinit is called.; On any non-ok return out_handle is untouched.

Note: Not thread-safe; single-shot startup helper.

Since: 0.1.0

Definition at line 93 of file ra8_display_pal.c.

References display_cfg_t::iface, display_backend_iface::init, k_ra8_err_busy, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_log_error, ra8_log_info, s_handle, s_initialized, and s_tag.

Referenced by app_bringup_display(), app_bringup_panel(), cm_bringup_panel(), ez_bringup_panel(), gh_glcdc_programmed(), internal_tc_glcdc_bringup(), lcd_bringup_panel(), main(), mg_bringup_panel(), sfr_bringup_panel(), sh_panel_or_halt(), wc_panel_up(), wd_panel_up(), and wk_panel_up().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Layering

Framebuffer ownership

Refresh model

Typedef Documentation

◆ display_backend_iface_t

◆ display_handle_t

Enumeration Type Documentation

◆ display_pixfmt_t

◆ display_refresh_hint_t

Function Documentation

◆ display_clear()

◆ display_deinit()

◆ display_flush()

◆ display_full_rect()

◆ display_get_caps()

◆ display_get_framebuffer()

◆ display_init()