emu_exc.c

Go to the documentation of this file.

 
#include "emu_exc.h"
 
#include <stdio.h>
 
#include "board_periph.h"
#include "emu_console.h"
#include "emu_engine.h"
#include "emu_host_io_internal.h"
#include "emu_memmap.h"
#include "emu_seams.h"

typedef enum : uint32_t {
  k_op_branch_self  = 0xE7FEU, 
  k_op_wfi          = 0xBF30U, 
  k_op_cpsie_i      = 0xB662U, 
  k_op_bn_mask      = 0xF800U, 
  k_op_bn_base      = 0xE000U, 
  k_op_bn_imm       = 0x07FFU, 
  k_bn_imm_sext_shl = 21U,     
  k_bn_imm_sext_shr = 20U,     
  k_idle_scan_fwd   = 8U,      
  k_idle_loop_max   = 32U,     
  k_thumb_op5_shift = 11U,     
  k_thumb_op5_mask  = 0x1FU,   
  k_thumb32_op5_min = 0x1DU,   
} emu_exc_decode_t;
 
static uint32_t s_systick_fires;
 
/* Hand-modelled Cortex-M exception state. Unicorn's M33 core has no NVIC /
 * exception unit, so ra8_emulator takes SysTick / PendSV / SVCall by hand: it
 * tracks the active-exception priority stack here (everything else -- MSP/PSP/
 * CONTROL/xPSR/PRIMASK -- is read straight from Unicorn). s_exc_stack holds the
 * priority of each handler currently active so a higher-priority exception
 * (e.g. SysTick, prio 0x40) can pre-empt a lower one (PendSV, prio 0xFF) but
 * not vice-versa, exactly as the real priority logic would nest them. */
static uint32_t s_exc_stack[k_exc_nest_max]; 
static uint32_t s_exc_depth;                 
static uint32_t s_pendsv_takes;              
static uint32_t s_svc_takes;                 
static uint64_t s_exc_return_pc;             
static bool     s_exc_return_hit;            
static bool     s_systick_pending;           
static bool     s_pendsv_stop;               
static bool     s_bkpt_hit;                  
static uint32_t s_bkpt_pc;                   

RA8_INTERNAL static uint32_t internal_exc_active_prio(void)
{
  return (s_exc_depth == 0U) ? (uint32_t)k_exc_prio_none : s_exc_stack[s_exc_depth - 1U];
}

RA8_INTERNAL static uint32_t internal_exc_priority(uc_engine* uc, uint32_t exc_num)
{
  if (exc_num == (uint32_t)k_exc_svcall) {
    return (rd32(uc, (uint64_t)k_scb_shpr2) >> (3U * (uint32_t)k_byte_bits)) &
           (uint32_t)k_byte_mask;
  }
  if (exc_num == (uint32_t)k_exc_pendsv) {
    return (rd32(uc, (uint64_t)k_scb_shpr3) >> (2U * (uint32_t)k_byte_bits)) &
           (uint32_t)k_byte_mask;
  }
  if (exc_num == (uint32_t)k_exc_systick) {
    return (rd32(uc, (uint64_t)k_scb_shpr3) >> (3U * (uint32_t)k_byte_bits)) &
           (uint32_t)k_byte_mask;
  }
  return (uint32_t)k_exc_prio_max;
}

RA8_INTERNAL static void
internal_exc_stack_frame(uc_engine* uc, uint32_t sp, bool fp_active, uint32_t frame_xpsr)
{
  wr32(uc, (uint64_t)sp + 0U, reg_get(uc, UC_ARM_REG_R0));
  wr32(uc, (uint64_t)sp + 4U, reg_get(uc, UC_ARM_REG_R1));
  wr32(uc, (uint64_t)sp + 8U, reg_get(uc, UC_ARM_REG_R2));
  wr32(uc, (uint64_t)sp + (uint64_t)k_frame_off_r3, reg_get(uc, UC_ARM_REG_R3));
  wr32(uc, (uint64_t)sp + 16U, reg_get(uc, UC_ARM_REG_R12));
  wr32(uc, (uint64_t)sp + (uint64_t)k_frame_off_lr, reg_get(uc, UC_ARM_REG_LR));
  wr32(uc, (uint64_t)sp + (uint64_t)k_frame_off_pc, reg_get(uc, UC_ARM_REG_PC));
  wr32(uc, (uint64_t)sp + (uint64_t)k_frame_off_xpsr, frame_xpsr);
 
  /* Armv8-M FP extended frame: S0-S15 + FPSCR sit directly above the 8-word
   * basic frame (ThreadX's PendSV adds S16-S31 on top of this). */
  if (fp_active) {
    for (uint32_t i = 0U; i < (uint32_t)k_fp_s_words; i++) {
      wr32(uc,
           (uint64_t)sp + (uint64_t)k_frame_off_s0 + (uint64_t)(i * (uint32_t)k_word_bytes),
           reg_get(uc, UC_ARM_REG_S0 + (int)i));
    }
    wr32(uc, (uint64_t)sp + (uint64_t)k_frame_off_fpscr, reg_get(uc, UC_ARM_REG_FPSCR));
  }
}

