Display PAL dispatcher – forwards every public call into the bound backend's vtable. More...

#include "ra8_display_pal.h"
#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_display_pal_internal.h"
#include "ra8_err.h"
#include "ra8_log.h"

Include dependency graph for ra8_display_pal.c:

Functions
static ra8_err_t	internal_validate_handle (const display_handle_t *d)
	Reject d if it is NULL or refers to an un-initialised handle.
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.

Variables
static const char *const	s_tag = "ra8_display_pal"
	Module log tag.
static struct display_handle	s_handle
	Single PAL handle – one display per board.
static bool	s_initialized = false
	True once display_init has succeeded.

Detailed Description

Display PAL dispatcher – forwards every public call into the bound backend's vtable.

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

Owns one module-static display_handle and one s_initialized flag. The dispatcher does no hardware work itself; its only job is to validate arguments, dispatch through the iface, and refuse re-init while a handle is live.

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

Definition in file ra8_display_pal.c.

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().

◆ internal_validate_handle()

ra8_err_t internal_validate_handle ( const display_handle_t * d )

static

Reject d if it is NULL or refers to an un-initialised handle.

Every dispatch path runs this. Kept as a tiny inline so each caller stays well under the NASA P10 Rule 4 60-line cap.

Parameters

[in] d Candidate handle.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	d points at the live handle.
k_ra8_err_null_ptr	d was NULL.
k_ra8_err_invalid_arg	d did not match the live handle or no handle is initialised.

Precondition: None.; None.

Postcondition: No state mutated.; Returned value reflects the current init flag only.

Note: Thread-safe.

Since: 0.1.0

Definition at line 74 of file ra8_display_pal.c.

References k_ra8_err_invalid_arg, k_ra8_err_null_ptr, k_ra8_ok, s_handle, and s_initialized.

Referenced by display_clear(), display_deinit(), display_flush(), display_full_rect(), display_get_caps(), and display_get_framebuffer().

Variable Documentation

◆ s_handle

struct display_handle s_handle

static

Single PAL handle – one display per board.

Definition at line 39 of file ra8_display_pal.c.

Referenced by display_clear(), display_deinit(), display_flush(), display_full_rect(), display_get_caps(), display_get_framebuffer(), display_init(), and internal_validate_handle().

◆ s_initialized

bool s_initialized = false

static

True once display_init has succeeded.

Definition at line 42 of file ra8_display_pal.c.

Referenced by display_deinit(), display_init(), internal_aead_decrypt_check(), internal_aead_encrypt_check(), internal_session_validate_args(), internal_validate_handle(), ra8_dma_deinit(), ra8_dma_init(), ra8_dma_request(), ra8_mipi_dsi_deinit(), ra8_mipi_dsi_enter_stop(), ra8_mipi_dsi_exit_stop(), ra8_mipi_dsi_init(), ra8_nsc_periph_init(), ra8_power_profile_get_stats(), ra8_power_profile_init(), ra8_power_profile_mark_enter(), ra8_power_profile_mark_exit(), ra8_power_profile_reset_stats(), ra8_psa_crypto_deinit(), ra8_psa_crypto_init(), ra8_psa_crypto_random(), ra8_psa_hash_compute(), ra8_psa_key_destroy(), ra8_psa_key_import(), ra8_psa_sign_hash(), ra8_psa_verify_hash(), ra8_sram_deinit(), ra8_sram_init(), ra8_tls_get_cipher_suite(), ra8_tls_get_verify_result(), ra8_tls_global_deinit(), ra8_tls_global_init(), ra8_tls_handshake(), ra8_tls_recv(), ra8_tls_send(), and ra8_tls_session_close().

◆ s_tag

const char* const s_tag = "ra8_display_pal"

static

Module log tag.

Definition at line 36 of file ra8_display_pal.c.

Functions

Variables

Detailed Description

Function Documentation

◆ display_clear()

◆ display_deinit()

◆ display_flush()

◆ display_full_rect()

◆ display_get_caps()

◆ display_get_framebuffer()

◆ display_init()

◆ internal_validate_handle()

Variable Documentation

◆ s_handle

◆ s_initialized

◆ s_tag