2D Drawing Engine (DRW / D/AVE 2D) HAL driver implementation More...

#include "ra8_drw.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_drw_internal.h"
#include "ra8_drw_regs.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_lpm.h"
#include "ra8_mstp.h"

Include dependency graph for ra8_drw.c:

Functions
bool	priv_ra8_drw_internal_rect_below_min (uint16_t min_dim, uint16_t width, uint16_t height)
	Pure rect-below-min predicate – see header for full contract.
bool	priv_ra8_drw_internal_rect_above_max (uint16_t max_w, uint16_t max_h, uint16_t width, uint16_t height)
	Pure rect-above-max predicate – see header for full contract.
uint32_t	priv_ra8_drw_internal_origin (void)
	Implementation of priv_ra8_drw_internal_origin() – shadow read.
uint32_t	priv_ra8_drw_internal_rect_origin (const ra8_drw_rect_t *rect)
	Framebuffer byte address of a rectangle's top-left pixel.
bool	priv_ra8_drw_internal_rect_off_surface (const ra8_drw_rect_t *rect)
	Reject a rectangle that would rasterize outside the framebuffer.
void	priv_ra8_drw_internal_color1_write (uint32_t argb8888)
	Implementation of priv_ra8_drw_internal_color1_write() – MMIO + shadow.
static uint32_t	internal_pack_writeformat (ra8_drw_writeformat_t fmt)
	Fold the three-bit WRITEFORMAT field into a 32-bit CONTROL2 value (WRITEFORMAT2 lives at bit 8, WRITEFORMAT[1:0] at bits 21:20).
static uint32_t	internal_pack_readformat (ra8_drw_readformat_t fmt)
	Pack a 4-bit READFORMAT value into CONTROL2.READFORMAT_H+L.
static uint32_t	internal_bytes_per_px (ra8_drw_writeformat_t fmt)
	Map a WRITEFORMAT code to its framebuffer pixel stride in bytes.
static uint32_t	internal_pack_surface_defaults (ra8_drw_writeformat_t fmt)
	Build the CONTROL2 value a plain solid-fill surface needs at init.
static uint32_t	internal_control2_rmw (uint32_t clear_mask, uint32_t set_mask)
	Read-modify-write a CONTROL2 mask; preserve unrelated bits.
void	priv_program_rect_bbox (const ra8_drw_rect_t *rect)
	Programme the bounding box that describes an axis-aligned rect.
static void	internal_drw_program_cache_options (const ra8_drw_config_t *cfg)
	Program the optional CACHECTL and DBWER features from the config.
ra8_err_t	ra8_drw_init (const ra8_drw_config_t *cfg)
	Power on the DRW block, install the supplied configuration, and arm the IRQ control register.
ra8_err_t	ra8_drw_deinit (void)
	Tear down the DRW block: disable IRQs, drop the registered callback, and request MSTP gate.
ra8_err_t	ra8_drw_get_status (uint32_t *out_mask)
	Read the DRW STATUS register into *out_mask.
ra8_err_t	ra8_drw_get_hwrevision (uint32_t *out)
	Read the read-only HWREVISION register into *out.
ra8_err_t	ra8_drw_clear_status (uint32_t mask)
	Acknowledge a subset of pending DRW interrupts via IRQCTL.
ra8_err_t	ra8_drw_set_irq_enables (uint32_t enable_mask)
	Set the IRQCTL enable bits (ENUMIRQEN, DLISTIRQEN, BUSIRQEN).
ra8_err_t	ra8_drw_attach_handler (ra8_drw_event_fn_t fn, void *ctx)
	Register a software callback for DRW IRQ events.
void	ra8_drw_dispatch (void)
	Snapshot STATUS, ack pending DRW IRQs, and fire callback.
ra8_err_t	ra8_drw_wait_idle (uint32_t poll_budget)
	Poll STATUS until all "busy" bits clear or budget runs out.
ra8_err_t	ra8_drw_enter_stop (void)
	Drop the DRW into MSTP-gated stop (clock removed).
ra8_err_t	ra8_drw_exit_stop (void)
	Re-enable the DRW MSTP gate (clock restored).
ra8_err_t	ra8_drw_reset (void)
	Software reset: drain pipeline, ack IRQs, reset PERFCOUNTers.
ra8_err_t	ra8_drw_cache_flush (bool flush_fb, bool flush_texture)
	Pulse FB and/or texture cache flush bits in CACHECTL.
ra8_err_t	ra8_drw_set_gradient (const ra8_drw_gradient_t *grad)
	Programme the COLOR1 and COLOR2 registers from a 2-stop gradient.
ra8_err_t	ra8_drw_set_pattern (uint8_t pattern_byte)
	Set the per-byte PATTERN bitmap (HUM Ch 62.2.9 p 3698).
ra8_err_t	ra8_drw_set_pattern_enable (bool enable, bool source_from_l5)
	Toggle CONTROL2.PATTERNENABLE / PATTERNSOURCEL5.
static uint32_t	internal_pack_blend_bits (const ra8_drw_blend_t *blend)
	Pack ra8_drw_blend_t into a CONTROL2 set-bit slab.
ra8_err_t	ra8_drw_set_blend (const ra8_drw_blend_t *blend)
	Configure the alpha-blend unit using ra8_drw_blend_t fields.
ra8_err_t	ra8_drw_set_color_key (uint32_t key_rgb, bool enable)
	Programme the COLKEY register and toggle COLKEYENABLE.
static uint32_t	internal_pack_texture_bits (const ra8_drw_texture_t *tex)
	Pack ra8_drw_texture_t into a CONTROL2 set-bit slab.
ra8_err_t	ra8_drw_set_texture (const ra8_drw_texture_t *tex)
	Programme TEXORIGIN, TEXPITCH, TEXMASK, U/V limiters and the CONTROL2 texture / CLUT / RLE / colour-key bits.
ra8_err_t	ra8_drw_clear_texture (void)
	Disable the texture unit (clear CONTROL2.TEXTUREENABLE / RLE / CLUT).
ra8_err_t	ra8_drw_load_clut (uint8_t start_index, const uint32_t *entries, uint32_t count)
	Load a CLUT entry pair (TEXCLADDR, TEXCLDATA, TEXCLOFFSET).

Variables
static const char *	s_tag = "DRW"
	Logging tag for the DRW driver.
static ra8_drw_event_fn_t	s_drw_fn
	Currently registered DRW event callback (or nullptr).
static void *	s_drw_ctx
	Opaque context paired with s_drw_fn.
static uint32_t	s_drw_origin
	Cached ORIGIN (framebuffer base) for the per-primitive render trigger.
static uint32_t	s_drw_control2
	Software shadow of the write-only CONTROL2 register.
static uint32_t	s_drw_color1
	Software shadow of the write-only COLOR1 register.
