ra8_isr.c

Go to the documentation of this file.

 
#include "ra8_isr.h"
 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_hw_intrinsics.h"
#include "ra8_icu_regs.h"
#include "ra8_log.h"
 
static const char* s_tag = "ISR";

typedef enum : uintptr_t {
  k_ra8_isr_nvic_iser_base = 0xE000E100UL, 
  k_ra8_isr_nvic_icer_base = 0xE000E180UL, 
  k_ra8_isr_nvic_icpr_base = 0xE000E280UL, 
  k_ra8_isr_nvic_ipr_base  = 0xE000E400UL, 
} ra8_isr_nvic_t;

typedef enum : uint16_t {
  k_ra8_isr_nvic_bits_per_word = 32U, 
  k_ra8_isr_nvic_prio_shift    = 4U,  
} ra8_isr_nvic_layout_t;

typedef struct {
  ra8_isr_handler_t handler;  
  void*             ctx;      
  ra8_elc_event_t   event;    
  uint8_t           priority; 
  bool              in_use;   
} ra8_isr_slot_t;

static ra8_isr_slot_t s_slots[k_ra8_isr_slot_count];
 
/* The slot pool must not exceed the ICU IELSR capacity: a slot with index
 * >= k_ra8_icu_num_ielsr could be allocated and its NVIC line enabled, but
 * ra8_icu_ielsr() returns NULL for it, leaving the interrupt NVIC-enabled with
 * no ICU event route (#237). Pin the two capacity constants together so they
 * cannot silently diverge. */
static_assert((uint16_t)k_ra8_isr_slot_count == (uint16_t)k_ra8_icu_num_ielsr,
              "ra8_isr slot pool must equal the ICU IELSR capacity (see #237)");
 
/* =============================================================================
 * NVIC pokes (no-op on host)
 * =============================================================================
 *
 * The fake maps the SCB / NVIC window via ra8_fake_mmap (core
 * region base 0xE0000000, size 0x100000). Writes land in host
 * RAM; the tests observe the register state via the same aliases.
 */

RA8_INTERNAL static void internal_nvic_enable(uint16_t n)
{
  const uint16_t     word = n / k_ra8_isr_nvic_bits_per_word;
  const uint16_t     bit  = n % k_ra8_isr_nvic_bits_per_word;
  volatile uint32_t* iser =
    (volatile uint32_t*)(k_ra8_isr_nvic_iser_base + ((uintptr_t)word * sizeof(uint32_t)));
  *iser = (uint32_t)1UL << bit;
}

RA8_INTERNAL static void internal_nvic_disable(uint16_t n)
{
  const uint16_t     word = n / k_ra8_isr_nvic_bits_per_word;
  const uint16_t     bit  = n % k_ra8_isr_nvic_bits_per_word;
  volatile uint32_t* icer =
    (volatile uint32_t*)(k_ra8_isr_nvic_icer_base + ((uintptr_t)word * sizeof(uint32_t)));
  *icer = (uint32_t)1UL << bit;
}

RA8_INTERNAL static void internal_nvic_clear_pending(uint16_t n)
{
  const uint16_t     word = n / k_ra8_isr_nvic_bits_per_word;
  const uint16_t     bit  = n % k_ra8_isr_nvic_bits_per_word;
  volatile uint32_t* icpr =
    (volatile uint32_t*)(k_ra8_isr_nvic_icpr_base + ((uintptr_t)word * sizeof(uint32_t)));
  *icpr = (uint32_t)1UL << bit;
}

RA8_INTERNAL static void internal_nvic_set_priority(uint16_t n, uint8_t prio)
{
  volatile uint8_t* ipr = (volatile uint8_t*)(k_ra8_isr_nvic_ipr_base + (uintptr_t)n);
  *ipr                  = (uint8_t)(prio << k_ra8_isr_nvic_prio_shift);
}

RA8_INTERNAL static void internal_ielsr_write(uint16_t slot, ra8_elc_event_t event)
{
  volatile uint32_t* ielsr = ra8_icu_ielsr(slot);
  if (ielsr != nullptr) { /* GCOVR_EXCL_BR_LINE -- slot bounds already validated */
    /* HUM Ch 14.2 "IELSRn : ICU Event Link Setting Register n", p 547 */
    *ielsr = (uint32_t)event & k_ra8_ielsr_iels_mask;
  }
}

