ra8_dotf.c

Go to the documentation of this file.

 
#include "ra8_dotf.h"
 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_dotf_regs.h"
#include "ra8_err.h"
#include "ra8_hw_err.h"
#include "ra8_log.h"
#include "ra8_mstp.h"

typedef enum : uint8_t {
  k_ra8_dotf_no_region      = 0xFFU, 
  k_ra8_dotf_self_test_spin = 8U,    
} ra8_dotf_misc_t;

typedef enum : uint32_t {
  k_ra8_dotf_bswap_byte_mask = 0xFFUL,       
  k_ra8_dotf_bswap_byte0     = 0x000000FFUL, 
  k_ra8_dotf_bswap_byte1     = 0x0000FF00UL, 
  k_ra8_dotf_bswap_byte2     = 0x00FF0000UL, 
  k_ra8_dotf_bswap_byte3     = 0xFF000000UL, 
} ra8_dotf_bswap_const_t;

typedef enum : uint8_t {
  k_ra8_dotf_bswap_shift_byte = 8U,  
  k_ra8_dotf_bswap_shift_word = 24U, 
} ra8_dotf_bswap_shift_t;

typedef enum : uint8_t {
  k_ra8_dotf_key_words_128 = 4U, 
  k_ra8_dotf_key_words_192 = 6U, 
  k_ra8_dotf_key_words_256 = 8U, 
} ra8_dotf_key_word_count_t;

typedef struct {
  ra8_dotf_region_t     regions[k_ra8_dotf_max_regions];      
  uint8_t               region_valid[k_ra8_dotf_max_regions]; 
  uint8_t               active_region_id;                     
  ra8_dotf_key_handle_t key;                                  
  uint32_t              iv_cache[k_ra8_dotf_iv_word_count];   
  uint8_t               iv_valid;                             
  ra8_dotf_key_size_t   cached_key_size;                      
  ra8_dotf_sca_level_t  cached_sca;                           
  uint8_t               enabled;                              
} ra8_dotf_chan_state_t;

static const char* s_tag = "DOTF";

static ra8_dotf_event_fn_t s_dotf_fn;

static void* s_dotf_ctx;

static ra8_dotf_chan_state_t s_dotf_state[k_ra8_dotf_channel_count];

static const ra8_mstp_t s_dotf_mstp_table[k_ra8_dotf_channel_count] = {
  k_ra8_mstp_ospi0,
  k_ra8_mstp_ospi1,
};
 
/* =============================================================================
 * Internal helpers
 * =============================================================================
 */

RA8_INTERNAL
static inline bool internal_channel_in_range(uint8_t channel)
{
  return (uint16_t)channel < (uint16_t)k_ra8_dotf_channel_count;
}

RA8_INTERNAL
static inline uint32_t internal_window_lo(uint8_t channel)
{
  return (channel == 0U) ? k_ra8_dotf0_window_lo : k_ra8_dotf1_window_lo;
}

RA8_INTERNAL
static inline uint32_t internal_window_hi(uint8_t channel)
{
  return (channel == 0U) ? k_ra8_dotf0_window_hi : k_ra8_dotf1_window_hi;
}

RA8_INTERNAL
static inline uint8_t internal_key_words(ra8_dotf_key_size_t size)
{
  if (size == k_ra8_dotf_key_size_192) {
    return k_ra8_dotf_key_words_192;
  }
  if (size == k_ra8_dotf_key_size_256) {
    return k_ra8_dotf_key_words_256;
  }
  return k_ra8_dotf_key_words_128;
}

RA8_INTERNAL
static inline uint32_t internal_sca_bits(ra8_dotf_sca_level_t level)
{
  if (level == k_ra8_dotf_sca_max) {
    return k_ra8_dotf_reg00_sca_en | k_ra8_dotf_reg00_sca_mode;
  }
  if (level == k_ra8_dotf_sca_standard) {
    return k_ra8_dotf_reg00_sca_en;
  }
  return 0U;
}

RA8_INTERNAL
static inline uint32_t internal_bswap32(uint32_t v)
{
  return ((v & k_ra8_dotf_bswap_byte0) << (uint32_t)k_ra8_dotf_bswap_shift_word) |
         ((v & k_ra8_dotf_bswap_byte1) << (uint32_t)k_ra8_dotf_bswap_shift_byte) |
         ((v & k_ra8_dotf_bswap_byte2) >> (uint32_t)k_ra8_dotf_bswap_shift_byte) |
         ((v & k_ra8_dotf_bswap_byte3) >> (uint32_t)k_ra8_dotf_bswap_shift_word);
}

