ra8_drw.h File Reference

2D Drawing Engine (DRW / D/AVE 2D) HAL driver – public API More...

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

Include dependency graph for ra8_drw.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_drw_config_t
	Minimal DRW configuration captured by ra8_drw_init. More...
struct	ra8_drw_rect_t
	Rectangle parameters for ra8_drw_fill_rect. More...
struct	ra8_drw_blend_t
	Per-pixel + global alpha blending parameters. More...
struct	ra8_drw_texture_t
	Texture parameters for ra8_drw_blit_textured_rect. More...
struct	ra8_drw_line_t
	Anti-aliased line parameters. More...
struct	ra8_drw_triangle_t
	Anti-aliased filled triangle parameters. More...
struct	ra8_drw_gradient_t
	COLOR1 + COLOR2 two-stop gradient. More...
struct	ra8_drw_dlist_t
	Builder state for composing a DRW display list in a caller buffer. More...

Typedefs
typedef void(*	ra8_drw_event_fn_t) (void *ctx, uint32_t status_mask)
	DRW asynchronous event callback signature.

Functions
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.
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.
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).
ra8_err_t	ra8_drw_fill_rect (const ra8_drw_rect_t *rect)
	Issue a solid-fill rectangle blit into the framebuffer.
ra8_err_t	ra8_drw_blit_textured_rect (const ra8_drw_rect_t *rect)
	Blit a textured rectangle (texture must be programmed first).
ra8_err_t	ra8_drw_draw_line (const ra8_drw_line_t *line)
	Issue an anti-aliased line stroke between two points.
ra8_err_t	ra8_drw_draw_triangle (const ra8_drw_triangle_t *tri)
	Issue an anti-aliased filled triangle.
ra8_err_t	ra8_drw_run_dlist (const uint32_t *dlist_addr)
	Trigger execution of a display list.
ra8_err_t	ra8_drw_perf_arm (ra8_drw_perftrigger_t event_ctr1, ra8_drw_perftrigger_t event_ctr2)
	Programme PERFTRIGGER for the two performance counters and reset both PERFCOUNTk registers.
ra8_err_t	ra8_drw_perf_read (ra8_drw_perfcounter_id_t id, uint32_t *out)
	Read one PERFCOUNTk register.
ra8_err_t	ra8_drw_perf_reset (ra8_drw_perfcounter_id_t id)
	Reset one PERFCOUNTk register to zero.

Detailed Description

2D Drawing Engine (DRW / D/AVE 2D) HAL driver – public API

Tag

[Ring 3 / HAL] {World: NS}

Bare-metal driver for the RA8D2 2D drawing engine ("D/AVE 2D"). After the expansion the API now covers every register the HUM Ch 62 documents, every operating mode (solid fill, textured blit, RLE source, CLUT lookup, color key, alpha blend, anti- aliased line / triangle, display list) and every IRQ source (enum complete, dlist complete, bus error).

• Lifecycle: ra8_drw_init, ra8_drw_deinit, power transitions, MSTP gate.
• Diagnostics: ra8_drw_get_status, ra8_drw_clear_status, ra8_drw_get_hwrevision, ra8_drw_wait_idle.
• IRQ: ra8_drw_attach_handler, ra8_drw_dispatch, ra8_drw_set_irq_enables.
• Drawing: solid fill, textured blit, anti-aliased line, anti-aliased triangle, display list trigger.
• Surface: per-pixel + global alpha blending, color key, pattern, all six limiters with band post- process.
• Texture: base / pitch / U/V mask / clamp / filter, CLUT load, RLE source, ACLUT44 / I8 / etc.
• Performance: both PERFCOUNTk + PERFTRIGGER selector.
• Cache: explicit FB and texture flush hooks.

Copyright

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

Definition in file ra8_drw.h.

Typedef Documentation

ra8_drw_event_fn_t

typedef void(* ra8_drw_event_fn_t) (void *ctx, uint32_t status_mask)

