ra8_i3c.h File Reference

I3C Bus Interface driver – unified native-I3C + I2C-compat modes. More...

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

Include dependency graph for ra8_i3c.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_i3c_cfg_t
	Per-channel bring-up configuration for ra8_i3c_init. More...
struct	ra8_i3c_daa_target_t
	One target entry filled in by ENTDAA (native mode). More...
struct	ra8_i3c_ibi_t
	Decoded IBI inbound descriptor (native mode). More...
struct	ra8_i3c_peripheral_cfg_t
	Bring-up configuration for I2C-compat responder mode. More...

Typedefs
typedef void(*	ra8_i3c_event_fn_t) (void *ctx, uint32_t status)
	Event callback fired by ra8_i3c_dispatch.

Enumerations
enum	ra8_i3c_mode_t : uint8_t {   k_ra8_i3c_mode_native = 0U ,   k_ra8_i3c_mode_i2c = 1U }
	Operating mode selected per channel at ra8_i3c_init. More...
enum	ra8_i3c_err_t : uint8_t {   k_ra8_i3c_err_none = 0x00U ,   k_ra8_i3c_err_arb_lost = 0x01U ,   k_ra8_i3c_err_nack = 0x02U ,   k_ra8_i3c_err_timeout = 0x04U }
	Latched error bits returned by ra8_i3c_get_errors (I2C mode). More...
enum	ra8_i3c_ibi_type_t : uint8_t {   k_ra8_i3c_ibi_type_interrupt = 0U ,   k_ra8_i3c_ibi_type_hot_join = 1U ,   k_ra8_i3c_ibi_type_main_request = 2U }
	Type encoded in an IBI status descriptor (native mode). More...
enum	ra8_i3c_hdr_mode_t : uint8_t {   k_ra8_i3c_hdr_mode_sdr = 0U ,   k_ra8_i3c_hdr_mode_ddr = 1U ,   k_ra8_i3c_hdr_mode_ts = 2U }
	HDR transfer-mode selector for ra8_i3c_set_hdr_mode (native). More...
enum	ra8_i3c_peripheral_status_t : uint8_t {   k_ra8_i3c_peripheral_status_idle = 0x00U ,   k_ra8_i3c_peripheral_status_aas = 0x01U ,   k_ra8_i3c_peripheral_status_rx_full = 0x02U ,   k_ra8_i3c_peripheral_status_tx_empty = 0x04U ,   k_ra8_i3c_peripheral_status_stop = 0x08U ,   k_ra8_i3c_peripheral_status_nack = 0x10U }
	Latched responder-mode event bits from ra8_i3c_peripheral_status. More...

Functions
ra8_err_t	ra8_i3c_init (uint8_t channel, const ra8_i3c_cfg_t *cfg)
	Initialise an I3C channel in the configured mode.
ra8_err_t	ra8_i3c_deinit (uint8_t channel)
	Tear down an I3C channel and gate the peripheral.
ra8_err_t	ra8_i3c_write (uint8_t channel, uint8_t addr, const uint8_t *data, uint32_t len, bool restart)
	Write len bytes to addr.
ra8_err_t	ra8_i3c_read (uint8_t channel, uint8_t addr, uint8_t *buf, uint32_t len, bool restart)
	Read len bytes from addr.
ra8_err_t	ra8_i3c_transfer (uint8_t channel, uint8_t addr, const uint8_t *wr, uint32_t wr_len, uint8_t *rd, uint32_t rd_len)
	Write-then-read with repeated-START framing (I2C mode).
ra8_err_t	ra8_i3c_set_clock (uint8_t channel, uint32_t bus_hz, uint32_t pclka_hz)
	Re-programme the I2C bit rate (I2C mode).
ra8_err_t	ra8_i3c_scan (uint8_t channel, uint8_t addr, bool *out_acked)
	Probe whether a 7-bit address acknowledges (I2C mode).
ra8_err_t	ra8_i3c_get_errors (uint8_t channel, uint8_t *out_mask)
	Read the latched I2C error mask (I2C mode).
ra8_err_t	ra8_i3c_clear_errors (uint8_t channel)
	Clear latched I2C error bits (I2C mode).
ra8_err_t	ra8_i3c_abort (uint8_t channel)
	Abort an in-flight I2C transfer and release the bus (I2C mode).
ra8_err_t	ra8_i3c_attach_handler (uint8_t channel, ra8_i3c_event_fn_t fn, void *ctx)
	Attach an event callback for a channel.
void	ra8_i3c_dispatch (uint8_t channel)
	Snapshot status and fire the channel's callback.
ra8_err_t	ra8_i3c_set_address (uint32_t addr)
	Programme the primary dynamic address (native mode).
ra8_err_t	ra8_i3c_bus_enable (bool enable)
	Enable/disable bus-primary operation via BCTL.BUSE (native mode).
ra8_err_t	ra8_i3c_get_status (uint32_t *out_mask)
	Read the native INST status register (native mode).
ra8_err_t	ra8_i3c_clear_status (uint32_t mask)
	Clear native INST status bits (native mode).
ra8_err_t	ra8_i3c_enter_stop (void)
	Put native I3C0 into MSTP-gated stop (native mode).
ra8_err_t	ra8_i3c_exit_stop (void)
	Exit MSTP-gated stop (native mode).
ra8_err_t	ra8_i3c_dynamic_address_assign (ra8_i3c_daa_target_t *targets, uint8_t target_count)
	Issue ENTDAA to enumerate I3C targets (native mode).
ra8_err_t	ra8_i3c_set_dynamic_address (uint8_t static_addr, uint8_t dynamic_addr)
	Issue SETDASA to assign one target a dynamic address (native mode).
ra8_err_t	ra8_i3c_reset_dynamic_addresses (void)
	Issue RSTDAA to clear all dynamic addresses (native mode).
ra8_err_t	ra8_i3c_send_ccc (uint8_t ccc, uint8_t target_addr, const uint8_t *payload, uint8_t len)
	Generic CCC send – broadcast or directed write (native mode).
