ra8_sci.c

Go to the documentation of this file.

 
#include "ra8_sci.h"
 
#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_mstp_regs.h"
#include "ra8_register_guard.h"
#include "ra8_sci_internal.h"
#include "ra8_sci_regs.h"
 
static const char* s_tag = "SCI";
 
/* =============================================================================
 * Per-channel state
 * =============================================================================
 */

ra8_sci_state_t s_sci_state[k_ra8_sci_channel_count_val];

static const ra8_mstp_t s_mstp_table[k_ra8_sci_channel_count_val] = {
  k_ra8_mstp_sci0,
  k_ra8_mstp_sci1,
  k_ra8_mstp_sci2,
  k_ra8_mstp_sci3,
  k_ra8_mstp_sci4,
  k_ra8_mstp_sci5,
  k_ra8_mstp_sci6,
  k_ra8_mstp_sci7,
  k_ra8_mstp_sci8,
  k_ra8_mstp_sci9,
};
 
/* =============================================================================
 * Internal helpers
 * =============================================================================
 */

RA8_HW_REGISTER_ACCESS
RA8_INTERNAL static inline volatile r_sci_regs_t* internal_reg(uint8_t channel)
{
  if (channel > k_ra8_sci_channel_max_index) {
    return nullptr;
  }
  return ra8_sci(channel);
}

RA8_INTERNAL static uint8_t internal_brr(uint32_t pclk_hz, uint32_t baud)
{
  if ((baud == 0U) || (pclk_hz == 0U)) {
    return 0U;
  }
  const uint32_t divisor = k_ra8_sci_brr_async_divisor * baud;
  const uint32_t n       = pclk_hz / divisor;
  if (n == 0U) {
    return 0U;
  }
  return (uint8_t)(n - 1U);
}

RA8_INTERNAL static uint32_t internal_ccr1(const ra8_sci_cfg_t* cfg)
{
  uint32_t ccr1 = (1U << k_ra8_sci_ccr1_bit_spb2dt) | (1U << k_ra8_sci_ccr1_bit_spb2io);
  if (cfg->parity != k_ra8_sci_parity_none) {
    ccr1 |= (1U << k_ra8_sci_ccr1_bit_pe);
    if (cfg->parity == k_ra8_sci_parity_odd) {
      ccr1 |= (1U << k_ra8_sci_ccr1_bit_pm);
    }
  }
  return ccr1;
}

RA8_INTERNAL static uint32_t internal_ccr3(const ra8_sci_cfg_t* cfg)
{
  /* LSBF = 1 (LSB-first) is the UART standard wire order. SCI_B's
   * reset state is MSB-first; without this bit the host receives
   * each byte bit-reversed (e.g. 'h' = 0x68 transmits as 0x16). FSP
   * r_sci_b_uart sets LSBF unconditionally for async configs.
   *
   * BPEN = 1 (Synchronizer Bypass Enable) is required when the bus
   * clock (PCLK) is also used as the operation clock (TCLK) -- which
   * is what we're doing in async mode with the on-chip baud-rate
   * generator on the synchronized clock. Without BPEN the SCI's
   * shift state machine waits forever for an independent SCICLK
   * edge that never arrives, and the chip looks alive at the
   * register level (TDR latches, CCR0.TE=1) but never advances --
   * CSR.TDRE and CSR.TEND stay 0 indefinitely. HUM Ch 38.2.8 p 2207
   * "BPEN bit" is the authoritative source. */
  uint32_t ccr3 = (1U << k_ra8_sci_ccr3_bit_lsbf) | (1U << k_ra8_sci_ccr3_bit_bpen);
 
  /* MOD = 000 (Asynchronous) -- already 0. */
 
  /* CHR[1:0]. 8-bit -> 10b, 7-bit -> 11b. */
  if (cfg->data_bits == k_ra8_sci_data_7) {
    ccr3 |= (k_ra8_sci_ccr3_chr_7bit << k_ra8_sci_ccr3_shift_chr);
  } else {
    ccr3 |= (k_ra8_sci_ccr3_chr_8bit << k_ra8_sci_ccr3_shift_chr);
  }
 
  /* STP -- 1 = 2 stop bits. */
  if (cfg->stop_bits == k_ra8_sci_stop_2) {
    ccr3 |= (1U << k_ra8_sci_ccr3_bit_stp);
  }
 
  return ccr3;
}

