ra8_npu.c

Go to the documentation of this file.

 
#include "ra8_attributes.h"
#include "ra8_device.h"
 
#ifdef RA8_HAS_NPU
 
#include <stdint.h>
 
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_mstp.h"
#include "ra8_npu.h"
#include "ra8_npu_regs.h"

static const char* s_tag = "NPU";

typedef enum : uint16_t {
  k_ra8_npu_mstp_reg_shift = 8U,  
  k_ra8_npu_mstp_bit       = 16U, 
} ra8_npu_mstp_enc_t;

typedef enum : uint32_t {
  k_ra8_npu_reset_poll_iters = 100000U,  
  k_ra8_npu_job_poll_iters   = 2000000U, 
} ra8_npu_budget_t;

typedef enum : uint8_t {
  k_ra8_npu_addr_hi_shift = 32U, 
} ra8_npu_split_t;

typedef enum : uint32_t {
  k_ra8_npu_status_fault_mask =
    ((uint32_t)1U << k_ra8_npu_status_bus_error_bit) |
    ((uint32_t)1U << k_ra8_npu_status_cmd_parse_bit) |
    ((uint32_t)1U << k_ra8_npu_status_wd_fault_bit) |
    ((uint32_t)1U << k_ra8_npu_status_ecc_fault_bit), 
} ra8_npu_mask_t;

static const ra8_mstp_t s_npu_mstp_id =
  (ra8_mstp_t)(((uint16_t)k_ra8_mstp_reg_a << k_ra8_npu_mstp_reg_shift) | k_ra8_npu_mstp_bit);

static bool s_npu_initialized = false;

static bool s_npu_job_submitted = false;

typedef enum : uint8_t {
  k_ra8_npu_irq_idle  = 0U, 
  k_ra8_npu_irq_armed = 1U, 
  k_ra8_npu_irq_done  = 2U, 
  k_ra8_npu_irq_fault = 3U, 
} ra8_npu_irq_state_t;

static volatile ra8_npu_irq_state_t s_npu_irq_state = k_ra8_npu_irq_idle;

RA8_INTERNAL
static inline void internal_npu_wait_for_irq(void)
{
#ifdef __ARM_ARCH
  __asm__ volatile("wfi");
#endif
}

RA8_INTERNAL
static ra8_err_t internal_npu_apply_reset(void)
{
  /* Ethos-U55 NPU TRM "NPU_RESET" reg @ 0x0C -- request reset, privileged +
   * secure pending level (both pending-level bits written 0). */
  *ra8_npu_reg(k_ra8_npu_off_reset) = 0U;
  for (uint32_t i = 0U; i < k_ra8_npu_reset_poll_iters; i++) {
    /* Ethos-U55 NPU TRM "NPU_STATUS" reg @ 0x04 -- reset bit clears when done. */
    const uint32_t status = *ra8_npu_reg(k_ra8_npu_off_status);
    if ((status & ((uint32_t)1U << k_ra8_npu_status_reset_bit)) == 0U) {
      return k_ra8_ok;
    }
  }
  return k_ra8_err_hw_timeout;
}

RA8_INTERNAL
static void internal_npu_write_region(ra8_npu_region_idx_t idx, uint64_t base)
{
  const uint32_t lo_off =
    (uint32_t)k_ra8_npu_off_basep0_lo + ((uint32_t)idx * (uint32_t)k_ra8_npu_basep_stride_bytes);
  const uint32_t hi_off = lo_off + (uint32_t)k_ra8_npu_reg_hi_offset;
  /* Ethos-U55 NPU TRM "BASEPn" regs @ 0x80 + n*8 -- tensor arena AXI base. */
  *ra8_npu_reg(lo_off) = (uint32_t)base;
  *ra8_npu_reg(hi_off) = (uint32_t)(base >> k_ra8_npu_addr_hi_shift);
}
 
ra8_err_t ra8_npu_init(void)
{
  const ra8_err_t mst = ra8_mstp_enable(s_npu_mstp_id);
  RA8_RETURN_ON_ERROR(mst, s_tag, "npu_init: mstp enable");
  const ra8_err_t rst = internal_npu_apply_reset();
  RA8_RETURN_ON_ERROR(rst, s_tag, "npu_init: reset");
  s_npu_initialized   = true;
  s_npu_job_submitted = false;
  s_npu_irq_state     = k_ra8_npu_irq_idle;
  ra8_log_info(s_tag, "npu_init");
  return k_ra8_ok;
}
 
