ra8_spi_b.c

Go to the documentation of this file.

 
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_hw_err.h"
#include "ra8_log.h"
#include "ra8_mstp.h"
#include "ra8_spi.h"
#include "ra8_spi_regs.h"
 
static const char* s_tag = "SPI_B";
 
/* =============================================================================
 * Constants and lookup tables
 * =============================================================================
 */

static const ra8_mstp_t s_spi_mstp_table[k_ra8_spi_b_channel_count] = {
  k_ra8_mstp_spi0,
  k_ra8_mstp_spi1,
};

typedef enum : uint32_t {
  k_ra8_spi_b_poll_limit = 200000U, 
} ra8_spi_b_poll_t;

typedef enum : uint32_t {
  k_ra8_spi_b_default_baud_hz  = 1900000UL,   
  k_ra8_spi_b_default_pclka_hz = 125000000UL, 
} ra8_spi_b_default_t;

typedef enum : uint8_t {
  k_ra8_spi_b_bytes_per_unit_8  = 1U, 
  k_ra8_spi_b_bytes_per_unit_16 = 2U, 
  k_ra8_spi_b_bytes_per_unit_32 = 4U, 
} ra8_spi_b_unit_bytes_t;

typedef enum : uint32_t {
  k_ra8_spi_b_dummy_tx_8  = 0x000000FFUL, 
  k_ra8_spi_b_dummy_tx_16 = 0x0000FFFFUL, 
  k_ra8_spi_b_dummy_tx_32 = 0xFFFFFFFFUL, 
} ra8_spi_b_dummy_t;
 
/* =============================================================================
 * Per-channel runtime state
 * =============================================================================
 */

typedef struct {
  ra8_spi_complete_fn_t cb;          
  void*                 ctx;         
  bool                  initialized; 
} ra8_spi_state_t;

static ra8_spi_state_t s_spi_state[k_ra8_spi_b_channel_count];
 
/* =============================================================================
 * Bit-rate helper
 * =============================================================================
 */

RA8_INTERNAL static uint8_t internal_spbr(uint32_t baud_hz, uint32_t pclka_hz)
{
  if ((baud_hz == 0U) || (pclka_hz == 0U)) {
    return 0U;
  }
  const uint32_t divisor = 2U * baud_hz;
  const uint32_t n       = pclka_hz / divisor;
  if (n == 0U) {
    return 0U;
  }
  const uint32_t result = n - 1U;
  if (result > (uint32_t)k_ra8_spbr_max) {
    return k_ra8_spbr_max;
  }
  return (uint8_t)result;
}

RA8_INTERNAL static uint32_t internal_spcmd(const ra8_spi_cfg_t* cfg)
{
  uint32_t v = 0U;
  /* CPHA / CPOL match SPI mode 0..3. */
  if ((cfg->mode == k_ra8_spi_mode_1) || (cfg->mode == k_ra8_spi_mode_3)) {
    v |= k_ra8_spcmd_mask_cpha;
  }
  if ((cfg->mode == k_ra8_spi_mode_2) || (cfg->mode == k_ra8_spi_mode_3)) {
    v |= k_ra8_spcmd_mask_cpol;
  }
  if (cfg->lsb_first) {
    v |= k_ra8_spcmd_mask_lsbf;
  }
  /* 8-bit frame. */
  v |= ((uint32_t)k_ra8_spcmd_spb_8bit << k_ra8_spcmd_bit_spb_lo) & k_ra8_spcmd_mask_spb;
  return v;
}

RA8_INTERNAL static uint32_t internal_spcr_controller(void)
{
  uint32_t v = 0U;
  v |= k_ra8_spcr_mask_mstr;   /* Controller mode. */
  v |= k_ra8_spcr_mask_sckase; /* Auto-stop SCK.   */
  v |= k_ra8_spcr_mask_spe;    /* SPI enable.      */
  return v;
}

