ra8_drw.c

Go to the documentation of this file.

 
#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"

bool priv_ra8_drw_internal_rect_below_min(uint16_t min_dim, uint16_t width, uint16_t height)
{
  return (width < min_dim) || (height < min_dim);
}

bool priv_ra8_drw_internal_rect_above_max(uint16_t max_w,
                                          uint16_t max_h,
                                          uint16_t width,
                                          uint16_t height)
{
  return (width > max_w) || (height > max_h);
}
 
/* =============================================================================
 * Driver-private state
 * =============================================================================
 */

static const char* s_tag = "DRW";

static ra8_drw_event_fn_t s_drw_fn;

static void* s_drw_ctx;

static uint32_t s_drw_origin;

static uint32_t s_drw_control2;

static uint32_t s_drw_color1;

static uint32_t s_drw_pitch_px;

static uint32_t s_drw_bytes_px;

uint32_t priv_ra8_drw_internal_origin(void)
{
  return s_drw_origin;
}
 
uint32_t priv_ra8_drw_internal_rect_origin(const ra8_drw_rect_t* rect)
{
  const uint32_t x   = (uint32_t)(int32_t)rect->x;
  const uint32_t y   = (uint32_t)(int32_t)rect->y;
  const uint32_t off = ((y * s_drw_pitch_px) + x) * s_drw_bytes_px;
  return s_drw_origin + off;
}
 
bool priv_ra8_drw_internal_rect_off_surface(const ra8_drw_rect_t* rect)
{
  bool off = false;
  if ((rect->x < 0) || (rect->y < 0)) {
    off = true;
  } else {
    const uint32_t right = (uint32_t)(int32_t)rect->x + (uint32_t)rect->width_px;
    off                  = (right > s_drw_pitch_px);
  }
  return off;
}

void priv_ra8_drw_internal_color1_write(uint32_t argb8888)
{
  /* HUM Ch 62.2.7 "COLOR1: Base Color Register", p 3697 */
  *ra8_drw_reg32(k_ra8_drw_off_color1) = argb8888;
  s_drw_color1                         = argb8888;
}
 
/* =============================================================================
 * Internal helpers
 * =============================================================================
 */

RA8_INTERNAL
static inline uint32_t internal_pack_writeformat(ra8_drw_writeformat_t fmt)
{
  const uint32_t low  = ((uint32_t)fmt & 0x3U) << k_ra8_drw_control2_writeformat_pos;
  uint32_t       high = 0UL;
  if (((uint32_t)fmt & 0x4UL) != 0UL) {
    high = k_ra8_drw_control2_writeformat2_bit;
  }
  return low | high;
}

RA8_INTERNAL
static inline uint32_t internal_pack_readformat(ra8_drw_readformat_t fmt)
{
  const uint32_t code = (uint32_t)fmt;
  const uint32_t lo   = (code & 0x3U) << k_ra8_drw_control2_readformatl_pos;
  const uint32_t hi   = ((code >> 2U) & 0x3U) << k_ra8_drw_control2_readformath_pos;
  return lo | hi;
}

RA8_INTERNAL
static inline uint32_t internal_bytes_per_px(ra8_drw_writeformat_t fmt)
{
  /* RGB565 / ARGB4444 default to 16 bpp; the two exclusive overrides below
   * pick 8 or 32 bpp when they match. */
  uint32_t bytes = (uint32_t)k_ra8_drw_bytes_px_16bpp;
  if (fmt == k_ra8_drw_writefmt_a8) {
    bytes = (uint32_t)k_ra8_drw_bytes_px_8bpp;
  }
  if (fmt == k_ra8_drw_writefmt_argb8888) {
    bytes = (uint32_t)k_ra8_drw_bytes_px_32bpp;
  }
  return bytes;
}

RA8_INTERNAL
static inline uint32_t internal_pack_surface_defaults(ra8_drw_writeformat_t fmt)
{
  return internal_pack_writeformat(fmt) |
         ((uint32_t)k_ra8_drw_writealpha_pixel_cov << k_ra8_drw_control2_writealpha_pos) |
         k_ra8_drw_control2_bdi;
}