ra8_err_t ra8_npu_deinit(void)
{
  RA8_VALIDATE_INIT(s_npu_initialized, s_tag, "npu_deinit: not initialized");
  const ra8_err_t dis = ra8_mstp_disable(s_npu_mstp_id);
  RA8_RETURN_ON_ERROR(dis, s_tag, "npu_deinit: mstp disable");
  s_npu_initialized   = false;
  s_npu_job_submitted = false;
  s_npu_irq_state     = k_ra8_npu_irq_idle;
  return k_ra8_ok;
}
 
ra8_err_t ra8_npu_reset(void)
{
  RA8_VALIDATE_INIT(s_npu_initialized, s_tag, "npu_reset: not initialized");
  const ra8_err_t rst = internal_npu_apply_reset();
  RA8_RETURN_ON_ERROR(rst, s_tag, "npu_reset");
  s_npu_job_submitted = false;
  s_npu_irq_state     = k_ra8_npu_irq_idle;
  return k_ra8_ok;
}
 
ra8_err_t ra8_npu_read_id(uint32_t* out_id)
{
  RA8_CHECK_NULL_PTR(out_id, s_tag, "out_id must not be nullptr");
  RA8_VALIDATE_INIT(s_npu_initialized, s_tag, "npu_read_id: not initialized");
  /* Ethos-U55 NPU TRM "NPU_ID" reg @ 0x00 -- architecture / product id. */
  *out_id = *ra8_npu_reg(k_ra8_npu_off_id);
  return k_ra8_ok;
}
 
ra8_err_t ra8_npu_submit(const ra8_npu_job_t* job)
{
  RA8_CHECK_NULL_PTR(job, s_tag, "job must not be nullptr");
  RA8_CHECK_NULL_PTR(job->cmd_stream, s_tag, "job->cmd_stream must not be nullptr");
  RA8_VALIDATE_INIT(s_npu_initialized, s_tag, "npu_submit: not initialized");
  if (job->cmd_stream_bytes == 0U) {
    ra8_log_error(s_tag, "npu_submit: empty command stream");
    return k_ra8_err_invalid_size;
  }
  if (job->region_count > (uint8_t)k_ra8_npu_region_count) {
    ra8_log_error(s_tag, "npu_submit: too many regions");
    return k_ra8_err_invalid_arg;
  }
  const uint64_t qbase = (uint64_t)(uintptr_t)job->cmd_stream;
  /* Ethos-U55 NPU TRM "QBASE" regs @ 0x10 / 0x14 -- command-stream address. */
  *ra8_npu_reg(k_ra8_npu_off_qbase_lo) = (uint32_t)qbase;
  *ra8_npu_reg(k_ra8_npu_off_qbase_hi) = (uint32_t)(qbase >> k_ra8_npu_addr_hi_shift);
  /* Ethos-U55 NPU TRM "QSIZE" reg @ 0x20 -- command-stream length in bytes. */
  *ra8_npu_reg(k_ra8_npu_off_qsize) = job->cmd_stream_bytes;
  for (uint8_t r = 0U; r < job->region_count; r++) {
    internal_npu_write_region((ra8_npu_region_idx_t)r, job->region_base[r]);
  }
  s_npu_job_submitted = true;
  return k_ra8_ok;
}
 
ra8_err_t ra8_npu_run(void)
{
  RA8_VALIDATE_INIT(s_npu_initialized, s_tag, "npu_run: not initialized");
  if (!s_npu_job_submitted) {
    ra8_log_error(s_tag, "npu_run: no job submitted");
    return k_ra8_err_invalid_state;
  }
  /* Ethos-U55 NPU TRM "NPU_CMD" reg @ 0x08 -- transition_to_running_state. */
  *ra8_npu_reg(k_ra8_npu_off_cmd) = ((uint32_t)1U << k_ra8_npu_cmd_run_bit);
  return k_ra8_ok;
}
 
ra8_err_t ra8_npu_read_status(ra8_npu_status_t* out)
{
  RA8_CHECK_NULL_PTR(out, s_tag, "out must not be nullptr");
  RA8_VALIDATE_INIT(s_npu_initialized, s_tag, "npu_read_status: not initialized");
  /* Ethos-U55 NPU TRM "NPU_STATUS" reg @ 0x04 -- state + fault flags. */
  const uint32_t raw = *ra8_npu_reg(k_ra8_npu_off_status);
  out->raw           = raw;
  out->running       = (raw & ((uint32_t)1U << k_ra8_npu_status_state_bit)) != 0U;
  out->irq_raised    = (raw & ((uint32_t)1U << k_ra8_npu_status_irq_raised_bit)) != 0U;
  out->cmd_end       = (raw & ((uint32_t)1U << k_ra8_npu_status_cmd_end_bit)) != 0U;
  out->fault         = (raw & (uint32_t)k_ra8_npu_status_fault_mask) != 0U;
  return k_ra8_ok;
}
 