DRW asynchronous event callback signature.

Fired from ra8_drw_dispatch after the DRW IRQ snapshots and acknowledges the STATUS register. The status_mask argument carries the raw STATUS value the dispatcher observed before clearing it; consumers test bits with the k_ra8_drw_status_* masks from ra8_drw_regs.h.

Definition at line 257 of file ra8_drw.h.

Function Documentation

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

ra8_err_t ra8_drw_blit_textured_rect ( const ra8_drw_rect_t * rect )

nodiscard

Blit a textured rectangle (texture must be programmed first).

The caller programmes the texture state via ra8_drw_set_texture (which also enables CONTROL2.TEXTUREENABLE). This function then writes the rectangle limiter set + SIZE and starts the engine via a write to CONTROL.

Parameters

[in]

rect

Destination rectangle. Must not be nullptr.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Blit issued.
k_ra8_err_null_ptr	rect was nullptr.
k_ra8_err_invalid_arg	width/height out of range.

Precondition

rect non-null and validated.

Texture state is programmed (CONTROL2.TEXTUREENABLE = 1).

Postcondition

DRW engine has accepted the textured rectangle.

CACHECTL pulsed to flush stale FB lines before consumption.

Since

0.1.0

Definition at line 98 of file ra8_drw_draw.c.

References ra8_drw_rect_t::height_px, k_ra8_drw_cachectl_cflushtx, k_ra8_drw_max_height_px, k_ra8_drw_max_width_px, k_ra8_drw_min_dim_px, k_ra8_drw_off_cachectl, k_ra8_drw_off_control, k_ra8_drw_off_lustart, k_ra8_drw_off_luxadd, k_ra8_drw_off_luyadd, k_ra8_drw_off_lvstartf, k_ra8_drw_off_lvstarti, k_ra8_drw_off_lvxaddi, k_ra8_drw_off_lvyaddi, k_ra8_drw_off_lvyxaddf, k_ra8_drw_off_origin, k_ra8_drw_subpixel_unit, k_ra8_err_invalid_arg, k_ra8_ok, priv_program_rect_bbox(), 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_CHECK_NULL_PTR, ra8_drw_reg32(), s_tag, and ra8_drw_rect_t::width_px.

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

ra8_err_t ra8_drw_draw_line ( const ra8_drw_line_t * line )

nodiscard

Issue an anti-aliased line stroke between two points.

Pre-computes the four perpendicular limiters bounding the stroke, programmes COLOR1, then enables LIM1..LIM4 with the standard intersect topology. HUM Ch 62.4.4 "Lines" p 3725.

Parameters

[in]

line

Line parameters. Must not be nullptr.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Line issued.
k_ra8_err_null_ptr	line was nullptr.
k_ra8_err_invalid_arg	width_px == 0 or > 1024.

Precondition

line non-null.

Driver is initialized.

Postcondition

DRW engine has accepted the line; STATUS may be busy.

COLOR1 holds line->color_argb8888.

Since

0.1.0

Definition at line 206 of file ra8_drw_draw.c.

References ra8_drw_line_t::color_argb8888, internal_program_line_limiters(), k_ra8_drw_cachectl_all_en, k_ra8_drw_cachectl_cflushfx, k_ra8_drw_control_line_quad, k_ra8_drw_max_width_px, k_ra8_drw_off_cachectl, k_ra8_drw_off_control, k_ra8_drw_off_origin, k_ra8_drw_off_size, k_ra8_drw_size_height_pos, k_ra8_err_invalid_arg, k_ra8_ok, priv_ra8_drw_internal_color1_write(), priv_ra8_drw_internal_origin(), RA8_CHECK_NULL_PTR, ra8_drw_reg32(), s_tag, ra8_drw_line_t::width_px, ra8_drw_line_t::x0, ra8_drw_line_t::x1, ra8_drw_line_t::y0, and ra8_drw_line_t::y1.

ra8_drw_draw_triangle()