RA8_INTERNAL static void internal_clear_csr_flags(volatile r_sci_regs_t* reg)
{
  /* HUM Ch 38.2.24 "CFCLR : Common Flag Clear Register", p 2238 --
   * one write clears ERS / DCMF / DPER / DFER / ORER / MFF / PER /
   * FER / TDRE / RDRF in CSR. */
  reg->CFCLR = k_ra8_sci_cfclr_default;
 
  /* HUM Ch 38.2.26 "FFCLR : FIFO Flag Clear Register", p 2239 --
   * clears FRSR.DR (the only defined W1C bit). */
  reg->FFCLR = k_ra8_sci_ffclr_default;
}

RA8_INTERNAL static ra8_err_t internal_wait_tx_end(volatile r_sci_regs_t* reg)
{
  /* HUM Ch 38.2.17 "CSR : Common Status Register", p 2225 -- TEND (bit 30) goes
   * high when both the data register and the shift register are empty. The
   * ra8_fake_mmio host fault seam drives this real poll on the unit-test build, so
   * the success and timeout legs run on host (T1-01) rather than short-circuit. */
  const uint32_t mask = (1U << k_ra8_sci_csr_bit_tend);
  return ra8_hw_wait_flag_set32(&reg->CSR, mask, k_ra8_hw_budget_medium);
}

RA8_INTERNAL static uint32_t internal_ccr2(const ra8_sci_cfg_t* cfg)
{
  const uint8_t brr  = internal_brr(cfg->pclk_hz, cfg->baud);
  uint32_t      ccr2 = 0U;
  ccr2 |= ((uint32_t)brr << k_ra8_sci_ccr2_shift_brr);
  /* MDDR reset value -- keep modulation off. */
  ccr2 |= (k_ra8_sci_mddr_default << k_ra8_sci_ccr2_shift_mddr);
  return ccr2;
}
 
/* =============================================================================
 * Public API
 * =============================================================================
 */

RA8_INTERNAL static void internal_program_ccr_bank(volatile r_sci_regs_t* reg,
                                                   const ra8_sci_cfg_t*   cfg)
{
  /* HUM Ch 38.2.5 "CCR0 : Common Control Register 0", p 2182 -- disable
   * TX/RX/IE bits before reconfiguring CCR1..CCR4 and FCR. */
  reg->CCR0 = 0U;
 
  /* HUM Ch 38.2.11 "FCR : FIFO Control Register", p 2215 -- non-FIFO
   * polling mode for the bring-up demo: TFRST/RFRST cleared, all
   * trigger numbers reset to 0. */
  reg->FCR = 0U;
 
  /* HUM Ch 38.2.6 "CCR1 : Common Control Register 1", p 2185 */
  reg->CCR1 = internal_ccr1(cfg);
 
  /* HUM Ch 38.2.8 "CCR3 : Common Control Register 3", p 2203 -- mode
   * + framing must be programmed before TE/RE go high. */
  reg->CCR3 = internal_ccr3(cfg);
 
  /* HUM Ch 38.2.7 "CCR2 : Common Control Register 2", p 2189 -- BRR
   * derived from cfg->pclk_hz and cfg->baud. */
  reg->CCR2 = internal_ccr2(cfg);
 
  /* HUM Ch 38.2.9 "CCR4 : Common Control Register 4", p 2210 -- no
   * sample / transmit timing adjustment for async UART. */
  reg->CCR4 = 0U;
 
  /* HUM Ch 38.2.24 "CFCLR : Common Flag Clear Register", p 2238 +
   * HUM Ch 38.2.26 "FFCLR : FIFO Flag Clear Register", p 2239 -- drop
   * any latches inherited from a previous boot before TX/RX go live.
   * Mirrors FSP r_sci_b_uart.c. */
  internal_clear_csr_flags(reg);
}
 