ra8_err_t ra8_npu_poll(bool* out_done)
{
  RA8_CHECK_NULL_PTR(out_done, s_tag, "out_done must not be nullptr");
  RA8_VALIDATE_INIT(s_npu_initialized, s_tag, "npu_poll: not initialized");
  /* Ethos-U55 NPU TRM "NPU_STATUS" reg @ 0x04 -- fault + cmd-end flags. */
  const uint32_t raw = *ra8_npu_reg(k_ra8_npu_off_status);
  if ((raw & (uint32_t)k_ra8_npu_status_fault_mask) != 0U) {
    ra8_log_error(s_tag, "npu_poll: fault latched");
    return k_ra8_err_hw_error;
  }
  *out_done = (raw & ((uint32_t)1U << k_ra8_npu_status_cmd_end_bit)) != 0U;
  return k_ra8_ok;
}
 
ra8_err_t ra8_npu_wait(void)
{
  RA8_VALIDATE_INIT(s_npu_initialized, s_tag, "npu_wait: not initialized");
  for (uint32_t i = 0U; i < k_ra8_npu_job_poll_iters; i++) {
    bool            done = false;
    const ra8_err_t err  = ra8_npu_poll(&done);
    RA8_RETURN_ON_ERROR(err, s_tag, "npu_wait: poll");
    if (done) {
      return k_ra8_ok;
    }
  }
  return k_ra8_err_hw_timeout;
}
 
ra8_err_t ra8_npu_clear_irq(void)
{
  RA8_VALIDATE_INIT(s_npu_initialized, s_tag, "npu_clear_irq: not initialized");
  /* Ethos-U55 NPU TRM "NPU_CMD" reg @ 0x08 -- write 1 to clear_irq. */
  *ra8_npu_reg(k_ra8_npu_off_cmd) = ((uint32_t)1U << k_ra8_npu_cmd_clear_irq_bit);
  return k_ra8_ok;
}
 
ra8_err_t ra8_npu_irq_arm(void)
{
  RA8_VALIDATE_INIT(s_npu_initialized, s_tag, "npu_irq_arm: not initialized");
  if (!s_npu_job_submitted) {
    ra8_log_error(s_tag, "npu_irq_arm: no job submitted");
    return k_ra8_err_invalid_state;
  }
  s_npu_irq_state = k_ra8_npu_irq_armed;
  return k_ra8_ok;
}
 
RA8_ISR_SAFE
void ra8_npu_irq_handler(void* ctx)
{
  (void)ctx;
  /* Delegate register access to the already-cited status/clear accessors so the
   * ISR itself adds no new MMIO citation and stays a two-op hot path. */
  ra8_npu_status_t st = {};
  if (ra8_npu_read_status(&st) == k_ra8_ok) {
    if (st.fault) {
      s_npu_irq_state = k_ra8_npu_irq_fault;
    } else if (st.cmd_end) {
      s_npu_irq_state = k_ra8_npu_irq_done;
    } else {
      /* Spurious / early IRQ with neither terminal bit set: leave the latch
       * armed and re-wait; the clear below still de-asserts the line. */
    }
  }
  (void)ra8_npu_clear_irq();
}
 
ra8_err_t ra8_npu_wait_irq(void)
{
  RA8_VALIDATE_INIT(s_npu_initialized, s_tag, "npu_wait_irq: not initialized");
  if (s_npu_irq_state == k_ra8_npu_irq_idle) {
    ra8_log_error(s_tag, "npu_wait_irq: not armed");
    return k_ra8_err_invalid_state;
  }
  for (uint32_t i = 0U; i < k_ra8_npu_job_poll_iters; i++) {
    const ra8_npu_irq_state_t state = s_npu_irq_state;
    if (state == k_ra8_npu_irq_done) {
      return k_ra8_ok;
    }
    if (state == k_ra8_npu_irq_fault) {
      ra8_log_error(s_tag, "npu_wait_irq: fault latched");
      return k_ra8_err_hw_error;
    }
    internal_npu_wait_for_irq();
  }
  return k_ra8_err_hw_timeout;
}
 
#else
/* RA8D2 (no NPU): this translation unit is intentionally empty. */
typedef int ra8_npu_not_on_this_device_t;
#endif /* RA8_HAS_NPU */