ra8_err_t	ra8_i3c_recv_ccc (uint8_t ccc, uint8_t target_addr, uint8_t *buf, uint8_t max_len, uint8_t *got_len)
	Generic CCC receive – directed read (native mode).
ra8_err_t	ra8_i3c_set_hdr_mode (uint8_t target_addr, ra8_i3c_hdr_mode_t mode)
	Programme the NCMDQP transfer-mode field for a target (native mode).
ra8_err_t	ra8_i3c_ibi_enable (uint8_t target_addr)
	Enable inbound IBI capture for a target (native mode).
ra8_err_t	ra8_i3c_ibi_drain (ra8_i3c_ibi_t *ibi)
	Pop one inbound IBI (alias of ra8_i3c_ibi_read, native mode).
ra8_err_t	ra8_i3c_ibi_read (ra8_i3c_ibi_t *out_ibi)
	Drain one inbound IBI from NIBIQP (native mode).
ra8_err_t	ra8_i3c_target_open (uint8_t static_addr)
	Enter peripheral (target) mode (native mode).
ra8_err_t	ra8_i3c_peripheral_open (uint8_t channel, const ra8_i3c_peripheral_cfg_t *cfg)
	Open a channel in I2C-compat responder mode.
ra8_err_t	ra8_i3c_peripheral_close (uint8_t channel)
	Close responder mode on a channel.
ra8_err_t	ra8_i3c_peripheral_send (uint8_t channel, const uint8_t *data, uint32_t len)
	Queue bytes for the controller to read (responder mode).
ra8_err_t	ra8_i3c_peripheral_receive (uint8_t channel, uint8_t *buf, uint32_t len)
	Read bytes the controller wrote (responder mode).
ra8_err_t	ra8_i3c_peripheral_status (uint8_t channel, uint8_t *out_mask)
	Read the latched responder-mode status (responder mode).

Detailed Description

I3C Bus Interface driver – unified native-I3C + I2C-compat modes.

Tag

[Ring 3 / HAL] {World: NS}

Single driver for the RA8D2 I3C peripheral (I3C0 @ 0x4035F000). The peripheral can run in two modes, selected per channel at init via ra8_i3c_cfg_t::mode:

• k_ra8_i3c_mode_native – full MIPI I3C: dynamic address assignment (DAA), Common Command Codes (CCC), private SDR read/write, HDR mode, In-Band Interrupts (IBI), and peripheral (target) mode. Mirrors FSP r_i3c – every transfer is a command descriptor pushed to NCMDQP with payload through NTDTBP0.
• k_ra8_i3c_mode_i2c – legacy I2C-compatibility controller (7-bit static addressing, START/RESTART/STOP, ACK/NACK, bus scan, SMBus). Mirrors FSP r_iic_b.

The data path (ra8_i3c_init, ra8_i3c_write, ra8_i3c_read, ra8_i3c_transfer, ra8_i3c_deinit) is shared and dispatches on the channel's configured mode. Mode-specific calls return k_ra8_err_invalid_state when used against a channel in the other mode:

• I2C-only: ra8_i3c_scan, ra8_i3c_set_clock, ra8_i3c_get_errors, ra8_i3c_clear_errors, ra8_i3c_abort.
• Native-only: ra8_i3c_set_address, ra8_i3c_bus_enable, ra8_i3c_dynamic_address_assign, ra8_i3c_set_dynamic_address, ra8_i3c_reset_dynamic_addresses, ra8_i3c_send_ccc, ra8_i3c_recv_ccc, ra8_i3c_set_hdr_mode, ra8_i3c_ibi_enable, ra8_i3c_ibi_drain, ra8_i3c_ibi_read, ra8_i3c_target_open, ra8_i3c_enter_stop, ra8_i3c_exit_stop.

See HUM Ch 40 "I3C Bus Interface (I3C)" pp 2445-2701 for the register-level reference.

Copyright

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

Definition in file ra8_i3c.h.

Typedef Documentation

ra8_i3c_event_fn_t

typedef void(* ra8_i3c_event_fn_t) (void *ctx, uint32_t status)

Event callback fired by ra8_i3c_dispatch.

Parameters

[in]	ctx	Opaque context registered with ra8_i3c_attach_handler.
[in]	status	In native mode the INST snapshot; in I2C mode the latched ra8_i3c_err_t mask.

Since

0.1.0

Definition at line 123 of file ra8_i3c.h.

Enumeration Type Documentation

ra8_i3c_err_t

enum ra8_i3c_err_t : uint8_t

Latched error bits returned by ra8_i3c_get_errors (I2C mode).

Mirrors the legacy IIC_B status: a bitwise OR of the conditions latched since the last ra8_i3c_clear_errors.

Invariant

k_ra8_i3c_err_none is the all-clear sentinel (0).

See also

ra8_i3c_get_errors

Since

0.1.0

Enumerator
k_ra8_i3c_err_none	No latched error.
k_ra8_i3c_err_arb_lost	Arbitration lost (BST.ALF).
k_ra8_i3c_err_nack	NACK received (BST.NACKDF).
k_ra8_i3c_err_timeout	Bus timeout (BST.TODF).

Definition at line 107 of file ra8_i3c.h.

ra8_i3c_hdr_mode_t

enum ra8_i3c_hdr_mode_t : uint8_t

HDR transfer-mode selector for ra8_i3c_set_hdr_mode (native).

Invariant

Values map to NCMDQP word-0 [27:26].

See also

ra8_i3c_set_hdr_mode

Since

0.1.0

Enumerator
k_ra8_i3c_hdr_mode_sdr	Plain SDR transfer (default).
k_ra8_i3c_hdr_mode_ddr	HDR-DDR.
k_ra8_i3c_hdr_mode_ts	HDR-TS.

Definition at line 185 of file ra8_i3c.h.

ra8_i3c_ibi_type_t

enum ra8_i3c_ibi_type_t : uint8_t

Type encoded in an IBI status descriptor (native mode).

Invariant

Values match the MIPI IBI-ID low bits.

See also

ra8_i3c_ibi_t

Since

0.1.0

Enumerator
k_ra8_i3c_ibi_type_interrupt	Peripheral-initiated IBI.
k_ra8_i3c_ibi_type_hot_join	Hot-join request.
k_ra8_i3c_ibi_type_main_request	Mainship request.