static uint32_t	s_drw_pitch_px
	Cached framebuffer pitch in pixels.
static uint32_t	s_drw_bytes_px
	Cached framebuffer bytes per pixel for the configured WRITEFORMAT.

Detailed Description

2D Drawing Engine (DRW / D/AVE 2D) HAL driver implementation

Tag: [Ring 3 / HAL] {World: NS}

Full RA8D2 D/AVE 2D driver. the expansion takes the driver from the original solid-fill MVP up to the complete HUM Ch 62 register surface: textured blits, CLUT loads, RLE-encoded source, per-pixel + global alpha blending, anti-aliased line / triangle, display-list mode, every IRQ source, performance counters and cache-flush hooks.

Every register access carries a HUM Ch 62 citation immediately above it so cite_check.py can validate provenance.

State Machine: <p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p>

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

Definition in file ra8_drw.c.

Function Documentation

◆ internal_bytes_per_px()

uint32_t internal_bytes_per_px ( ra8_drw_writeformat_t fmt )

inlinestatic

Map a WRITEFORMAT code to its framebuffer pixel stride in bytes.

HUM Ch 62.3.1.1 "Color Formats" p 3707 lists the framebuffer formats: A8 is 8 bpp, RGB565 and ARGB4444 are 16 bpp, ARGB8888 is 32 bpp. The stride is needed to advance ORIGIN to a rectangle's top-left pixel.

Parameters

[in] fmt One of ra8_drw_writeformat_t.

Returns: Bytes occupied by one framebuffer pixel (1, 2 or 4).

Return values

1	fmt is k_ra8_drw_writefmt_a8.
4	fmt is k_ra8_drw_writefmt_argb8888.
2	fmt is RGB565 or ARGB4444.

Precondition: fmt is one of the four documented WRITEFORMAT codes.; Caller uses the result only for framebuffer address arithmetic.

Postcondition: Returned value is non-zero.; No side effects.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 329 of file ra8_drw.c.

References k_ra8_drw_bytes_px_16bpp, k_ra8_drw_bytes_px_32bpp, k_ra8_drw_bytes_px_8bpp, k_ra8_drw_writefmt_a8, and k_ra8_drw_writefmt_argb8888.

Referenced by ra8_drw_init().

◆ internal_control2_rmw()

uint32_t internal_control2_rmw	(	uint32_t	clear_mask,
		uint32_t	set_mask )

inlinestatic

Read-modify-write a CONTROL2 mask; preserve unrelated bits.

Parameters

[in]	clear_mask	Bits to clear before applying set_mask.
[in]	set_mask	Bits to set after the clear.

Returns: Updated CONTROL2 value (also written back to the register).

Precondition: Driver initialized; CONTROL2 is reachable.; Caller must ensure no draw is in flight (CONTROL2 is latched at the start of an enumeration).

Postcondition: CONTROL2 = (old & ~clear_mask) | set_mask.; Other CONTROL2 fields preserved.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 405 of file ra8_drw.c.

References k_ra8_drw_off_control2, ra8_drw_reg32(), and s_drw_control2.

Referenced by ra8_drw_clear_texture(), ra8_drw_set_blend(), ra8_drw_set_color_key(), ra8_drw_set_pattern_enable(), and ra8_drw_set_texture().

◆ internal_drw_program_cache_options()

void internal_drw_program_cache_options ( const ra8_drw_config_t * cfg )

static

Program the optional CACHECTL and DBWER features from the config.

Applies the two boolean surface options that ra8_drw_init exposes: the DRW cache enable (CACHECTL) and the bufferable-write enable (DBWER). Both are all-or-nothing writes derived directly from the caller's config, split out so ra8_drw_init stays under the function-size threshold.

Parameters

[in] cfg Validated driver configuration (already null-checked).

Precondition: cfg is non-null (ra8_drw_init guarantees this).; The DRW clock is running (module-stop already cancelled).

Postcondition: CACHECTL reflects cfg->enable_caches.; DBWER reflects cfg->enable_buffered_writes.

Note: Internal helper, not thread-safe.

Since: 0.1.0

Definition at line 469 of file ra8_drw.c.

References ra8_drw_config_t::enable_buffered_writes, ra8_drw_config_t::enable_caches, k_ra8_drw_cachectl_all_en, k_ra8_drw_dbwer_bwe, k_ra8_drw_off_cachectl, k_ra8_drw_off_dbwer, and ra8_drw_reg32().

Referenced by ra8_drw_init().

◆ internal_pack_blend_bits()

uint32_t internal_pack_blend_bits ( const ra8_drw_blend_t * blend )

static

Pack ra8_drw_blend_t into a CONTROL2 set-bit slab.

HUM Ch 62.2.2 "CONTROL2: Surface Control Register" p 3691. Each field of blend maps to a single CONTROL2 bit; this helper just collects them so ra8_drw_set_blend stays under the function-size threshold.

Parameters

[in] blend Caller-supplied blend descriptor.

Returns: CONTROL2 set-bit slab.

Precondition: blend is non-null.

Postcondition: No side effects.

Note: Internal helper, not thread-safe.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.

Since: 0.1.0

Definition at line 769 of file ra8_drw.c.

Referenced by ra8_drw_set_blend().

◆ internal_pack_readformat()

uint32_t internal_pack_readformat ( ra8_drw_readformat_t fmt )

inlinestatic

Pack a 4-bit READFORMAT value into CONTROL2.READFORMAT_H+L.

Parameters

[in] fmt One of ra8_drw_readformat_t.

Returns: CONTROL2 word with the four READFORMAT bits set.

Precondition: fmt is in the documented set (0x0..0xC).; Caller OR-combines with the rest of CONTROL2.

Postcondition: Returned word touches only READFORMAT_L (18:19) and READFORMAT_H (4:5).; No side effects.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 298 of file ra8_drw.c.

References k_ra8_drw_control2_readformath_pos, and k_ra8_drw_control2_readformatl_pos.

Referenced by internal_pack_texture_bits().

◆ internal_pack_surface_defaults()

uint32_t internal_pack_surface_defaults ( ra8_drw_writeformat_t fmt )

inlinestatic

Build the CONTROL2 value a plain solid-fill surface needs at init.

Plain solid-fill mode: no texture, no pattern. Beyond the framebuffer pixel format two defaults matter and NEITHER is the reset value.

WRITEALPHA (bits 23:22, HUM Ch 62.2.2 p 3694) selects what reaches the framebuffer alpha byte. Its reset value 00 means "use alpha from COLOR2", and COLOR2 is 0 for a solid fill – so every filled pixel landed with alpha 0x00 on silicon (bench: a 0xFF00FF00 fill read back 0x0000FF00). Select 01, "use source alpha (pixel coverage)", which the bench shows is COLOR1's alpha scaled by coverage: an opaque fill lands 0xFF and a 0x80-alpha fill lands 0x80.