RA8_INTERNAL static void internal_ielsr_clear(uint16_t slot)
{
  volatile uint32_t* ielsr = ra8_icu_ielsr(slot);
  if (ielsr != nullptr) { /* GCOVR_EXCL_BR_LINE -- slot bounds already validated */
    *ielsr = 0U;
  }
}
 
/* =============================================================================
 * Public API
 * =============================================================================
 */
 
ra8_err_t ra8_isr_init(void)
{
  ra8_log_info(s_tag, "ra8_isr_init");
 
  for (uint16_t slot = 0U; slot < k_ra8_isr_slot_count; ++slot) {
    s_slots[slot].handler  = nullptr;
    s_slots[slot].ctx      = nullptr;
    s_slots[slot].event    = (ra8_elc_event_t)0U;
    s_slots[slot].priority = 0U;
    s_slots[slot].in_use   = false;
 
    internal_nvic_disable(slot);
    internal_nvic_clear_pending(slot);
    internal_ielsr_clear(slot);
  }
  return k_ra8_ok;
}

RA8_INTERNAL static uint16_t internal_find_event(ra8_elc_event_t event)
{
  for (uint16_t slot = 0U; slot < k_ra8_isr_slot_count; ++slot) {
    if (s_slots[slot].in_use && s_slots[slot].event == event) {
      return slot;
    }
  }
  return k_ra8_isr_slot_none;
}

RA8_INTERNAL static uint16_t internal_find_free(void)
{
  for (uint16_t slot = 0U; slot < k_ra8_isr_slot_count; ++slot) {
    if (!s_slots[slot].in_use) {
      return slot;
    }
  }
  return k_ra8_isr_slot_none;
}
 
ra8_err_t ra8_isr_register(ra8_elc_event_t   event,
                           ra8_isr_handler_t handler,
                           void*             ctx,
                           uint8_t           priority,
                           uint16_t*         out_slot)
{
  RA8_CHECK_NULL_PTR(handler, s_tag, "handler must not be NULL");
  if (priority > k_ra8_isr_prio_max) {
    return k_ra8_err_invalid_arg;
  }
 
  const uint16_t existing = internal_find_event(event);
  if (existing != k_ra8_isr_slot_none) {
    return k_ra8_err_exists;
  }
 
  const uint16_t slot = internal_find_free();
  if (slot == k_ra8_isr_slot_none) {
    ra8_log_error(s_tag, "no free slot");
    return k_ra8_err_no_mem;
  }
 
  s_slots[slot].handler  = handler;
  s_slots[slot].ctx      = ctx;
  s_slots[slot].event    = event;
  s_slots[slot].priority = priority;
  s_slots[slot].in_use   = true;
 
  internal_ielsr_write(slot, event);
  internal_nvic_clear_pending(slot);
  internal_nvic_set_priority(slot, priority);
  internal_nvic_enable(slot);
 
  if (out_slot != nullptr) {
    *out_slot = slot;
  }
  return k_ra8_ok;
}
 
ra8_err_t ra8_isr_unregister(ra8_elc_event_t event)
{
  const uint16_t slot = internal_find_event(event);
  if (slot == k_ra8_isr_slot_none) {
    return k_ra8_err_not_found;
  }
  /* internal_find_event returns a slot < k_ra8_isr_slot_count or slot_none, so
   * the write below is in bounds; the explicit guard makes that provable to the
   * static analyzer (matches the bound in ra8_isr_dispatch). */
  /* GCOVR_EXCL_BR_START -- unreachable given the contract above */
  if (slot >= k_ra8_isr_slot_count) {
    /* GCOVR_EXCL_BR_STOP */
    return k_ra8_err_not_found; /* GCOVR_EXCL_LINE -- slot bound proven */
  }
 
  internal_nvic_disable(slot);
  internal_ielsr_clear(slot);
  internal_nvic_clear_pending(slot);
 
  s_slots[slot].handler  = nullptr;
  s_slots[slot].ctx      = nullptr;
  s_slots[slot].event    = (ra8_elc_event_t)0U;
  s_slots[slot].priority = 0U;
  s_slots[slot].in_use   = false;
  return k_ra8_ok;
}
 