RA8_INTERNAL static uint32_t internal_exc_return_value(bool in_thread, bool use_psp, bool fp_active)
{
  /* EXC_RETURN encodes where to unstack: Thread/PSP, Thread/MSP, or (when an
   * exception pre-empts another) Handler/MSP. */
  uint32_t exc_ret;
  if (!in_thread) {
    exc_ret = (uint32_t)k_exc_ret_handler;
  } else if (use_psp) {
    exc_ret = (uint32_t)k_exc_ret_psp;
  } else {
    exc_ret = (uint32_t)k_exc_ret_msp;
  }
  if (fp_active) {
    exc_ret &= ~(uint32_t)k_exc_ret_ftype; /* FType=0: an FP frame was stacked. */
  }
  return exc_ret;
}

void exc_enter(uc_engine* uc, uint32_t exc_num, uint32_t handler)
{
  const uint32_t xpsr_in   = reg_get(uc, UC_ARM_REG_XPSR);
  const uint32_t control   = reg_get(uc, UC_ARM_REG_CONTROL);
  const bool     in_thread = (xpsr_in & (uint32_t)k_xpsr_ipsr_mask) == 0U;
  const bool     use_psp   = in_thread && ((control & (uint32_t)k_control_spsel) != 0U);
  const bool     fp_active = (control & (uint32_t)k_control_fpca) != 0U;
 
  const int sp_reg = use_psp ? UC_ARM_REG_PSP : UC_ARM_REG_MSP;
  uint32_t  sp     = reg_get(uc, sp_reg);
 
  /* Hardware aligns the stack pointer to 8 bytes on entry and flags the pad in
   * the stacked xPSR (bit 9) so the matching exception return can remove it. */
  uint32_t frame_xpsr = xpsr_in;
  if ((sp & 0x4U) != 0U) {
    sp -= 4U;
    frame_xpsr |= (uint32_t)k_xpsr_align9;
  } else {
    frame_xpsr &= ~(uint32_t)k_xpsr_align9;
  }
  sp -= (uint32_t)k_exc_frame_bytes;
  if (fp_active) {
    sp -= (uint32_t)k_fp_frame_extra;
  }
 
  internal_exc_stack_frame(uc, sp, fp_active, frame_xpsr);
 
  /* Commit the new value of whichever stack the frame went onto. */
  reg_set(uc, sp_reg, sp);
 
  const uint32_t exc_ret = internal_exc_return_value(in_thread, use_psp, fp_active);
 
  /* Handler mode always runs on MSP with CONTROL.SPSEL clear. */
  reg_set(uc, UC_ARM_REG_CONTROL, control & ~(uint32_t)k_control_spsel);
  reg_set(uc, UC_ARM_REG_SP, reg_get(uc, UC_ARM_REG_MSP));
 
  uint32_t handler_xpsr =
    (xpsr_in & ~(uint32_t)k_xpsr_ipsr_mask) | (exc_num & (uint32_t)k_xpsr_ipsr_mask);
  handler_xpsr |= (uint32_t)k_xpsr_t_bit; /* M-profile is always Thumb. */
  reg_set(uc, UC_ARM_REG_XPSR, handler_xpsr);
  reg_set(uc, UC_ARM_REG_LR, exc_ret);
  reg_set(uc, UC_ARM_REG_PC, handler & ~1U);
 
  if (s_exc_depth < (uint32_t)k_exc_nest_max) {
    s_exc_stack[s_exc_depth] = internal_exc_priority(uc, exc_num);
    s_exc_depth++;
  }
}