BDI (bit 12) forces the blend destination factor fD to 0 (HUM Ch 62.6.5.1 p 3733, Table 62.9 "SRC_ONE"). Without it the reset factors are fS = fD = 1, i.e. dst = src + dst – a fill would ADD to whatever the framebuffer already held rather than replace it. Bench-confirmed: filling 0xFF00FF00 over a 0x00000010 framebuffer produced 0xFF00FF10 without BDI and 0xFF00FF00 with it.

Parameters

[in] fmt Framebuffer pixel format from the caller's config.

Returns: CONTROL2 word to write and to seed the software shadow with.

Return values

(packed) WRITEFORMAT | WRITEALPHA=01 | BDI, all other fields zero.

Precondition: fmt is one of the four documented WRITEFORMAT codes.; Caller owns the CONTROL2 shadow and writes the result to both.

Postcondition: No side effects.; Texture, pattern, colour-key and alpha-channel-blend bits are clear.

Note: Pure; thread-safe.

See also: ra8_drw_set_blend Overwrites the blend bits, BDI included.

Since: 0.1.0

Definition at line 379 of file ra8_drw.c.

References internal_pack_writeformat(), k_ra8_drw_control2_bdi, k_ra8_drw_control2_writealpha_pos, and k_ra8_drw_writealpha_pixel_cov.

Referenced by ra8_drw_init().

◆ internal_pack_texture_bits()

uint32_t internal_pack_texture_bits ( const ra8_drw_texture_t * tex )

static

Pack ra8_drw_texture_t into a CONTROL2 set-bit slab.

HUM Ch 62.2.2 "CONTROL2: Surface Control Register" p 3691, including format, clamp/filter, CLUT, color-key and RLE bits.

Parameters

[in] tex Caller-supplied texture descriptor.

Returns: CONTROL2 set-bit slab.

Precondition: tex is non-null.

Postcondition: No side effects.

Note: Internal helper, not thread-safe.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.

Since: 0.1.0

Definition at line 868 of file ra8_drw.c.

Referenced by ra8_drw_set_texture().

◆ internal_pack_writeformat()

uint32_t internal_pack_writeformat ( ra8_drw_writeformat_t fmt )

inlinestatic

Fold the three-bit WRITEFORMAT field into a 32-bit CONTROL2 value (WRITEFORMAT2 lives at bit 8, WRITEFORMAT[1:0] at bits 21:20).

Parameters

[in] fmt One of ra8_drw_writeformat_t.

Returns: CONTROL2 word with format bits set, all other bits zero.

Precondition: fmt is one of the documented enum values (0..3).; Caller will OR additional CONTROL2 bits as needed.

Postcondition: Returned value has only the format bits set.; No side effects.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 270 of file ra8_drw.c.

References k_ra8_drw_control2_writeformat2_bit, and k_ra8_drw_control2_writeformat_pos.

Referenced by internal_pack_surface_defaults().

◆ priv_program_rect_bbox()

void priv_program_rect_bbox ( const ra8_drw_rect_t * rect )

Programme the bounding box that describes an axis-aligned rect.

Writes SIZE (HUM Ch 62.2.29 p 3704) and clears the six spatial limiters (HUM Ch 62.2.10-62.2.12 pp 3698-3699). An axis-aligned solid rectangle needs NO limiter: HUM Ch 62.6.2 p 3716 has the engine scan "the whole bounding box" anchored at ORIGIN, so the box scan already produces exactly the requested extent. Position comes from ORIGIN, which the caller writes last because that write is the render trigger (HUM Ch 62.2.31 p 3705).

Shared between ra8_drw.c and ra8_drw_draw.c so the solid-fill and the textured-blit primitive describe their extent identically.

Parameters

[in] rect Rectangle in pixel space (validated by caller).

Precondition: rect dimensions in [1..1024].; Driver initialized.

Postcondition: SIZE = (height << 16) | width.; L1..L4 START / XADD / YADD are all zero.

Note: Not thread-safe; writes MMIO.

Since: 0.1.0

Definition at line 416 of file ra8_drw.c.

References ra8_drw_rect_t::height_px, k_ra8_drw_off_l1start, k_ra8_drw_off_l1xadd, k_ra8_drw_off_l1yadd, k_ra8_drw_off_l2start, k_ra8_drw_off_l2xadd, k_ra8_drw_off_l2yadd, k_ra8_drw_off_l3start, k_ra8_drw_off_l3xadd, k_ra8_drw_off_l3yadd, k_ra8_drw_off_l4start, k_ra8_drw_off_l4xadd, k_ra8_drw_off_l4yadd, k_ra8_drw_off_size, k_ra8_drw_size_height_pos, ra8_drw_reg32(), and ra8_drw_rect_t::width_px.

Referenced by ra8_drw_blit_textured_rect(), and ra8_drw_fill_rect().

◆ priv_ra8_drw_internal_color1_write()

void priv_ra8_drw_internal_color1_write ( uint32_t argb8888 )

Implementation of priv_ra8_drw_internal_color1_write() – MMIO + shadow.

Write COLOR1 through the software shadow (write-only register).

Definition at line 238 of file ra8_drw.c.

References k_ra8_drw_off_color1, ra8_drw_reg32(), and s_drw_color1.

Referenced by ra8_drw_draw_line(), ra8_drw_draw_triangle(), ra8_drw_fill_rect(), ra8_drw_set_blend(), and ra8_drw_set_gradient().

◆ priv_ra8_drw_internal_origin()

uint32_t priv_ra8_drw_internal_origin ( void )

Implementation of priv_ra8_drw_internal_origin() – shadow read.

Read the cached ORIGIN (framebuffer base) render-trigger value.

Definition at line 212 of file ra8_drw.c.

References s_drw_origin.

Referenced by ra8_drw_draw_line(), and ra8_drw_draw_triangle().

◆ priv_ra8_drw_internal_rect_above_max()

bool priv_ra8_drw_internal_rect_above_max	(	uint16_t	max_w,
		uint16_t	max_h,
		uint16_t	width,
		uint16_t	height )

Pure rect-above-max predicate – see header for full contract.

Pure predicate for the "rect exceeds max dim" rejection.

Promoted helper so the line-780 OR can be driven under MC/DC.

Parameters

[in]	max_w	Maximum permitted width.
[in]	max_h	Maximum permitted height.
[in]	width	Width in pixels.
[in]	height	Height in pixels.

Returns: Boolean reject predicate.

Return values

true	Dimension above max.
false	Both within bounds.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on inputs.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 97 of file ra8_drw.c.

Referenced by ra8_drw_blit_textured_rect(), and ra8_drw_dlist_add_fill().

◆ priv_ra8_drw_internal_rect_below_min()