ra8_err_t ra8_drw_draw_triangle ( const ra8_drw_triangle_t * tri )

nodiscard

Issue an anti-aliased filled triangle.

Computes the three edge limiters and writes CONTROL with LIM1..LIM3 enabled. HUM Ch 62.4.5 "Triangles" p 3726.

Parameters

[in]

tri

Triangle parameters. Must not be nullptr.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Triangle issued.
k_ra8_err_null_ptr	tri was nullptr.

Precondition

tri non-null.

Driver is initialized.

Postcondition

DRW engine has accepted the triangle.

COLOR1 holds tri->color_argb8888.

Since

0.1.0

Definition at line 245 of file ra8_drw_draw.c.

References ra8_drw_triangle_t::color_argb8888, internal_to_subpixel(), k_ra8_drw_cachectl_all_en, k_ra8_drw_cachectl_cflushfx, k_ra8_drw_control_triangle, k_ra8_drw_off_cachectl, k_ra8_drw_off_control, 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_origin, k_ra8_drw_off_size, k_ra8_drw_size_height_pos, k_ra8_ok, priv_ra8_drw_internal_color1_write(), priv_ra8_drw_internal_origin(), RA8_CHECK_NULL_PTR, ra8_drw_reg32(), s_tag, ra8_drw_triangle_t::x0, ra8_drw_triangle_t::x1, ra8_drw_triangle_t::x2, ra8_drw_triangle_t::y0, ra8_drw_triangle_t::y1, and ra8_drw_triangle_t::y2.

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

ra8_err_t ra8_drw_fill_rect ( const ra8_drw_rect_t * rect )

nodiscard

Issue a solid-fill rectangle blit into the framebuffer.

Programmes the DRW limiters to bound a rectangle, sets COLOR1 to the requested ARGB colour, then writes CONTROL with the four limiter-enable bits set to kick the engine.

Parameters

[in]

rect

Rectangle parameters. Must not be nullptr.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Blit issued (engine may still be busy).
k_ra8_err_null_ptr	rect was nullptr.
k_ra8_err_invalid_arg	width/height was 0 or > 1024.

Precondition

rect is non-null.

Driver is initialized; framebuffer ORIGIN is valid memory.

Postcondition

DRW engine has accepted the rectangle; STATUS may be busy.

Caller may follow with ra8_drw_get_status to wait on k_ra8_drw_status_busyenum to fall to 0.

Note

Not thread-safe with respect to other DRW operations.

See also

ra8_drw_get_status

Since

0.1.0

Definition at line 59 of file ra8_drw_draw.c.

References ra8_drw_rect_t::color_argb8888, ra8_drw_rect_t::height_px, k_ra8_drw_max_height_px, k_ra8_drw_max_width_px, k_ra8_drw_min_dim_px, k_ra8_drw_off_control, k_ra8_drw_off_origin, k_ra8_err_invalid_arg, k_ra8_ok, priv_program_rect_bbox(), priv_ra8_drw_internal_color1_write(), priv_ra8_drw_internal_rect_off_surface(), priv_ra8_drw_internal_rect_origin(), RA8_CHECK_NULL_PTR, ra8_drw_reg32(), s_tag, and ra8_drw_rect_t::width_px.

Referenced by drw_blend_fill(), and drw_demo_fill_and_check().

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:

1. Ungate the DRW peripheral via ra8_mstp_enable(k_ra8_mstp_drw).
2. Mask + clear all DRW IRQs (write IRQCTL = all_clr).
3. Programme the framebuffer base address (ORIGIN), pitch (PITCH), and format (CONTROL2).
4. Enable framebuffer + texture caches if cfg->enable_caches.
5. 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_perf_arm()

ra8_err_t ra8_drw_perf_arm ( ra8_drw_perftrigger_t event_ctr1, ra8_drw_perftrigger_t event_ctr2 )

nodiscard

Programme PERFTRIGGER for the two performance counters and reset both PERFCOUNTk registers.