RA8_INTERNAL static void internal_exc_restore_fp_frame(uc_engine* uc, uint32_t sp)
{
  /* Armv8-M FP extended frame (EXC_RETURN bit4 clear): S0-S15 + FPSCR sit above
   * the basic frame. Restore them so the thread's scalar FP state survives.
   * PC/xPSR keep their basic-frame offsets (accounted for by the caller). */
  for (uint32_t i = 0U; i < (uint32_t)k_fp_s_words; i++) {
    reg_set(
      uc,
      UC_ARM_REG_S0 + (int)i,
      rd32(uc, (uint64_t)sp + (uint64_t)k_frame_off_s0 + (uint64_t)(i * (uint32_t)k_word_bytes)));
  }
  reg_set(uc, UC_ARM_REG_FPSCR, rd32(uc, (uint64_t)sp + (uint64_t)k_frame_off_fpscr));
}

RA8_INTERNAL static void
internal_exc_restore_mode(uc_engine* uc, uint32_t xpsr, bool to_thread, bool to_psp)
{
  /* Restore mode: on return to Thread, CONTROL.SPSEL follows EXC_RETURN bit2;
   * on return to a pre-empted handler the core stays on MSP. */
  uint32_t control = reg_get(uc, UC_ARM_REG_CONTROL);
  if (to_thread && to_psp) {
    control |= (uint32_t)k_control_spsel;
  } else {
    control &= ~(uint32_t)k_control_spsel;
  }
  reg_set(uc, UC_ARM_REG_CONTROL, control);
 
  uint32_t new_xpsr = xpsr | (uint32_t)k_xpsr_t_bit;
  if (to_thread) {
    new_xpsr &= ~(uint32_t)k_xpsr_ipsr_mask; /* Thread mode: IPSR == 0 */
  }
  reg_set(uc, UC_ARM_REG_XPSR, new_xpsr);
}

void exc_return(uc_engine* uc, uint32_t exc_ret)
{
  const bool to_psp    = (exc_ret & (uint32_t)k_exc_ret_spsel) != 0U;
  const bool to_thread = (exc_ret & (uint32_t)k_exc_ret_mode) != 0U;
  const bool fp_frame  = (exc_ret & (uint32_t)k_exc_ret_ftype) == 0U;
  const int  sp_reg    = to_psp ? UC_ARM_REG_PSP : UC_ARM_REG_MSP;
  uint32_t   sp        = reg_get(uc, sp_reg);
 
  const uint32_t r0   = rd32(uc, (uint64_t)sp + 0U);
  const uint32_t r1   = rd32(uc, (uint64_t)sp + 4U);
  const uint32_t r2   = rd32(uc, (uint64_t)sp + 8U);
  const uint32_t r3   = rd32(uc, (uint64_t)sp + (uint64_t)k_frame_off_r3);
  const uint32_t r12  = rd32(uc, (uint64_t)sp + 16U);
  const uint32_t lr   = rd32(uc, (uint64_t)sp + (uint64_t)k_frame_off_lr);
  const uint32_t pc   = rd32(uc, (uint64_t)sp + (uint64_t)k_frame_off_pc);
  const uint32_t xpsr = rd32(uc, (uint64_t)sp + (uint64_t)k_frame_off_xpsr);
 
  if (fp_frame) {
    internal_exc_restore_fp_frame(uc, sp);
  }
 
  sp += (uint32_t)k_exc_frame_bytes;
  if (fp_frame) {
    sp += (uint32_t)k_fp_frame_extra;
  }
  if ((xpsr & (uint32_t)k_xpsr_align9) != 0U) {
    sp += 4U; /* undo the entry-time 8-byte realignment pad */
  }
  reg_set(uc, sp_reg, sp);
 
  reg_set(uc, UC_ARM_REG_R0, r0);
  reg_set(uc, UC_ARM_REG_R1, r1);
  reg_set(uc, UC_ARM_REG_R2, r2);
  reg_set(uc, UC_ARM_REG_R3, r3);
  reg_set(uc, UC_ARM_REG_R12, r12);
  reg_set(uc, UC_ARM_REG_LR, lr);
 
  internal_exc_restore_mode(uc, xpsr, to_thread, to_psp);
 
  /* Active SP becomes whichever stack the returned-to context uses. */
  reg_set(uc, UC_ARM_REG_SP, reg_get(uc, to_psp && to_thread ? UC_ARM_REG_PSP : UC_ARM_REG_MSP));
  reg_set(uc, UC_ARM_REG_PC, pc & ~1U);
 
  if (s_exc_depth > 0U) {
    s_exc_depth--;
  }
}