bool priv_ra8_drw_internal_rect_below_min	(	uint16_t	min_dim,
		uint16_t	width,
		uint16_t	height )

Pure rect-below-min predicate – see header for full contract.

Pure predicate for the "rect is below min dim" rejection.

Promoted helper so the line-776 OR can be driven under MC/DC.

Parameters

[in]	min_dim	Minimum permitted dimension (1 px).
[in]	width	Width in pixels.
[in]	height	Height in pixels.

Returns: Boolean reject predicate.

Return values

true	Dimension below min.
false	Both dimensions in range.

Precondition: None.; None.

Postcondition: No state mutated.; Return depends solely on inputs.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 75 of file ra8_drw.c.

Referenced by ra8_drw_blit_textured_rect(), and ra8_drw_dlist_add_fill().

◆ priv_ra8_drw_internal_rect_off_surface()

bool priv_ra8_drw_internal_rect_off_surface ( const ra8_drw_rect_t * rect )

Reject a rectangle that would rasterize outside the framebuffer.

With the bounding box positioned by ORIGIN there is no limiter clipping left to contain an out-of-range rectangle, so a negative origin or a right edge past the pitch would have the engine scribble over unrelated memory. Callers must reject before triggering a render.

Parameters

[in] rect Rectangle in pixel space.

Returns: Boolean reject predicate.

Return values

true	Caller must return `k_ra8_err_invalid_arg`.
false	The rect starts on the surface and fits the pitch.

Precondition: Driver initialized (pitch cached).; rect is non-null.

Postcondition: No state mutated.; Return depends only on rect and the cached pitch.

MC/DC:

Decision rect->x < 0 || rect->y < 0 (2 conditions), then the independent right > pitch test. N+1 = 3 vectors for the OR:

x>=0, y>=0 -> false (control)
x<0, y>=0 -> true (varies x)
x>=0, y<0 -> true (varies y)

Note: Not thread-safe; reads driver-private state.

Since: 0.1.0

Definition at line 225 of file ra8_drw.c.

References s_drw_pitch_px, ra8_drw_rect_t::width_px, ra8_drw_rect_t::x, and ra8_drw_rect_t::y.

Referenced by ra8_drw_blit_textured_rect(), ra8_drw_dlist_add_fill(), and ra8_drw_fill_rect().

◆ priv_ra8_drw_internal_rect_origin()

uint32_t priv_ra8_drw_internal_rect_origin ( const ra8_drw_rect_t * rect )

Framebuffer byte address of a rectangle's top-left pixel.

The engine scans its bounding box anchored at ORIGIN (HUM Ch 62.6.2 p 3716), so a primitive is positioned by pointing ORIGIN at its own top-left pixel rather than at the framebuffer base. Computes base + ((y * pitch) + x) * bytes_per_px from the geometry cached at ra8_drw_init.

Parameters

[in] rect Rectangle in pixel space (validated by caller).

Returns: Absolute byte address to write to ORIGIN.

Return values

base	The rect is at (0, 0).

Precondition: Driver initialized (pitch and pixel stride cached).; rect lies on the surface – see priv_ra8_drw_internal_rect_off_surface.

Postcondition: No state mutated.; Result is within the framebuffer for an on-surface rect.

Note: Pure with respect to hardware; reads driver-private state.

Since: 0.1.0

Definition at line 217 of file ra8_drw.c.

References s_drw_bytes_px, s_drw_origin, s_drw_pitch_px, ra8_drw_rect_t::x, and ra8_drw_rect_t::y.

Referenced by ra8_drw_blit_textured_rect(), ra8_drw_dlist_add_fill(), and ra8_drw_fill_rect().

◆ ra8_drw_attach_handler()

ra8_err_t ra8_drw_attach_handler	(	ra8_drw_event_fn_t	fn,
		void *	ctx )

nodiscard

Register a software callback for DRW IRQ events.

Parameters

[in]	fn	Callback function pointer (may be nullptr to detach the previously registered callback).
[in]	ctx	Opaque caller context, passed back as the first argument of fn.

Returns: ra8_err_t always k_ra8_ok.

Precondition: Caller owns ctx for the lifetime of the callback.; Either fn == nullptr (detach) or fn is callable.

Postcondition: Subsequent calls to ra8_drw_dispatch will invoke fn.; Previous callback (if any) is replaced atomically with respect to the dispatch path.

Note: Not interrupt-safe; install once at init.

See also: ra8_drw_dispatch

Since: 0.1.0

Definition at line 607 of file ra8_drw.c.

References k_ra8_ok, s_drw_ctx, and s_drw_fn.

◆ ra8_drw_cache_flush()

ra8_err_t ra8_drw_cache_flush	(	bool	flush_fb,
		bool	flush_texture )

nodiscard

Pulse FB and/or texture cache flush bits in CACHECTL.

Parameters

[in]	flush_fb	True to set CFLUSHFX (framebuffer flush).
[in]	flush_texture	True to set CFLUSHTX (texture flush).

Returns: ra8_err_t always k_ra8_ok.

Precondition: Driver has been initialized.; At least one of the booleans is true (no-op accepted but logged).

Postcondition: Selected cache(s) are flushed; enable bits are preserved.; No effect on geometry / blend state.

Since: 0.1.0

Definition at line 688 of file ra8_drw.c.

References k_ra8_drw_cachectl_cflushfx, k_ra8_drw_cachectl_cflushtx, k_ra8_drw_off_cachectl, k_ra8_ok, ra8_drw_reg32(), ra8_log_warn, and s_tag.

◆ ra8_drw_clear_status()

ra8_err_t ra8_drw_clear_status ( uint32_t mask )

nodiscard

Acknowledge a subset of pending DRW interrupts via IRQCTL.

Writes the supplied mask to IRQCTL (write-1-to-clear semantics for the *CLR bits). The mask should be one of the documented k_ra8_drw_irqctl_*_clr enum values; arbitrary other bits in the mask will set / clear the corresponding enable bits and the caller must be prepared for that.

Parameters

[in] mask IRQCTL bits to write (W1C for ENUMIRQCLR, DLISTIRQCLR, BUSIRQCLR).

Returns: ra8_err_t error code.

Return values

k_ra8_ok IRQCTL written.

Precondition: Driver has been initialized.; Caller's mask is constructed from documented bit enums.

Postcondition: Bits selected by mask have been pushed to IRQCTL.; No state outside DRW is touched.

Note: Thread-safe; the write is a single 32-bit store.

Since: 0.1.0

Definition at line 589 of file ra8_drw.c.

References k_ra8_drw_off_irqctl, k_ra8_ok, and ra8_drw_reg32().

◆ ra8_drw_clear_texture()

ra8_err_t ra8_drw_clear_texture ( void )

nodiscard