ra8_err_t ra8_sci_init(uint8_t channel, const ra8_sci_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg, s_tag, "sci_init: cfg");
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
 
  /* HUM Ch 11.2.7 "MSTPCRB : Module Stop Control Register B", p 445 */
  const ra8_err_t mst_err = ra8_mstp_enable(s_mstp_table[channel]);
  if (mst_err != k_ra8_ok) {
    ra8_log_error_val(s_tag, "sci_init: mstp enable failed", (uint32_t)mst_err);
    return k_ra8_err_hw_init_failed;
  }
 
  internal_program_ccr_bank(reg, cfg);
 
  /* HUM Ch 38.2.5 "CCR0 : Common Control Register 0", p 2182 -- enable
   * transmitter and receiver. Interrupt-enable bits are toggled
   * separately by ra8_sci_attach_{rx,tx}_handler. */
  reg->CCR0 = (1U << k_ra8_sci_ccr0_bit_te) | (1U << k_ra8_sci_ccr0_bit_re);
 
  s_sci_state[channel].initialized = true;
  s_sci_state[channel].tx_buf      = nullptr;
  s_sci_state[channel].tx_len      = 0U;
  s_sci_state[channel].tx_idx      = 0U;
  s_sci_state[channel].rx_buf      = nullptr;
  s_sci_state[channel].rx_len      = 0U;
  s_sci_state[channel].rx_idx      = 0U;
  ra8_log_info_val(s_tag, "sci_init channel", (uint32_t)channel);
  return k_ra8_ok;
}
 
ra8_err_t ra8_sci_deinit(uint8_t channel)
{
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
 
  /* Drop CCR0 and tear the async descriptor down atomically w.r.t. the
   * TXI/RXI ISR. Without the mask, a pending interrupt can still observe a
   * non-zero tx_len/rx_len after CCR0 is cleared and then dereference the
   * buffer pointer this path is nulling -- a NULL deref in interrupt
   * context. Mirrors the ra8_sci_abort teardown. */
  ra8_register_guard_t guard;
  ra8_register_guard_enter(&guard);
  /* HUM Ch 38.2.5 "CCR0 : Common Control Register 0", p 2182 */
  reg->CCR0                        = 0U;
  s_sci_state[channel].rx_fn       = nullptr;
  s_sci_state[channel].rx_ctx      = nullptr;
  s_sci_state[channel].tx_fn       = nullptr;
  s_sci_state[channel].tx_ctx      = nullptr;
  s_sci_state[channel].initialized = false;
  s_sci_state[channel].tx_buf      = nullptr;
  s_sci_state[channel].tx_len      = 0U;
  s_sci_state[channel].tx_idx      = 0U;
  s_sci_state[channel].rx_buf      = nullptr;
  s_sci_state[channel].rx_len      = 0U;
  s_sci_state[channel].rx_idx      = 0U;
  ra8_register_guard_exit(&guard);
  return ra8_mstp_disable(s_mstp_table[channel]);
}
 
/* ---- Polling TX / RX -------------------------------------------------- */
 
ra8_err_t ra8_sci_putc_polling(uint8_t channel, uint8_t byte)
{
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 38.2.17 "CSR : Common Status Register", p 2225 -- spin
   * until TDRE = 1 (transmit data register empty). */
  const uint32_t  mask = (1U << k_ra8_sci_csr_bit_tdre);
  const ra8_err_t werr = ra8_hw_wait_flag_set32(&reg->CSR, mask, k_ra8_hw_budget_medium);
  if (werr != k_ra8_ok) {
    return werr;
  }
  /* HUM Ch 38.2.3 "TDR : Transmit Data Register", p 2181 -- write to
   * TDAT[7:0] (low 8 bits of TDR) launches one frame in non-FIFO
   * 8-bit async mode. */
  reg->TDR = (uint32_t)byte;
  return k_ra8_ok;
}
 
ra8_err_t ra8_sci_getc_polling(uint8_t channel, uint8_t* out_byte)
{
  RA8_CHECK_NULL_PTR(out_byte, s_tag, "getc: out_byte");
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 38.2.17 "CSR : Common Status Register", p 2225 -- spin
   * until RDRF = 1 (receive data full). */
  const uint32_t  mask = (1U << k_ra8_sci_csr_bit_rdrf);
  const ra8_err_t werr = ra8_hw_wait_flag_set32(&reg->CSR, mask, k_ra8_hw_budget_medium);
  if (werr != k_ra8_ok) {
    return werr;
  }
  /* HUM Ch 38.2.2 "RDR : Receive Data Register", p 2180 -- RDAT[7:0]
   * holds the byte just received in 8-bit async mode. */
  *out_byte = (uint8_t)(reg->RDR & k_ra8_sci_rdr_mask_data8);
  return k_ra8_ok;
}
 
