Full-featured Serial Communications Interface driver. More...

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

Include dependency graph for ra8_sci.h:

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

Data Structures
struct	ra8_sci_cfg_t
	Configuration descriptor for ra8_sci_init. More...

Typedefs
typedef void(*	ra8_sci_rx_fn_t) (void *ctx, uint8_t byte)
	RX interrupt callback signature.
typedef bool(*	ra8_sci_tx_fn_t) (void ctx, uint8_t byte)
	TX-empty interrupt callback signature.

Enumerations
enum	ra8_sci_parity_t : uint8_t { k_ra8_sci_parity_none = 0U , k_ra8_sci_parity_even = 1U , k_ra8_sci_parity_odd = 2U }
	Parity mode for ra8_sci_cfg_t::parity. More...
enum	ra8_sci_stop_bits_t : uint8_t { k_ra8_sci_stop_1 = 0U , k_ra8_sci_stop_2 = 1U }
	Stop-bit count. More...
enum	ra8_sci_data_bits_t : uint8_t { k_ra8_sci_data_7 = 7U , k_ra8_sci_data_8 = 8U }
	Data-bit count. More...
enum	ra8_sci_err_mask_t : uint8_t { k_ra8_sci_err_none = 0x00U , k_ra8_sci_err_overrun = 0x01U , k_ra8_sci_err_framing = 0x02U , k_ra8_sci_err_parity = 0x04U }
	Bit mask of SCI error flags. More...
enum	ra8_sci_dir_t : uint8_t { k_ra8_sci_dir_tx = 0x01U , k_ra8_sci_dir_rx = 0x02U , k_ra8_sci_dir_both = 0x03U }
	Direction selector for ra8_sci_abort. More...

Functions
ra8_err_t	ra8_sci_init (uint8_t channel, const ra8_sci_cfg_t *cfg)
	Initialise an SCI channel using the descriptor.
ra8_err_t	ra8_sci_deinit (uint8_t channel)
	Tear down a channel – disable TX/RX, release MSTP.
ra8_err_t	ra8_sci_putc_polling (uint8_t channel, uint8_t byte)
	Poll-send one byte (blocking, bounded by ra8_hw_err spin budget).
ra8_err_t	ra8_sci_getc_polling (uint8_t channel, uint8_t *out_byte)
	Poll-receive one byte (blocking, bounded spin).
ra8_err_t	ra8_sci_write_polling (uint8_t channel, const uint8_t *data, uint32_t len)
	Send len bytes by polling (convenience wrapper).
ra8_err_t	ra8_sci_flush (uint8_t channel)
	Block until the channel's transmit shift register is empty.
ra8_err_t	ra8_sci_attach_rx_handler (uint8_t channel, ra8_sci_rx_fn_t fn, void *ctx)
	Install the RX interrupt callback + context.
ra8_err_t	ra8_sci_attach_tx_handler (uint8_t channel, ra8_sci_tx_fn_t fn, void *ctx)
	Install the TX interrupt callback + context.
ra8_err_t	ra8_sci_get_errors (uint8_t channel, uint8_t *out_mask)
	Read the SSR error bits (ORER, FER, PER).
ra8_err_t	ra8_sci_clear_errors (uint8_t channel)
	Clear the SSR error flags via write-zero.
ra8_err_t	ra8_sci_set_baud (uint8_t channel, uint32_t baud, uint32_t pclk_hz)
	Change the baud rate without tearing down the channel.
ra8_err_t	ra8_sci_enter_stop (uint8_t channel)
	Put the channel into MSTP-gated stop state.
ra8_err_t	ra8_sci_exit_stop (uint8_t channel)
	Exit MSTP-gated stop state; the channel must be re-init'd.
ra8_err_t	ra8_sci_write (uint8_t channel, const uint8_t *data, uint32_t len)
	Arm an interrupt-driven TX of len bytes from data.
ra8_err_t	ra8_sci_read (uint8_t channel, uint8_t *buf, uint32_t len)
	Arm an interrupt-driven RX of len bytes into buf.
ra8_err_t	ra8_sci_abort (uint8_t channel, ra8_sci_dir_t direction)
	Cancel an in-flight async TX or RX.
ra8_err_t	ra8_sci_read_stop (uint8_t channel, uint32_t *remaining)
	Stop an in-flight RX and report how many bytes were not yet consumed.
ra8_err_t	ra8_sci_baud_calculate (uint32_t baud, uint32_t pclk_hz, uint16_t brr_out, uint8_t clk_div_out)
	Pure-math conversion from a target baud rate to BRR + clock divider settings.
ra8_err_t	ra8_sci_receive_suspend (uint8_t channel)
	Suspend reception by clearing CCR0.RE.
ra8_err_t	ra8_sci_receive_resume (uint8_t channel)
	Resume reception by setting CCR0.RE.
ra8_err_t	ra8_sci_write_dma (uint8_t channel, const uint8_t data, uint16_t len, ra8_dma_complete_fn_t on_complete, void ctx, uint8_t *out_dma_channel)
	Kick off a DMA-backed TX transfer.
ra8_err_t	ra8_sci_read_dma (uint8_t channel, uint8_t out_buf, uint16_t len, ra8_dma_complete_fn_t on_complete, void ctx, uint8_t *out_dma_channel)
	Kick off a DMA-backed RX transfer.