Disable the texture unit (clear CONTROL2.TEXTUREENABLE / RLE / CLUT).

Returns: ra8_err_t always k_ra8_ok.

Precondition: Driver has been initialized.; Caller drained any in-flight textured blit.

Postcondition: CONTROL2.{TEXTUREENABLE,RLEENABLE,CLUTENABLE,COLKEYENABLE} = 0.; Other CONTROL2 fields preserved.

Since: 0.1.0

Definition at line 938 of file ra8_drw.c.

References internal_control2_rmw(), k_ra8_drw_control2_clutenable, k_ra8_drw_control2_colkeyenable, k_ra8_drw_control2_rleenable, k_ra8_drw_control2_rlepixel_mask, k_ra8_drw_control2_textureenable, and k_ra8_ok.

◆ ra8_drw_deinit()

ra8_err_t ra8_drw_deinit ( void )

nodiscard

Tear down the DRW block: disable IRQs, drop the registered callback, and request MSTP gate.

Returns: ra8_err_t propagated from ra8_mstp_disable.

Return values

k_ra8_ok DRW powered down successfully.

Precondition: Driver was previously initialized (otherwise the disable is a no-op since ref count is already zero).; Caller holds single-threaded teardown context.

Postcondition: Registered callback (if any) has been cleared.; DRW peripheral is in MSTP-stop state.

Note: Not thread-safe.

See also: ra8_drw_init

Since: 0.1.0

Definition at line 545 of file ra8_drw.c.

References k_ra8_drw_irqctl_all_clr, k_ra8_drw_off_cachectl, k_ra8_drw_off_dbwer, k_ra8_drw_off_irqctl, k_ra8_mstp_drw, ra8_drw_reg32(), ra8_mstp_disable(), s_drw_bytes_px, s_drw_color1, s_drw_control2, s_drw_ctx, s_drw_fn, s_drw_origin, and s_drw_pitch_px.

◆ ra8_drw_dispatch()

void ra8_drw_dispatch ( void )

Snapshot STATUS, ack pending DRW IRQs, and fire callback.

Intended to be called from the DRW ISR (or from a host test). Reads STATUS, writes IRQCTL = all_clr to ack pending bits, then invokes the registered callback (if any) with the snapshot.

Precondition: Driver has been initialized.; Called from IRQ context or with IRQs masked.

Postcondition: All pending DRW IRQ flags acknowledged in IRQCTL.; Registered callback fired exactly once with the snapshot.

Note: Safe in IRQ context.

See also: ra8_drw_attach_handler

Since: 0.1.0

Definition at line 615 of file ra8_drw.c.

References k_ra8_drw_irqctl_all_clr, k_ra8_drw_off_irqctl, k_ra8_drw_off_status, ra8_drw_reg32(), s_drw_ctx, and s_drw_fn.

◆ ra8_drw_enter_stop()

ra8_err_t ra8_drw_enter_stop ( void )

nodiscard

Drop the DRW into MSTP-gated stop (clock removed).

Returns: ra8_err_t propagated from ra8_mstp_disable.

Return values

k_ra8_ok DRW gated.

Precondition: No DRW operation is in flight (caller drained the engine).; Caller holds single-threaded power transition lock.

Postcondition: DRW peripheral clock is disabled.; Registers retain their last-written value but cannot be accessed without first calling ra8_drw_exit_stop.

Note: Not thread-safe.

See also: ra8_drw_exit_stop

Since: 0.1.0

Definition at line 653 of file ra8_drw.c.

References k_ra8_drw_irqctl_all_clr, k_ra8_drw_off_irqctl, k_ra8_mstp_drw, ra8_drw_reg32(), and ra8_mstp_disable().

◆ ra8_drw_exit_stop()

ra8_err_t ra8_drw_exit_stop ( void )

nodiscard

Re-enable the DRW MSTP gate (clock restored).

Returns: ra8_err_t propagated from ra8_mstp_enable.

Return values

k_ra8_ok DRW running.

Precondition: Caller holds single-threaded power transition lock.; Previous ra8_drw_enter_stop happened (or this is first power-on; idempotent in that case).

Postcondition: DRW peripheral clock is enabled.; Caller may now read STATUS or issue further primitives.

Note: Not thread-safe.

See also: ra8_drw_enter_stop

Since: 0.1.0

Definition at line 662 of file ra8_drw.c.

References k_ra8_mstp_drw, and ra8_mstp_enable().

◆ ra8_drw_get_hwrevision()

ra8_err_t ra8_drw_get_hwrevision ( uint32_t * out )

nodiscard

Read the read-only HWREVISION register into *out.

Parameters

[out] out Receives HWREVISION (HUM Ch 62.2.6 p 3696). Decode via k_ra8_drw_hwrev_* masks.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	HWREVISION read.
k_ra8_err_null_ptr	out was nullptr.

Precondition: Driver has been initialized.; out non-null.

Postcondition: *out carries the alias-of-CONTROL2 HWREVISION value.; No DRW side effects.

Since: 0.1.0

Definition at line 581 of file ra8_drw.c.

References k_ra8_drw_off_hwrevision, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_drw_reg32(), and s_tag.

Referenced by demo_configure(), and drw_demo_configure().

◆ ra8_drw_get_status()

ra8_err_t ra8_drw_get_status ( uint32_t * out_mask )

nodiscard

Read the DRW STATUS register into *out_mask.

Parameters

[out] out_mask Receives the raw 32-bit STATUS value. Must be non-null. Bits decode via k_ra8_drw_status_*.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	STATUS read into *out_mask.
k_ra8_err_null_ptr	out_mask was nullptr.

Precondition: out_mask is non-null.; Driver has been initialized (peripheral clock running).

Postcondition: *out_mask reflects the latched STATUS bits at the time of the read.; No side effects on the DRW block (read is non-destructive).

Note: Thread-safe with respect to other read-only callers.

Since: 0.1.0

Definition at line 572 of file ra8_drw.c.

References k_ra8_drw_off_status, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_drw_reg32(), and s_tag.

Referenced by main().

◆ ra8_drw_init()

ra8_err_t ra8_drw_init ( const ra8_drw_config_t * cfg )

nodiscard

Power on the DRW block, install the supplied configuration, and arm the IRQ control register.

Sequence performed:

Ungate the DRW peripheral via ra8_mstp_enable(k_ra8_mstp_drw).
Mask + clear all DRW IRQs (write IRQCTL = all_clr).
Programme the framebuffer base address (ORIGIN), pitch (PITCH), and format (CONTROL2).
Enable framebuffer + texture caches if cfg->enable_caches.
Set DBWER.BWE if cfg->enable_buffered_writes.

Parameters

[in] cfg Pointer to the configuration. Must not be nullptr.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	DRW powered up + configured.
k_ra8_err_null_ptr	cfg was nullptr.
k_ra8_err_hw_init_failed	MSTP enable failed.