RA8_INTERNAL static ra8_err_t internal_wait_spsr(volatile r_spi_regs_t* reg, uint32_t flag_mask)
{
  /* Bounded busy-poll of SPSR. On the host test build the ra8_hw_err MMIO fault
   * seam (ra8_fake_mmio_*) drives this real loop to succeed-after-N or to time out,
   * so both the success and timeout legs are exercised on host (T1-01) rather
   * than compiled out behind an RA8_OFF_TARGET short-circuit. On target it is
   * a plain register spin with a fixed iteration bound. */
  return ra8_hw_wait_flag_set32(&reg->SPSR, flag_mask, (uint32_t)k_ra8_spi_b_poll_limit);
}
 
/* =============================================================================
 * Lifecycle: init / deinit
 * =============================================================================
 */

RA8_INTERNAL static void internal_spi_program_regs(volatile r_spi_regs_t* reg,
                                                   const ra8_spi_cfg_t*   cfg)
{
  /* HUM Ch 43.2.13 "SPSRC : SPI Status Clear Register" p 2905 */
  reg->SPSRC = k_ra8_spsrc_mask_all;
 
  /* HUM Ch 43.2.6 "SPCR3 : SPI Control Register 3" p 2891 */
  const uint8_t spbr = internal_spbr(cfg->baud_hz, cfg->pclka_hz);
  reg->SPCR3         = ((uint32_t)spbr << k_ra8_spcr3_bit_spbr) & k_ra8_spcr3_mask_spbr;
 
  /* HUM Ch 43.2.3 "SPDECR : SPI Delay Control Register" p 2883 */
  reg->SPDECR = 0U;
 
  /* SPCR2 only honors writes while SPE=0; SPLP2 (bit 17) is the */
  /* non-inverting loopback (rx = tx). */
  /* HUM Ch 43.2.4 "SPCR2 : SPI Control Register 2" p 2889 */
  reg->SPCR2 = (cfg->loopback ? (uint32_t)k_ra8_spcr2_mask_splp2 : 0U);
 
  /* HUM Ch 43.2.7 "SPCMDm : SPI Command Register" p 2893 */
  reg->SPCMD[0] = internal_spcmd(cfg);
 
  /* HUM Ch 43.2.10 "SPDCR : SPI Data Control Register" p 2896 */
  reg->SPDCR  = 0U;
  reg->SPDCR2 = 0U;
 
  /* HUM Ch 43.2.14 "SPFCR : SPI FIFO Clear Register" p 2906 */
  reg->SPFCR = k_ra8_spfcr_mask_spfrst;
 
  /* SPFRST drains residual FIFO contents through the shifter and */
  /* can leave SPRF set with a stale 0x00, so the first xfer8 */
  /* would race; re-clear SPSR right before the SPE assert. */
  /* HUM Ch 43.2.13 "SPSRC : SPI Status Clear Register" p 2905 */
  reg->SPSRC = k_ra8_spsrc_mask_all;
}
 
ra8_err_t ra8_spi_init(uint8_t channel, const ra8_spi_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg, s_tag, "spi_init: cfg");
  if (channel >= k_ra8_spi_b_channel_count) {
    return k_ra8_err_invalid_arg;
  }
  volatile r_spi_regs_t* reg = ra8_spi(channel);
  if (reg == nullptr) {           /* GCOVR_EXCL_BR_LINE -- bounded channel yields non-null reg */
    return k_ra8_err_invalid_arg; /* GCOVR_EXCL_LINE -- bounded channel yields non-null reg    */
  }
 
  /* HUM Ch 11.2.7 "MSTPCRB : Module Stop Control Register B" p 444 */
  const ra8_err_t mst_err = ra8_mstp_enable(s_spi_mstp_table[channel]);
  /* GCOVR_EXCL_BR_START -- MSTP HW readback */
  RA8_RETURN_ON_ERROR(mst_err, s_tag, "spi_init: mstp");
  /* GCOVR_EXCL_BR_STOP */
 
  /* Disable (SPE=0) before reprogramming. */
  /* HUM Ch 43.2.4 "SPCR : SPI Control Register" p 2884 */
  reg->SPCR = 0U;
 
  internal_spi_program_regs(reg, cfg);
 
  /* Re-enable with SPE+MSTR set. */
  /* HUM Ch 43.2.4 "SPCR : SPI Control Register" p 2884 */
  reg->SPCR = internal_spcr_controller();
 
  s_spi_state[channel].cb          = nullptr;
  s_spi_state[channel].ctx         = nullptr;
  s_spi_state[channel].initialized = true;
  ra8_log_info_val(s_tag, "spi_init channel", (uint32_t)channel);
  return k_ra8_ok;
}
 