ra8_err_t ra8_sci_write_polling(uint8_t channel, const uint8_t* data, uint32_t len)
{
  if ((data == nullptr) && (len != 0U)) {
    return k_ra8_err_null_ptr;
  }
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  for (uint32_t i = 0U; i < len; ++i) {
    const ra8_err_t err = ra8_sci_putc_polling(channel, data[i]);
    if (err != k_ra8_ok) {
      return err;
    }
  }
  /* HUM Ch 38.2.17 "CSR : Common Status Register", p 2225 -- TDRE
   * goes high as soon as TDR latches into the shifter, but the byte
   * may still be on the wire. Wait for TEND so the call only returns
   * after the last frame is fully transmitted. Mirrors FSP
   * r_sci_b_uart.c (`R_SCI_B_UART_Close` blocks on TEND for the
   * same reason before dropping TE). */
  if (len != 0U) {
    return internal_wait_tx_end(reg);
  }
  return k_ra8_ok;
}
 
ra8_err_t ra8_sci_flush(uint8_t channel)
{
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 38.2.17 "CSR : Common Status Register", p 2225 -- block on
   * TEND so the shift register has fully drained before the caller
   * proceeds (typically into a panic_halt / WFI that would gate the
   * SCI clock and discard in-flight bytes). */
  return internal_wait_tx_end(reg);
}
 
/* ---- Interrupt handler attach ---------------------------------------- */
 
ra8_err_t ra8_sci_attach_rx_handler(uint8_t channel, ra8_sci_rx_fn_t fn, void* ctx)
{
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  /* The RXI ISR reads rx_fn/rx_ctx and read-modify-writes CCR0; mask it
   * while we publish the handler and toggle RIE so neither a torn callback
   * pointer nor a lost CCR0 update is observable. */
  const uint32_t       rie = (1U << k_ra8_sci_ccr0_bit_rie);
  ra8_register_guard_t guard;
  ra8_register_guard_enter(&guard);
  s_sci_state[channel].rx_fn  = fn;
  s_sci_state[channel].rx_ctx = ctx;
  /* HUM Ch 38.2.5 "CCR0 : Common Control Register 0", p 2182 -- toggle
   * RIE (bit 16). */
  if (fn != nullptr) {
    reg->CCR0 = reg->CCR0 | rie;
  } else {
    reg->CCR0 = reg->CCR0 & ~rie;
  }
  ra8_register_guard_exit(&guard);
  return k_ra8_ok;
}
 
ra8_err_t ra8_sci_attach_tx_handler(uint8_t channel, ra8_sci_tx_fn_t fn, void* ctx)
{
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  /* The TXI ISR reads tx_fn/tx_ctx and read-modify-writes CCR0; mask it
   * while we publish the handler and toggle TIE. */
  const uint32_t       tie = (1U << k_ra8_sci_ccr0_bit_tie);
  ra8_register_guard_t guard;
  ra8_register_guard_enter(&guard);
  s_sci_state[channel].tx_fn  = fn;
  s_sci_state[channel].tx_ctx = ctx;
  /* HUM Ch 38.2.5 "CCR0 : Common Control Register 0", p 2182 -- toggle
   * TIE (bit 20). */
  if (fn != nullptr) {
    reg->CCR0 = reg->CCR0 | tie;
  } else {
    reg->CCR0 = reg->CCR0 & ~tie;
  }
  ra8_register_guard_exit(&guard);
  return k_ra8_ok;
}
 
/* ---- Error status ----------------------------------------------------- */
 