Precondition: cfg is non-null.; Caller holds single-threaded init context.

Postcondition: DRW is powered on, IRQs masked, ready for primitives.; ORIGIN, PITCH, and CONTROL2 reflect the supplied config.

Note: Not thread-safe; mask IRQs across the call.

See also: ra8_drw_deinit; ra8_drw_fill_rect

Since: 0.1.0

Definition at line 491 of file ra8_drw.c.

References ra8_drw_config_t::format, ra8_drw_config_t::framebuffer_addr, internal_bytes_per_px(), internal_drw_program_cache_options(), internal_pack_surface_defaults(), k_ra8_drw_irqctl_all_clr, k_ra8_drw_off_control2, k_ra8_drw_off_irqctl, k_ra8_drw_off_origin, k_ra8_drw_off_pitch, k_ra8_lpm_pd_timeout_default, k_ra8_mstp_drw, k_ra8_ok, ra8_drw_config_t::pitch_px, RA8_CHECK_NULL_PTR, ra8_drw_reg32(), ra8_log_info_val, ra8_lpm_graphics_power_on(), ra8_mstp_enable(), RA8_RETURN_ON_ERROR, s_drw_bytes_px, s_drw_color1, s_drw_control2, s_drw_origin, s_drw_pitch_px, and s_tag.

Referenced by demo_configure(), drw_blend_configure(), and drw_demo_configure().

◆ ra8_drw_load_clut()

ra8_err_t ra8_drw_load_clut	(	uint8_t	start_index,
		const uint32_t *	entries,
		uint32_t	count )

nodiscard

Load a CLUT entry pair (TEXCLADDR, TEXCLDATA, TEXCLOFFSET).

Walks the supplied entries array, writing TEXCLADDR with the starting CLUT index then streaming each ARGB8888 entry into TEXCLDATA. The DRW auto-increments CLADDR after each TEXCLDATA write (HUM Ch 62.5.4 p 3717).

Parameters

[in]	start_index	Index of the first CLUT slot to write [0..255].
[in]	entries	ARGB8888 entries to load (length = count).
[in]	count	Number of entries to write [1..256].

Returns: ra8_err_t error code.

Return values

k_ra8_ok	CLUT loaded.
k_ra8_err_null_ptr	entries was nullptr.
k_ra8_err_invalid_arg	start_index + count > 256, or count = 0.

Precondition: entries non-null.; count in [1, 256] and start_index + count <= 256.

Postcondition: All requested CLUT slots have been written.; TEXCLADDR points one past the last written index (auto-inc).

Since: 0.1.0

Definition at line 948 of file ra8_drw.c.

References k_ra8_drw_internal_clut_max, k_ra8_drw_off_texcladdr, k_ra8_drw_off_texcldata, k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_drw_reg32(), and s_tag.

◆ ra8_drw_reset()

ra8_err_t ra8_drw_reset ( void )

nodiscard

Software reset: drain pipeline, ack IRQs, reset PERFCOUNTers.

Returns: ra8_err_t always k_ra8_ok.

Precondition: Driver has been initialized.; Caller is OK with discarding pending draws.

Postcondition: All IRQ flags ack'd; PERFCOUNT1/2 zeroed.; CACHECTL flush bits pulsed.

Since: 0.1.0

Definition at line 667 of file ra8_drw.c.

References k_ra8_drw_cachectl_all_flush, k_ra8_drw_irqctl_all_clr, k_ra8_drw_off_cachectl, k_ra8_drw_off_irqctl, k_ra8_drw_off_perfcount1, k_ra8_drw_off_perfcount2, k_ra8_ok, and ra8_drw_reg32().

◆ ra8_drw_set_blend()

ra8_err_t ra8_drw_set_blend ( const ra8_drw_blend_t * blend )

nodiscard

Configure the alpha-blend unit using ra8_drw_blend_t fields.

Parameters

[in] blend Blend parameters. Must not be nullptr.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	CONTROL2 + COLOR1.A updated.
k_ra8_err_null_ptr	blend was nullptr.

Precondition: blend is non-null.; Driver has been initialized.

Postcondition: CONTROL2.{BSF,BDF,BSI,BDI,BSFA,BDFA,BSIA,BDIA,BC2,USEACB} reflect *blend; other CONTROL2 bits preserved.; COLOR1 alpha byte set to blend->global_alpha (other COLOR1 channels are NOT touched – caller controls the RGB triple via ra8_drw_set_gradient first).

Since: 0.1.0

Definition at line 805 of file ra8_drw.c.

References ra8_drw_blend_t::global_alpha, internal_control2_rmw(), internal_pack_blend_bits(), k_ra8_drw_color_a_pos, k_ra8_drw_control2_bc2, k_ra8_drw_control2_bdf, k_ra8_drw_control2_bdfa, k_ra8_drw_control2_bdi, k_ra8_drw_control2_bdia, k_ra8_drw_control2_bsf, k_ra8_drw_control2_bsfa, k_ra8_drw_control2_bsi, k_ra8_drw_control2_bsia, k_ra8_drw_control2_useacb, k_ra8_drw_internal_color_alpha_mask, k_ra8_ok, priv_ra8_drw_internal_color1_write(), RA8_CHECK_NULL_PTR, s_drw_color1, and s_tag.

Referenced by drw_blend_arm().

◆ ra8_drw_set_color_key()

ra8_err_t ra8_drw_set_color_key	(	uint32_t	key_rgb,
		bool	enable )

nodiscard

Programme the COLKEY register and toggle COLKEYENABLE.

Parameters

[in]	key_rgb	0x00RRGGBB colour key value (alpha bits ignored).
[in]	enable	True to set CONTROL2.COLKEYENABLE.

Returns: ra8_err_t always k_ra8_ok.

Precondition: Driver has been initialized.; Caller has chosen a key colour that does not occur in the source data when enable is true.

Postcondition: COLKEY = key_rgb (alpha cleared per HUM W=0 rule).; CONTROL2.COLKEYENABLE matches enable.

Since: 0.1.0

Definition at line 828 of file ra8_drw.c.

References internal_control2_rmw(), k_ra8_drw_control2_colkeyenable, k_ra8_drw_internal_color_alpha_mask, k_ra8_drw_off_colkey, k_ra8_ok, and ra8_drw_reg32().

◆ ra8_drw_set_gradient()

ra8_err_t ra8_drw_set_gradient ( const ra8_drw_gradient_t * grad )

nodiscard

Programme the COLOR1 and COLOR2 registers from a 2-stop gradient.

Parameters

[in] grad Pointer to the gradient. Must not be nullptr.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	COLOR1/COLOR2 updated.
k_ra8_err_null_ptr	grad was nullptr.

Precondition: grad is non-null.; Driver has been initialized.