Definition at line 152 of file ra8_i3c.h.

ra8_i3c_mode_t

enum ra8_i3c_mode_t : uint8_t

Operating mode selected per channel at ra8_i3c_init.

The I3C peripheral is a single block that can act as a native MIPI I3C controller/target or as a legacy I2C-compatibility controller. The mode is fixed for the life of an init/deinit cycle and recorded in the driver's per-channel state so the shared data-path functions can dispatch.

Invariant

Exactly one mode is active per channel between init/deinit.

See also

ra8_i3c_cfg_t

Since

0.1.0

Enumerator
k_ra8_i3c_mode_native	Native MIPI I3C (DAA/CCC/SDR/HDR/IBI).
k_ra8_i3c_mode_i2c	Legacy I2C-compatibility controller.

Definition at line 67 of file ra8_i3c.h.

ra8_i3c_peripheral_status_t

enum ra8_i3c_peripheral_status_t : uint8_t

Latched responder-mode event bits from ra8_i3c_peripheral_status.

Invariant

k_ra8_i3c_peripheral_status_idle is the all-clear sentinel (0).

See also

ra8_i3c_peripheral_status

Since

0.1.0

Enumerator
k_ra8_i3c_peripheral_status_idle	No latched event.
k_ra8_i3c_peripheral_status_aas	Address matched.
k_ra8_i3c_peripheral_status_rx_full	Receive buffer full.
k_ra8_i3c_peripheral_status_tx_empty	Transmit buffer empty.
k_ra8_i3c_peripheral_status_stop	STOP detected.
k_ra8_i3c_peripheral_status_nack	NACK detected.

Definition at line 787 of file ra8_i3c.h.

Function Documentation

ra8_i3c_abort()

ra8_err_t ra8_i3c_abort ( uint8_t channel )

nodiscard

Abort an in-flight I2C transfer and release the bus (I2C mode).

Parameters

[in]

channel

I3C channel index.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Bus released.
k_ra8_err_invalid_state	Channel is in native mode.

Precondition

Channel initialized in I2C mode.

Caller is single-threaded.

Postcondition

The bus is idle and any held state is cleared.

A subsequent transfer starts from a clean state.

Note

Not thread-safe.

Since

0.1.0

Definition at line 762 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_abort(), and s_i3c_chan.

ra8_i3c_attach_handler()

ra8_err_t ra8_i3c_attach_handler ( uint8_t channel, ra8_i3c_event_fn_t fn, void * ctx )

nodiscard

Attach an event callback for a channel.

Parameters

[in]	channel	I3C channel index.
[in]	fn	Callback (NULL to detach).
[in]	ctx	Opaque context passed back to fn.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Handler registered.
k_ra8_err_invalid_arg	channel out of range.

Precondition

Channel initialized.

Caller is single-threaded with respect to dispatch.

Postcondition

The channel's handler equals fn.

The channel's context equals ctx.

Note

Not thread-safe.

Since

0.1.0

Definition at line 415 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_i3c_i2c_channel_count, k_ra8_ok, s_i3c_ctx, and s_i3c_fn.

ra8_i3c_bus_enable()

ra8_err_t ra8_i3c_bus_enable ( bool enable )

nodiscard

Enable/disable bus-primary operation via BCTL.BUSE (native mode).

Parameters

[in]

enable

True to enable primary operation.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	BUSE updated.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition

I3C0 initialized in native mode.

Caller is single-threaded.

Postcondition

BCTL.BUSE reflects enable.

No transfer is in progress.

Note

Not thread-safe.

Since

0.1.0

Definition at line 385 of file ra8_i3c.c.

References r_i3c_regs_t::BCTL, k_ra8_i3c_bctl_buse_mask, k_ra8_ok, and ra8_i3c().

ra8_i3c_clear_errors()

ra8_err_t ra8_i3c_clear_errors ( uint8_t channel )

nodiscard

Clear latched I2C error bits (I2C mode).

Parameters

[in]

channel

I3C channel index.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Errors cleared.
k_ra8_err_invalid_state	Channel is in native mode.

Precondition

Channel initialized in I2C mode.

Caller is single-threaded.

Postcondition

The latched error mask reads k_ra8_i3c_err_none.

No transfer is in progress.

Note

Not thread-safe.

Since

0.1.0

Definition at line 751 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_clear_errors(), and s_i3c_chan.

ra8_i3c_clear_status()

ra8_err_t ra8_i3c_clear_status ( uint32_t mask )

nodiscard

Clear native INST status bits (native mode).

Parameters

[in]

mask

Bits to clear.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Bits cleared.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition

I3C0 initialized in native mode.

Caller is single-threaded.

Postcondition

The requested INST bits read 0.

Other bits are unchanged.

Note

Not thread-safe.

Since

0.1.0

Definition at line 406 of file ra8_i3c.c.

References r_i3c_regs_t::INST, k_ra8_ok, and ra8_i3c().

ra8_i3c_deinit()

ra8_err_t ra8_i3c_deinit ( uint8_t channel )

nodiscard

Tear down an I3C channel and gate the peripheral.

Parameters

[in]

channel

I3C channel index.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Channel torn down, MSTP gated.
k_ra8_err_invalid_arg	channel out of range.

Precondition

channel was previously initialized.

Caller is single-threaded with respect to the peripheral.

Postcondition

The channel is marked uninitialized.

The I3C MSTP is gated when no channel remains active.

Note

Not thread-safe.

Since

0.1.0

Definition at line 348 of file ra8_i3c.c.

References r_i3c_regs_t::BCTL, r_i3c_regs_t::CECTL, r_i3c_regs_t::INIE, r_i3c_regs_t::INSTE, k_ra8_err_invalid_arg, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, k_ra8_mstp_i3c, ra8_i3c(), ra8_i3c_i2c_deinit(), ra8_mstp_disable(), s_i3c_chan, s_i3c_ctx, and s_i3c_fn.

ra8_i3c_dispatch()

void ra8_i3c_dispatch

(

uint8_t

channel

)

Snapshot status and fire the channel's callback.