ra8_err_t ra8_spi_deinit(uint8_t channel)
{
  if (channel >= k_ra8_spi_b_channel_count) {
    return k_ra8_err_invalid_arg;
  }
  volatile r_spi_regs_t* reg = ra8_spi(channel);
  if (reg == nullptr) {           /* GCOVR_EXCL_BR_LINE -- bounded channel yields non-null reg */
    return k_ra8_err_invalid_arg; /* GCOVR_EXCL_LINE -- bounded channel yields non-null reg    */
  }
  /* Clear SPE. */
  /* HUM Ch 43.2.4 "SPCR : SPI Control Register" p 2884 */
  reg->SPCR                        = 0U;
  s_spi_state[channel].cb          = nullptr;
  s_spi_state[channel].ctx         = nullptr;
  s_spi_state[channel].initialized = false;
  return ra8_mstp_disable(s_spi_mstp_table[channel]);
}
 
/* =============================================================================
 * Legacy polling shim
 * =============================================================================
 */
 
ra8_err_t ra8_spi_controller_init(uint8_t channel)
{
  const ra8_spi_cfg_t cfg = {
    .baud_hz   = k_ra8_spi_b_default_baud_hz,
    .pclka_hz  = k_ra8_spi_b_default_pclka_hz,
    .mode      = k_ra8_spi_mode_0,
    .lsb_first = false,
  };
  /* The pre-existing test contract distinguishes "channel out of range"
   * with k_ra8_err_null_ptr (because ra8_spi() returns nullptr). Preserve. */
  if (ra8_spi(channel) == nullptr) {
    return k_ra8_err_null_ptr;
  }
  return ra8_spi_init(channel, &cfg);
}
 
ra8_err_t ra8_spi_xfer8(uint8_t channel, uint8_t tx, uint8_t* rx)
{
  volatile r_spi_regs_t* reg = ra8_spi(channel);
  RA8_CHECK_NULL_PTR(reg, s_tag, "channel out of range");
 
  /* Wait for TX buffer empty. */
  /* HUM Ch 43.2.9 "SPSR : SPI Status Register" p 2898 */
  ra8_err_t err = internal_wait_spsr(reg, k_ra8_spsr_mask_sptef);
  if (err != k_ra8_ok) {
    return err;
  }
 
  /* Push TX byte. */
  /* HUM Ch 43.2.2 "SPDR : SPI Data Register" p 2881 */
  reg->SPDR = (uint32_t)tx;
 
  /* Clear TX-empty flag (write-1). */
  /* HUM Ch 43.2.13 "SPSRC : SPI Status Clear Register" p 2905 */
  reg->SPSRC = k_ra8_spsrc_mask_sptefc;
 
  /* Wait for RX buffer full. */
  /* HUM Ch 43.2.9 "SPSR : SPI Status Register" p 2898 */
  err = internal_wait_spsr(reg, k_ra8_spsr_mask_sprf);
  if (err != k_ra8_ok) {
    return err;
  }
 
  /* Drain RX byte. */
  /* HUM Ch 43.2.2 "SPDR : SPI Data Register" p 2881 */
  const uint8_t received = (uint8_t)reg->SPDR;
 
  /* Clear RX-full flag. */
  /* HUM Ch 43.2.13 "SPSRC : SPI Status Clear Register" p 2905 */
  reg->SPSRC = k_ra8_spsrc_mask_sprfc;
 
  if (rx != nullptr) {
    *rx = received;
  }
  return k_ra8_ok;
}
 
/* =============================================================================
 * Multi-byte / multi-width polling transfers
 * =============================================================================
 */

RA8_INTERNAL static ra8_err_t internal_unit_bytes(ra8_spi_bit_width_t bit_width, uint8_t* out_bytes)
{
  switch (bit_width) {
    case k_ra8_spi_width_8:
      *out_bytes = k_ra8_spi_b_bytes_per_unit_8;
      return k_ra8_ok;
    case k_ra8_spi_width_16:
      *out_bytes = k_ra8_spi_b_bytes_per_unit_16;
      return k_ra8_ok;
    case k_ra8_spi_width_32:
      *out_bytes = k_ra8_spi_b_bytes_per_unit_32;
      return k_ra8_ok;
    default:
      return k_ra8_err_invalid_arg;
  }
}