Postcondition: COLOR1 = grad->color1_argb8888.; COLOR2 = grad->color2_argb8888.

Since: 0.1.0

Definition at line 713 of file ra8_drw.c.

References ra8_drw_gradient_t::color1_argb8888, ra8_drw_gradient_t::color2_argb8888, k_ra8_drw_off_color2, k_ra8_ok, priv_ra8_drw_internal_color1_write(), RA8_CHECK_NULL_PTR, ra8_drw_reg32(), and s_tag.

Referenced by drw_blend_arm().

◆ ra8_drw_set_irq_enables()

ra8_err_t ra8_drw_set_irq_enables ( uint32_t enable_mask )

nodiscard

Set the IRQCTL enable bits (ENUMIRQEN, DLISTIRQEN, BUSIRQEN).

Writes IRQCTL with the supplied combination of enable bits plus an unconditional W1C of every pending bit, so the caller cannot accidentally re-enable an interrupt while the corresponding flag is still latched.

Parameters

[in] enable_mask Bitwise OR of any of: k_ra8_drw_irqctl_enumirqen, k_ra8_drw_irqctl_dlistirqen, k_ra8_drw_irqctl_busirqen.

Returns: ra8_err_t error code.

Return values

k_ra8_ok IRQCTL updated.

Precondition: Driver has been initialized.; Only enable bits set; W1C bits will be ORed in by this call.

Postcondition: IRQCTL.{ENUM,DLIST,BUS}IRQEN match enable_mask.; All pending IRQ flags have been cleared.

Since: 0.1.0

Definition at line 597 of file ra8_drw.c.

References k_ra8_drw_irqctl_all_clr, k_ra8_drw_off_irqctl, k_ra8_ok, and ra8_drw_reg32().

◆ ra8_drw_set_pattern()

ra8_err_t ra8_drw_set_pattern ( uint8_t pattern_byte )

nodiscard

Set the per-byte PATTERN bitmap (HUM Ch 62.2.9 p 3698).

Parameters

[in] pattern_byte Pattern bitmap; only the low 8 bits used.

Returns: ra8_err_t always k_ra8_ok.

Precondition: Driver has been initialized.; Pattern source has been enabled via ra8_drw_set_pattern_enable.

Postcondition: PATTERN[7:0] = pattern_byte; upper bits zeroed (HUM W=0).; No effect on geometry / blend state.

Since: 0.1.0

Definition at line 723 of file ra8_drw.c.

References k_ra8_drw_internal_byte_mask, k_ra8_drw_off_pattern, k_ra8_ok, and ra8_drw_reg32().

◆ ra8_drw_set_pattern_enable()

ra8_err_t ra8_drw_set_pattern_enable	(	bool	enable,
		bool	source_from_l5 )

nodiscard

Toggle CONTROL2.PATTERNENABLE / PATTERNSOURCEL5.

Parameters

[in]	enable	True to set CONTROL2.PATTERNENABLE.
[in]	source_from_l5	True to set CONTROL2.PATTERNSOURCEL5.

Returns: ra8_err_t always k_ra8_ok.

Precondition: Driver has been initialized.; PATTERN already programmed if enable is true.

Postcondition: CONTROL2 reflects the requested pattern bits; other CONTROL2 fields preserved.; No effect on COLOR1/COLOR2.

Since: 0.1.0

Definition at line 732 of file ra8_drw.c.

References internal_control2_rmw(), k_ra8_drw_control2_patternenable, k_ra8_drw_control2_patternsourcel5, and k_ra8_ok.

◆ ra8_drw_set_texture()

ra8_err_t ra8_drw_set_texture ( const ra8_drw_texture_t * tex )

nodiscard

Programme TEXORIGIN, TEXPITCH, TEXMASK, U/V limiters and the CONTROL2 texture / CLUT / RLE / colour-key bits.

Parameters

[in] tex Texture descriptor. Must not be nullptr.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Texture programmed.
k_ra8_err_null_ptr	tex was nullptr.
k_ra8_err_invalid_arg	pitch_px > k_ra8_drw_max_texpitch_tx.

Precondition: tex non-null and points at validated descriptor.; Driver has been initialized.

Postcondition: TEXORIGIN, TEXPITCH, TEXMASK, U/V limiters, COLKEY (when enabled) all reflect *tex.; CONTROL2.{TEXTUREENABLE,TEXTURECLAMPX,TEXTURECLAMPY, TEXTUREFILTERX,TEXTUREFILTERY,READFORMAT,RLEENABLE, CLUTENABLE,CLUTFORMAT,COLKEYENABLE,RLEPIXELWIDTH} updated.

Since: 0.1.0

Definition at line 900 of file ra8_drw.c.

References ra8_drw_texture_t::base_addr, ra8_drw_texture_t::clut_offset, ra8_drw_texture_t::color_key_rgb, ra8_drw_texture_t::enable_color_key, internal_control2_rmw(), internal_pack_texture_bits(), k_ra8_drw_control2_clutenable, k_ra8_drw_control2_clutformat_565, k_ra8_drw_control2_colkeyenable, k_ra8_drw_control2_readformath_mask, k_ra8_drw_control2_readformatl_mask, k_ra8_drw_control2_rleenable, k_ra8_drw_control2_rlepixel_mask, k_ra8_drw_control2_textureclampx, k_ra8_drw_control2_textureclampy, k_ra8_drw_control2_textureenable, k_ra8_drw_control2_texturefilterx, k_ra8_drw_control2_texturefiltery, k_ra8_drw_internal_byte_mask, k_ra8_drw_internal_color_alpha_mask, k_ra8_drw_max_texpitch_tx, k_ra8_drw_off_colkey, k_ra8_drw_off_texcloffset, k_ra8_drw_off_texmask, k_ra8_drw_off_texorigin, k_ra8_drw_off_texpitch, k_ra8_err_invalid_arg, k_ra8_ok, ra8_drw_texture_t::pitch_px, RA8_CHECK_NULL_PTR, ra8_drw_reg32(), s_tag, ra8_drw_texture_t::u_mask, and ra8_drw_texture_t::v_mask.

◆ ra8_drw_wait_idle()

ra8_err_t ra8_drw_wait_idle ( uint32_t poll_budget )

nodiscard

Poll STATUS until all "busy" bits clear or budget runs out.

Bounded wait (NASA Rule 2). Returns k_ra8_err_hw_timeout if the engine remains busy after poll_budget reads.

Parameters

[in] poll_budget Maximum number of STATUS reads before timeout.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Engine idle.
k_ra8_err_hw_timeout	Budget exhausted.

Precondition: Driver has been initialized.; poll_budget >= 1.

Postcondition: On success, all of BUSYENUM / BUSYWRITE / DLISTACTIVE are 0.; On timeout, no register state is changed.