RA8_INTERNAL
static inline uint32_t internal_control2_rmw(uint32_t clear_mask, uint32_t set_mask)
{
  /* CONTROL2 is write-only on silicon (HUM Ch 62.2.2, R/W column "W"), so the
   * read-modify-write MUST source the software shadow, never the register. */
  const uint32_t nxt = (s_drw_control2 & ~clear_mask) | set_mask;
  /* HUM Ch 62.2.2 "CONTROL2: Surface Control Register", p 3691 */
  *ra8_drw_reg32(k_ra8_drw_off_control2) = nxt;
  s_drw_control2                         = nxt;
  return nxt;
}
 
void priv_program_rect_bbox(const ra8_drw_rect_t* rect)
{
  /* HUM Ch 62.2.29 "SIZE: Bounding Box Dimension Register", p 3704 */
  /* The bounding box IS the rectangle: HUM Ch 62.6.2 p 3716 has the engine
   * scan "the whole bounding box" anchored at ORIGIN, so an axis-aligned
   * solid rectangle needs no spatial limiter at all -- the scan produces
   * exactly the requested extent. */
  *ra8_drw_reg32(k_ra8_drw_off_size) =
    ((uint32_t)rect->height_px << k_ra8_drw_size_height_pos) | (uint32_t)rect->width_px;
 
  /* HUM Ch 62.2.10 "LnSTART: Limiter n Start Value Register", p 3698 */
  /* Clear the six spatial limiters so a previous line/triangle primitive
   * cannot leak an edge into this box. CONTROL disables them, but leaving
   * live values behind makes a mis-set CONTROL fail silently instead of
   * loudly. */
  *ra8_drw_reg32(k_ra8_drw_off_l1start) = 0UL;
  *ra8_drw_reg32(k_ra8_drw_off_l2start) = 0UL;
  *ra8_drw_reg32(k_ra8_drw_off_l3start) = 0UL;
  *ra8_drw_reg32(k_ra8_drw_off_l4start) = 0UL;
 
  /* HUM Ch 62.2.11 "LnXADD: Limiter n X-Axis Increment Register", p 3698 */
  *ra8_drw_reg32(k_ra8_drw_off_l1xadd) = 0UL;
  *ra8_drw_reg32(k_ra8_drw_off_l2xadd) = 0UL;
  *ra8_drw_reg32(k_ra8_drw_off_l3xadd) = 0UL;
  *ra8_drw_reg32(k_ra8_drw_off_l4xadd) = 0UL;
 
  /* HUM Ch 62.2.12 "LnYADD: Limiter n Y-Axis Increment Register", p 3699 */
  *ra8_drw_reg32(k_ra8_drw_off_l1yadd) = 0UL;
  *ra8_drw_reg32(k_ra8_drw_off_l2yadd) = 0UL;
  *ra8_drw_reg32(k_ra8_drw_off_l3yadd) = 0UL;
  *ra8_drw_reg32(k_ra8_drw_off_l4yadd) = 0UL;
}

RA8_INTERNAL
static void internal_drw_program_cache_options(const ra8_drw_config_t* cfg)
{
  /* HUM Ch 62.2.4 "CACHECTL: Cache Control Register", p 3694 */
  if (cfg->enable_caches) {
    *ra8_drw_reg32(k_ra8_drw_off_cachectl) = k_ra8_drw_cachectl_all_en;
  } else {
    *ra8_drw_reg32(k_ra8_drw_off_cachectl) = 0UL;
  }
 
  /* HUM Ch 62.2.35 "DBWER: DRW Bufferable Write Enable", p 3707 */
  if (cfg->enable_buffered_writes) {
    *ra8_drw_reg32(k_ra8_drw_off_dbwer) = k_ra8_drw_dbwer_bwe;
  } else {
    *ra8_drw_reg32(k_ra8_drw_off_dbwer) = 0UL;
  }
}
 
/* =============================================================================
 * Lifecycle
 * =============================================================================
 */
 