In native mode reads and clears the INST register and passes the snapshot to the handler; in I2C mode reads and clears the latched IIC_B error mask and passes it instead. A no-op when no handler is attached.

Parameters

[in]

channel

I3C channel index.

Precondition

Channel initialized.

A handler may or may not be attached.

Postcondition

The status flags are cleared after snapshot.

The handler (if any) has been invoked once.

Note

Not thread-safe; call from IRQ or polled context.

Since

0.1.0

Definition at line 426 of file ra8_i3c.c.

References r_i3c_regs_t::INST, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c(), ra8_i3c_i2c_clear_errors(), ra8_i3c_i2c_get_errors(), s_i3c_chan, s_i3c_ctx, and s_i3c_fn.

ra8_i3c_dynamic_address_assign()

ra8_err_t ra8_i3c_dynamic_address_assign ( ra8_i3c_daa_target_t * targets, uint8_t target_count )

nodiscard

Issue ENTDAA to enumerate I3C targets (native mode).

Parameters

[in,out]	targets	Caller array; rows updated in place.
[in]	target_count	Number of valid rows (1..max).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Command queued; FIFOs read.
k_ra8_err_null_ptr	targets NULL.
k_ra8_err_invalid_arg	target_count 0 or out of range.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition

I3C0 initialized in native mode and bus enabled.

targets non-NULL.

Postcondition

NCMDQP holds the ENTDAA descriptor.

targets reflect responses received before STOP.

Note

Not thread-safe.

Since

0.1.0

< Pid bcr dcr bytes.

< Index bcr.

< Index dcr.

Definition at line 470 of file ra8_i3c.c.

References internal_ra8_i3c_fifo_read(), k_ra8_err_invalid_arg, k_ra8_i3c_ccc_b_entdaa, k_ra8_i3c_cmd_addr_count_shift, k_ra8_i3c_cmd_attr_addr_assgn, k_ra8_i3c_cmd_attr_shift, k_ra8_i3c_cmd_code_shift, k_ra8_i3c_cmd_roc_shift, k_ra8_i3c_cmd_toc_shift, k_ra8_i3c_max_targets, k_ra8_i3c_ntst_cmdqef_mask, k_ra8_i3c_pid_bytes, k_ra8_ok, r_i3c_regs_t::NCMDQP, r_i3c_regs_t::NTST, RA8_CHECK_NULL_PTR, ra8_i3c(), and s_tag.

ra8_i3c_enter_stop()

ra8_err_t ra8_i3c_enter_stop ( void )

nodiscard

Put native I3C0 into MSTP-gated stop (native mode).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Stopped.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition

I3C0 initialized in native mode.

Caller is single-threaded.

Postcondition

BCTL/CECTL cleared and the MSTP gated.

The bus is idle.

Note

Not thread-safe.

Since

0.1.0

Definition at line 452 of file ra8_i3c.c.

References r_i3c_regs_t::BCTL, r_i3c_regs_t::CECTL, k_ra8_mstp_i3c, ra8_i3c(), and ra8_mstp_disable().

ra8_i3c_exit_stop()

ra8_err_t ra8_i3c_exit_stop ( void )

nodiscard

Exit MSTP-gated stop (native mode).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Resumed.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition

I3C0 was put into stop via ra8_i3c_enter_stop.

Caller is single-threaded.

Postcondition

The I3C MSTP is ungated.

The peripheral is ready for re-init of bus state.

Note

Not thread-safe.

Since

0.1.0

Definition at line 460 of file ra8_i3c.c.

References k_ra8_mstp_i3c, and ra8_mstp_enable().

ra8_i3c_get_errors()

ra8_err_t ra8_i3c_get_errors ( uint8_t channel, uint8_t * out_mask )

nodiscard

Read the latched I2C error mask (I2C mode).

Parameters

[in]	channel	I3C channel index.
[out]	out_mask	OR of ra8_i3c_err_t bits since the last clear.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Mask returned.
k_ra8_err_null_ptr	out_mask NULL.
k_ra8_err_invalid_state	Channel is in native mode.

Precondition

Channel initialized in I2C mode.

out_mask is non-NULL.

Postcondition

out_mask holds the latched error bits.

No peripheral state is mutated.

Note

Not thread-safe.

Since

0.1.0

Definition at line 740 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_get_errors(), and s_i3c_chan.

ra8_i3c_get_status()

ra8_err_t ra8_i3c_get_status ( uint32_t * out_mask )

nodiscard

Read the native INST status register (native mode).

Parameters

[out]

out_mask

INST snapshot.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Status returned.
k_ra8_err_null_ptr	out_mask NULL.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition

I3C0 initialized in native mode.

out_mask non-NULL.

Postcondition

out_mask holds the INST snapshot.

No peripheral state is mutated.

Note

Not thread-safe.

Since

0.1.0

Definition at line 398 of file ra8_i3c.c.

References r_i3c_regs_t::INST, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_i3c(), and s_tag.

ra8_i3c_ibi_drain()

ra8_err_t ra8_i3c_ibi_drain ( ra8_i3c_ibi_t * ibi )

nodiscard

Pop one inbound IBI (alias of ra8_i3c_ibi_read, native mode).

Parameters

[out]

ibi

Descriptor populated on success.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	One IBI dequeued.
k_ra8_err_no_data	IBI queue empty.
k_ra8_err_null_ptr	ibi NULL.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition

I3C0 initialized in native mode.

ibi non-NULL.

Postcondition

On success ibi holds the descriptor.

NTST.IBIQEFF cleared on success.

Note

Not thread-safe.

Since

0.1.0

Definition at line 888 of file ra8_i3c.c.

References ra8_i3c_ibi_read().

ra8_i3c_ibi_enable()

ra8_err_t ra8_i3c_ibi_enable ( uint8_t target_addr )

nodiscard

Enable inbound IBI capture for a target (native mode).

Parameters

[in]

target_addr

7-bit dynamic address authorised to push an IBI.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	IBI capture enabled.
k_ra8_err_invalid_arg	target_addr out of range.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition

I3C0 initialized in native mode.

Caller is in IRQ-masked or init context.