Since: 0.1.0

Definition at line 631 of file ra8_drw.c.

References k_ra8_drw_off_status, k_ra8_drw_status_busy_mask, k_ra8_err_hw_timeout, k_ra8_err_invalid_arg, k_ra8_ok, ra8_drw_reg32(), ra8_log_error, and s_tag.

Referenced by drw_blend_fill(), drw_demo_fill_and_check(), and main().

Variable Documentation

◆ s_drw_bytes_px

uint32_t s_drw_bytes_px

static

Cached framebuffer bytes per pixel for the configured WRITEFORMAT.

Note: Written by ra8_drw_init, cleared by ra8_drw_deinit.

Warning: Do not modify outside init/deinit – primitives only read it.

Since: 0.1.0

Definition at line 209 of file ra8_drw.c.

Referenced by priv_ra8_drw_internal_rect_origin(), ra8_drw_deinit(), and ra8_drw_init().

◆ s_drw_color1

uint32_t s_drw_color1

static

Software shadow of the write-only COLOR1 register.

COLOR1 is W-only like the rest of the DRW register file, so the alpha-preserving update in ra8_drw_set_blend cannot read it back from hardware. Every COLOR1 write goes through priv_ra8_drw_internal_color1_write, which keeps this shadow coherent.

Note: Updated on every COLOR1 write (gradient, blend, fill).

Warning: Never read COLOR1 from hardware; use this shadow.

Since: 0.1.0

Definition at line 182 of file ra8_drw.c.

Referenced by priv_ra8_drw_internal_color1_write(), ra8_drw_deinit(), ra8_drw_init(), and ra8_drw_set_blend().

◆ s_drw_control2

uint32_t s_drw_control2

static

Software shadow of the write-only CONTROL2 register.

Every CONTROL2 bit is W-only (HUM Ch 62.2.2, R/W column "W"), so a hardware read-modify-write returns undefined data on silicon. All CONTROL2 updates go through internal_control2_rmw, which modifies this shadow and writes the full value out.

Note: Seeded by ra8_drw_init with the packed WRITEFORMAT bits.

Warning: Never read CONTROL2 from hardware; use this shadow.

Since: 0.1.0

Definition at line 166 of file ra8_drw.c.

Referenced by internal_control2_rmw(), ra8_drw_deinit(), and ra8_drw_init().

◆ s_drw_ctx

void* s_drw_ctx

static

Opaque context paired with s_drw_fn.

Definition at line 134 of file ra8_drw.c.

Referenced by ra8_drw_attach_handler(), ra8_drw_deinit(), and ra8_drw_dispatch().

◆ s_drw_fn

ra8_drw_event_fn_t s_drw_fn

static

Currently registered DRW event callback (or nullptr).

Definition at line 128 of file ra8_drw.c.

Referenced by ra8_drw_attach_handler(), ra8_drw_deinit(), and ra8_drw_dispatch().

◆ s_drw_origin

uint32_t s_drw_origin

static

Cached ORIGIN (framebuffer base) for the per-primitive render trigger.

HUM Ch 62.2.31: writing ORIGIN triggers the start of rendering, so every geometry primitive must re-write it as its final step (the CONTROL write only selects the geometry mode). Cached at ra8_drw_init so the draw TU can issue the trigger without re-deriving the framebuffer address.

Note: Written by ra8_drw_init, cleared by ra8_drw_deinit.

Warning: Do not modify outside init/deinit – primitives only read it.

Since: 0.1.0

Definition at line 150 of file ra8_drw.c.

Referenced by priv_ra8_drw_internal_origin(), priv_ra8_drw_internal_rect_origin(), ra8_drw_deinit(), and ra8_drw_init().

◆ s_drw_pitch_px

uint32_t s_drw_pitch_px

static

Cached framebuffer pitch in pixels.

The engine scans the bounding box anchored at ORIGIN (HUM Ch 62.6.2 p 3716: "the 2D Drawing Engine scans the whole bounding box"), so every rectangle primitive has to advance ORIGIN to its own top-left pixel. That address is framebuffer + ((y * pitch) + x) * bytes_per_px, which needs the pitch and the pixel stride kept alongside the base.

Note: Written by ra8_drw_init, cleared by ra8_drw_deinit.

Warning: Do not modify outside init/deinit – primitives only read it.

Since: 0.1.0

Definition at line 199 of file ra8_drw.c.

Referenced by priv_ra8_drw_internal_rect_off_surface(), priv_ra8_drw_internal_rect_origin(), ra8_drw_deinit(), and ra8_drw_init().

◆ s_tag

const char* s_tag = "DRW"

static

Logging tag for the DRW driver.

TU-local read-only copy. ra8_drw_draw.c keeps its own identical copy so both TUs log under the same "DRW" tag without sharing linkage.

Note: Read-only after definition; do not reassign.

Warning: Direct modification breaks log correlation.

Since: 0.1.0

Definition at line 122 of file ra8_drw.c.

Functions

Variables

Detailed Description

Function Documentation

◆ internal_bytes_per_px()

◆ internal_control2_rmw()

◆ internal_drw_program_cache_options()

◆ internal_pack_blend_bits()

◆ internal_pack_readformat()

◆ internal_pack_surface_defaults()

◆ internal_pack_texture_bits()

◆ internal_pack_writeformat()

◆ priv_program_rect_bbox()

◆ priv_ra8_drw_internal_color1_write()

◆ priv_ra8_drw_internal_origin()

◆ priv_ra8_drw_internal_rect_above_max()

◆ priv_ra8_drw_internal_rect_below_min()

◆ priv_ra8_drw_internal_rect_off_surface()

◆ priv_ra8_drw_internal_rect_origin()

◆ ra8_drw_attach_handler()

◆ ra8_drw_cache_flush()

◆ ra8_drw_clear_status()

◆ ra8_drw_clear_texture()

◆ ra8_drw_deinit()

◆ ra8_drw_dispatch()

◆ ra8_drw_enter_stop()

◆ ra8_drw_exit_stop()

◆ ra8_drw_get_hwrevision()

◆ ra8_drw_get_status()

◆ ra8_drw_init()

◆ ra8_drw_load_clut()

◆ ra8_drw_reset()

◆ ra8_drw_set_blend()

◆ ra8_drw_set_color_key()

◆ ra8_drw_set_gradient()

◆ ra8_drw_set_irq_enables()

◆ ra8_drw_set_pattern()

◆ ra8_drw_set_pattern_enable()

◆ ra8_drw_set_texture()

◆ ra8_drw_wait_idle()

Variable Documentation

◆ s_drw_bytes_px

◆ s_drw_color1

◆ s_drw_control2

◆ s_drw_ctx

◆ s_drw_fn

◆ s_drw_origin

◆ s_drw_pitch_px

◆ s_tag