void	ra8_sci_dispatch_txi (uint8_t channel)
	TXI dispatch – advance the TX callback.
void	ra8_sci_dispatch_rxi (uint8_t channel)
	RXI dispatch – hand a received byte to the RX callback.
void	ra8_sci_dispatch_eri (uint8_t channel)
	ERI dispatch – clear SSR error flags, invoke optional error callback (none in reserved for 3.1b).

Detailed Description

Full-featured Serial Communications Interface driver.

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

full build-out of the SCI peripheral. Replaces the polling-only ra8_uart stub from with a driver that ticks every box on the 14-checkbox template:

Init / Deinit with a full configuration struct.
Polling TX / RX.
Interrupt-driven TX / RX with ring buffers.
Error-status handling (overrun, framing, parity).
Runtime baud-rate reconfigure.
Power-mode enter / exit.
Register-coverage full across the current r_sci_regs_t window.

DMA TX / RX land via ra8_sci_write_dma and ra8_sci_read_dma, which programme the ra8_dma substrate for a byte-stream transfer between a host buffer and the SCI TDR/RDR data registers. ELC trigger routing (one DMAC element per TXI / RXI event) is handled downstream once the NSC layer can annotate the trigger table safely; uses the k_ra8_elc_event_none software-start path which is what the host-side ra8_fake_dma loop simulates.

Register layout

The driver targets the SCI_B variant of the SCI peripheral (HUM Ch 38 "Serial Communications Interface", p 2174 onwards) – 32-bit registers throughout, with CCR0..CCR4 / FCR / CSR / CFCLR replacing the legacy 8-bit SMR / SCR / SSR / SCMR. See ra8_sci_regs.h for the full layout.

Threading

Not thread-safe. Configuration calls run from single-threaded init context. IRQ callbacks fire from handler mode and must not take any ra8_sci locks.

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

Definition in file ra8_sci.h.

Typedef Documentation

◆ ra8_sci_rx_fn_t

typedef void(* ra8_sci_rx_fn_t) (void *ctx, uint8_t byte)

RX interrupt callback signature.

Parameters

[in]	ctx	Caller-supplied context.
[in]	byte	Received byte.

Definition at line 130 of file ra8_sci.h.

◆ ra8_sci_tx_fn_t

typedef bool(* ra8_sci_tx_fn_t) (void *ctx, uint8_t *byte)

TX-empty interrupt callback signature.

Parameters

[in]	ctx	Caller-supplied context.
[out]	byte	Next byte to transmit.

Returns: true if *byte is valid; false to disable TIE (no more data to send).

Definition at line 141 of file ra8_sci.h.

Enumeration Type Documentation

◆ ra8_sci_data_bits_t

enum ra8_sci_data_bits_t : uint8_t

Data-bit count.

Enumerator
k_ra8_sci_data_7	RA8 SCI data 7.
k_ra8_sci_data_8	RA8 SCI data 8.

Definition at line 89 of file ra8_sci.h.

◆ ra8_sci_dir_t

enum ra8_sci_dir_t : uint8_t

Direction selector for ra8_sci_abort.

Mirrors FSP's uart_dir_t (TX=1, RX=2, BOTH=3) so callers can use one bitmask to abort either direction or both at once.

Enumerator
k_ra8_sci_dir_tx	Cancel an in-flight TX.
k_ra8_sci_dir_rx	Cancel an in-flight RX.
k_ra8_sci_dir_both	Cancel both directions.

Definition at line 150 of file ra8_sci.h.

◆ ra8_sci_err_mask_t

enum ra8_sci_err_mask_t : uint8_t

Bit mask of SCI error flags.

Enumerator
k_ra8_sci_err_none	RA8 SCI error none.
k_ra8_sci_err_overrun	ORER set.
k_ra8_sci_err_framing	FER set.
k_ra8_sci_err_parity	PER set.

Definition at line 116 of file ra8_sci.h.

◆ ra8_sci_parity_t

enum ra8_sci_parity_t : uint8_t

Parity mode for ra8_sci_cfg_t::parity.

Enumerator
k_ra8_sci_parity_none	RA8 SCI parity none.
k_ra8_sci_parity_even	RA8 SCI parity even.
k_ra8_sci_parity_odd	RA8 SCI parity odd.

Definition at line 70 of file ra8_sci.h.

◆ ra8_sci_stop_bits_t

enum ra8_sci_stop_bits_t : uint8_t

Stop-bit count.

Enumerator
k_ra8_sci_stop_1	RA8 SCI stop 1.
k_ra8_sci_stop_2	RA8 SCI stop 2.

Definition at line 80 of file ra8_sci.h.

Function Documentation

◆ ra8_sci_abort()

ra8_err_t ra8_sci_abort	(	uint8_t	channel,
		ra8_sci_dir_t	direction )

nodiscard

Cancel an in-flight async TX or RX.

Mirrors FSP R_SCI_B_UART_Abort (r_sci_b_uart.c). When direction includes k_ra8_sci_dir_tx, CCR0.TIE / CCR0.TEIE are cleared and the per-channel TX state is zeroed. When direction includes k_ra8_sci_dir_rx, CCR0.RIE is cleared and the per-channel RX state is zeroed. k_ra8_sci_dir_both aborts both. CCR0.TE / RE are left alone – callers may still poll or arm a fresh transfer.