Postcondition

NTIBIVCTL.VLCNT is set for the target.

Subsequent IBIs from the target are queued.

Note

Not thread-safe.

Since

0.1.0

< RA8 I3C ntibivctl one target.

Definition at line 871 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_i3c_addr_mask, k_ra8_i3c_ntibivctl_vlcnt_mask, k_ra8_i3c_ntibivctl_vlcnt_shift, k_ra8_ok, r_i3c_regs_t::NTIBIVCTL, and ra8_i3c().

ra8_i3c_ibi_read()

ra8_err_t ra8_i3c_ibi_read ( ra8_i3c_ibi_t * out_ibi )

nodiscard

Drain one inbound IBI from NIBIQP (native mode).

Parameters

[out]

out_ibi

Descriptor populated on success.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	One IBI dequeued.
k_ra8_err_no_data	IBI queue empty.
k_ra8_err_null_ptr	out_ibi NULL.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition

I3C0 initialized in native mode.

out_ibi non-NULL.

Postcondition

On success out_ibi holds the descriptor.

NTST.IBIQEFF cleared on success.

Note

Not thread-safe.

Since

0.1.0

< Ibi ID hot join.

< Ibi last mask.

Definition at line 920 of file ra8_i3c.c.

References ra8_i3c_ibi_t::address, internal_ra8_i3c_fifo_read(), k_ra8_err_no_data, k_ra8_i3c_addr_shift_in_ibi_id, k_ra8_i3c_ibi_status_ibi_st_mask, k_ra8_i3c_ibi_status_id_mask, k_ra8_i3c_ibi_status_id_shift, k_ra8_i3c_ibi_status_last_shift, k_ra8_i3c_ibi_status_length_mask, k_ra8_i3c_ibi_status_length_shift, k_ra8_i3c_ibi_type_hot_join, k_ra8_i3c_ibi_type_interrupt, k_ra8_i3c_ibi_type_main_request, k_ra8_i3c_ntst_ibiqeff_mask, k_ra8_ok, ra8_i3c_ibi_t::last, r_i3c_regs_t::NIBIQP, r_i3c_regs_t::NTST, ra8_i3c_ibi_t::payload, ra8_i3c_ibi_t::payload_len, RA8_CHECK_NULL_PTR, ra8_i3c(), s_tag, and ra8_i3c_ibi_t::type.

Referenced by ra8_i3c_ibi_drain().

ra8_i3c_init()

ra8_err_t ra8_i3c_init ( uint8_t channel, const ra8_i3c_cfg_t * cfg )

nodiscard

Initialise an I3C channel in the configured mode.

Ungates the I3C MSTP, runs the FSP-mirrored bring-up, and – in I2C mode – programmes the bit-rate from cfg. The channel's mode is recorded so later data-path calls dispatch correctly. Native mode leaves the bus disabled (call ra8_i3c_bus_enable separately).

Parameters

[in]	channel	I3C channel index (0 on RA8D2).
[in]	cfg	Bring-up configuration; must be non-NULL.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Channel ready in the requested mode.
k_ra8_err_null_ptr	cfg was NULL.
k_ra8_err_invalid_arg	channel out of range, or zero clocks in I2C mode.
k_ra8_err_hw_init_failed	MSTP enable failed.

Precondition

MSTP module is initialized.

No other driver owns the I3C peripheral.

Postcondition

On success the channel's mode equals cfg->mode.

On failure no peripheral state is left half-configured.

Note

Not thread-safe; call from single-threaded init.

Since

0.1.0

Definition at line 311 of file ra8_i3c.c.

References ra8_i3c_cfg_t::bus_hz, r_i3c_regs_t::INIE, r_i3c_regs_t::INST, r_i3c_regs_t::INSTE, r_i3c_regs_t::INSTFC, internal_ra8_i3c_reset_sequence(), k_ra8_err_invalid_arg, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, k_ra8_mstp_i3c, k_ra8_ok, ra8_i3c_cfg_t::mode, r_i3c_regs_t::MSDVAD, ra8_i3c_cfg_t::pclka_hz, RA8_CHECK_NULL_PTR, ra8_i3c(), ra8_i3c_i2c_init(), ra8_log_info, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, s_i3c_chan, and s_tag.

Referenced by combo_setup_or_halt(), i3c_demo_setup_or_halt(), imu_demo_setup_or_halt(), main(), ra8_board_touch_open(), and ra8_nsc_iic_init().

ra8_i3c_peripheral_close()

ra8_err_t ra8_i3c_peripheral_close ( uint8_t channel )

nodiscard

Close responder mode on a channel.

Parameters

[in]

channel

I3C channel index.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Responder mode closed.
k_ra8_err_invalid_arg	channel out of range.
k_ra8_err_invalid_state	Channel is not in I2C mode.

Precondition

Channel was opened in responder mode.

Caller is single-threaded.

Postcondition

The channel no longer answers as a responder.

The bus is released.

Note

Not thread-safe.

Since

0.1.0

Definition at line 796 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_peripheral_close(), and s_i3c_chan.

ra8_i3c_peripheral_open()

ra8_err_t ra8_i3c_peripheral_open ( uint8_t channel, const ra8_i3c_peripheral_cfg_t * cfg )

nodiscard

Open a channel in I2C-compat responder mode.

Parameters

[in]	channel	I3C channel index.
[in]	cfg	Responder configuration; non-NULL.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Responder mode entered.
k_ra8_err_null_ptr	cfg NULL.
k_ra8_err_invalid_arg	channel or address out of range.
k_ra8_err_invalid_state	Channel is not in I2C mode.

Precondition

Channel initialized in I2C mode.

cfg non-NULL.

Postcondition

The channel answers cfg->peripheral_addr_7b.

No transfer is in progress.

Note

Not thread-safe.

Since

0.1.0

Definition at line 778 of file ra8_i3c.c.

References ra8_i3c_peripheral_cfg_t::general_call, k_ra8_err_invalid_arg, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, k_ra8_ok, ra8_i3c_peripheral_cfg_t::peripheral_addr_7b, RA8_CHECK_NULL_PTR, ra8_i3c_i2c_peripheral_open(), s_i3c_chan, and s_tag.