ra8_err_t ra8_sci_get_errors(uint8_t channel, uint8_t* out_mask)
{
  RA8_CHECK_NULL_PTR(out_mask, s_tag, "get_errors: out");
  volatile const r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  uint8_t mask = k_ra8_sci_err_none;
  /* HUM Ch 38.2.17 "CSR : Common Status Register", p 2225 -- read the
   * three error flags out of the 32-bit status word. */
  const uint32_t csr = reg->CSR;
  if ((csr & (1U << k_ra8_sci_csr_bit_orer)) != 0U) {
    mask |= k_ra8_sci_err_overrun;
  }
  if ((csr & (1U << k_ra8_sci_csr_bit_fer)) != 0U) {
    mask |= k_ra8_sci_err_framing;
  }
  if ((csr & (1U << k_ra8_sci_csr_bit_per)) != 0U) {
    mask |= k_ra8_sci_err_parity;
  }
  *out_mask = mask;
  return k_ra8_ok;
}
 
ra8_err_t ra8_sci_clear_errors(uint8_t channel)
{
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 38.2.24 "CFCLR : Common Flag Clear Register", p 2238 --
   * write-1-to-clear lines for ORER / FER / PER. */
  reg->CFCLR = (1U << k_ra8_sci_cfclr_bit_orerc) | (1U << k_ra8_sci_cfclr_bit_ferc) |
               (1U << k_ra8_sci_cfclr_bit_perc);
  return k_ra8_ok;
}
 
/* ---- Runtime reconfigure --------------------------------------------- */
 
ra8_err_t ra8_sci_set_baud(uint8_t channel, uint32_t baud, uint32_t pclk_hz)
{
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  if (baud == 0U) {
    return k_ra8_err_invalid_arg;
  }
  const uint8_t brr = internal_brr(pclk_hz, baud);
  /* Guard the CCR2 read-modify-write against any SCI ISR that stores to
   * this channel's control registers: an interrupt landing between the
   * CCR2 read and the write-back would otherwise drop the freshly merged
   * BRR field (lost update). The mask is a no-op when uncontended, so the
   * final CCR2 value is byte-identical to the unguarded path. */
  ra8_register_guard_t guard;
  ra8_register_guard_enter(&guard);
  /* HUM Ch 38.2.7 "CCR2 : Common Control Register 2", p 2189 -- BRR
   * lives in CCR2[15:8]; preserve the rest of CCR2. */
  uint32_t v = reg->CCR2;
  v &= ~k_ra8_sci_ccr2_mask_brr_field;
  v |= ((uint32_t)brr << k_ra8_sci_ccr2_shift_brr);
  reg->CCR2 = v;
  ra8_register_guard_exit(&guard);
  return k_ra8_ok;
}
 
/* ---- Power transition ------------------------------------------------- */
 
ra8_err_t ra8_sci_enter_stop(uint8_t channel)
{
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 38.2.5 "CCR0 : Common Control Register 0", p 2182 */
  reg->CCR0 = 0U;
  return ra8_mstp_disable(s_mstp_table[channel]);
}
 
ra8_err_t ra8_sci_exit_stop(uint8_t channel)
{
  if (channel > k_ra8_sci_channel_max_index) {
    return k_ra8_err_invalid_arg;
  }
  return ra8_mstp_enable(s_mstp_table[channel]);
}
 
/* ---- Async byte-stream TX / RX (FSP Read/Write parity) --------------- */

typedef enum : uint16_t {
  k_ra8_sci_baud_brr_max    = 255U, 
  k_ra8_sci_baud_cks_max    = 3U,   
  k_ra8_sci_baud_div_step   = 4U,   
  k_ra8_sci_baud_n0_divisor = 32U,  
} ra8_sci_baud_calc_const_t;
 