Parameters

[in]	channel	SCI channel (0..9).
[in]	direction	TX, RX, or both.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Direction(s) aborted.
k_ra8_err_invalid_arg	channel > 9 or direction is not one of the three defined values.

Precondition: Channel previously initialized.

Postcondition: The selected direction(s) have IE bits cleared and the matching per-channel byte counter is zero.

Note: Thread safety: not thread-safe.

See also: ra8_sci_write; ra8_sci_read

Since: 0.1.0

Definition at line 815 of file ra8_sci.c.

References r_sci_regs_t::CCR0, internal_reg(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sci_ccr0_bit_rie, k_ra8_sci_ccr0_bit_teie, k_ra8_sci_ccr0_bit_tie, k_ra8_sci_dir_both, k_ra8_sci_dir_rx, k_ra8_sci_dir_tx, ra8_register_guard_enter(), ra8_register_guard_exit(), and s_sci_state.

◆ ra8_sci_attach_rx_handler()

ra8_err_t ra8_sci_attach_rx_handler	(	uint8_t	channel,
		ra8_sci_rx_fn_t	fn,
		void *	ctx )

nodiscard

Install the RX interrupt callback + context.

Parameters

[in]	channel	SCI channel.
[in]	fn	Callback fired on RDRF interrupt. Must not be NULL to enable; pass NULL to detach.
[in]	ctx	Context passed to the callback.

Returns: k_ra8_ok / k_ra8_err_invalid_arg.

Precondition: Channel previously initialized.

Postcondition: On success, SCR.RIE is set (if fn non-NULL).

Since: 0.1.0

Definition at line 558 of file ra8_sci.c.

References r_sci_regs_t::CCR0, internal_reg(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sci_ccr0_bit_rie, ra8_register_guard_enter(), ra8_register_guard_exit(), and s_sci_state.

Referenced by main().

◆ ra8_sci_attach_tx_handler()

ra8_err_t ra8_sci_attach_tx_handler	(	uint8_t	channel,
		ra8_sci_tx_fn_t	fn,
		void *	ctx )

nodiscard

Install the TX interrupt callback + context.

Parameters

[in]	channel	SCI channel.
[in]	fn	Callback fired on TDRE interrupt. Return true with the next byte or false to disable.
[in]	ctx	Context passed to the callback.

Returns: k_ra8_ok / k_ra8_err_invalid_arg.

Precondition: Channel previously initialized.

Postcondition: On success, SCR.TIE is set (if fn non-NULL).

Since: 0.1.0

Definition at line 583 of file ra8_sci.c.

References r_sci_regs_t::CCR0, internal_reg(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sci_ccr0_bit_tie, ra8_register_guard_enter(), ra8_register_guard_exit(), and s_sci_state.

◆ ra8_sci_baud_calculate()

ra8_err_t ra8_sci_baud_calculate	(	uint32_t	baud,
		uint32_t	pclk_hz,
		uint16_t *	brr_out,
		uint8_t *	clk_div_out )

nodiscard

Pure-math conversion from a target baud rate to BRR + clock divider settings.

Mirrors FSP R_SCI_B_UART_BaudCalculate (r_sci_b_uart.c) for the simple non-modulated 16x base-clock path. Implements the formula from HUM Ch 38.2.7 "CCR2 : Common Control Register 2", p 2189 Table 38.7:

N = TCLK / (64 * 2^(2n - 1) * B) - 1

with n = *clk_div_out chosen as the smallest CKS divider for which BRR fits in 8 bits. *brr_out receives the 8-bit BRR. Pure math only – this routine does not touch any hardware register. Use ra8_sci_set_baud to apply the result.

Parameters

[in]	baud	Target baud rate in bps; must be > 0.
[in]	pclk_hz	PCLKB frequency in Hz; must be > 0.
[out]	brr_out	Computed BRR value (0..255).
[out]	clk_div_out	Computed CKS divider exponent (0..3).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	BRR computed within hardware reach.
k_ra8_err_null_ptr	brr_out or clk_div_out is NULL.
k_ra8_err_invalid_arg	baud or pclk_hz is zero, or the requested baud cannot be reached with any CKS divider (BRR > 255).

Precondition: brr_out and clk_div_out are non-NULL.

Postcondition: On success, the pair (*brr_out, *clk_div_out) yields an effective baud whose error vs. baud is < 5 percent for standard 9.6k/19.2k/57.6k/115.2k targets at typical PCLKB rates.

Note: Thread safety: pure function; safe to call concurrently.

See also: ra8_sci_set_baud

Since: 0.1.0

Definition at line 717 of file ra8_sci.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sci_baud_brr_max, k_ra8_sci_baud_cks_max, k_ra8_sci_baud_div_step, k_ra8_sci_baud_n0_divisor, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_sci_clear_errors()

ra8_err_t ra8_sci_clear_errors ( uint8_t channel )

nodiscard

Clear the SSR error flags via write-zero.

Parameters

[in] channel SCI channel.

Returns: k_ra8_ok / k_ra8_err_invalid_arg.

Precondition: IRQs masked or single-threaded init context.

Postcondition: ORER, FER, PER read back as 0.

Since: 0.1.0

Definition at line 633 of file ra8_sci.c.

References r_sci_regs_t::CFCLR, internal_reg(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sci_cfclr_bit_ferc, k_ra8_sci_cfclr_bit_orerc, and k_ra8_sci_cfclr_bit_perc.

Referenced by ra8_sci_dispatch_eri().

◆ ra8_sci_deinit()

ra8_err_t ra8_sci_deinit ( uint8_t channel )

nodiscard

Tear down a channel – disable TX/RX, release MSTP.

Parameters

[in] channel SCI channel number.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Channel released.
k_ra8_err_invalid_arg	channel > 9.

Precondition: IRQs masked or single-threaded init context.; Caller previously called ra8_sci_init(channel).

Postcondition: TX/RX disabled; MSTP reference for the channel decremented.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 443 of file ra8_sci.c.

References r_sci_regs_t::CCR0, internal_reg(), k_ra8_err_invalid_arg, ra8_mstp_disable(), ra8_register_guard_enter(), ra8_register_guard_exit(), s_mstp_table, and s_sci_state.

◆ ra8_sci_dispatch_eri()

void ra8_sci_dispatch_eri ( uint8_t channel )

ERI dispatch – clear SSR error flags, invoke optional error callback (none in reserved for 3.1b).

Parameters

[in] channel SCI channel whose ERI fired.

Precondition: Called from ISR context.

Postcondition: SSR error bits are cleared.

Since: 0.1.0

See implementation for details.

Precondition: Module has been initialized.

Postcondition: Side effects bounded to documented state.

Note: Not thread-safe unless documented otherwise.

Definition at line 259 of file ra8_sci_dma_isr.c.

References k_ra8_sci_channel_max_index, and ra8_sci_clear_errors().

Referenced by uart_irq_tei_isr().

◆ ra8_sci_dispatch_rxi()

void ra8_sci_dispatch_rxi ( uint8_t channel )

RXI dispatch – hand a received byte to the RX callback.

Parameters

[in] channel SCI channel whose RXI fired.

Precondition: Called from ISR context.

Postcondition: If an RX callback is attached, it has been invoked with the byte read from RDR.

Since: 0.1.0

See implementation for details.

Precondition: Module has been initialized.

Postcondition: Side effects bounded to documented state.

Note: Not thread-safe unless documented otherwise.

Definition at line 219 of file ra8_sci_dma_isr.c.

References r_sci_regs_t::CCR0, k_ra8_sci_ccr0_bit_rie, k_ra8_sci_channel_max_index, k_ra8_sci_rdr_mask_data8, ra8_sci(), r_sci_regs_t::RDR, and s_sci_state.

Referenced by uart_irq_rxi_isr().

◆ ra8_sci_dispatch_txi()

void ra8_sci_dispatch_txi ( uint8_t channel )

TXI dispatch – advance the TX callback.

Parameters

[in] channel SCI channel whose TXI fired.

Precondition: Called from ISR context (or from test helper).

Postcondition: If the attached TX callback returns true, the next byte has been written to TDR. Otherwise TIE is cleared.

Since: 0.1.0

See implementation for details.

Precondition: Module has been initialized.

Postcondition: Side effects bounded to documented state.

Note: Not thread-safe unless documented otherwise.

Definition at line 163 of file ra8_sci_dma_isr.c.

References r_sci_regs_t::CCR0, k_ra8_sci_ccr0_bit_tie, k_ra8_sci_channel_max_index, ra8_sci(), s_sci_state, and r_sci_regs_t::TDR.

Referenced by uart_irq_txi_isr().

◆ ra8_sci_enter_stop()

ra8_err_t ra8_sci_enter_stop ( uint8_t channel )

nodiscard

Put the channel into MSTP-gated stop state.

Parameters

[in] channel SCI channel.

Returns: k_ra8_ok / k_ra8_err_invalid_arg.

Precondition: IRQs masked or single-threaded context.

Postcondition: Channel is MSTP-gated.

Warning: Callers lose every register setting; pair with ra8_sci_exit_stop + re-init if reconfiguration is needed.

Since: 0.1.0

Definition at line 677 of file ra8_sci.c.

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

◆ ra8_sci_exit_stop()

ra8_err_t ra8_sci_exit_stop ( uint8_t channel )

nodiscard

Exit MSTP-gated stop state; the channel must be re-init'd.

Parameters

[in] channel SCI channel.

Returns: k_ra8_ok / k_ra8_err_invalid_arg.

Precondition: Channel is currently MSTP-gated.

Postcondition: MSTP bit is cleared; caller must call ra8_sci_init to restore registers.

Since: 0.1.0

Definition at line 688 of file ra8_sci.c.

References k_ra8_err_invalid_arg, k_ra8_sci_channel_max_index, ra8_mstp_enable(), and s_mstp_table.

◆ ra8_sci_flush()

ra8_err_t ra8_sci_flush ( uint8_t channel )

nodiscard

Block until the channel's transmit shift register is empty.

Spins on CSR.TEND (HUM Ch 38.2.17 "CSR : Common Status Register", p 2225). TEND asserts only after both TDR and the shift register are drained, so this call guarantees that every byte previously handed to the SCI has finished clocking out on the wire.

The intended use is before any panic / sleep / WFI sequence that would gate the SCI clock and silently lose in-flight bytes:

(void)ra8_sci_write_polling(k_demo_sci_channel, panic_msg, len);
(void)ra8_sci_flush(k_demo_sci_channel);  // wait for the wire
panic_halt();                            // safe to WFI now

The wait is bounded by ra8_hw_wait_flag_set32 (medium budget – roughly 65k tight-loop iterations), so the call is guaranteed to return in finite time even if TXD is wedged. On the host (RA8_OFF_TARGET) the fake does not model the shift-register drain, so this routine returns k_ra8_ok without polling.

Parameters

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

Returns: ra8_err_t error code.

Return values

k_ra8_ok	TEND observed high (or fake stub).
k_ra8_err_invalid_arg	channel > 9.
k_ra8_err_hw_timeout	Spin budget elapsed without TEND.

Precondition: Channel previously initialized via ra8_sci_init.

Postcondition: On success, the SCI transmit shift register is empty – safe to drop CCR0.TE, gate the MSTP clock, or execute WFI.

Note: Thread safety: not thread-safe with respect to ISR-driven TX on the same channel (the ISR may refill TDR mid-poll). Drain or abort the async TX first, then flush.

See also: ra8_sci_write_polling; ra8_sci_abort

Since: 0.1.0

Definition at line 543 of file ra8_sci.c.

References internal_reg(), internal_wait_tx_end(), and k_ra8_err_invalid_arg.

Referenced by internal_uart_flush(), main(), and ra8_board_uart_console_flush().

◆ ra8_sci_get_errors()

ra8_err_t ra8_sci_get_errors	(	uint8_t	channel,
		uint8_t *	out_mask )

nodiscard

Read the SSR error bits (ORER, FER, PER).

Parameters

[in]	channel	SCI channel.
[out]	out_mask	OR of k_ra8_sci_err_* values.

Returns: k_ra8_ok / k_ra8_err_null_ptr / k_ra8_err_invalid_arg.

Precondition: out_mask non-NULL.

Postcondition: No hardware state is modified.

Since: 0.1.0

Definition at line 609 of file ra8_sci.c.

References r_sci_regs_t::CSR, internal_reg(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sci_csr_bit_fer, k_ra8_sci_csr_bit_orer, k_ra8_sci_csr_bit_per, k_ra8_sci_err_framing, k_ra8_sci_err_none, k_ra8_sci_err_overrun, k_ra8_sci_err_parity, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_sci_getc_polling()

ra8_err_t ra8_sci_getc_polling	(	uint8_t	channel,
		uint8_t *	out_byte )

nodiscard

Poll-receive one byte (blocking, bounded spin).

Parameters

[in]	channel	SCI channel number.
[out]	out_byte	Received byte on success.

Returns: k_ra8_ok / k_ra8_err_hw_timeout / k_ra8_err_null_ptr.

Precondition: out_byte non-NULL.; Channel previously initialized.

Postcondition: On success, one byte was drained from RDR.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 496 of file ra8_sci.c.

References r_sci_regs_t::CSR, internal_reg(), k_ra8_err_invalid_arg, k_ra8_hw_budget_medium, k_ra8_ok, k_ra8_sci_csr_bit_rdrf, k_ra8_sci_rdr_mask_data8, RA8_CHECK_NULL_PTR, ra8_hw_wait_flag_set32(), r_sci_regs_t::RDR, and s_tag.

Referenced by internal_lin_rx_buf(), modem_rx_byte(), ra8_board_uart_console_read(), ra8_nsc_sci_getc(), and ra8_sci_lin_read_response().

◆ ra8_sci_init()

ra8_err_t ra8_sci_init	(	uint8_t	channel,
		const ra8_sci_cfg_t *	cfg )

nodiscard

Initialise an SCI channel using the descriptor.

Ungates the channel through ra8_mstp_enable, programs CCR1 / CCR2 (BRR + MDDR) / CCR3 (mode + framing) / CCR4 / FCR registers from cfg, then enables CCR0.TE + CCR0.RE. Errors before the final enable step leave the channel gated.

Parameters

[in]	channel	SCI channel number (0..9).
[in]	cfg	Configuration descriptor.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Channel ready.
k_ra8_err_null_ptr	cfg was NULL.
k_ra8_err_invalid_arg	channel > 9 or cfg has bad field values.
k_ra8_err_hw_init_failed	ra8_mstp_enable failed.

Precondition: IRQs masked or single-threaded init context.; ra8_mstp_init has been called.

Postcondition: On success, the channel is clocked, configured, and ready to TX / RX.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 410 of file ra8_sci.c.

References r_sci_regs_t::CCR0, internal_program_ccr_bank(), internal_reg(), k_ra8_err_hw_init_failed, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sci_ccr0_bit_re, k_ra8_sci_ccr0_bit_te, RA8_CHECK_NULL_PTR, ra8_log_error_val, ra8_log_info_val, ra8_mstp_enable(), s_mstp_table, s_sci_state, and s_tag.

Referenced by blc_setup_or_halt(), demo_setup_or_halt(), internal_demo_setup_or_halt(), modem_setup_or_halt(), ra8_board_uart_console_init(), ra8_nsc_sci_init(), ra8_sci_lin_init(), and uart_irq_setup_or_halt().

◆ ra8_sci_putc_polling()

ra8_err_t ra8_sci_putc_polling	(	uint8_t	channel,
		uint8_t	byte )

nodiscard

Poll-send one byte (blocking, bounded by ra8_hw_err spin budget).

Parameters

[in]	channel	SCI channel number.
[in]	byte	Byte to transmit.

Returns: k_ra8_ok / k_ra8_err_hw_timeout / k_ra8_err_invalid_arg.

Precondition: Channel previously initialized.

Postcondition: On success, the byte has been handed to the TX register.

Note: Thread safety: not thread-safe with respect to IRQ TX on the same channel.

Since: 0.1.0

Definition at line 476 of file ra8_sci.c.

References r_sci_regs_t::CSR, internal_reg(), k_ra8_err_invalid_arg, k_ra8_hw_budget_medium, k_ra8_ok, k_ra8_sci_csr_bit_tdre, ra8_hw_wait_flag_set32(), and r_sci_regs_t::TDR.

Referenced by internal_lin_tx_buf(), modem_tx_byte(), ra8_nsc_sci_putc(), ra8_sci_lin_send_header(), ra8_sci_lin_send_response(), and ra8_sci_write_polling().

◆ ra8_sci_read()

ra8_err_t ra8_sci_read	(	uint8_t	channel,
		uint8_t *	buf,
		uint32_t	len )

nodiscard

Arm an interrupt-driven RX of len bytes into buf.

Mirrors FSP R_SCI_B_UART_Read (r_sci_b_uart.c): installs an internal byte-counting RX state machine, sets CCR0.RIE, and returns immediately. Each subsequent RXI copies the byte from RDR into buf[index++] and decrements remaining. When remaining reaches zero, RIE is cleared automatically. A previously-attached user RX callback is still invoked per byte.

Parameters

[in]	channel	SCI channel (0..9).
[out]	buf	Destination buffer; must stay live until the transfer drains or ra8_sci_read_stop is called.
[in]	len	Number of bytes to receive. Zero is a no-op.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Transfer armed.
k_ra8_err_null_ptr	buf is NULL with len > 0.
k_ra8_err_invalid_arg	channel > 9 or channel not initialized.
k_ra8_err_busy	A previous async RX is still draining.

Precondition: Channel previously initialized via ra8_sci_init.; buf non-NULL when len > 0.

Postcondition: On success, CCR0.RIE = 1 and the per-channel RX state holds buf / len / index = 0.

Note: Thread safety: not thread-safe.

See also: ra8_sci_read_stop; ra8_sci_abort; ra8_sci_dispatch_rxi

Since: 0.1.0

Definition at line 781 of file ra8_sci.c.

References r_sci_regs_t::CCR0, internal_reg(), k_ra8_err_busy, k_ra8_err_invalid_arg, k_ra8_err_null_ptr, k_ra8_ok, k_ra8_sci_ccr0_bit_rie, ra8_register_guard_enter(), ra8_register_guard_exit(), and s_sci_state.

Referenced by main(), and uart_irq_rx_cb().

◆ ra8_sci_read_dma()

ra8_err_t ra8_sci_read_dma	(	uint8_t	channel,
		uint8_t *	out_buf,
		uint16_t	len,
		ra8_dma_complete_fn_t	on_complete,
		void *	ctx,
		uint8_t *	out_dma_channel )

nodiscard

Kick off a DMA-backed RX transfer.

Programmes the ra8_dma substrate to copy len bytes from the channel's RDR register into out_buf[] as byte elements (src_inc=false, dst_inc=true). Completion callback fires from DMAC ISR context on transfer-end.

Parameters

[in]	channel	SCI channel 0..9.
[out]	out_buf	Destination byte buffer. Must stay live until on_complete fires.
[in]	len	Number of bytes; must be non-zero.
[in]	on_complete	Completion callback. May be NULL.
[in]	ctx	Context passed to on_complete.
[out]	out_dma_channel	Allocated DMAC channel on success.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Transfer armed.
k_ra8_err_null_ptr	out_buf or out_dma_channel NULL.
k_ra8_err_invalid_arg	channel > 9 or len zero.
k_ra8_err_no_mem	All DMAC channels in use.
k_ra8_err_hw_error	Underlying ra8_dma_request failed.

Precondition: Channel previously initialized via ra8_sci_init.; ra8_dma_init has been called.; out_buf and out_dma_channel are non-NULL.

Postcondition: On success, the DMAC channel is programmed and armed.; *out_dma_channel holds a valid DMAC channel index.

Note: Thread safety: not thread-safe.

See also: ra8_sci_write_dma; ra8_dma_release

Since: 0.1.0

Definition at line 134 of file ra8_sci_dma_isr.c.

References internal_dma_args_ok(), internal_make_dma_request(), k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_dma_request(), ra8_sci(), r_sci_regs_t::RDR, and s_tag.

◆ ra8_sci_read_stop()

ra8_err_t ra8_sci_read_stop	(	uint8_t	channel,
		uint32_t *	remaining )

nodiscard

Stop an in-flight RX and report how many bytes were not yet consumed.

Mirrors FSP R_SCI_B_UART_ReadStop (r_sci_b_uart.c). Clears the per-channel RX byte counter, then writes the value that was just cleared into *remaining so the caller knows how much of the original len is still pending. Disarms RIE.

Parameters

[in]	channel	SCI channel (0..9).
[out]	remaining	Bytes still pending at stop time. Set to 0 if no RX was active.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	RX state cleared, *remaining updated.
k_ra8_err_null_ptr	remaining is NULL.
k_ra8_err_invalid_arg	channel > 9.

Precondition: remaining is non-NULL.; Channel previously initialized.

Postcondition: CCR0.RIE = 0 and the per-channel RX state is zeroed.

Note: Thread safety: not thread-safe.

See also: ra8_sci_read

Since: 0.1.0

Definition at line 850 of file ra8_sci.c.

References r_sci_regs_t::CCR0, internal_reg(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sci_ccr0_bit_rie, RA8_CHECK_NULL_PTR, ra8_register_guard_enter(), ra8_register_guard_exit(), s_sci_state, and s_tag.

◆ ra8_sci_receive_resume()

ra8_err_t ra8_sci_receive_resume ( uint8_t channel )

nodiscard

Resume reception by setting CCR0.RE.

Parameters

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

Returns: ra8_err_t error code.

Return values

k_ra8_ok	RX re-armed (CCR0.RE = 1).
k_ra8_err_invalid_arg	channel > 9.

Precondition: Channel previously initialized.

Postcondition: CCR0.RE = 1.

Note: Thread safety: not thread-safe.

See also: ra8_sci_receive_suspend

Since: 0.1.0

Definition at line 897 of file ra8_sci.c.

References r_sci_regs_t::CCR0, internal_reg(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sci_ccr0_bit_re, ra8_register_guard_enter(), and ra8_register_guard_exit().

◆ ra8_sci_receive_suspend()

ra8_err_t ra8_sci_receive_suspend ( uint8_t channel )

nodiscard

Suspend reception by clearing CCR0.RE.

Mirrors FSP R_SCI_B_UART_ReceiveSuspend (r_sci_b_uart.c) but with a real implementation: FSP returns FSP_ERR_UNSUPPORTED for SCI_B because the hardware does not have a dedicated "RX-suspend" bit. We approximate it by dropping CCR0.RE – the receive shift register stops sampling RXD and RXI is silenced. ra8_sci_receive_resume re-asserts RE.

Parameters

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

Returns: ra8_err_t error code.

Return values

k_ra8_ok	RX paused (CCR0.RE = 0).
k_ra8_err_invalid_arg	channel > 9.

Precondition: Channel previously initialized.

Postcondition: CCR0.RE = 0; bytes already in RDR remain readable.

Note: Thread safety: not thread-safe.

See also: ra8_sci_receive_resume

Since: 0.1.0

Definition at line 878 of file ra8_sci.c.

References r_sci_regs_t::CCR0, internal_reg(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sci_ccr0_bit_re, ra8_register_guard_enter(), and ra8_register_guard_exit().

◆ ra8_sci_set_baud()

ra8_err_t ra8_sci_set_baud	(	uint8_t	channel,
		uint32_t	baud,
		uint32_t	pclk_hz )

nodiscard

Change the baud rate without tearing down the channel.

Parameters

[in]	channel	SCI channel.
[in]	baud	New target baud rate in bps.
[in]	pclk_hz	Current PCLKB frequency in Hz.

Returns: k_ra8_ok / k_ra8_err_invalid_arg.

Precondition: Channel initialized.; IRQs masked or single-threaded context.

Postcondition: BRR reflects the new divider.

Since: 0.1.0

Definition at line 648 of file ra8_sci.c.

References r_sci_regs_t::CCR2, internal_brr(), internal_reg(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_sci_ccr2_mask_brr_field, k_ra8_sci_ccr2_shift_brr, ra8_register_guard_enter(), and ra8_register_guard_exit().

◆ ra8_sci_write()

ra8_err_t ra8_sci_write	(	uint8_t	channel,
		const uint8_t *	data,
		uint32_t	len )

nodiscard

Arm an interrupt-driven TX of len bytes from data.

Mirrors FSP R_SCI_B_UART_Write (r_sci_b_uart.c): installs an internal byte-counting state machine on the channel, sets CCR0.TIE, and returns immediately. Each subsequent TXI then shifts one byte out of TDR and decrements the remaining count; when the count reaches zero, TIE is cleared automatically. If a user TX callback was previously attached via ra8_sci_attach_tx_handler, it is still invoked once per byte (with *byte already populated from data[i]) so existing flow-control hooks keep working.

Parameters

[in]	channel	SCI channel (0..9).
[in]	data	Source buffer; must stay live until the transfer drains or is aborted.
[in]	len	Number of bytes to send. Zero is a no-op.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Transfer armed.
k_ra8_err_null_ptr	data is NULL with len > 0.
k_ra8_err_invalid_arg	channel > 9 or channel not initialized.
k_ra8_err_busy	A previous async TX is still draining.

Precondition: Channel previously initialized via ra8_sci_init.; data non-NULL when len > 0.

Postcondition: On success, CCR0.TIE = 1 and the per-channel TX state holds data / len.

Note: Thread safety: not thread-safe; ISR contention is the caller's responsibility.

See also: ra8_sci_abort; ra8_sci_dispatch_txi

Since: 0.1.0

Definition at line 747 of file ra8_sci.c.

References r_sci_regs_t::CCR0, internal_reg(), k_ra8_err_busy, k_ra8_err_invalid_arg, k_ra8_err_null_ptr, k_ra8_ok, k_ra8_sci_ccr0_bit_tie, ra8_register_guard_enter(), ra8_register_guard_exit(), and s_sci_state.

Referenced by uart_irq_rx_cb().

◆ ra8_sci_write_dma()

ra8_err_t ra8_sci_write_dma	(	uint8_t	channel,
		const uint8_t *	data,
		uint16_t	len,
		ra8_dma_complete_fn_t	on_complete,
		void *	ctx,
		uint8_t *	out_dma_channel )

nodiscard

Kick off a DMA-backed TX transfer.

Programmes the ra8_dma substrate to copy len bytes from data[] into the channel's TDR register as byte elements (src_inc=true, dst_inc=false). The caller-supplied completion callback fires from DMAC ISR context on transfer-end. The allocated DMAC channel is returned in *out_dma_channel so the caller can release it via ra8_dma_release once the transfer is done.

Uses k_ra8_elc_event_none (software-start). Real hardware one-element-per-TXI routing is a task alongside the TrustZone retrofit.

Parameters

[in]	channel	SCI channel 0..9.
[in]	data	Source byte buffer. Must stay live until on_complete fires.
[in]	len	Number of bytes to transfer; must be non-zero.
[in]	on_complete	Completion callback. May be NULL.
[in]	ctx	Context passed to on_complete.
[out]	out_dma_channel	Allocated DMAC channel on success.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Transfer armed.
k_ra8_err_null_ptr	data or out_dma_channel NULL.
k_ra8_err_invalid_arg	channel > 9 or len zero.
k_ra8_err_no_mem	All DMAC channels in use.
k_ra8_err_hw_error	Underlying ra8_dma_request failed.

Precondition: Channel previously initialized via ra8_sci_init.; ra8_dma_init has been called.; out_dma_channel is non-NULL.

Postcondition: On success, the DMAC channel is programmed and armed.; *out_dma_channel holds a valid DMAC channel index.

Note: Thread safety: not thread-safe.

See also: ra8_sci_read_dma; ra8_dma_release

Since: 0.1.0

Definition at line 104 of file ra8_sci_dma_isr.c.

References internal_dma_args_ok(), internal_make_dma_request(), k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_dma_request(), ra8_sci(), s_tag, and r_sci_regs_t::TDR.

◆ ra8_sci_write_polling()

ra8_err_t ra8_sci_write_polling	(	uint8_t	channel,
		const uint8_t *	data,
		uint32_t	len )

nodiscard

Send len bytes by polling (convenience wrapper).

Parameters

[in]	channel	SCI channel number.
[in]	data	Byte buffer.
[in]	len	Number of bytes.

Returns: k_ra8_ok or the first error the inner putc returned.

Precondition: data non-NULL unless len == 0.

Postcondition: On success, every byte has been handed to TDR.

Since: 0.1.0

Definition at line 516 of file ra8_sci.c.

References internal_reg(), internal_wait_tx_end(), k_ra8_err_invalid_arg, k_ra8_err_null_ptr, k_ra8_ok, and ra8_sci_putc_polling().

Referenced by blc_print(), blc_print_hex(), internal_uart_write(), main(), and ra8_board_uart_console_write().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Register layout

Threading

Typedef Documentation

◆ ra8_sci_rx_fn_t

◆ ra8_sci_tx_fn_t

Enumeration Type Documentation

◆ ra8_sci_data_bits_t

◆ ra8_sci_dir_t

◆ ra8_sci_err_mask_t

◆ ra8_sci_parity_t

◆ ra8_sci_stop_bits_t

Function Documentation

◆ ra8_sci_abort()

◆ ra8_sci_attach_rx_handler()

◆ ra8_sci_attach_tx_handler()

◆ ra8_sci_baud_calculate()

◆ ra8_sci_clear_errors()

◆ ra8_sci_deinit()

◆ ra8_sci_dispatch_eri()

◆ ra8_sci_dispatch_rxi()

◆ ra8_sci_dispatch_txi()

◆ ra8_sci_enter_stop()

◆ ra8_sci_exit_stop()

◆ ra8_sci_flush()

◆ ra8_sci_get_errors()

◆ ra8_sci_getc_polling()

◆ ra8_sci_init()

◆ ra8_sci_putc_polling()

◆ ra8_sci_read()

◆ ra8_sci_read_dma()

◆ ra8_sci_read_stop()

◆ ra8_sci_receive_resume()

◆ ra8_sci_receive_suspend()

◆ ra8_sci_set_baud()

◆ ra8_sci_write()

◆ ra8_sci_write_dma()

◆ ra8_sci_write_polling()