SCI Simple-SPI controller-mode driver (polling, full-duplex). More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_spi.h"

Include dependency graph for ra8_sci_spi.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	ra8_sci_spi_cfg_t
	Configuration descriptor for ra8_sci_spi_init. More...

Functions
ra8_err_t	ra8_sci_spi_init (uint8_t channel, const ra8_sci_spi_cfg_t *cfg)
	Bring an SCI channel up as a Simple-SPI controller.
ra8_err_t	ra8_sci_spi_deinit (uint8_t channel)
	Disable the channel and release its MSTP gate.
ra8_err_t	ra8_sci_spi_set_clock (uint8_t channel, uint32_t baud_hz, uint32_t pclk_hz)
	Re-program the bit-rate without otherwise reconfiguring.
ra8_err_t	ra8_sci_spi_xfer8 (uint8_t channel, uint8_t tx, uint8_t *rx)
	Full-duplex single-frame transfer.
ra8_err_t	ra8_sci_spi_xfer (uint8_t channel, const uint8_t tx, uint8_t rx, uint32_t len)
	Full-duplex multi-byte transfer.

Detailed Description

SCI Simple-SPI controller-mode driver (polling, full-duplex).

Tag: [Ring 3 / HAL] {World: NS}

Drives an RA8D2 SCI_B channel in Simple SPI mode (CCR3.MOD = 011b) as a controller, with an internal clock and the SCKn pin as the clock output. This is the transport the EK-RA8D2 Pmod2 (J25) microSD uses: HUM Table 20.13 routes P601 (SCK0_B) / P602 (CIPO0_B) / P603 (COPI0_B) / P604 (SS0_B) to SCI0 Simple SPI at PSEL = 00100b – the RSPI/SPI_B peripheral has no function on those pins. Use the chip-select as a GPIO so it can be held low across a multi-frame SD transaction.

Bit-rate (HUM Table 38.7, clock-synchronous / simple-SPI row, BGDM = 0): B = TCLK / (4 * 4^n * (N + 1)) with n = CCR2.CKS and N = CCR2.BRR. The driver picks the smallest n that keeps N <= 255.

SPI mode maps to CCR3.CPOL/CPHA directly (mode 0 = CPOL 0, CPHA 0), which is the SD-over-SPI default.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file ra8_sci_spi.h.

Function Documentation

◆ ra8_sci_spi_deinit()

ra8_err_t ra8_sci_spi_deinit ( uint8_t channel )

nodiscard

Disable the channel and release its MSTP gate.

Parameters

[in] channel SCI channel index (0..9).

Return values

k_ra8_ok	Channel disabled.
k_ra8_err_invalid_arg	channel out of range.

Precondition: ra8_sci_spi_init succeeded for this channel.

Postcondition: TE/RE are cleared and the MSTP gate is released.

Since: 0.1.0

Definition at line 216 of file ra8_sci_spi.c.

References r_sci_regs_t::CCR0, k_ra8_err_invalid_arg, k_ra8_sci_spi_channel_count, ra8_mstp_disable(), ra8_sci(), and s_mstp_table.

Referenced by c6_probe_sweep_mode(), priv_ra8_esp_hosted_spi_close(), and priv_ra8_esp_hosted_spi_open().

◆ ra8_sci_spi_init()

ra8_err_t ra8_sci_spi_init	(	uint8_t	channel,
		const ra8_sci_spi_cfg_t *	cfg )

nodiscard

Bring an SCI channel up as a Simple-SPI controller.

Parameters

[in]	channel	SCI channel index (0..9).
[in]	cfg	Configuration; must be non-NULL.

Return values

k_ra8_ok	Channel is enabled (TE+RE) and ready to transfer.
k_ra8_err_null_ptr	cfg is NULL.
k_ra8_err_invalid_arg	channel out of range or baud 0.

Precondition: The SCKn / CIPOn / COPIn pins are routed to the SCI function (PSEL = 00100b) and the chip-select is owned as a GPIO.

Postcondition: The SCI MSTP gate is enabled and the channel is in Simple-SPI controller mode at the requested bit-rate.

Note: Not thread-safe; serialize access to a channel.

Since: 0.1.0

Definition at line 185 of file ra8_sci_spi.c.

