Implementation of the e-ink page-turn refresh-cadence policy. More...

#include "ra8_display_pal_policy.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"

Include dependency graph for ra8_display_pal_policy.c:

Functions
static uint16_t	internal_clamp_clean_every (uint16_t n)
	Clamp a requested clean cadence to the documented bounds.
static void	internal_decide_fast_clean (display_policy_t p, display_turn_event_t event, display_policy_decision_t out)
	Resolve the k_display_policy_fast_clean decision for a non-open turn.
ra8_err_t	display_policy_init (display_policy_t *p, display_policy_kind_t kind, uint16_t clean_every)
	Initialise a refresh-cadence policy.
ra8_err_t	display_policy_decide (display_policy_t p, display_turn_event_t event, display_policy_decision_t out)
	Decide the flush parameters for one page-transition event.
ra8_err_t	display_policy_full_rect (uint16_t w, uint16_t h, display_rect_t *out)
	Build the full-page damage rectangle for a page turn.

Variables
static const char *const	s_tag_policy = "disp_policy"
	Log tag for the refresh-cadence policy module.

Detailed Description

Implementation of the e-ink page-turn refresh-cadence policy.

Pure decision logic (no MMIO/heap/I/O) implementing ra8_display_pal_policy.h. The application owns a display_policy_t, feeds page-transition events in, and applies the returned display_policy_decision_t through display_flush.

[Ring 4 / Display] {World: NS}

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

Since: 0.1.0

Definition in file ra8_display_pal_policy.c.

Function Documentation

◆ display_policy_decide()

ra8_err_t display_policy_decide	(	display_policy_t *	p,
		display_turn_event_t	event,
		display_policy_decision_t *	out )

nodiscard

Decide the flush parameters for one page-transition event.

k_display_event_open always yields a clean INIT full update and resets the counter (clears any boot ghosting).
k_display_policy_fast_only: A2 partial for every non-open event.
k_display_policy_quality: GC16 full for every event.
k_display_policy_fast_clean: a clean GC16 full when the turn is a clean turn – (turns_since_clean + 1 >= clean_every) OR event == chapter – else A2 partial. A clean turn resets the counter.

Parameters

[in,out]	p	Policy state (counter updated).
[in]	event	The page-transition that occurred.
[out]	out	Receives the waveform hint + full/partial extent.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Decision written.
k_ra8_err_null_ptr	`p` or `out` is NULL.
k_ra8_err_invalid_arg	`event` out of range.

Precondition: p was initialised by display_policy_init.; out points to writable storage.

Postcondition: On success out holds a valid hint and the counter reflects the event.; On failure neither p nor out is modified.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 131 of file ra8_display_pal_policy.c.

References display_policy_decision_t::full_update, display_policy_decision_t::hint, internal_decide_fast_clean(), k_display_event_chapter, k_display_event_open, k_display_policy_fast_clean, k_display_policy_fast_only, k_display_policy_quality, k_display_refresh_fast, k_display_refresh_init, k_display_refresh_quality, k_ra8_err_invalid_arg, k_ra8_ok, display_policy_t::kind, RA8_CHECK_NULL_PTR, ra8_log_error, s_tag_policy, and display_policy_t::turns_since_clean.

Referenced by er_flush_event().

◆ display_policy_full_rect()

ra8_err_t display_policy_full_rect	(	uint16_t	w,
		uint16_t	h,
		display_rect_t *	out )

nodiscard

Build the full-page damage rectangle for a page turn.

A page turn repaints the whole content area, so the partial-update rect is the full framebuffer. Apps that repaint only a sub-region (e.g. a status line) can build their own display_rect_t instead.

Parameters

[in]	w	Framebuffer width in pixels (> 0).
[in]	h	Framebuffer height in pixels (> 0).
[out]	out	Receives the {0,0,w,h} rectangle.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Rectangle written.
k_ra8_err_null_ptr	`out` is NULL.
k_ra8_err_invalid_arg	`w` or `h` is 0.

Precondition: out points to writable storage.; w and h are non-zero.

Postcondition: On success out == {0,0,w,h}.; On failure out is unmodified.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 167 of file ra8_display_pal_policy.c.

References display_rect_t::h, k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_log_error, s_tag_policy, display_rect_t::w, display_rect_t::x, and display_rect_t::y.

Referenced by er_flush_event().

◆ display_policy_init()

ra8_err_t display_policy_init	(	display_policy_t *	p,
		display_policy_kind_t	kind,
		uint16_t	clean_every )

nodiscard

Initialise a refresh-cadence policy.

Selects the strategy and (for k_display_policy_fast_clean) the clean cadence, then resets the turn counter. The policy is then driven one event at a time via display_policy_decide.