Referenced by iic_facade_peripheral_phase(), and internal_iic_peripheral_setup_or_halt().

ra8_i3c_peripheral_receive()

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

nodiscard

Read bytes the controller wrote (responder mode).

Parameters

[in]	channel	I3C channel index.
[out]	buf	Destination buffer; non-NULL.
[in]	len	Byte count (> 0).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Bytes read.
k_ra8_err_null_ptr	buf NULL.
k_ra8_err_invalid_state	Channel is not in I2C mode.

Precondition

Channel opened in responder mode.

buf valid for len.

Postcondition

buf holds the received bytes.

The receive buffer is drained.

Note

Not thread-safe.

Since

0.1.0

Definition at line 818 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_peripheral_receive(), and s_i3c_chan.

Referenced by iic_facade_service(), and internal_iic_peripheral_service().

ra8_i3c_peripheral_send()

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

nodiscard

Queue bytes for the controller to read (responder mode).

Parameters

[in]	channel	I3C channel index.
[in]	data	Bytes to send; non-NULL when len > 0.
[in]	len	Byte count.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Bytes queued.
k_ra8_err_null_ptr	data NULL with len > 0.
k_ra8_err_invalid_state	Channel is not in I2C mode.

Precondition

Channel opened in responder mode.

data valid for len.

Postcondition

The bytes are staged for the next controller read.

No controller transfer is corrupted.

Note

Not thread-safe.

Since

0.1.0

Definition at line 807 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_peripheral_send(), and s_i3c_chan.

Referenced by iic_facade_service(), and internal_iic_peripheral_service().

ra8_i3c_peripheral_status()

ra8_err_t ra8_i3c_peripheral_status ( uint8_t channel, uint8_t * out_mask )

nodiscard

Read the latched responder-mode status (responder mode).

Parameters

[in]	channel	I3C channel index.
[out]	out_mask	OR of ra8_i3c_peripheral_status_t bits; non-NULL.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Status returned.
k_ra8_err_null_ptr	out_mask NULL.
k_ra8_err_invalid_state	Channel is not in I2C mode.

Precondition

Channel opened in responder mode.

out_mask non-NULL.

Postcondition

out_mask holds the latched event bits.

No peripheral state is mutated.

Note

Not thread-safe.

Since

0.1.0

Definition at line 829 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_peripheral_status(), and s_i3c_chan.

Referenced by iic_facade_service(), and internal_iic_peripheral_service().

ra8_i3c_read()

ra8_err_t ra8_i3c_read ( uint8_t channel, uint8_t addr, uint8_t * buf, uint32_t len, bool restart )

nodiscard

Read len bytes from addr.

I2C mode: controller receive from 7-bit addr. Native mode: private SDR read from dynamic address addr; restart is ignored.

Parameters

[in]	channel	I3C channel index.
[in]	addr	7-bit target/dynamic address.
[out]	buf	Destination buffer; must be non-NULL.
[in]	len	Byte count (> 0).
[in]	restart	True to hold the bus for a following transfer (I2C).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	All bytes received.
k_ra8_err_null_ptr	buf NULL.
k_ra8_err_invalid_arg	channel/addr out of range, or len 0.
k_ra8_err_nack	Target did not acknowledge (I2C).
k_ra8_err_hw_timeout	Bus stalled (I2C).

Precondition

Channel initialized.

In native mode the bus is enabled.

Postcondition

On success buf holds the received bytes.

On failure the bus is released (I2C) where possible.

Note

Not thread-safe.

Since

0.1.0

Definition at line 666 of file ra8_i3c.c.