void ra8_isr_dispatch(uint16_t slot)
{
  if (slot >= k_ra8_isr_slot_count) {
    return;
  }
  const ra8_isr_handler_t handler = s_slots[slot].handler;
  void* const             ctx     = s_slots[slot].ctx;
 
  /* Clear IELSR.IR via the accessor in ra8_icu_regs.h. The IR flag is
   * WRITE-ZERO-to-clear, not write-one-to-clear: HUM Ch 14.2.17 p 547 states
   * under "IR flag (Interrupt Status Flag)" -> [Clearing condition] that "the
   * IR flag is cleared to 0 by writing 0". ORing a 1 into the bit -- which
   * this did until issue #170 -- therefore cannot ever clear it. The ICU then
   * re-asserts the request the instant the handler returns and the core
   * live-locks in an interrupt storm that starves the main loop. Bench-proven
   * on an EK-RA8D2: lpm_periodic_idle sat in IRQ0_Handler with
   * IELSR0 = 0x00010080 (IR set) and emitted no UART at all; writing IR = 0
   * through J-Link released it and the app printed immediately.
   *
   * Read-modify-write with the IR bit masked OFF: every other field (IELS,
   * DTCE) keeps its value and only IR receives the clearing zero. */
  volatile uint32_t* ielsr = ra8_icu_ielsr(slot);
  if (ielsr != nullptr) { /* GCOVR_EXCL_BR_LINE -- validated above */
    /* HUM Ch 14.2.17 "IELSRn : Interrupt Controller Unit Event Link Setting Register n", p 546-547 */
    *ielsr = *ielsr & ~((uint32_t)1U << k_ra8_ielsr_ir_bit);
  }
 
  if (handler != nullptr) {
    handler(ctx);
  }
}
 
ra8_err_t ra8_isr_set_priority(ra8_elc_event_t event, uint8_t priority)
{
  if (priority > k_ra8_isr_prio_max) {
    return k_ra8_err_invalid_arg;
  }
  const uint16_t slot = internal_find_event(event);
  if (slot == k_ra8_isr_slot_none) {
    return k_ra8_err_not_found;
  }
  s_slots[slot].priority = priority;
  internal_nvic_set_priority(slot, priority);
  return k_ra8_ok;
}
 
ra8_err_t ra8_isr_lookup_slot(ra8_elc_event_t event, uint16_t* out_slot)
{
  RA8_CHECK_NULL_PTR(out_slot, s_tag, "out_slot must not be NULL");
  *out_slot = internal_find_event(event);
  return k_ra8_ok;
}
 
ra8_err_t ra8_isr_set_dtc(uint16_t slot, bool enable)
{
  if (slot >= k_ra8_isr_slot_count) {
    return k_ra8_err_invalid_arg;
  }
  if (!s_slots[slot].in_use) {
    return k_ra8_err_not_found;
  }
  volatile uint32_t* ielsr = ra8_icu_ielsr(slot);
  if (ielsr == nullptr) {      /* GCOVR_EXCL_BR_LINE -- slot bounds already validated */
    return k_ra8_err_hw_error; /* GCOVR_EXCL_LINE -- slot bound proves reg            */
  }
  /* HUM Ch 14.2.17 "IELSRn : ICU Event Link Setting Register n", p 547: DTCE[24]
   * enables DTC activation. The read-modify-write touches only DTCE -- the IELS
   * event field ra8_isr_register wrote is preserved, and the write-0-to-clear IR
   * status flag is retained by writing back its own read value (ORing/ANDing the
   * DTCE mask leaves bit 16 unchanged; see ra8_isr_dispatch and issue #170). */
  const uint32_t cur = *ielsr;
  const uint32_t next =
    enable ? (cur | (uint32_t)k_ra8_ielsr_dtce_mask) : (cur & ~(uint32_t)k_ra8_ielsr_dtce_mask);
  *ielsr = next;
  return k_ra8_ok;
}
 
void ra8_isr_globals_enable(void)
{
  /* PRIMASK clear -- maskable IRQs may now dispatch (host no-op via seam). */
  ra8_hw_irq_enable();
}
 
void ra8_isr_globals_disable(void)
{
  /* PRIMASK set -- subsequent maskable IRQs pend until re-enabled (host
   * no-op via seam). */
  ra8_hw_irq_disable();
}