RA8_INTERNAL static void internal_apply_bit_width(volatile r_spi_regs_t* reg,
                                                  ra8_spi_bit_width_t    bit_width)
{
  /* HUM Ch 43.2.7 "SPCMDm : SPI Command Register" p 2893 */
  uint32_t spcmd0 = reg->SPCMD[0] & ~k_ra8_spcmd_mask_spb;
  spcmd0 |= ((uint32_t)bit_width << k_ra8_spcmd_bit_spb_lo) & k_ra8_spcmd_mask_spb;
  reg->SPCMD[0] = spcmd0;
}

RA8_INTERNAL static void internal_push_unit(volatile r_spi_regs_t* reg,
                                            const void*            tx,
                                            uint32_t               idx,
                                            ra8_spi_bit_width_t    bit_width)
{
  uint32_t value = 0U;
  if (tx == nullptr) {
    if (bit_width == k_ra8_spi_width_32) {
      value = k_ra8_spi_b_dummy_tx_32;
    } else if (bit_width == k_ra8_spi_width_16) {
      value = k_ra8_spi_b_dummy_tx_16;
    } else {
      value = k_ra8_spi_b_dummy_tx_8;
    }
  } else if (bit_width == k_ra8_spi_width_32) {
    value = ((const uint32_t*)tx)[idx];
  } else if (bit_width == k_ra8_spi_width_16) {
    value = (uint32_t)((const uint16_t*)tx)[idx];
  } else {
    value = (uint32_t)((const uint8_t*)tx)[idx];
  }
  /* HUM Ch 43.2.2 "SPDR : SPI Data Register" p 2881 */
  reg->SPDR = value;
}

RA8_INTERNAL static void internal_pop_unit(volatile const r_spi_regs_t* reg,
                                           void*                        rx,
                                           uint32_t                     idx,
                                           ra8_spi_bit_width_t          bit_width)
{
  /* HUM Ch 43.2.2 "SPDR : SPI Data Register" p 2881 */
  const uint32_t value = reg->SPDR;
  if (rx == nullptr) {
    return;
  }
  if (bit_width == k_ra8_spi_width_32) {
    ((uint32_t*)rx)[idx] = value;
  } else if (bit_width == k_ra8_spi_width_16) {
    ((uint16_t*)rx)[idx] = (uint16_t)value;
  } else {
    ((uint8_t*)rx)[idx] = (uint8_t)value;
  }
}

RA8_INTERNAL static ra8_err_t internal_xfer_common(uint8_t             channel,
                                                   const void*         tx,
                                                   void*               rx,
                                                   uint32_t            len,
                                                   ra8_spi_bit_width_t bit_width)
{
  if (channel >= k_ra8_spi_b_channel_count) {
    return k_ra8_err_invalid_arg;
  }
  uint8_t         bytes_per_unit = 0U;
  const ra8_err_t bw_err         = internal_unit_bytes(bit_width, &bytes_per_unit);
  if (bw_err != k_ra8_ok) {
    return bw_err;
  }
  if (len == 0U) {
    return k_ra8_ok;
  }
  // mcdc-deactivated: TU-local helper internal_xfer_common null-pair guard; the public-API ra8_spi_b_transfer entry validates that at least one of (tx, rx) is non-NULL before calling this helper, so the AND's two conditions cannot both be true on any reachable path -- defensive depth guard only.
  if ((tx == nullptr) && (rx == nullptr)) {
    return k_ra8_err_null_ptr;
  }
  volatile r_spi_regs_t* reg = ra8_spi(channel);
  if (reg == nullptr) {           /* GCOVR_EXCL_BR_LINE -- bounded channel yields non-null reg */
    return k_ra8_err_invalid_arg; /* GCOVR_EXCL_LINE -- bounded channel yields non-null reg    */
  }
 
  /* Lock SPCMD0.SPB to the requested width before pushing data. */
  internal_apply_bit_width(reg, bit_width);
  /* Suppress unused warning when callers never pass a 32-bit frame. */
  (void)bytes_per_unit;
 
  for (uint32_t i = 0U; i < len; i++) {
    /* HUM Ch 43.2.9 "SPSR : SPI Status Register" p 2898 */
    ra8_err_t err = internal_wait_spsr(reg, k_ra8_spsr_mask_sptef);
    if (err != k_ra8_ok) {
      return err;
    }
    internal_push_unit(reg, tx, i, bit_width);
    /* HUM Ch 43.2.13 "SPSRC : SPI Status Clear Register" p 2905 */
    reg->SPSRC = k_ra8_spsrc_mask_sptefc;
 
    err = internal_wait_spsr(reg, k_ra8_spsr_mask_sprf);
    if (err != k_ra8_ok) {
      return err;
    }
    internal_pop_unit(reg, rx, i, bit_width);
    /* HUM Ch 43.2.13 "SPSRC : SPI Status Clear Register" p 2905 */
    reg->SPSRC = k_ra8_spsrc_mask_sprfc;
  }
  return k_ra8_ok;
}
 