ra8_err_t
ra8_sci_baud_calculate(uint32_t baud, uint32_t pclk_hz, uint16_t* brr_out, uint8_t* clk_div_out)
{
  RA8_CHECK_NULL_PTR(brr_out, s_tag, "baud_calc: brr_out");
  RA8_CHECK_NULL_PTR(clk_div_out, s_tag, "baud_calc: clk_div_out");
  if ((baud == 0U) || (pclk_hz == 0U)) {
    return k_ra8_err_invalid_arg;
  }
 
  /* HUM Ch 38.2.7 "CCR2 : Common Control Register 2", p 2189 -- walk
   * CKS = 0..3 and pick the smallest divider that yields a BRR <= 255.
   * Mirrors the FSP `R_SCI_B_UART_BaudCalculate` outer loop
   * (r_sci_b_uart.c) but without the bit-rate-modulation pass
   * since the project always programs BRME=0. */
  uint64_t divisor = (uint64_t)k_ra8_sci_baud_n0_divisor;
  for (uint8_t n = 0U; n <= (uint8_t)k_ra8_sci_baud_cks_max; ++n) {
    const uint64_t denom    = divisor * (uint64_t)baud;
    const uint64_t quotient = (uint64_t)pclk_hz / denom;
    if (quotient > 0U) {
      const uint64_t candidate = quotient - 1U;
      if (candidate <= (uint64_t)k_ra8_sci_baud_brr_max) {
        *brr_out     = (uint16_t)candidate;
        *clk_div_out = n;
        return k_ra8_ok;
      }
    }
    divisor *= (uint64_t)k_ra8_sci_baud_div_step;
  }
  return k_ra8_err_invalid_arg;
}
 
ra8_err_t ra8_sci_write(uint8_t channel, const uint8_t* data, uint32_t len)
{
  if ((data == nullptr) && (len != 0U)) {
    return k_ra8_err_null_ptr;
  }
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  if (!s_sci_state[channel].initialized) {
    return k_ra8_err_invalid_arg;
  }
  if (s_sci_state[channel].tx_len != 0U) {
    return k_ra8_err_busy;
  }
  if (len == 0U) {
    return k_ra8_ok;
  }
  /* Publish the async TX descriptor and arm TIE atomically w.r.t. the
   * TXI ISR: it tests tx_len then dereferences tx_buf, so a torn publish
   * (or a CCR0 RMW racing the ISR's TIE clear) must not be observable. */
  ra8_register_guard_t guard;
  ra8_register_guard_enter(&guard);
  s_sci_state[channel].tx_buf = data;
  s_sci_state[channel].tx_len = len;
  s_sci_state[channel].tx_idx = 0U;
  /* HUM Ch 38.2.5 "CCR0 : Common Control Register 0", p 2182 -- arm
   * TIE so the next TDRE event fires the dispatcher. Mirrors FSP
   * r_sci_b_uart.c which sets TE | TIE in a single store. */
  reg->CCR0 = reg->CCR0 | (1U << k_ra8_sci_ccr0_bit_tie);
  ra8_register_guard_exit(&guard);
  return k_ra8_ok;
}
 
ra8_err_t ra8_sci_read(uint8_t channel, uint8_t* buf, uint32_t len)
{
  if ((buf == nullptr) && (len != 0U)) {
    return k_ra8_err_null_ptr;
  }
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  if (!s_sci_state[channel].initialized) {
    return k_ra8_err_invalid_arg;
  }
  if (s_sci_state[channel].rx_len != 0U) {
    return k_ra8_err_busy;
  }
  if (len == 0U) {
    return k_ra8_ok;
  }
  /* Publish the async RX descriptor and arm RIE atomically w.r.t. the
   * RXI ISR (it tests rx_len then writes through rx_buf). */
  ra8_register_guard_t guard;
  ra8_register_guard_enter(&guard);
  s_sci_state[channel].rx_buf = buf;
  s_sci_state[channel].rx_len = len;
  s_sci_state[channel].rx_idx = 0U;
  /* HUM Ch 38.2.5 "CCR0 : Common Control Register 0", p 2182 -- arm
   * RIE so the next RDRF event fires the dispatcher. Mirrors FSP
   * r_sci_b_uart.c which stashes p_rx_dest / rx_dest_bytes for
   * use by `rxi_isr`. */
  reg->CCR0 = reg->CCR0 | (1U << k_ra8_sci_ccr0_bit_rie);
  ra8_register_guard_exit(&guard);
  return k_ra8_ok;
}
 