RA8_INTERNAL
static ra8_err_t internal_validate_region(uint8_t channel, const ra8_dotf_region_t* region)
{
  if ((region->start_addr & k_ra8_dotf_addr_low_mask) != 0U) {
    return k_ra8_err_invalid_arg;
  }
  if ((region->end_addr & k_ra8_dotf_addr_low_mask) != 0U) {
    return k_ra8_err_invalid_arg;
  }
  if (region->start_addr > region->end_addr) {
    /* HUM Ch 45.3.1 p 3049: "Setting CONVAREAST[31:12] >
     * CONVAREAED[31:12] is prohibited." */
    return k_ra8_err_invalid_arg;
  }
  if (region->region_id >= k_ra8_dotf_max_regions) {
    return k_ra8_err_invalid_arg;
  }
  const uint32_t lo = internal_window_lo(channel);
  const uint32_t hi = internal_window_hi(channel);
  if ((region->start_addr < lo) || (region->end_addr > hi)) {
    /* HUM Ch 45.3 p 3049 ("Image of decryption area setting"):
     * conversion area must lie inside the matching XSPI window. */
    return k_ra8_err_invalid_arg;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_check_overlap(uint8_t channel, const ra8_dotf_region_t* region)
{
  for (uint8_t other = 0U; other < k_ra8_dotf_channel_count; ++other) {
    if (other == channel) {
      continue;
    }
    const ra8_dotf_chan_state_t* st = &s_dotf_state[other];
    if (st->active_region_id == k_ra8_dotf_no_region) {
      continue;
    }
    const ra8_dotf_region_t* live = &st->regions[st->active_region_id];
    /* Ranges overlap if: start_a <= end_b && start_b <= end_a. */
    /* mcdc-deactivated: ra8_dotf overlap-detection AND; the four DOTF channels are bound to disjoint XSPI windows by HUM 45.1, and ra8_dotf_set_region rejects regions outside the per-channel window upstream. As a result the cross-channel overlap helper is only entered for region pairs that the HUM windows make non-overlapping by construction -- the AND's two inequalities are co-dependent and cannot independently flip on any reachable input. */
    if ((region->start_addr <= live->end_addr) && (live->start_addr <= region->end_addr)) {
      return k_ra8_err_conflict;
    }
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static uint32_t internal_assemble_reg00(const ra8_dotf_chan_state_t* st, bool enable)
{
  uint32_t v = k_ra8_dotf_reg00_mode_ctr; /* HUM 45.1 mode = CTR. */
  v |= (uint32_t)st->cached_key_size;     /* Key size bits.       */
  v |= internal_sca_bits(st->cached_sca); /* SCA bits.            */
  if (enable) {
    v |= k_ra8_dotf_reg00_aes_enable;
  }
  return v;
}

RA8_INTERNAL
static void internal_stage_key(volatile ra8_dotf_regs_t* reg, const ra8_dotf_key_handle_t* h)
{
  const uint8_t words = internal_key_words(h->size);
  for (uint8_t i = 0U; i < words; ++i) {
    /* HUM Ch 45.3 "Register Descriptions" p 3049: REG03 is the AES
     * IV staging window; the FSP reference re-uses it for wrapped-key
     * delivery via the OutputKeyForDotf adaptor. Big-endian per
     * ``r_ospi_b.c``. */
    reg->REG03 = internal_bswap32(h->words[i]);
  }
}

RA8_INTERNAL
static void internal_stage_iv(volatile ra8_dotf_regs_t* reg, const uint32_t* iv)
{
  for (uint8_t i = 0U; i < k_ra8_dotf_iv_word_count; ++i) {
    /* HUM Ch 45.1 p 3048 -- counter = {IV[127:28], Address[31:4]}.
     * REG03 is the AES IV staging window per HUM Ch 45.3 "Register
     * Descriptions" p 3049. */
    reg->REG03 = internal_bswap32(iv[i]);
  }
}

RA8_INTERNAL
static inline void internal_channel_reset(volatile ra8_dotf_regs_t* reg)
{
  /* HUM Ch 45.3.1 "CONVAREAST : DOTF Conversion Area Start Address Register" p 3049 */
  reg->CONVAREAST = 0U;
  /* HUM Ch 45.3.2 "CONVAREAD : DOTF Conversion Area End Address Register" p 3049 */
  reg->CONVAREAD = 0U;
  /* REG00 holds the AES core enable + mode select.
   * HUM Ch 45.3 "Register Descriptions" p 3049 */
  reg->REG00 = k_ra8_dotf_reg00_disable_value;
}

RA8_INTERNAL
static void internal_state_reset(uint8_t channel)
{
  ra8_dotf_chan_state_t* st = &s_dotf_state[channel];
  for (uint8_t i = 0U; i < k_ra8_dotf_max_regions; ++i) {
    st->region_valid[i]       = 0U;
    st->regions[i].start_addr = 0U;
    st->regions[i].end_addr   = 0U;
    st->regions[i].key_index  = 0U;
    st->regions[i].region_id  = 0U;
  }
  st->active_region_id = k_ra8_dotf_no_region;
  st->key.size         = k_ra8_dotf_key_size_128;
  st->key.key_index    = 0U;
  st->key.valid        = 0U;
  for (uint8_t i = 0U; i < 8U; ++i) {
    st->key.words[i] = 0U;
  }
  for (uint8_t i = 0U; i < k_ra8_dotf_iv_word_count; ++i) {
    st->iv_cache[i] = 0U;
  }
  st->iv_valid        = 0U;
  st->cached_key_size = k_ra8_dotf_key_size_128;
  st->cached_sca      = k_ra8_dotf_sca_standard;
  st->enabled         = 0U;
}
 
/* =============================================================================
 * Lifecycle
 * =============================================================================
 */
 
[[nodiscard]] ra8_err_t ra8_dotf_init(void)
{
  for (uint8_t ch = 0U; ch < k_ra8_dotf_channel_count; ++ch) {
    /* DOTF clock gating: shared MSTPB16/17 with the matching XSPI.
     * HUM Ch 45.6.1 "Module-stop Function" p 3050 */
    const ra8_err_t mst_err = ra8_mstp_enable(s_dotf_mstp_table[ch]);
    RA8_RETURN_ON_ERROR(mst_err, s_tag, "dotf_init: mstp enable failed");
 
    volatile ra8_dotf_regs_t* reg = ra8_dotf_regs(ch);
    if (reg == nullptr) { /* GCOVR_EXCL_BR_LINE -- loop proves ch<2; accessor nulls only ch>=2 */
      return k_ra8_err_hw_init_failed; /* GCOVR_EXCL_LINE -- same bounded-channel accessor invariant */
    }
    internal_channel_reset(reg);
    internal_state_reset(ch);
  }
  s_dotf_fn  = nullptr;
  s_dotf_ctx = nullptr;
  ra8_log_info(s_tag, "dotf_init");
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_dotf_deinit(void)
{
  for (uint8_t ch = 0U; ch < k_ra8_dotf_channel_count; ++ch) {
    volatile ra8_dotf_regs_t* reg = ra8_dotf_regs(ch);
    if (reg != nullptr) {
      /* Force bypass on teardown.
       * HUM Ch 45.3 "Register Descriptions" p 3049 */
      reg->REG00 = k_ra8_dotf_reg00_disable_value;
    }
    internal_state_reset(ch);
    /* Gate the shared OSPI/DOTF clock.
     * HUM Ch 45.6.1 "Module-stop Function" p 3050 */
    (void)ra8_mstp_disable(s_dotf_mstp_table[ch]);
  }
  s_dotf_fn  = nullptr;
  s_dotf_ctx = nullptr;
  return k_ra8_ok;
}
 
/* =============================================================================
 * Region staging
 * =============================================================================
 */
 
[[nodiscard]] ra8_err_t ra8_dotf_set_region(uint8_t channel, const ra8_dotf_region_t* region)
{
  RA8_CHECK_NULL_PTR(region, s_tag, "region must not be nullptr");
  if (!internal_channel_in_range(channel)) {
    return k_ra8_err_invalid_arg;
  }
  const ra8_err_t verr = internal_validate_region(channel, region);
  if (verr != k_ra8_ok) {
    return verr;
  }
  const ra8_err_t cerr = internal_check_overlap(channel, region);
  if (cerr != k_ra8_ok) {
    ra8_log_warn_val(s_tag, "set_region overlaps other channel", (uint32_t)channel);
    return cerr;
  }
  ra8_dotf_chan_state_t* st           = &s_dotf_state[channel];
  st->regions[region->region_id]      = *region;
  st->region_valid[region->region_id] = 1U;
  ra8_log_info_val(s_tag, "set_region staged channel", (uint32_t)channel);
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_dotf_select_region(uint8_t channel, uint8_t region_id)
{
  if (!internal_channel_in_range(channel)) {
    return k_ra8_err_invalid_arg;
  }
  if (region_id >= k_ra8_dotf_max_regions) {
    return k_ra8_err_invalid_arg;
  }
  ra8_dotf_chan_state_t* st = &s_dotf_state[channel];
  if (st->region_valid[region_id] == 0U) {
    return k_ra8_err_invalid_state;
  }
  volatile ra8_dotf_regs_t* reg = ra8_dotf_regs(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel mapping failed");
 
  const ra8_dotf_region_t* r = &st->regions[region_id];
  /* FSP r_ospi_b.c "Set the end and start area for DOTF
   * conversion in that order to ensure that end address is always
   * higher than start address."
   * HUM Ch 45.3.2 "CONVAREAD : DOTF Conversion Area End Address Register" p 3049 */
  reg->CONVAREAD = r->end_addr & k_ra8_dotf_addr_mask;
  /* HUM Ch 45.3.1 "CONVAREAST : DOTF Conversion Area Start Address Register" p 3049 */
  reg->CONVAREAST      = r->start_addr & k_ra8_dotf_addr_mask;
  st->active_region_id = region_id;
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_dotf_get_active_region(uint8_t channel, ra8_dotf_region_t* region)
{
  RA8_CHECK_NULL_PTR(region, s_tag, "region must not be nullptr");
  if (!internal_channel_in_range(channel)) {
    return k_ra8_err_invalid_arg;
  }
  const ra8_dotf_chan_state_t* st = &s_dotf_state[channel];
  if (st->active_region_id == k_ra8_dotf_no_region) {
    return k_ra8_err_invalid_state;
  }
  *region = st->regions[st->active_region_id];
  return k_ra8_ok;
}
 
/* =============================================================================
 * Key + IV staging
 * =============================================================================
 */
 
[[nodiscard]] ra8_err_t ra8_dotf_install_key(uint8_t channel, const ra8_dotf_key_handle_t* handle)
{
  RA8_CHECK_NULL_PTR(handle, s_tag, "handle must not be nullptr");
  if (!internal_channel_in_range(channel)) {
    return k_ra8_err_invalid_arg;
  }
  if (handle->valid == 0U) {
    return k_ra8_err_invalid_arg;
  }
  if ((handle->size != k_ra8_dotf_key_size_128) && (handle->size != k_ra8_dotf_key_size_192) &&
      (handle->size != k_ra8_dotf_key_size_256)) {
    return k_ra8_err_invalid_arg;
  }
  volatile ra8_dotf_regs_t* reg = ra8_dotf_regs(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel mapping failed");
 
  ra8_dotf_chan_state_t* st = &s_dotf_state[channel];
  st->key                   = *handle;
  st->cached_key_size       = handle->size;
  internal_stage_key(reg, handle);
  ra8_log_info_val(s_tag, "install_key channel", (uint32_t)channel);
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_dotf_set_iv(uint8_t channel, const uint32_t* iv_words)
{
  RA8_CHECK_NULL_PTR(iv_words, s_tag, "iv_words must not be nullptr");
  if (!internal_channel_in_range(channel)) {
    return k_ra8_err_invalid_arg;
  }
  volatile ra8_dotf_regs_t* reg = ra8_dotf_regs(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel mapping failed");
 
  ra8_dotf_chan_state_t* st = &s_dotf_state[channel];
  for (uint8_t i = 0U; i < k_ra8_dotf_iv_word_count; ++i) {
    st->iv_cache[i] = iv_words[i];
  }
  st->iv_valid = 1U;
  internal_stage_iv(reg, iv_words);
  return k_ra8_ok;
}

RA8_INTERNAL
static void internal_rotate_iv(ra8_dotf_chan_state_t*    st,
                               volatile ra8_dotf_regs_t* reg,
                               const uint32_t*           iv_words)
{
  if (iv_words != nullptr) {
    for (uint8_t i = 0U; i < k_ra8_dotf_iv_word_count; ++i) {
      st->iv_cache[i] = iv_words[i];
    }
    st->iv_valid = 1U;
    internal_stage_iv(reg, iv_words);
  } else if (st->iv_valid != 0U) {
    internal_stage_iv(reg, st->iv_cache);
  } else {
    /* No IV ever installed, no IV to re-stage. */
  }
}

RA8_INTERNAL
static ra8_err_t internal_validate_rotate_inputs(uint8_t                      channel,
                                                 const ra8_dotf_key_handle_t* new_handle)
{
  if (!internal_channel_in_range(channel)) {
    return k_ra8_err_invalid_arg;
  }
  if (new_handle->valid == 0U) {
    return k_ra8_err_invalid_arg;
  }
  if ((new_handle->size != k_ra8_dotf_key_size_128) &&
      (new_handle->size != k_ra8_dotf_key_size_192) &&
      (new_handle->size != k_ra8_dotf_key_size_256)) {
    return k_ra8_err_invalid_arg;
  }
  if (s_dotf_state[channel].active_region_id == k_ra8_dotf_no_region) {
    return k_ra8_err_invalid_state;
  }
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_dotf_rotate_key(uint8_t                      channel,
                                            const ra8_dotf_key_handle_t* new_handle,
                                            const uint32_t*              iv_words)
{
  RA8_CHECK_NULL_PTR(new_handle, s_tag, "new_handle must not be nullptr");
  const ra8_err_t val_err = internal_validate_rotate_inputs(channel, new_handle);
  RA8_RETURN_ON_ERROR(val_err, s_tag, "rotate_key: validation failed");
 
  volatile ra8_dotf_regs_t* reg = ra8_dotf_regs(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel mapping failed");
 
  ra8_dotf_chan_state_t* st          = &s_dotf_state[channel];
  const uint8_t          was_enabled = st->enabled;
 
  /* Step 1: quiesce the AES core.
   * HUM Ch 45.3 "Register Descriptions" p 3049 */
  reg->REG00  = k_ra8_dotf_reg00_disable_value;
  st->enabled = 0U;
 
  /* Step 2: replace key + (optionally) IV. */
  st->key             = *new_handle;
  st->cached_key_size = new_handle->size;
  internal_stage_key(reg, new_handle);
  internal_rotate_iv(st, reg, iv_words);
 
  /* Step 3: re-arm if previously enabled. */
  if (was_enabled != 0U) {
    /* HUM Ch 45.3 "Register Descriptions" p 3049 */
    reg->REG00  = internal_assemble_reg00(st, true);
    st->enabled = 1U;
  }
  ra8_log_info_val(s_tag, "rotate_key channel", (uint32_t)channel);
  return k_ra8_ok;
}
 
/* =============================================================================
 * Enable / disable
 * =============================================================================
 */
 
[[nodiscard]] ra8_err_t ra8_dotf_enable(uint8_t channel)
{
  if (!internal_channel_in_range(channel)) {
    return k_ra8_err_invalid_arg;
  }
  volatile ra8_dotf_regs_t* reg = ra8_dotf_regs(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel mapping failed");
 
  ra8_dotf_chan_state_t* st = &s_dotf_state[channel];
  /* REG00 enables AES; pattern is (mode=CTR | key_size | sca | enable).
   * The reset-default ``0x2200_0000`` matches mode=CTR + key_size=128
   * with SCA off; the cached state may override every field.
   * HUM Ch 45.3 "Register Descriptions" p 3049 */
  reg->REG00  = internal_assemble_reg00(st, true);
  st->enabled = 1U;
  ra8_log_info_val(s_tag, "enable channel", (uint32_t)channel);
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_dotf_disable(uint8_t channel)
{
  if (!internal_channel_in_range(channel)) {
    return k_ra8_err_invalid_arg;
  }
  volatile ra8_dotf_regs_t* reg = ra8_dotf_regs(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel mapping failed");
 
  /* Writing 0 to REG00 puts the channel in bypass.
   * HUM Ch 45.3 "Register Descriptions" p 3049 */
  reg->REG00                    = k_ra8_dotf_reg00_disable_value;
  s_dotf_state[channel].enabled = 0U;
  return k_ra8_ok;
}
 
/* =============================================================================
 * REG00 sub-field tuning
 * =============================================================================
 */
 
[[nodiscard]] ra8_err_t ra8_dotf_set_sca_level(uint8_t channel, ra8_dotf_sca_level_t level)
{
  if (!internal_channel_in_range(channel)) {
    return k_ra8_err_invalid_arg;
  }
  if ((level != k_ra8_dotf_sca_off) && (level != k_ra8_dotf_sca_standard) &&
      (level != k_ra8_dotf_sca_max)) {
    return k_ra8_err_invalid_arg;
  }
  ra8_dotf_chan_state_t* st = &s_dotf_state[channel];
  st->cached_sca            = level;
  if (st->enabled != 0U) {
    volatile ra8_dotf_regs_t* reg = ra8_dotf_regs(channel);
    RA8_CHECK_NULL_PTR(reg, s_tag, "channel mapping failed");
    /* HUM Ch 45.3 "Register Descriptions" p 3049 */
    reg->REG00 = internal_assemble_reg00(st, true);
  }
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_dotf_set_key_size(uint8_t channel, ra8_dotf_key_size_t size)
{
  if (!internal_channel_in_range(channel)) {
    return k_ra8_err_invalid_arg;
  }
  if ((size != k_ra8_dotf_key_size_128) && (size != k_ra8_dotf_key_size_192) &&
      (size != k_ra8_dotf_key_size_256)) {
    return k_ra8_err_invalid_arg;
  }
  ra8_dotf_chan_state_t* st = &s_dotf_state[channel];
  st->cached_key_size       = size;
  if (st->enabled != 0U) {
    volatile ra8_dotf_regs_t* reg = ra8_dotf_regs(channel);
    RA8_CHECK_NULL_PTR(reg, s_tag, "channel mapping failed");
    /* HUM Ch 45.3 "Register Descriptions" p 3049 */
    reg->REG00 = internal_assemble_reg00(st, true);
  }
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_dotf_run_self_test(uint8_t channel, uint32_t* out_status)
{
  RA8_CHECK_NULL_PTR(out_status, s_tag, "out_status must not be nullptr");
  if (!internal_channel_in_range(channel)) {
    return k_ra8_err_invalid_arg;
  }
  volatile ra8_dotf_regs_t* reg = ra8_dotf_regs(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel mapping failed");
 
  /* Save current REG00 so the function is observably side-effect-free
   * once the self-test completes. */
  const uint32_t saved = reg->REG00;
  /* HUM Ch 45.1 p 3048 ("Supports self-test function").
   * REG00 bit 20 triggers BIST; the bit auto-clears in real silicon.
   * HUM Ch 45.3 "Register Descriptions" p 3049 */
  reg->REG00               = saved | k_ra8_dotf_reg00_self_test;
  const ra8_err_t wait_err = ra8_hw_wait_flag_clear32(&reg->REG00,
                                                      k_ra8_dotf_reg00_self_test,
                                                      (uint32_t)k_ra8_dotf_self_test_spin);
  *out_status              = reg->REG00;
  /* HUM Ch 45.3 "Register Descriptions" p 3049 */
  reg->REG00 = saved;
  return wait_err;
}
 
/* =============================================================================
 * Status
 * =============================================================================
 */
 
[[nodiscard]] ra8_err_t ra8_dotf_get_status(uint8_t channel, uint32_t* out_mask)
{
  RA8_CHECK_NULL_PTR(out_mask, s_tag, "out_mask must not be nullptr");
  if (!internal_channel_in_range(channel)) {
    return k_ra8_err_invalid_arg;
  }
  volatile ra8_dotf_regs_t* reg = ra8_dotf_regs(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel mapping failed");
 
  /* Raw REG00 read for diagnostics.
   * HUM Ch 45.3 "Register Descriptions" p 3049 */
  *out_mask = reg->REG00;
  return k_ra8_ok;
}
 
[[nodiscard]] ra8_err_t ra8_dotf_clear_status(uint8_t channel)
{
  if (!internal_channel_in_range(channel)) {
    return k_ra8_err_invalid_arg;
  }
  volatile ra8_dotf_regs_t* reg = ra8_dotf_regs(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel mapping failed");
 
  /* Clearing REG00 wipes the AES enable + status bits.
   * HUM Ch 45.3 "Register Descriptions" p 3049 */
  reg->REG00                    = k_ra8_dotf_reg00_disable_value;
  s_dotf_state[channel].enabled = 0U;
  return k_ra8_ok;
}
 
/* =============================================================================
 * IRQ glue
 * =============================================================================
 */
 
[[nodiscard]] ra8_err_t ra8_dotf_attach_handler(ra8_dotf_event_fn_t fn, void* ctx)
{
  s_dotf_fn  = fn;
  s_dotf_ctx = ctx;
  return k_ra8_ok;
}
 
RA8_ISR_SAFE
void ra8_dotf_dispatch(uint8_t channel)
{
  if (!internal_channel_in_range(channel)) {
    return;
  }
  const ra8_dotf_event_fn_t fn  = s_dotf_fn;
  void* const               ctx = s_dotf_ctx;
  if (fn != nullptr) {
    fn(ctx, channel);
  }
}