RA8_INTERNAL static bool internal_is_exc_return(uint64_t pc)
{
  return (pc & (uint64_t)k_exc_ret_v8_mask) == (uint64_t)k_exc_ret_v8_mask;
}

uint32_t exc_vector(uc_engine* uc, uint32_t vtor_base, uint32_t exc_num)
{
  uint32_t vtor = rd32(uc, (uint64_t)k_scb_vtor);
  if (vtor == 0U) {
    vtor = vtor_base;
  }
  const uint32_t handler = rd32(uc, (uint64_t)vtor + ((uint64_t)exc_num * 4U)) & ~1U;
  if ((handler == 0U) || (handler == (uint32_t)k_vector_erased)) {
    return 0U;
  }
  return handler;
}

RA8_INTERNAL static bool
internal_exc_take_periph_irq(uc_engine* uc, uint32_t vtor_base, uint32_t active)
{
  uint32_t irq = 0U;
  if (!board_periph_next_irq(&irq)) {
    return false;
  }
  const uint8_t  prio_byte = (uint8_t)rd32(uc, (uint64_t)k_nvic_ipr_base + irq);
  const uint32_t prio =
    (uint32_t)(prio_byte >> (uint32_t)k_nvic_prio_shift) & (uint32_t)k_lo4_mask; /* 4 MSBs used */
  if (prio >= active) {
    return false; /* an equal/higher-priority handler is active -- defer */
  }
  const uint32_t handler = exc_vector(uc, vtor_base, (uint32_t)k_exc_irq_vec0 + irq);
  if (handler == 0U) {
    return false; /* no ISR installed: drop (default handler would just return) */
  }
  /* Clear the NVIC ISPR pending bit on activation, as hardware does. */
  const uint64_t ispr_word = (uint64_t)k_nvic_ispr_base + ((uint64_t)(irq / 32U) * 4U);
  uint32_t       ispr      = rd32(uc, ispr_word);
  ispr &= ~(1U << (irq % 32U));
  wr32(uc, ispr_word, ispr);
 
  exc_enter(uc, (uint32_t)k_exc_irq_vec0 + irq, handler);
  board_periph_note_irq_taken(irq);
  return true;
}

bool exc_take_pending(uc_engine* uc, uint32_t vtor_base, bool allow_systick)
{
  const uint32_t primask = reg_get(uc, UC_ARM_REG_PRIMASK);
  if ((primask & 1U) != 0U) {
    return false; /* interrupts masked -- no exception may be taken now */
  }
  const uint32_t active = internal_exc_active_prio();
 
  /* SysTick first: highest-priority of the modelled exceptions, so it can
   * pre-empt a lower-priority PendSV that is spinning for a runnable thread.
   * Skipped on a context-switch stop (allow_systick == false) so the tick does
   * not advance while ready threads still have work to run. */
  if (allow_systick && s_systick_pending) {
    const bool armed =
      (rd32(uc, (uint64_t)k_syst_csr) & (uint32_t)k_syst_csr_run) == (uint32_t)k_syst_csr_run;
    if (!armed) {
      s_systick_pending = false; /* disabled SysTick: drop the pended tick */
    } else if (internal_exc_priority(uc, (uint32_t)k_exc_systick) < active) {
      const uint32_t handler = exc_vector(uc, vtor_base, (uint32_t)k_exc_systick);
      if (handler != 0U) {
        s_systick_pending = false;
        exc_enter(uc, (uint32_t)k_exc_systick, handler);
        s_systick_fires++;
        return true;
      }
    }
  }
 
  /* PendSV: taken when the firmware has requested a context switch. */
  uint32_t icsr = rd32(uc, (uint64_t)k_scb_icsr);
  if ((icsr & (1U << (uint32_t)k_icsr_pendsvset)) != 0U) {
    if (internal_exc_priority(uc, (uint32_t)k_exc_pendsv) < active) {
      const uint32_t handler = exc_vector(uc, vtor_base, (uint32_t)k_exc_pendsv);
      if (handler != 0U) {
        /* Hardware clears PENDSVSET when PendSV is activated. */
        icsr &= ~(1U << (uint32_t)k_icsr_pendsvset);
        wr32(uc, (uint64_t)k_scb_icsr, icsr);
        exc_enter(uc, (uint32_t)k_exc_pendsv, handler);
        s_pendsv_takes++;
        return true;
      }
    }
  }
 
  /* Peripheral NVIC IRQs queued by the ICU model (timer overflow / underflow
   * routed through IELSR). Taken last among the modelled exceptions but via the
   * identical real entry/return path, with NVIC IPR priority honoured. */
  return internal_exc_take_periph_irq(uc, vtor_base, active);
}