References ra8_sci_spi_cfg_t::baud_hz, r_sci_regs_t::CCR0, r_sci_regs_t::CCR1, r_sci_regs_t::CCR3, r_sci_regs_t::CCR4, r_sci_regs_t::CFCLR, internal_apply_rate(), internal_ccr3(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sci_ccr0_bit_re, k_ra8_sci_ccr0_bit_te, k_ra8_sci_cfclr_default, k_ra8_sci_spi_channel_count, ra8_sci_spi_cfg_t::pclk_hz, RA8_CHECK_NULL_PTR, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, ra8_sci(), s_mstp_table, and s_tag.

Referenced by c6_probe_sweep_mode(), eoh_setup_or_halt(), etoc_setup_or_halt(), fs_fmt_setup_or_halt(), internal_bringup_spi(), internal_pc_setup_or_halt(), internal_sci_transport_bringup(), microsd_sd_spi_open(), priv_ra8_esp_hosted_spi_open(), sd_demo_setup_or_halt(), and sh_sd_bus_init().

◆ ra8_sci_spi_set_clock()

ra8_err_t ra8_sci_spi_set_clock	(	uint8_t	channel,
		uint32_t	baud_hz,
		uint32_t	pclk_hz )

nodiscard

Re-program the bit-rate without otherwise reconfiguring.

Parameters

[in]	channel	SCI channel index (0..9).
[in]	baud_hz	Desired SCK bit-rate (Hz), non-zero.
[in]	pclk_hz	SCI baud-clock source (PCLKA, Hz).

Return values

k_ra8_ok	Bit-rate updated.
k_ra8_err_invalid_arg	channel out of range or baud 0.

Precondition: ra8_sci_spi_init succeeded for this channel.

Postcondition: CCR2.CKS/BRR reflect the new rate; the channel stays enabled.

Since: 0.1.0

Definition at line 230 of file ra8_sci_spi.c.

References r_sci_regs_t::CCR0, internal_apply_rate(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sci_spi_channel_count, and ra8_sci().

Referenced by eoh_spi_set_clock(), etoc_spi_set_clock(), fs_fmt_spi_set_clock(), internal_pc_spi_set_clock(), internal_sci_spi_set_clock(), internal_sci_transport_set_clock(), internal_set_clock(), microsd_spi_set_clock(), sd_demo_spi_set_clock(), and sh_sd_set_clock().

◆ ra8_sci_spi_xfer()

ra8_err_t ra8_sci_spi_xfer	(	uint8_t	channel,
		const uint8_t *	tx,
		uint8_t *	rx,
		uint32_t	len )

nodiscard

Full-duplex multi-byte transfer.

Either buffer may be NULL: a NULL tx shifts idle (0xFF) bytes (SD/flash read convention); a NULL rx discards the received bytes. len == 0 is a no-op success.

Parameters

[in]	channel	SCI channel index (0..9).
[in]	tx	Bytes to shift out, or NULL for idle fill.
[out]	rx	Buffer for received bytes, or NULL to discard.
[in]	len	Number of bytes to transfer.

Return values

k_ra8_ok	All bytes transferred.
k_ra8_err_invalid_arg	channel out of range.
k_ra8_err_hw_timeout	A per-frame poll expired.

Precondition: ra8_sci_spi_init succeeded for this channel.

Postcondition: len frames were clocked.

Since: 0.1.0

Definition at line 281 of file ra8_sci_spi.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sci_spi_channel_count, k_ra8_sci_spi_idle_byte, and ra8_sci_spi_xfer8().

Referenced by eoh_spi_xfer(), etoc_spi_xfer(), fs_fmt_spi_xfer(), internal_pc_spi_xfer(), internal_sci_spi_write_read(), internal_sci_transport_xfer(), internal_transfer(), internal_xfer(), microsd_spi_xfer(), sd_demo_spi_xfer(), and sh_sd_xfer().

◆ ra8_sci_spi_xfer8()

ra8_err_t ra8_sci_spi_xfer8	(	uint8_t	channel,
		uint8_t	tx,
		uint8_t *	rx )

nodiscard

Full-duplex single-frame transfer.

Parameters

[in]	channel	SCI channel index (0..9).
[in]	tx	Byte shifted out on COPI.
[out]	rx	Byte shifted in on CIPO; may be NULL to discard.

Return values

k_ra8_ok	Frame completed.
k_ra8_err_invalid_arg	channel out of range.
k_ra8_err_hw_timeout	The TX-empty or RX-full poll expired.

Precondition: ra8_sci_spi_init succeeded for this channel.

Postcondition: One frame was clocked; *rx holds the received byte.

Since: 0.1.0

Definition at line 250 of file ra8_sci_spi.c.

References r_sci_regs_t::CFCLR, r_sci_regs_t::CSR, k_ra8_hw_budget_long, k_ra8_ok, k_ra8_sci_cfclr_bit_rdrfc, k_ra8_sci_csr_bit_rdrf, k_ra8_sci_csr_bit_tdre, k_ra8_sci_rdr_mask_data8, RA8_CHECK_NULL_PTR, ra8_hw_wait_flag_set32(), ra8_sci(), r_sci_regs_t::RDR, s_tag, and r_sci_regs_t::TDR.

Referenced by internal_sci_spi_xfer8(), and ra8_sci_spi_xfer().

Data Structures

Functions

Detailed Description

Function Documentation

◆ ra8_sci_spi_deinit()

◆ ra8_sci_spi_init()

◆ ra8_sci_spi_set_clock()

◆ ra8_sci_spi_xfer()

◆ ra8_sci_spi_xfer8()