Parameters

[in]	event_ctr1	Trigger event for PERFCOUNT1.
[in]	event_ctr2	Trigger event for PERFCOUNT2.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Counters armed.
k_ra8_err_invalid_arg	Either event > 0x1F.

Precondition

Driver has been initialized.

Each event in [0..0x1F]; "Setting prohibited" values rejected where they fall outside the documented set.

Postcondition

PERFTRIGGER carries both selectors; PERFCOUNT1 = PERFCOUNT2 = 0.

Counters begin incrementing on the next clock matching the selected event.

Since

0.1.0

Definition at line 496 of file ra8_drw_draw.c.

References k_ra8_drw_internal_perfev_max, k_ra8_drw_off_perfcount1, k_ra8_drw_off_perfcount2, k_ra8_drw_off_perftrigger, k_ra8_drw_perftrigger2_pos, k_ra8_err_invalid_arg, k_ra8_ok, and ra8_drw_reg32().

ra8_drw_perf_read()

ra8_err_t ra8_drw_perf_read ( ra8_drw_perfcounter_id_t id, uint32_t * out )

nodiscard

Read one PERFCOUNTk register.

Parameters

[in]	id	Counter identifier.
[out]	out	Receives the 32-bit count.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Count read.
k_ra8_err_null_ptr	out was nullptr.
k_ra8_err_invalid_arg	id outside enum.

Precondition

out non-null.

Driver has been initialized.

Postcondition

*out holds the snapshot.

No DRW side effects.

Since

0.1.0

Definition at line 515 of file ra8_drw_draw.c.

References k_ra8_drw_off_perfcount1, k_ra8_drw_off_perfcount2, k_ra8_drw_perfctr_1, k_ra8_drw_perfctr_2, k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_drw_reg32(), and s_tag.

ra8_drw_perf_reset()

ra8_err_t ra8_drw_perf_reset ( ra8_drw_perfcounter_id_t id )

nodiscard

Reset one PERFCOUNTk register to zero.

Parameters

[in]

id

Counter identifier.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Counter cleared.
k_ra8_err_invalid_arg	id outside enum.

Precondition

Driver has been initialized.

id is one of k_ra8_drw_perfctr_*.

Postcondition

PERFCOUNTid = 0.

No effect on the other counter.

Since

0.1.0

Definition at line 532 of file ra8_drw_draw.c.

References k_ra8_drw_off_perfcount1, k_ra8_drw_off_perfcount2, k_ra8_drw_perfctr_1, k_ra8_drw_perfctr_2, k_ra8_err_invalid_arg, k_ra8_ok, and ra8_drw_reg32().

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

ra8_err_t ra8_drw_run_dlist ( const uint32_t * dlist_addr )

nodiscard

Trigger execution of a display list.

Writes DLISTSTART with the supplied address. The DRW pulls one 32-bit word at a time from RAM and decodes it as (register index, value) pairs until it hits a terminator. HUM Ch 62.6 "Display List Mode" p 3724-3725.

Parameters

[in]

dlist_addr

Pointer to the first display-list word in memory; must be 4-byte aligned and reside in a region the DRW bus initiator can read.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Display list trigger written.
k_ra8_err_invalid_arg	Address null or unaligned.

Precondition

dlist_addr non-null and 4-byte aligned.

Driver is initialized; CACHECTL flushed if RAM was just written.

Postcondition

DLISTSTART = dlist_addr; engine begins fetching.

On completion the DLISTIRQ flag will be raised in STATUS.

Since

0.1.0

Definition at line 312 of file ra8_drw_draw.c.

References k_ra8_drw_cachectl_all_flush, k_ra8_drw_internal_align_mask, k_ra8_drw_off_cachectl, k_ra8_drw_off_dliststart, k_ra8_err_invalid_arg, k_ra8_ok, and ra8_drw_reg32().

Referenced by ra8_drw_dlist_run().

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