RA8_INTERNAL static const char* internal_unmapped_access_kind(uc_mem_type type)
{
  if (type == UC_MEM_READ_UNMAPPED) {
    return "read";
  }
  if (type == UC_MEM_WRITE_UNMAPPED) {
    return "write";
  }
  return "fetch";
}

RA8_INTERNAL static bool internal_on_unmapped(uc_engine*  uc,
                                              uc_mem_type type,
                                              uint64_t    addr,
                                              int         size,
                                              int64_t     value,
                                              void*       user)
{
  (void)size;
  (void)value;
  (void)user;
  /* A FETCH into the EXC_RETURN range is not a fault -- it is the core taking
   * an exception return (the handler ran "BX lr" with an EXC_RETURN magic in
   * LR). Capture it and stop cleanly so the run loop can unstack the frame and
   * resume; the Unicorn fetch-fault error this produces is expected/handled. */
  if ((type == UC_MEM_FETCH_UNMAPPED) && internal_is_exc_return(addr)) {
    s_exc_return_pc  = addr;
    s_exc_return_hit = true;
    (void)uc_emu_stop(uc);
    return false;
  }
  (void)priv_emu_io_errf("  UNMAPPED %s @ 0x%08llX (extend the memory/peripheral map)\n",
                         internal_unmapped_access_kind(type),
                         (unsigned long long)addr);
  return false; /* stop emulation and report */
}

RA8_INTERNAL static bool internal_on_intr_sec_insn(uc_engine* uc, uint32_t pc, uint32_t insn)
{
  if (insn == (uint32_t)k_armv8m_sg_opcode) {
    const uint32_t next = pc + (uint32_t)k_thumb2_insn_bytes;
    (void)uc_reg_write(uc, UC_ARM_REG_PC, &next);
    (void)uc_emu_stop(uc);
    return true;
  }
  if ((insn == (uint32_t)k_fpcxtns_push) || (insn == (uint32_t)k_fpcxtns_pop)) {
    uint32_t sp = 0U;
    (void)uc_reg_read(uc, UC_ARM_REG_SP, &sp);
    if (insn == (uint32_t)k_fpcxtns_push) {
      sp -= (uint32_t)k_word_bytes;
      const uint32_t zero = 0U;
      (void)emu_mem_write(uc, (uint64_t)sp, &zero, sizeof(zero));
    } else {
      sp += (uint32_t)k_word_bytes;
    }
    const uint32_t next = pc + (uint32_t)k_thumb2_insn_bytes;
    (void)uc_reg_write(uc, UC_ARM_REG_SP, &sp);
    (void)uc_reg_write(uc, UC_ARM_REG_PC, &next);
    (void)uc_emu_stop(uc);
    return true;
  }
  return false;
}

RA8_INTERNAL static bool internal_on_intr_bkpt(uc_engine* uc, uint32_t pc, uint32_t insn)
{
  if (((uint16_t)(insn & (uint32_t)k_lo16_mask) & (uint16_t)k_bkpt_hw_mask) ==
      (uint16_t)k_bkpt_hw_base) {
    s_bkpt_hit = true;
    s_bkpt_pc  = pc;
    (void)uc_emu_stop(uc);
    return true;
  }
  return false;
}