[[nodiscard]] ra8_err_t ra8_drw_init(const ra8_drw_config_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg, s_tag, "cfg must not be nullptr");
 
  /* The DRW lives in the GRAPHICS POWER DOMAIN, which is gated OFF out of
   * reset (PDCTRGD = 0x81: PDPGSF = 1, PDDE = 1 -- HUM Ch 11.2.14 p 452;
   * domain contents in HUM Ch 11.5.1 Table 11.7 p 480). Cancelling
   * module-stop is NOT sufficient: with the domain dark every DRW register
   * reads 0 and every write is lost, which is exactly why the engine never
   * rasterised a pixel on silicon (#247) while ra8_emulator -- modelling no
   * power domain -- rendered happily. Power the domain first.
   * Bench evidence: HWREVISION reads 0x00000000 before this call and
   * 0x0FBE0107 after it. */
  const ra8_err_t pd_err = ra8_lpm_graphics_power_on((uint32_t)k_ra8_lpm_pd_timeout_default);
  /* GCOVR_EXCL_BR_START -- HW power-up ack */
  RA8_RETURN_ON_ERROR(pd_err, s_tag, "drw_init: graphics power");
  /* GCOVR_EXCL_BR_STOP */
 
  /* HUM Ch 11.2.8 "MSTPCRC: Module Stop Control Register C", p 446 */
  const ra8_err_t mst_err = ra8_mstp_enable(k_ra8_mstp_drw);
  /* GCOVR_EXCL_BR_START -- MSTP HW readback */
  RA8_RETURN_ON_ERROR(mst_err, s_tag, "drw_init: mstp enable");
  /* GCOVR_EXCL_BR_STOP */
 
  /* HUM Ch 62.2.3 "IRQCTL: Interrupt Control Register", p 3693 */
  /* Clear all pending IRQs and leave them masked. */
  *ra8_drw_reg32(k_ra8_drw_off_irqctl) = k_ra8_drw_irqctl_all_clr;
 
  /* HUM Ch 62.2.31 "ORIGIN: Framebuffer Base Address Register", p 3705 */
  /* Cache the framebuffer base: writing ORIGIN is the render TRIGGER, so
   * every primitive re-writes it as its final step (see ra8_drw_draw.c).
   * This init write fires a trigger too, but the limiters/SIZE are still
   * zero so no pixel is produced. */
  s_drw_origin                         = (uint32_t)cfg->framebuffer_addr;
  *ra8_drw_reg32(k_ra8_drw_off_origin) = s_drw_origin;
 
  s_drw_pitch_px = (uint32_t)cfg->pitch_px;
  s_drw_bytes_px = internal_bytes_per_px(cfg->format);
 
  /* HUM Ch 62.2.30 "PITCH: Framebuffer Pitch and Spanstore Delay
 * Register", p 3705. Spanstore delay (SSD) field [31:16] kept 0. */
  *ra8_drw_reg32(k_ra8_drw_off_pitch) = (uint32_t)cfg->pitch_px;
 
  /* HUM Ch 62.2.2 "CONTROL2: Surface Control Register", p 3690 */
  s_drw_control2                         = internal_pack_surface_defaults(cfg->format);
  *ra8_drw_reg32(k_ra8_drw_off_control2) = s_drw_control2;
  s_drw_color1                           = 0U;
 
  internal_drw_program_cache_options(cfg);
 
  ra8_log_info_val(s_tag, "drw_init fb", (uint32_t)cfg->framebuffer_addr);
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_drw_deinit(void)
{
  /* HUM Ch 62.2.3 "IRQCTL: Interrupt Control Register", p 3693 */
  /* Clear and disable every interrupt before dropping the clock. */
  *ra8_drw_reg32(k_ra8_drw_off_irqctl) = k_ra8_drw_irqctl_all_clr;
 
  /* HUM Ch 62.2.4 "CACHECTL: Cache Control Register", p 3694 */
  *ra8_drw_reg32(k_ra8_drw_off_cachectl) = 0UL;
 
  /* HUM Ch 62.2.35 "DBWER: DRW Bufferable Write Enable", p 3707 */
  *ra8_drw_reg32(k_ra8_drw_off_dbwer) = 0UL;
 
  s_drw_fn       = nullptr;
  s_drw_ctx      = nullptr;
  s_drw_origin   = 0U;
  s_drw_pitch_px = 0U;
  s_drw_bytes_px = 0U;
  s_drw_control2 = 0U;
  s_drw_color1   = 0U;
  return ra8_mstp_disable(k_ra8_mstp_drw);
}
 