Parameters

[out]	p	Policy state to initialise.
[in]	kind	Strategy to run.
[in]	clean_every	GC16 cadence for k_display_policy_fast_clean; clamped to [min,max]; ignored by the other strategies.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Initialised.
k_ra8_err_null_ptr	`p` is NULL.
k_ra8_err_invalid_arg	`kind` out of range.

Precondition: p points to writable storage.; kind is a defined display_policy_kind_t.

Postcondition: On success turns_since_clean == 0 and the struct invariants hold.; On failure p is unmodified.

Note: Not thread-safe; the reader UI is single-threaded.

Since: 0.1.0

Definition at line 118 of file ra8_display_pal_policy.c.

References display_policy_t::clean_every, internal_clamp_clean_every(), k_display_policy_fast_clean, k_ra8_err_invalid_arg, k_ra8_ok, display_policy_t::kind, RA8_CHECK_NULL_PTR, ra8_log_error, s_tag_policy, and display_policy_t::turns_since_clean.

Referenced by main().

◆ internal_clamp_clean_every()

uint16_t internal_clamp_clean_every ( uint16_t n )

static

Clamp a requested clean cadence to the documented bounds.

Applies a symmetric min/max clamp to n using the constants k_display_policy_clean_every_min and k_display_policy_clean_every_max. Values below the floor are raised to the floor; values above the ceiling are lowered to the ceiling; in-range values are returned unchanged. The function is branchless-equivalent for the common in-range case.

Parameters

[in] n Requested cadence (fast turns between GC16 cleans).

Returns: uint16_t Clamped cadence in [k_display_policy_clean_every_min, k_display_policy_clean_every_max].

Return values

k_display_policy_clean_every_min	Returned when `n` is below the floor.
k_display_policy_clean_every_max	Returned when `n` exceeds the ceiling.
n	Returned unchanged when in range.

Precondition: n is a uint16_t (caller is responsible for providing a valid value).; k_display_policy_clean_every_min <= k_display_policy_clean_every_max.

Postcondition: The returned value is in [k_display_policy_clean_every_min, k_display_policy_clean_every_max].; The policy state is not modified (pure, side-effect-free).

Note: Not thread-safe; called only from display_policy_init which is single-threaded in the reader UI.

Since: 0.1.0

Definition at line 59 of file ra8_display_pal_policy.c.

References k_display_policy_clean_every_max, and k_display_policy_clean_every_min.

Referenced by display_policy_init().

◆ internal_decide_fast_clean()

void internal_decide_fast_clean	(	display_policy_t *	p,
		display_turn_event_t	event,
		display_policy_decision_t *	out )

static

Resolve the k_display_policy_fast_clean decision for a non-open turn.

A2 partial by default; a clean GC16 full when this turn is a "clean turn" – the MC/DC decision (turns_since_clean + 1 >= clean_every) || (event == chapter) – which also resets the counter. On a clean turn p->turns_since_clean is reset to zero and the full-update flag is set with k_display_refresh_quality; on a fast turn the counter is incremented by one and k_display_refresh_fast is selected with a partial update.

Parameters

[in,out]	p	Policy state (counter updated on every call).
[in]	event	The non-open page-transition (must not be k_display_event_open; caller is responsible).
[out]	out	Receives the waveform hint and full/partial extent.

Returns: Nothing.

Precondition: p was initialised by display_policy_init with k_display_policy_fast_clean as the kind.; out points to writable display_policy_decision_t storage.

Postcondition: On a clean turn p->turns_since_clean == 0 and out->hint == k_display_refresh_quality.; On a fast turn p->turns_since_clean is one greater than on entry and out->hint == k_display_refresh_fast.

Note: Not thread-safe; called only from display_policy_decide which is single-threaded in the reader UI.

Since: 0.1.0

Definition at line 101 of file ra8_display_pal_policy.c.

References display_policy_t::clean_every, display_policy_decision_t::full_update, display_policy_decision_t::hint, k_display_event_chapter, k_display_refresh_fast, k_display_refresh_quality, and display_policy_t::turns_since_clean.

Referenced by display_policy_decide().

Variable Documentation

◆ s_tag_policy

const char* const s_tag_policy = "disp_policy"

static

Log tag for the refresh-cadence policy module.

Definition at line 27 of file ra8_display_pal_policy.c.

Referenced by display_policy_decide(), display_policy_full_rect(), and display_policy_init().

Functions

Variables

Detailed Description

Function Documentation

◆ display_policy_decide()

◆ display_policy_full_rect()

◆ display_policy_init()

◆ internal_clamp_clean_every()

◆ internal_decide_fast_clean()

Variable Documentation

◆ s_tag_policy