ra8_err_t
ra8_spi_write(uint8_t channel, const void* tx, uint32_t len, ra8_spi_bit_width_t bit_width)
{
  if ((tx == nullptr) && (len > 0U)) {
    return k_ra8_err_null_ptr;
  }
  return internal_xfer_common(channel, tx, nullptr, len, bit_width);
}
 
ra8_err_t ra8_spi_read(uint8_t channel, void* rx, uint32_t len, ra8_spi_bit_width_t bit_width)
{
  if ((rx == nullptr) && (len > 0U)) {
    return k_ra8_err_null_ptr;
  }
  return internal_xfer_common(channel, nullptr, rx, len, bit_width);
}
 
ra8_err_t ra8_spi_write_read(uint8_t             channel,
                             const void*         tx,
                             void*               rx,
                             uint32_t            len,
                             ra8_spi_bit_width_t bit_width)
{
  if (len > 0U) {
    if (tx == nullptr) {
      return k_ra8_err_null_ptr;
    }
    if (rx == nullptr) {
      return k_ra8_err_null_ptr;
    }
  }
  return internal_xfer_common(channel, tx, rx, len, bit_width);
}
 
/* =============================================================================
 * Runtime reconfigure
 * =============================================================================
 */
 
ra8_err_t ra8_spi_set_clock(uint8_t channel, uint32_t baud_hz, uint32_t pclka_hz)
{
  if (channel >= k_ra8_spi_b_channel_count) {
    return k_ra8_err_invalid_arg;
  }
  volatile r_spi_regs_t* reg = ra8_spi(channel);
  if (reg == nullptr) {           /* GCOVR_EXCL_BR_LINE -- bounded channel yields non-null reg */
    return k_ra8_err_invalid_arg; /* GCOVR_EXCL_LINE -- bounded channel yields non-null reg    */
  }
  if (baud_hz == 0U) {
    return k_ra8_err_invalid_arg;
  }
  /* Update SPCR3.SPBR[15:8]. */
  /* HUM Ch 43.2.6 "SPCR3 : SPI Control Register 3" p 2891 */
  const uint8_t  spbr     = internal_spbr(baud_hz, pclka_hz);
  const uint32_t spcr3_in = reg->SPCR3 & ~k_ra8_spcr3_mask_spbr;
  reg->SPCR3 = spcr3_in | (((uint32_t)spbr << k_ra8_spcr3_bit_spbr) & k_ra8_spcr3_mask_spbr);
  return k_ra8_ok;
}
 
/* =============================================================================
 * Error status
 * =============================================================================
 */
 