RA8_INTERNAL static void internal_on_intr(uc_engine* uc, uint32_t int_no, void* user_data)
{
  (void)int_no;
  uint32_t pc = 0U;
  (void)uc_reg_read(uc, UC_ARM_REG_PC, &pc);
 
  /* Cortex-M exception RETURN. Unicorn's M-profile core does not pop the
   * exception frame itself, but it DOES trap a branch to an EXC_RETURN magic
   * (0xFFFFFFFx) by raising an interrupt with the magic left in PC (Thumb bit
   * masked off, but the stack/mode selector bits 2/3 intact). Unstack the basic
   * frame and resume the interrupted context. This is how every handler that
   * ra8_emulator vectors in (SysTick / PendSV / SVCall) returns. */
  if (internal_is_exc_return((uint64_t)pc)) {
    s_exc_return_pc  = (uint64_t)pc;
    s_exc_return_hit = true;
    (void)uc_emu_stop(uc);
    return;
  }
 
  /* MVE (Helium) contiguous load/store raises a NoCP UsageFault on Unicorn's
   * M33; ::emu_mve_nocp_emulate documents the decode and why it precedes SVCall. */
  if (emu_mve_nocp_emulate(uc, pc)) {
    (void)uc_emu_stop(uc);
    return;
  }
 
  /* Armv8-M secure gateway: every Non-Secure-Callable veneer starts with `SG`
   * (0xE97FE97F) then `B.W __acle_se_<fn>`. Unicorn's M33 has no Security
   * Extension, so it raises INTR on the unrecognised SG instead of switching to
   * Secure state. ra8_emulator has a single flat address space (no S/NS split), so
   * the faithful model is to treat SG as a NOP and let the following branch reach
   * the secure entry directly. Without this the SG is mis-taken as an `svc` and
   * re-taken forever (the firmware has no SVC), looping until the stack
   * underflows -- the tz_nsc_cgc_usb fault. The matching `BXNS`/`BLXNS` returns
   * are handled below. */
  uint32_t insn = 0U;
  (void)emu_mem_read(uc, (uint64_t)pc, &insn, sizeof(insn));
 
  /* Armv8-M Security Extension instructions (SG / FPCXTNS) reduce to their plain
   * effects in this single-domain model; a BKPT is a deliberate firmware halt. */
  if (internal_on_intr_sec_insn(uc, pc, insn)) {
    return;
  }
  if (internal_on_intr_bkpt(uc, pc, insn)) {
    return;
  }
 
  /* Otherwise it is a synchronous `svc` -- take SVCall (#11). ThreadX in single
   * mode never issues one, but bare-metal / future RTOS first-thread-start
   * paths do. The VTOR fallback is the MRAM vector-table base; the live VTOR
   * (set by SystemInit) is read inside exc_vector. */
  (void)user_data;
  const uint32_t vtor_base = (uint32_t)emu_memmap_mram_base();
  const uint32_t handler   = exc_vector(uc, vtor_base, (uint32_t)k_exc_svcall);
  if (handler != 0U) {
    exc_enter(uc, (uint32_t)k_exc_svcall, handler);
    s_svc_takes++;
  }
  (void)uc_emu_stop(uc);
}