/* =============================================================================
 * Status / IRQ
 * =============================================================================
 */
 
[[nodiscard]] ra8_err_t ra8_drw_get_status(uint32_t* out_mask)
{
  RA8_CHECK_NULL_PTR(out_mask, s_tag, "out_mask must not be nullptr");
  /* HUM Ch 62.2.5 "STATUS: Status Control Register", p 3695 */
  /* STATUS aliases CONTROL: a read returns engine status bits. */
  *out_mask = *ra8_drw_reg32(k_ra8_drw_off_status);
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_drw_get_hwrevision(uint32_t* out)
{
  RA8_CHECK_NULL_PTR(out, s_tag, "out must not be nullptr");
  /* HUM Ch 62.2.6 "HWREVISION: Hardware Revision Register", p 3696 */
  *out = *ra8_drw_reg32(k_ra8_drw_off_hwrevision);
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_drw_clear_status(uint32_t mask)
{
  /* HUM Ch 62.2.3 "IRQCTL: Interrupt Control Register", p 3693 */
  /* Write-1-to-clear semantics for ENUMIRQCLR/DLISTIRQCLR/BUSIRQCLR. */
  *ra8_drw_reg32(k_ra8_drw_off_irqctl) = mask;
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_drw_set_irq_enables(uint32_t enable_mask)
{
  /* HUM Ch 62.2.3 "IRQCTL: Interrupt Control Register", p 3693 */
  /* Combine caller's enable bits with an unconditional W1C of every
 * pending flag so we never re-enable while a stale flag is latched. */
  const uint32_t value                 = (enable_mask | k_ra8_drw_irqctl_all_clr);
  *ra8_drw_reg32(k_ra8_drw_off_irqctl) = value;
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_drw_attach_handler(ra8_drw_event_fn_t fn, void* ctx)
{
  s_drw_fn  = fn;
  s_drw_ctx = ctx;
  return k_ra8_ok;
}
 
RA8_ISR_SAFE
void ra8_drw_dispatch(void)
{
  /* HUM Ch 62.2.5 "STATUS: Status Control Register", p 3695 */
  const uint32_t status = *ra8_drw_reg32(k_ra8_drw_off_status);
 
  /* HUM Ch 62.2.3 "IRQCTL: Interrupt Control Register", p 3693 */
  /* Acknowledge all pending IRQ flags (write-1-to-clear). */
  *ra8_drw_reg32(k_ra8_drw_off_irqctl) = k_ra8_drw_irqctl_all_clr;
 
  const ra8_drw_event_fn_t fn  = s_drw_fn;
  void* const              ctx = s_drw_ctx;
  if (fn != nullptr) {
    fn(ctx, status);
  }
}
 
[[nodiscard]] ra8_err_t ra8_drw_wait_idle(uint32_t poll_budget)
{
  if (poll_budget == 0UL) {
    return k_ra8_err_invalid_arg;
  }
  /* NASA Rule 2: bounded loop. */
  for (uint32_t i = 0UL; i < poll_budget; ++i) {
    /* HUM Ch 62.2.5 "STATUS: Status Control Register", p 3695 */
    const uint32_t s = *ra8_drw_reg32(k_ra8_drw_off_status);
    if ((s & k_ra8_drw_status_busy_mask) == 0UL) {
      return k_ra8_ok;
    }
  }
  ra8_log_error(s_tag, "drw_wait_idle: timeout");
  return k_ra8_err_hw_timeout;
}
 
/* =============================================================================
 * Power transition
 * =============================================================================
 */
 
[[nodiscard]] ra8_err_t ra8_drw_enter_stop(void)
{
  /* HUM Ch 62.2.3 "IRQCTL: Interrupt Control Register", p 3693 */
  /* Quiesce IRQs before removing the clock, otherwise a pending bit
 * could latch and surprise us when we power back up. */
  *ra8_drw_reg32(k_ra8_drw_off_irqctl) = k_ra8_drw_irqctl_all_clr;
  return ra8_mstp_disable(k_ra8_mstp_drw);
}
 
[[nodiscard]] ra8_err_t ra8_drw_exit_stop(void)
{
  return ra8_mstp_enable(k_ra8_mstp_drw);
}
 
[[nodiscard]] ra8_err_t ra8_drw_reset(void)
{
  /* HUM Ch 62.2.3 "IRQCTL: Interrupt Control Register", p 3693 */
  *ra8_drw_reg32(k_ra8_drw_off_irqctl) = k_ra8_drw_irqctl_all_clr;
 
  /* HUM Ch 62.2.4 "CACHECTL: Cache Control Register", p 3694 */
  /* Pulse both cache flushes while preserving enable bits. */
  const uint32_t cur_cc                  = *ra8_drw_reg32(k_ra8_drw_off_cachectl);
  *ra8_drw_reg32(k_ra8_drw_off_cachectl) = cur_cc | k_ra8_drw_cachectl_all_flush;
 
  /* HUM Ch 62.2.34 "PERFCOUNTk: Performance Counter k", p 3706 */
  *ra8_drw_reg32(k_ra8_drw_off_perfcount1) = 0UL;
  *ra8_drw_reg32(k_ra8_drw_off_perfcount2) = 0UL;
  return k_ra8_ok;
}
 
/* =============================================================================
 * Cache control
 * =============================================================================
 */
 
[[nodiscard]] ra8_err_t ra8_drw_cache_flush(bool flush_fb, bool flush_texture)
{
  if (!flush_fb && !flush_texture) {
    ra8_log_warn(s_tag, "cache_flush: nothing to flush");
  } else {
    /* HUM Ch 62.2.4 "CACHECTL: Cache Control Register", p 3694 */
    /* Preserve enable bits, OR in the requested flush pulses. */
    const uint32_t cur = *ra8_drw_reg32(k_ra8_drw_off_cachectl);
    uint32_t       nxt = cur;
    if (flush_fb) {
      nxt |= k_ra8_drw_cachectl_cflushfx;
    }
    if (flush_texture) {
      nxt |= k_ra8_drw_cachectl_cflushtx;
    }
    *ra8_drw_reg32(k_ra8_drw_off_cachectl) = nxt;
  }
  return k_ra8_ok;
}
 
/* =============================================================================
 * Surface / blend / colour
 * =============================================================================
 */
 
[[nodiscard]] ra8_err_t ra8_drw_set_gradient(const ra8_drw_gradient_t* grad)
{
  RA8_CHECK_NULL_PTR(grad, s_tag, "grad must not be nullptr");
  /* COLOR1 goes through the shadowed writer (write-only register). */
  priv_ra8_drw_internal_color1_write(grad->color1_argb8888);
  /* HUM Ch 62.2.8 "COLOR2: Secondary Color Register", p 3697 */
  *ra8_drw_reg32(k_ra8_drw_off_color2) = grad->color2_argb8888;
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_drw_set_pattern(uint8_t pattern_byte)
{
  /* HUM Ch 62.2.9 "PATTERN: Pattern Register", p 3698 */
  /* Only PATTERN[7:0] is writable; bits 31:8 must be zero. */
  *ra8_drw_reg32(k_ra8_drw_off_pattern) =
    (uint32_t)pattern_byte & (uint32_t)k_ra8_drw_internal_byte_mask;
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_drw_set_pattern_enable(bool enable, bool source_from_l5)
{
  uint32_t set_bits = 0UL;
  if (enable) {
    set_bits |= k_ra8_drw_control2_patternenable;
  }
  if (source_from_l5) {
    set_bits |= k_ra8_drw_control2_patternsourcel5;
  }
  const uint32_t clr_mask = (k_ra8_drw_control2_patternenable | k_ra8_drw_control2_patternsourcel5);
  (void)internal_control2_rmw(clr_mask, set_bits);
  return k_ra8_ok;
}

RA8_INTERNAL
static uint32_t internal_pack_blend_bits(const ra8_drw_blend_t* blend)
{
  uint32_t set_bits = 0UL;
  if (blend->use_alpha_channel) {
    set_bits |= k_ra8_drw_control2_useacb;
  }
  if (blend->src_factor) {
    set_bits |= k_ra8_drw_control2_bsf;
  }
  if (blend->dst_factor) {
    set_bits |= k_ra8_drw_control2_bdf;
  }
  if (blend->src_invert) {
    set_bits |= k_ra8_drw_control2_bsi;
  }
  if (blend->dst_invert) {
    set_bits |= k_ra8_drw_control2_bdi;
  }
  if (blend->src_factor_alpha) {
    set_bits |= k_ra8_drw_control2_bsfa;
  }
  if (blend->dst_factor_alpha) {
    set_bits |= k_ra8_drw_control2_bdfa;
  }
  if (blend->src_invert_alpha) {
    set_bits |= k_ra8_drw_control2_bsia;
  }
  if (blend->dst_invert_alpha) {
    set_bits |= k_ra8_drw_control2_bdia;
  }
  if (blend->use_color2_dst) {
    set_bits |= k_ra8_drw_control2_bc2;
  }
  return set_bits;
}
 
[[nodiscard]] ra8_err_t ra8_drw_set_blend(const ra8_drw_blend_t* blend)
{
  RA8_CHECK_NULL_PTR(blend, s_tag, "blend must not be nullptr");
 
  /* HUM Ch 62.2.2 "CONTROL2: Surface Control Register", p 3691 */
  const uint32_t set_bits = internal_pack_blend_bits(blend);
  const uint32_t clr_mask =
    (k_ra8_drw_control2_useacb | k_ra8_drw_control2_bsf | k_ra8_drw_control2_bdf |
     k_ra8_drw_control2_bsi | k_ra8_drw_control2_bdi | k_ra8_drw_control2_bsfa |
     k_ra8_drw_control2_bdfa | k_ra8_drw_control2_bsia | k_ra8_drw_control2_bdia |
     k_ra8_drw_control2_bc2);
  (void)internal_control2_rmw(clr_mask, set_bits);
 
  /* Update only the alpha byte; preserve RGB to avoid surprise drift.
   * COLOR1 is write-only on silicon, so the current value comes from the
   * software shadow, and the write goes through the shadowed writer. */
  const uint32_t new_color1 = (s_drw_color1 & k_ra8_drw_internal_color_alpha_mask) |
                              ((uint32_t)blend->global_alpha << k_ra8_drw_color_a_pos);
  priv_ra8_drw_internal_color1_write(new_color1);
 
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_drw_set_color_key(uint32_t key_rgb, bool enable)
{
  /* HUM Ch 62.2.28 "COLKEY: Color Key Register", p 3704 */
  /* Bits 31:24 must be zero per the HUM table. */
  *ra8_drw_reg32(k_ra8_drw_off_colkey) = key_rgb & k_ra8_drw_internal_color_alpha_mask;
 
  uint32_t set_bits = 0UL;
  if (enable) {
    set_bits = k_ra8_drw_control2_colkeyenable;
  }
  (void)internal_control2_rmw(k_ra8_drw_control2_colkeyenable, set_bits);
  return k_ra8_ok;
}
 
/* =============================================================================
 * Texture
 * =============================================================================
 */

RA8_INTERNAL
static uint32_t internal_pack_texture_bits(const ra8_drw_texture_t* tex)
{
  uint32_t set_bits = k_ra8_drw_control2_textureenable;
  set_bits |= internal_pack_readformat(tex->format);
  if (tex->clamp_x) {
    set_bits |= k_ra8_drw_control2_textureclampx;
  }
  if (tex->clamp_y) {
    set_bits |= k_ra8_drw_control2_textureclampy;
  }
  if (tex->filter_x) {
    set_bits |= k_ra8_drw_control2_texturefilterx;
  }
  if (tex->filter_y) {
    set_bits |= k_ra8_drw_control2_texturefiltery;
  }
  if (tex->enable_clut) {
    set_bits |= k_ra8_drw_control2_clutenable;
  }
  if (tex->clut_565) {
    set_bits |= k_ra8_drw_control2_clutformat_565;
  }
  if (tex->enable_color_key) {
    set_bits |= k_ra8_drw_control2_colkeyenable;
  }
  if (tex->enable_rle) {
    set_bits |= k_ra8_drw_control2_rleenable;
  }
  set_bits |= ((uint32_t)tex->rle_pixel_width & 0x3U) << k_ra8_drw_control2_rlepixel_pos;
  return set_bits;
}
 
[[nodiscard]] ra8_err_t ra8_drw_set_texture(const ra8_drw_texture_t* tex)
{
  RA8_CHECK_NULL_PTR(tex, s_tag, "tex must not be nullptr");
  if ((uint16_t)tex->pitch_px > k_ra8_drw_max_texpitch_tx) {
    return k_ra8_err_invalid_arg;
  }
 
  /* HUM Ch 62.2.17 "TEXORIGIN: Texture Base Address Register", p 3700 */
  *ra8_drw_reg32(k_ra8_drw_off_texorigin) = (uint32_t)tex->base_addr;
 
  /* HUM Ch 62.2.15 "TEXPITCH: Texels Per Texture Line Register", p 3700 */
  *ra8_drw_reg32(k_ra8_drw_off_texpitch) = (uint32_t)tex->pitch_px;
 
  /* HUM Ch 62.2.16 "TEXMASK: Texture U/V Mask Register", p 3700.
 * U mask in [15:0], V mask in [31:16]. */
  *ra8_drw_reg32(k_ra8_drw_off_texmask) = ((uint32_t)tex->v_mask << 16U) | (uint32_t)tex->u_mask;
 
  /* HUM Ch 62.2.27 "TEXCLOFFSET: CLUT Offset Register", p 3704 */
  *ra8_drw_reg32(k_ra8_drw_off_texcloffset) =
    (uint32_t)tex->clut_offset & (uint32_t)k_ra8_drw_internal_byte_mask;
 
  const uint32_t set_bits = internal_pack_texture_bits(tex);
  const uint32_t clr_mask =
    (k_ra8_drw_control2_textureenable | k_ra8_drw_control2_textureclampx |
     k_ra8_drw_control2_textureclampy | k_ra8_drw_control2_texturefilterx |
     k_ra8_drw_control2_texturefiltery | k_ra8_drw_control2_clutenable |
     k_ra8_drw_control2_clutformat_565 | k_ra8_drw_control2_colkeyenable |
     k_ra8_drw_control2_rleenable | k_ra8_drw_control2_rlepixel_mask |
     k_ra8_drw_control2_readformatl_mask | k_ra8_drw_control2_readformath_mask);
  (void)internal_control2_rmw(clr_mask, set_bits);
 
  if (tex->enable_color_key) {
    /* HUM Ch 62.2.28 "COLKEY: Color Key Register", p 3704 */
    *ra8_drw_reg32(k_ra8_drw_off_colkey) = tex->color_key_rgb & k_ra8_drw_internal_color_alpha_mask;
  }
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_drw_clear_texture(void)
{
  const uint32_t clr_mask = (k_ra8_drw_control2_textureenable | k_ra8_drw_control2_rleenable |
                             k_ra8_drw_control2_clutenable | k_ra8_drw_control2_colkeyenable |
                             k_ra8_drw_control2_rlepixel_mask);
  (void)internal_control2_rmw(clr_mask, 0UL);
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t
ra8_drw_load_clut(uint8_t start_index, const uint32_t* entries, uint32_t count)
{
  RA8_CHECK_NULL_PTR(entries, s_tag, "entries must not be nullptr");
  if (count == 0UL) {
    return k_ra8_err_invalid_arg;
  }
  if (((uint32_t)start_index + count) > (uint32_t)k_ra8_drw_internal_clut_max) {
    return k_ra8_err_invalid_arg;
  }
 
  /* HUM Ch 62.2.25 "TEXCLADDR: CLUT Start Address Register", p 3703 */
  *ra8_drw_reg32(k_ra8_drw_off_texcladdr) = (uint32_t)start_index;
 
  /* HUM Ch 62.2.26 "TEXCLDATA: CLUT Data Register", p 3703 */
  /* The DRW auto-increments CLADDR after each TEXCLDATA write per
 * HUM Ch 62.5.4 "CLUT setup", p 3717. NASA Rule 2: bounded loop. */
  for (uint32_t i = 0UL; i < count; ++i) {
    *ra8_drw_reg32(k_ra8_drw_off_texcldata) = entries[i];
  }
  return k_ra8_ok;
}