References internal_ra8_i3c_fifo_read(), internal_ra8_i3c_xfer_cmd_word(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_addr_mask, k_ra8_i3c_cmd_xfer_length_max, k_ra8_i3c_cmd_xfer_length_shift, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, k_ra8_i3c_ntst_cmdqef_mask, k_ra8_ok, r_i3c_regs_t::NCMDQP, r_i3c_regs_t::NTST, RA8_CHECK_NULL_PTR, ra8_i3c(), ra8_i3c_i2c_read(), s_i3c_chan, and s_tag.

Referenced by er_fg_read(), internal_i3c_compat_read(), and ra8_nsc_iic_read().

ra8_i3c_recv_ccc()

ra8_err_t ra8_i3c_recv_ccc ( uint8_t ccc, uint8_t target_addr, uint8_t * buf, uint8_t max_len, uint8_t * got_len )

nodiscard

Generic CCC receive – directed read (native mode).

Parameters

[in]	ccc	Direct CCC opcode (bit 7 set).
[in]	target_addr	Dynamic address.
[out]	buf	Destination buffer.
[in]	max_len	Maximum bytes to drain (> 0).
[out]	got_len	Bytes actually drained.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Read complete.
k_ra8_err_invalid_arg	Non-direct CCC, address bad, or max_len 0.
k_ra8_err_null_ptr	Output pointers NULL.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition

I3C0 initialized in native mode.

buf and got_len non-NULL.

Postcondition

buf holds the response bytes.

got_len holds the drained count.

Note

Not thread-safe.

Since

0.1.0

Definition at line 593 of file ra8_i3c.c.

References internal_ra8_i3c_ccc_cmd_word(), internal_ra8_i3c_fifo_read(), k_ra8_err_invalid_arg, k_ra8_i3c_addr_mask, k_ra8_i3c_ccc_direct_mask, k_ra8_i3c_cmd_xfer_length_shift, k_ra8_i3c_ntst_cmdqef_mask, k_ra8_ok, r_i3c_regs_t::NCMDQP, r_i3c_regs_t::NTST, priv_ra8_i3c_internal_recv_ccc_invalid(), RA8_CHECK_NULL_PTR, ra8_i3c(), and s_tag.

ra8_i3c_reset_dynamic_addresses()

ra8_err_t ra8_i3c_reset_dynamic_addresses ( void )

nodiscard

Issue RSTDAA to clear all dynamic addresses (native mode).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Descriptor queued.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition

I3C0 initialized in native mode.

Caller is single-threaded.

Postcondition

NCMDQP holds the RSTDAA descriptor.

The command-queue-empty flag is cleared.

Note

Not thread-safe.

Since

0.1.0

Definition at line 539 of file ra8_i3c.c.

References internal_ra8_i3c_ccc_cmd_word(), k_ra8_i3c_ccc_b_rstdaa, k_ra8_i3c_ntst_cmdqef_mask, k_ra8_ok, r_i3c_regs_t::NCMDQP, r_i3c_regs_t::NTST, and ra8_i3c().

ra8_i3c_scan()

ra8_err_t ra8_i3c_scan ( uint8_t channel, uint8_t addr, bool * out_acked )

nodiscard

Probe whether a 7-bit address acknowledges (I2C mode).

Parameters

[in]	channel	I3C channel index.
[in]	addr	7-bit address to probe.
[out]	out_acked	Set true if the address ACKed; false otherwise.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Probe completed (see out_acked).
k_ra8_err_null_ptr	out_acked NULL.
k_ra8_err_invalid_state	Channel is in native mode.

Precondition

Channel initialized in I2C mode.

out_acked is non-NULL.

Postcondition

out_acked reflects the ACK/NACK outcome.

The bus is released with a STOP.

Note

Not thread-safe.

Since

0.1.0

Definition at line 729 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_scan(), and s_i3c_chan.

Referenced by main().

ra8_i3c_send_ccc()

ra8_err_t ra8_i3c_send_ccc ( uint8_t ccc, uint8_t target_addr, const uint8_t * payload, uint8_t len )

nodiscard

Generic CCC send – broadcast or directed write (native mode).

Parameters

[in]	ccc	CCC opcode.
[in]	target_addr	Dynamic address (directed CCCs only).
[in]	payload	Optional payload; NULL when len is 0.
[in]	len	Payload byte count.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Descriptor queued.
k_ra8_err_invalid_arg	Address out of range.
k_ra8_err_null_ptr	payload NULL with len > 0.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition

I3C0 initialized in native mode.

Caller is single-threaded.

Postcondition

NCMDQP holds the CCC descriptor.

Payload (if any) was pushed to NTDTBP0.

Note

Not thread-safe.

Since

0.1.0

Definition at line 555 of file ra8_i3c.c.

References internal_ra8_i3c_ccc_cmd_word(), internal_ra8_i3c_fifo_write(), k_ra8_err_invalid_arg, k_ra8_err_null_ptr, k_ra8_i3c_addr_mask, k_ra8_i3c_byte_shift, k_ra8_i3c_cmd_attr_immed, k_ra8_i3c_cmd_attr_shift, k_ra8_i3c_cmd_immed_bytes_shift, k_ra8_i3c_cmd_xfer_length_shift, k_ra8_i3c_immediate_max_bytes, k_ra8_i3c_ntst_cmdqef_mask, k_ra8_ok, r_i3c_regs_t::NCMDQP, r_i3c_regs_t::NTST, and ra8_i3c().

ra8_i3c_set_address()

ra8_err_t ra8_i3c_set_address ( uint32_t addr )

nodiscard

Programme the primary dynamic address (native mode).

Parameters

[in]

addr

7-bit primary address.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Address programmed.
k_ra8_err_invalid_arg	addr out of range.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition

I3C0 initialized in native mode.

Caller is single-threaded.

Postcondition

MSDVAD reflects addr with the valid bit set.

The bus may still be disabled.

Note

Not thread-safe.

Since

0.1.0

Definition at line 372 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_i3c_msdvad_addr_max, k_ra8_i3c_msdvad_mdyad_mask, k_ra8_i3c_msdvad_mdyad_shift, k_ra8_i3c_msdvad_mdyadv_mask, k_ra8_ok, r_i3c_regs_t::MSDVAD, and ra8_i3c().

ra8_i3c_set_clock()

ra8_err_t ra8_i3c_set_clock ( uint8_t channel, uint32_t bus_hz, uint32_t pclka_hz )

nodiscard

Re-programme the I2C bit rate (I2C mode).

Parameters

[in]	channel	I3C channel index.
[in]	bus_hz	Target bus clock in Hz.
[in]	pclka_hz	Source clock for the divider calculation.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Bit rate updated.
k_ra8_err_invalid_arg	channel out of range or zero clocks.
k_ra8_err_invalid_state	Channel is in native mode.

Precondition

Channel initialized in I2C mode.

bus_hz and pclka_hz are non-zero.

Postcondition

On success the divider reflects bus_hz / pclka_hz.

On failure the previous divider is unchanged.

Note

Not thread-safe.

Since

0.1.0

Definition at line 718 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_set_clock(), and s_i3c_chan.

ra8_i3c_set_dynamic_address()

ra8_err_t ra8_i3c_set_dynamic_address ( uint8_t static_addr, uint8_t dynamic_addr )

nodiscard

Issue SETDASA to assign one target a dynamic address (native mode).

Parameters

[in]	static_addr	7-bit static address in use by the target.
[in]	dynamic_addr	7-bit dynamic address to assign.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Descriptor queued.
k_ra8_err_invalid_arg	Address out of range.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition

I3C0 initialized in native mode.

Caller is single-threaded.

Postcondition

NCMDQP holds the SETDASA descriptor.

The command-queue-empty flag is cleared.

Note

Not thread-safe.

Since

0.1.0

Definition at line 518 of file ra8_i3c.c.

References internal_ra8_i3c_ccc_cmd_word(), k_ra8_err_invalid_arg, k_ra8_i3c_addr_mask, k_ra8_i3c_ccc_d_setdasa, k_ra8_i3c_cmd_attr_immed, k_ra8_i3c_cmd_attr_shift, k_ra8_i3c_cmd_immed_bytes_shift, k_ra8_i3c_ntst_cmdqef_mask, k_ra8_i3c_setdasa_payload_bytes, k_ra8_ok, r_i3c_regs_t::NCMDQP, r_i3c_regs_t::NTST, and ra8_i3c().

ra8_i3c_set_hdr_mode()

ra8_err_t ra8_i3c_set_hdr_mode ( uint8_t target_addr, ra8_i3c_hdr_mode_t mode )

nodiscard

Programme the NCMDQP transfer-mode field for a target (native mode).

Parameters

[in]	target_addr	7-bit dynamic address.
[in]	mode	HDR-mode selector.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Descriptor queued.
k_ra8_err_invalid_arg	target_addr or mode out of range.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition

I3C0 initialized in native mode and bus enabled.

Caller is single-threaded.

Postcondition

NCMDQP holds an HDR-mode descriptor.

The command-queue-empty flag is cleared.

Note

Not thread-safe.

Since

0.1.0

Definition at line 845 of file ra8_i3c.c.

References internal_ra8_i3c_xfer_cmd_word(), k_ra8_err_invalid_arg, k_ra8_i3c_addr_mask, k_ra8_i3c_cmd_hdr_mode_mask, k_ra8_i3c_cmd_xfer_mode_shift, k_ra8_i3c_hdr_mode_ddr, k_ra8_i3c_hdr_mode_sdr, k_ra8_i3c_hdr_mode_ts, k_ra8_i3c_ntst_cmdqef_mask, k_ra8_ok, r_i3c_regs_t::NCMDQP, r_i3c_regs_t::NTST, priv_ra8_i3c_internal_hdr_mode_invalid(), and ra8_i3c().

ra8_i3c_target_open()

ra8_err_t ra8_i3c_target_open ( uint8_t static_addr )

nodiscard

Enter peripheral (target) mode (native mode).

Parameters

[in]

static_addr

Static (pre-DAA) 7-bit address.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Peripheral mode entered.
k_ra8_err_invalid_arg	static_addr out of range.
k_ra8_err_invalid_state	I3C0 is not in native mode.

Precondition

I3C0 initialized in native mode.

Caller is single-threaded init context.

Postcondition

BCTL.SLVE set; BCTL.BUSE clear.

NSDVAD reflects static_addr with the valid bit set.

Note

Not thread-safe.

Since

0.1.0

Definition at line 893 of file ra8_i3c.c.

References r_i3c_regs_t::BCTL, k_ra8_err_invalid_arg, k_ra8_i3c_addr_mask, k_ra8_i3c_bctl_buse_mask, k_ra8_i3c_bctl_slve_mask, k_ra8_i3c_nsdvad_sdyad_mask, k_ra8_i3c_nsdvad_sdyad_shift, k_ra8_i3c_nsdvad_sdyadv_mask, k_ra8_ok, r_i3c_regs_t::NSDVAD, and ra8_i3c().

ra8_i3c_transfer()

ra8_err_t ra8_i3c_transfer ( uint8_t channel, uint8_t addr, const uint8_t * wr, uint32_t wr_len, uint8_t * rd, uint32_t rd_len )

nodiscard

Write-then-read with repeated-START framing (I2C mode).

Transmits wr_len bytes, issues a repeated START, then reads rd_len bytes from the same address. Native mode returns k_ra8_err_invalid_state (use ra8_i3c_write / ra8_i3c_read or CCCs).

Parameters

[in]	channel	I3C channel index.
[in]	addr	7-bit target address.
[in]	wr	Bytes to write; non-NULL when wr_len > 0.
[in]	wr_len	Write byte count.
[out]	rd	Read destination; non-NULL when rd_len > 0.
[in]	rd_len	Read byte count.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Transfer completed.
k_ra8_err_null_ptr	A required buffer was NULL.
k_ra8_err_invalid_arg	channel/addr out of range.
k_ra8_err_invalid_state	Channel is in native mode.
k_ra8_err_nack	Target did not acknowledge.

Precondition

Channel initialized in I2C mode.

wr_len + rd_len > 0.

Postcondition

On success both phases completed and STOP was issued.

On failure the bus is released.

Note

Not thread-safe.

Since

0.1.0

Definition at line 702 of file ra8_i3c.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_mode_i2c, ra8_i3c_i2c_transfer(), and s_i3c_chan.

Referenced by imu_demo_iic_read(), and internal_i3c_compat_transfer().

ra8_i3c_write()

ra8_err_t ra8_i3c_write ( uint8_t channel, uint8_t addr, const uint8_t * data, uint32_t len, bool restart )

nodiscard

Write len bytes to addr.

In I2C mode this is a controller transmit to 7-bit addr with optional repeated-START framing. In native mode it is a private SDR write to the dynamic address addr; restart is ignored.

Parameters

[in]	channel	I3C channel index.
[in]	addr	7-bit target/dynamic address.
[in]	data	Bytes to transmit; may be NULL only when len is 0.
[in]	len	Byte count.
[in]	restart	True to hold the bus for a following transfer (I2C).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	All bytes transmitted.
k_ra8_err_null_ptr	data NULL with len > 0.
k_ra8_err_invalid_arg	channel or addr out of range.
k_ra8_err_nack	Target did not acknowledge (I2C).
k_ra8_err_hw_timeout	Bus stalled (I2C).

Precondition

Channel initialized.

In native mode the bus is enabled.

Postcondition

On success the payload has been queued/transmitted.

On failure the bus is released (I2C) where possible.

Note

Not thread-safe.

Since

0.1.0

Definition at line 621 of file ra8_i3c.c.

References internal_ra8_i3c_fifo_write(), internal_ra8_i3c_xfer_cmd_word(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_i3c_addr_mask, k_ra8_i3c_byte_shift, k_ra8_i3c_cmd_attr_immed, k_ra8_i3c_cmd_attr_shift, k_ra8_i3c_cmd_immed_bytes_shift, k_ra8_i3c_cmd_xfer_length_max, k_ra8_i3c_cmd_xfer_length_shift, k_ra8_i3c_i2c_channel_count, k_ra8_i3c_immediate_max_bytes, k_ra8_i3c_mode_i2c, k_ra8_i3c_ntst_cmdqef_mask, k_ra8_ok, r_i3c_regs_t::NCMDQP, r_i3c_regs_t::NTST, ra8_i3c(), ra8_i3c_i2c_write(), and s_i3c_chan.

Referenced by er_fg_read(), imu_demo_iic_write(), internal_i3c_compat_write(), and ra8_nsc_iic_write().