RA8_INTERNAL static void internal_on_icsr_write(uc_engine*  uc,
                                                uc_mem_type type,
                                                uint64_t    addr,
                                                int         size,
                                                int64_t     value,
                                                void*       user)
{
  (void)type;
  (void)addr;
  (void)size;
  (void)user;
  if (((uint32_t)value & (1U << (uint32_t)k_icsr_pendsvset)) == 0U) {
    return; /* not a PendSV request (e.g. PENDSVCLR / status write) */
  }
  /* Only end the chunk when PendSV could actually activate now: interrupts
   * unmasked and no equal/higher-priority handler already running. If masked
   * (the store sits inside a ThreadX critical section), do NOT stop -- the run
   * loop would otherwise relaunch from this same store and re-pend forever,
   * since uc_emu_stop here leaves PC on the store. With those guards, the run
   * loop's exc_take_pending takes PendSV and moves PC to the handler, so the
   * store is never re-executed. The masked case is picked up at the next
   * boundary once TX_RESTORE re-enables interrupts. */
  uint32_t primask = 0U;
  (void)uc_reg_read(uc, UC_ARM_REG_PRIMASK, &primask);
  if ((primask & 1U) != 0U) {
    return;
  }
  if (internal_exc_priority(uc, (uint32_t)k_exc_pendsv) >= internal_exc_active_prio()) {
    return; /* a higher/equal-priority handler is active -- defer */
  }
  /* Advance PC past the storing instruction before stopping so the PendSV we
   * are about to take stacks the return address of the NEXT instruction -- as
   * real hardware does (PendSV activates after the store retires), not the store
   * itself. Re-stacking the store would re-pend PendSV on every return and spin.
   * Thumb length: a halfword whose top 5 bits are 0b111xx with xx != 00 starts a
   * 32-bit instruction; otherwise it is 16-bit. */
  uint32_t pc = 0U;
  (void)uc_reg_read(uc, UC_ARM_REG_PC, &pc);
  uint16_t hw0 = 0U;
  (void)emu_mem_read(uc, pc, &hw0, sizeof(hw0));
  const uint32_t op5  = (uint32_t)(hw0 >> (uint32_t)k_thumb_op5_shift) & (uint32_t)k_thumb_op5_mask;
  const uint32_t step = (op5 >= (uint32_t)k_thumb32_op5_min) ? 4U : 2U;
  uint32_t       next = pc + step;
  (void)uc_reg_write(uc, UC_ARM_REG_PC, &next);
  /* Mark this as a context-switch stop so the run loop takes PendSV WITHOUT
   * advancing the SysTick: a context switch consumes no modelled time, so a
   * thread that suspends (e.g. tx_thread_sleep) must not have its tick-based
   * wait expired the instant it yields -- that would starve lower-priority
   * ready threads. Time (SysTick) advances only on a full-budget run (genuine
   * execution / idle spin). See the run loop's inner dispatch. */
  s_pendsv_stop = true;
  (void)uc_emu_stop(uc);
}

void emu_exc_install_core(uc_engine* uc)
{
  static uc_hook s_h_unmapped;
  static uc_hook s_h_intr;
  static uc_hook s_h_icsr;
  (void)uc_hook_add(uc,
                    &s_h_unmapped,
                    UC_HOOK_MEM_UNMAPPED,
                    (void*)internal_on_unmapped,
                    nullptr,
                    1,
                    0);
  /* SVCall / exception-return: Unicorn raises UC_HOOK_INTR on a Thumb `svc` and
   * on a branch to an EXC_RETURN magic; internal_on_intr vectors / unstacks accordingly. */
  (void)uc_hook_add(uc, &s_h_intr, UC_HOOK_INTR, (void*)internal_on_intr, nullptr, 1, 0);
  /* Watch the ICSR word so a PENDSVSET store ends the chunk at once, giving
   * PendSV next-instruction activation (see internal_on_icsr_write). ICSR lives in PPB
   * RAM, so this memory-write hook is the only way to observe the request. */
  (void)uc_hook_add(uc,
                    &s_h_icsr,
                    UC_HOOK_MEM_WRITE,
                    (void*)internal_on_icsr_write,
                    nullptr,
                    (uint64_t)k_scb_icsr,
                    (uint64_t)k_scb_icsr + 3U);
}

void emu_exc_arm_systick(void)
{
  s_systick_pending = true;
}

bool emu_exc_take_exc_return(uint64_t* out_pc)
{
  if (!s_exc_return_hit) {
    return false;
  }
  s_exc_return_hit = false;
  *out_pc          = s_exc_return_pc;
  return true;
}

void emu_exc_clear_pendsv_stop(void)
{
  s_pendsv_stop = false;
}

bool emu_exc_pendsv_stop(void)
{
  return s_pendsv_stop;
}

bool emu_exc_bkpt_hit(void)
{
  return s_bkpt_hit;
}

uint32_t emu_exc_bkpt_pc(void)
{
  return s_bkpt_pc;
}

uint32_t emu_exc_systick_fires(void)
{
  return s_systick_fires;
}

uint32_t emu_exc_pendsv_takes(void)
{
  return s_pendsv_takes;
}

uint32_t emu_exc_svc_takes(void)
{
  return s_svc_takes;
}

void emu_exc_reset(void)
{
  s_exc_depth       = 0U;
  s_systick_pending = true;
  s_bkpt_hit        = false;
  s_exc_return_hit  = false;
  s_pendsv_stop     = false;
  s_systick_fires   = 0U;
  s_pendsv_takes    = 0U;
  s_svc_takes       = 0U;
}