ra8_err_t ra8_sci_abort(uint8_t channel, ra8_sci_dir_t direction)
{
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  if ((direction != k_ra8_sci_dir_tx) && (direction != k_ra8_sci_dir_rx) &&
      (direction != k_ra8_sci_dir_both)) {
    return k_ra8_err_invalid_arg;
  }
  /* Disarm and tear down the async descriptor atomically w.r.t. the
   * TXI/RXI ISR. Without the mask, the ISR can latch tx_len > 0, take an
   * interrupt while this path nulls tx_buf, then dereference the stale
   * NULL -- a use-after-free / NULL deref in interrupt context.
   * HUM Ch 38.2.5 "CCR0 : Common Control Register 0", p 2182 */
  ra8_register_guard_t guard;
  ra8_register_guard_enter(&guard);
  if ((direction & k_ra8_sci_dir_tx) != 0U) {
    const uint32_t tie_teie     = (1U << k_ra8_sci_ccr0_bit_tie) | (1U << k_ra8_sci_ccr0_bit_teie);
    reg->CCR0                   = reg->CCR0 & ~tie_teie;
    s_sci_state[channel].tx_buf = nullptr;
    s_sci_state[channel].tx_len = 0U;
    s_sci_state[channel].tx_idx = 0U;
  }
  if ((direction & k_ra8_sci_dir_rx) != 0U) {
    const uint32_t rie          = (1U << k_ra8_sci_ccr0_bit_rie);
    reg->CCR0                   = reg->CCR0 & ~rie;
    s_sci_state[channel].rx_buf = nullptr;
    s_sci_state[channel].rx_len = 0U;
    s_sci_state[channel].rx_idx = 0U;
  }
  ra8_register_guard_exit(&guard);
  return k_ra8_ok;
}
 
ra8_err_t ra8_sci_read_stop(uint8_t channel, uint32_t* remaining)
{
  RA8_CHECK_NULL_PTR(remaining, s_tag, "read_stop: remaining");
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  /* Mirror FSP `R_SCI_B_UART_ReadStop` r_sci_b_uart.c: stash the
   * pre-stop count, zero state, then disarm RIE. */
  /* Snapshot the residual count, null the descriptor, and disarm RIE
   * atomically w.r.t. the RXI ISR so the reported remaining matches the
   * state we tear down (and the ISR cannot deref a half-nulled rx_buf). */
  const uint32_t       rie = (1U << k_ra8_sci_ccr0_bit_rie);
  ra8_register_guard_t guard;
  ra8_register_guard_enter(&guard);
  const uint32_t pending      = (s_sci_state[channel].rx_len > s_sci_state[channel].rx_idx)
                                  ? (s_sci_state[channel].rx_len - s_sci_state[channel].rx_idx)
                                  : 0U;
  *remaining                  = pending;
  s_sci_state[channel].rx_buf = nullptr;
  s_sci_state[channel].rx_len = 0U;
  s_sci_state[channel].rx_idx = 0U;
  /* HUM Ch 38.2.5 "CCR0 : Common Control Register 0", p 2182 */
  reg->CCR0 = reg->CCR0 & ~rie;
  ra8_register_guard_exit(&guard);
  return k_ra8_ok;
}
 
ra8_err_t ra8_sci_receive_suspend(uint8_t channel)
{
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 38.2.5 "CCR0 : Common Control Register 0", p 2182 -- drop
   * RE to silence the RX shift register. FSP returns UNSUPPORTED here;
   * we approximate the feature by toggling CCR0.RE so RXI stops firing
   * and the FIFO/RDR stops accepting fresh frames. Guard the RMW against
   * the RXI ISR's own CCR0 update. */
  const uint32_t       re = (1U << k_ra8_sci_ccr0_bit_re);
  ra8_register_guard_t guard;
  ra8_register_guard_enter(&guard);
  reg->CCR0 = reg->CCR0 & ~re;
  ra8_register_guard_exit(&guard);
  return k_ra8_ok;
}
 
ra8_err_t ra8_sci_receive_resume(uint8_t channel)
{
  volatile r_sci_regs_t* reg = internal_reg(channel);
  if (reg == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  /* HUM Ch 38.2.5 "CCR0 : Common Control Register 0", p 2182 -- guard the
   * RE RMW against the RXI ISR's concurrent CCR0 update. */
  const uint32_t       re = (1U << k_ra8_sci_ccr0_bit_re);
  ra8_register_guard_t guard;
  ra8_register_guard_enter(&guard);
  reg->CCR0 = reg->CCR0 | re;
  ra8_register_guard_exit(&guard);
  return k_ra8_ok;
}