ra8_err_t ra8_spi_get_errors(uint8_t channel, uint8_t* out_mask)
{
  RA8_CHECK_NULL_PTR(out_mask, s_tag, "spi get_errors");
  if (channel >= k_ra8_spi_b_channel_count) {
    return k_ra8_err_invalid_arg;
  }
  volatile const r_spi_regs_t* reg = ra8_spi(channel);
  if (reg == nullptr) {           /* GCOVR_EXCL_BR_LINE -- bounded channel yields non-null reg */
    return k_ra8_err_invalid_arg; /* GCOVR_EXCL_LINE -- bounded channel yields non-null reg    */
  }
  const uint32_t ss = reg->SPSR;
  uint8_t        m  = k_ra8_spi_err_none;
  if ((ss & k_ra8_spsr_mask_ovrf) != 0U) {
    m |= k_ra8_spi_err_overrun;
  }
  if ((ss & k_ra8_spsr_mask_modf) != 0U) {
    m |= k_ra8_spi_err_mode;
  }
  if ((ss & k_ra8_spsr_mask_perf) != 0U) {
    m |= k_ra8_spi_err_parity;
  }
  if ((ss & k_ra8_spsr_mask_udrf) != 0U) {
    m |= k_ra8_spi_err_underrun;
  }
  *out_mask = m;
  return k_ra8_ok;
}
 
ra8_err_t ra8_spi_clear_errors(uint8_t channel)
{
  if (channel >= k_ra8_spi_b_channel_count) {
    return k_ra8_err_invalid_arg;
  }
  volatile r_spi_regs_t* reg = ra8_spi(channel);
  if (reg == nullptr) {           /* GCOVR_EXCL_BR_LINE -- bounded channel yields non-null reg */
    return k_ra8_err_invalid_arg; /* GCOVR_EXCL_LINE -- bounded channel yields non-null reg    */
  }
  /* SPI_B status flags clear via SPSRC (write-1). */
  /* HUM Ch 43.2.13 "SPSRC : SPI Status Clear Register" p 2905 */
  reg->SPSRC = k_ra8_spsr_mask_errs;
  return k_ra8_ok;
}
 
ra8_err_t ra8_spi_attach_transfer_handler(uint8_t channel, ra8_spi_complete_fn_t fn, void* ctx)
{
  if (channel >= k_ra8_spi_b_channel_count) {
    return k_ra8_err_invalid_arg;
  }
  s_spi_state[channel].cb  = fn;
  s_spi_state[channel].ctx = ctx;
  return k_ra8_ok;
}
 
/* =============================================================================
 * Power transition
 * =============================================================================
 */
 
ra8_err_t ra8_spi_enter_stop(uint8_t channel)
{
  if (channel >= k_ra8_spi_b_channel_count) {
    return k_ra8_err_invalid_arg;
  }
  volatile r_spi_regs_t* reg = ra8_spi(channel);
  if (reg == nullptr) {           /* GCOVR_EXCL_BR_LINE -- bounded channel yields non-null reg */
    return k_ra8_err_invalid_arg; /* GCOVR_EXCL_LINE -- bounded channel yields non-null reg    */
  }
  /* Clear SPE. */
  /* HUM Ch 43.2.4 "SPCR : SPI Control Register" p 2884 */
  reg->SPCR = 0U;
  return ra8_mstp_disable(s_spi_mstp_table[channel]);
}
 
ra8_err_t ra8_spi_exit_stop(uint8_t channel)
{
  if (channel >= k_ra8_spi_b_channel_count) {
    return k_ra8_err_invalid_arg;
  }
  return ra8_mstp_enable(s_spi_mstp_table[channel]);
}
 
/* =============================================================================
 * ISR dispatch -- placeholder; real IRQ routing lands with NVIC wiring.
 * =============================================================================
 */
 
RA8_ISR_SAFE
void ra8_spi_dispatch_spti(uint8_t channel)
{
  if (channel >= k_ra8_spi_b_channel_count) {
    return;
  }
  (void)s_spi_state[channel].cb;
}
 
RA8_ISR_SAFE
void ra8_spi_dispatch_spri(uint8_t channel)
{
  if (channel >= k_ra8_spi_b_channel_count) {
    return;
  }
  (void)s_spi_state[channel].cb;
}
 
RA8_ISR_SAFE
void ra8_spi_dispatch_spei(uint8_t channel)
{
  if (channel >= k_ra8_spi_b_channel_count) {
    return;
  }
  uint8_t mask = 0U;
  (void)ra8_spi_get_errors(channel, &mask);
  (void)ra8_spi_clear_errors(channel);
  const ra8_spi_complete_fn_t cb = s_spi_state[channel].cb;
  if ((mask != 0U) && (cb != nullptr)) {
    cb(s_spi_state[channel].ctx, mask);
  }
}