Functions
fsp_err_t	R_IIC_MASTER_Open (i2c_master_ctrl_t const p_ctrl, i2c_master_cfg_t const const p_cfg)

fsp_err_t	R_IIC_MASTER_Read (i2c_master_ctrl_t const p_ctrl, uint8_t const p_dest, uint32_t const bytes, bool const restart)

fsp_err_t	R_IIC_MASTER_Write (i2c_master_ctrl_t const p_ctrl, uint8_t const p_src, uint32_t const bytes, bool const restart)

fsp_err_t	R_IIC_MASTER_Abort (i2c_master_ctrl_t *const p_ctrl)

fsp_err_t	R_IIC_MASTER_SlaveAddressSet (i2c_master_ctrl_t *const p_ctrl, uint32_t const slave, i2c_master_addr_mode_t const addr_mode)

fsp_err_t	R_IIC_MASTER_Close (i2c_master_ctrl_t *const p_ctrl)

fsp_err_t	R_IIC_MASTER_CallbackSet (i2c_master_ctrl_t const p_ctrl, void(p_callback)(i2c_master_callback_args_t ), void const const p_context, i2c_master_callback_args_t *const p_callback_memory)

fsp_err_t	R_IIC_MASTER_StatusGet (i2c_master_ctrl_t const p_ctrl, i2c_master_status_t p_status)

Detailed Description

Driver for the IIC peripheral on RZ microprocessor. This module implements the I2C Master Interface.

Overview

The I2C master on IIC HAL module supports transactions with an I2C Slave device. Callbacks must be provided which are invoked when a transmit or receive operation has completed. The callback argument will contain information about the transaction status, bytes transferred and a pointer to the user defined context.

Features

Supports multiple transmission rates
- Standard Mode Support with up to 100-kHz transaction rate.
- Fast Mode Support with up to 400-kHz transaction rate.
I2C Master Read from a slave device.
I2C Master Write to a slave device.
Abort any in-progress transactions.
Set the address of the slave device.
Non-blocking behavior is achieved by the use of callbacks.
Additional build-time features
- Optional (build time) DMAC support for read and write respectively.
- Optional (build time) support for 10-bit slave addressing.

Configuration

Build Time Configurations for r_iic_master

The following build time configurations are defined in fsp_cfg/r_iic_master_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.
DMAC on Transmission and Reception	Enabled Disabled	Disabled	If enabled, DMAC instances will be included in the build for both transmission and reception. Even if enabled, DMAC is not used without adding DMAC driver.
10-bit slave addressing	Enabled Disabled	Disabled	If enabled, the driver will support 10-bit slave addressing mode along with the default 7-bit slave addressing mode.
Multiplex Interrupt	Enabled Disabled	Disabled	Enable multiplex interrupt for a single driver.

Configurations for Connectivity > I2C Master (r_iic_master)

This module can be added to the Stacks tab via New Stack > Connectivity > I2C Master (r_iic_master).

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_i2c_master0	Module name.
Channel	Value must be a non-negative integer	0	Specify the IIC channel. Do not specify the safety channel when using DMAC.
Rate	Standard Fast-mode	Standard	Select the transfer rate. If the requested transfer rate cannot be achieved, the settings with the largest possible transfer rate that is less than or equal to the requested transfer rate are used. The theoretical calculated transfer rate and duty cycle are printed in a comment in the generated iic_master_extended_cfg_t structure.
Rise Time (ns)	Value must be a non-negative integer	120	Set the rise time (tr) in nanoseconds.
Fall Time (ns)	Value must be a non-negative integer	120	Set the fall time (tf) in nanoseconds.
Duty Cycle (%)	Value must be an integer between 0 and 100	50	Set the SCL duty cycle.
Slave Address	Value must be non-negative	0x00	Specify the slave address.
Address Mode	7-Bit 10-Bit	7-Bit	Select the slave address mode. Ensure 10-bit slave addressing is enabled in the configuration to use 10-Bit setting here.
Timeout Mode	Short Mode Long Mode	Short Mode	Select the timeout mode to detect bus hang.
Timeout during SCL Low	Enabled Disabled	Enabled	Select if the timeout can occur when SCL is held low for a duration longer than what is set in the timeout mode.
Callback	Name must be a valid C symbol	NULL	A user callback function must be provided. This will be called from the interrupt service routine (ISR) upon IIC transaction completion reporting the transaction status.
Interrupt Priority Level	MCU Specific Options		Select the interrupt priority level. This is set for TXI, RXI, TEI and ERI interrupts.

Clock Configuration

The IIC peripheral module uses the PCLKL as its clock source. The actual I2C transfer rate will be calculated and set by the tooling depending on the selected transfer rate. If the PCLKL is configured in such a manner that the selected internal rate cannot be achieved, an error will be returned.

Pin Configuration

The IIC peripheral module uses pins on the MCU to communicate to external devices. I/O pins must be selected and configured as required by the external device. An I2C channel would consist of two pins - SDA and SCL for data/address and clock respectively.

Usage Notes

Interrupt Configuration

The IIC error (EEI), receive buffer full (RXI), transmit buffer empty (TXI) and transmit end (TEI) interrupts for the selected channel used must be enabled in the properties of the selected device.
Set equal priority levels for all the interrupts mentioned above. Setting the interrupts to different priority levels could result in improper operation.

IIC Master Rate Calculation

The FSP Configuration editor calculates the internal baud-rate setting based on the configured transfer rate. The closest possible baud-rate that can be achieved (less than or equal to the requested rate) at the current PCLKL settings is calculated and used.
If a valid clock rate could not be calculated, an error is returned by the tool.

Enabling DMAC with the IIC

DMAC transfer support is configurable and is disabled from the build by default. IIC driver provides two DMAC instances for transmission and reception respectively. The DMAC instances can be enabled individually during configuration.
DMAC activation is not available for safety channel.
For further details on DMAC please refer Direct Memory Access Controller (r_dmac)

Multiple Devices on the Bus

A single IIC instance can be used to communicate with multiple slave devices on the same channel by using the SlaveAddressSet API.

Multi-Master Support

If multiple masters are connected on the same bus, the I2C Master is capable of detecting bus busy state before initiating the communication.

Restart

IIC master can hold the the bus after an I2C transaction by issuing Restart. This will mimic a stop followed by start condition.

Examples

Basic Example

This is a basic example of minimal use of the r_iic_master in an application.

This example shows how this driver can be used for basic read and write operations.

iic_master_instance_ctrl_t g_i2c_device_ctrl_1;
i2c_master_cfg_t           g_i2c_device_cfg_1 =
{
    .channel       = I2C_CHANNEL,
    .rate          = I2C_MASTER_RATE_FAST,
    .slave         = I2C_SLAVE_DEVICE,
    .addr_mode     = I2C_MASTER_ADDR_MODE_7BIT,
    .rxi_irq       = VECTOR_NUMBER_IIC2_RXI,
    .txi_irq       = VECTOR_NUMBER_IIC2_TXI,
    .tei_irq       = VECTOR_NUMBER_IIC2_TEI,
    .eri_irq       = VECTOR_NUMBER_IIC2_EEI,
    .ipl           = (12),
    .p_callback    = i2c_callback,     // Callback
    .p_context     = &g_i2c_device_ctrl_1,
    .p_transfer_tx = NULL,
    .p_transfer_rx = NULL,
    .p_extend      = &g_iic_master_cfg_extend
};
void i2c_callback (i2c_master_callback_args_t * p_args)
{
    g_i2c_callback_event = p_args->event;
}
void basic_example (void)
{
    fsp_err_t err;
    uint32_t  i;
    uint32_t  timeout_ms = I2C_TRANSACTION_BUSY_DELAY;
    /* Initialize the IIC module */
    err = R_IIC_MASTER_Open(&g_i2c_device_ctrl_1, &g_i2c_device_cfg_1);
    /* Handle any errors. This function should be defined by the user. */
    handle_error(err);
    /* Write some data to the transmit buffer */
    for (i = 0; i < I2C_BUFFER_SIZE_BYTES; i++)
    {
        g_i2c_tx_buffer[i] = (uint8_t) i;
    }
    /* Send data to I2C slave */
    g_i2c_callback_event = I2C_MASTER_EVENT_ABORTED;
    err = R_IIC_MASTER_Write(&g_i2c_device_ctrl_1, &g_i2c_tx_buffer[0], I2C_BUFFER_SIZE_BYTES, false);
    handle_error(err);
    /* Since there is nothing else to do, block until Callback triggers*/
    while ((I2C_MASTER_EVENT_TX_COMPLETE != g_i2c_callback_event) && timeout_ms)
    {
        R_BSP_SoftwareDelay(1U, BSP_DELAY_UNITS_MILLISECONDS);
        timeout_ms--;
    }
    if (I2C_MASTER_EVENT_ABORTED == g_i2c_callback_event)
    {
        __BKPT(0);
    }
    /* Read data back from the I2C slave */
    g_i2c_callback_event = I2C_MASTER_EVENT_ABORTED;
    timeout_ms           = I2C_TRANSACTION_BUSY_DELAY;
    err = R_IIC_MASTER_Read(&g_i2c_device_ctrl_1, &g_i2c_rx_buffer[0], I2C_BUFFER_SIZE_BYTES, false);
    handle_error(err);
    /* Since there is nothing else to do, block until Callback triggers*/
    while ((I2C_MASTER_EVENT_RX_COMPLETE != g_i2c_callback_event) && timeout_ms)
    {
        R_BSP_SoftwareDelay(1U, BSP_DELAY_UNITS_MILLISECONDS);
        timeout_ms--;
    }
    if (I2C_MASTER_EVENT_ABORTED == g_i2c_callback_event)
    {
        __BKPT(0);
    }
    /* Verify the read data */
    if (0U != memcmp(g_i2c_tx_buffer, g_i2c_rx_buffer, I2C_BUFFER_SIZE_BYTES))
    {
        __BKPT(0);
    }
}

Multiple Slave devices on the same channel (bus)

This example demonstrates how a single IIC driver can be used to communicate with different slave devices which are on the same channel.

Note: The callback function from the first example applies to this example as well.

iic_master_instance_ctrl_t g_i2c_device_ctrl_2;
i2c_master_cfg_t           g_i2c_device_cfg_2 =
{
    .channel       = I2C_CHANNEL,
    .rate          = I2C_MASTER_RATE_STANDARD,
    .slave         = I2C_SLAVE_TEMP_SENSOR,
    .addr_mode     = I2C_MASTER_ADDR_MODE_7BIT,
    .rxi_irq       = VECTOR_NUMBER_IIC2_RXI,
    .txi_irq       = VECTOR_NUMBER_IIC2_TXI,
    .tei_irq       = VECTOR_NUMBER_IIC2_TEI,
    .eri_irq       = VECTOR_NUMBER_IIC2_EEI,
    .ipl           = (12),
    .p_callback    = i2c_callback,     // Callback
    .p_context     = &g_i2c_device_ctrl_2,
    .p_transfer_tx = NULL,
    .p_transfer_rx = NULL,
    .p_extend      = &g_iic_master_cfg_extend_2
};
void single_channel_multi_slave (void)
{
    fsp_err_t err;
    uint32_t  timeout_ms = I2C_TRANSACTION_BUSY_DELAY;
    err = R_IIC_MASTER_Open(&g_i2c_device_ctrl_2, &g_i2c_device_cfg_2);
    /* Handle any errors. This function should be defined by the user. */
    handle_error(err);
    /* Clear the receive buffer */
    memset(g_i2c_rx_buffer, '0', I2C_BUFFER_SIZE_BYTES);
    /* Read data from I2C slave */
    g_i2c_callback_event = I2C_MASTER_EVENT_ABORTED;
    err = R_IIC_MASTER_Read(&g_i2c_device_ctrl_2, &g_i2c_rx_buffer[0], I2C_BUFFER_SIZE_BYTES, false);
    handle_error(err);
    while ((I2C_MASTER_EVENT_RX_COMPLETE != g_i2c_callback_event) && timeout_ms)
    {
        R_BSP_SoftwareDelay(1U, BSP_DELAY_UNITS_MILLISECONDS);
        timeout_ms--;
    }
    if (I2C_MASTER_EVENT_ABORTED == g_i2c_callback_event)
    {
        __BKPT(0);
    }
    /* Send data to I2C slave on the same channel */
    err = R_IIC_MASTER_SlaveAddressSet(&g_i2c_device_ctrl_2, I2C_SLAVE_DISPLAY_ADAPTER, I2C_MASTER_ADDR_MODE_7BIT);
    handle_error(err);
    g_i2c_tx_buffer[0]   = 0xAA;       // NOLINT
    g_i2c_tx_buffer[1]   = 0xBB;       // NOLINT
    g_i2c_callback_event = I2C_MASTER_EVENT_ABORTED;
    timeout_ms           = I2C_TRANSACTION_BUSY_DELAY;
    err = R_IIC_MASTER_Write(&g_i2c_device_ctrl_2, &g_i2c_tx_buffer[0], 2U, false);
    handle_error(err);
    while ((I2C_MASTER_EVENT_TX_COMPLETE != g_i2c_callback_event) && timeout_ms)
    {
        R_BSP_SoftwareDelay(1U, BSP_DELAY_UNITS_MILLISECONDS);
        timeout_ms--;
    }
    if (I2C_MASTER_EVENT_ABORTED == g_i2c_callback_event)
    {
        __BKPT(0);
    }
}

Data Structures
struct	iic_master_clock_settings_t

struct	iic_master_instance_ctrl_t

struct	iic_master_extended_cfg_t

Enumerations
enum	iic_master_timeout_mode_t

enum	iic_master_timeout_scl_low_t

Data Structure Documentation

◆ iic_master_clock_settings_t

struct iic_master_clock_settings_t

I2C clock settings

Data Fields
uint8_t	cks_value	Internal Reference Clock Select.
uint8_t	brh_value	High-level period of SCL clock.
uint8_t	brl_value	Low-level period of SCL clock.

◆ iic_master_instance_ctrl_t

struct iic_master_instance_ctrl_t

I2C control structure. DO NOT INITIALIZE.

Data Fields
i2c_master_cfg_t const *	p_cfg
	Pointer to the configuration structure.

uint32_t	slave
	The address of the slave device.

i2c_master_addr_mode_t	addr_mode
	Indicates how slave fields should be interpreted.

uint32_t	open
	Flag to determine if the device is open.

R_IIC0_Type *	p_reg
	Base register for this channel.

uint8_t *	p_buff
	Holds the data associated with the transfer.

uint32_t	total
	Holds the total number of data bytes to transfer.

uint32_t	remain
	Tracks the remaining data bytes to transfer.

uint32_t	loaded
	Tracks the number of data bytes written to the register.

uint8_t	addr_low
	Holds the last address byte to issue.

uint8_t	addr_high
	Holds the first address byte to issue in 10-bit mode.

uint8_t	addr_total
	Holds the total number of address bytes to transfer.

uint8_t	addr_remain
	Tracks the remaining address bytes to transfer.

uint8_t	addr_loaded
	Tracks the number of address bytes written to the register.

volatile bool	read
	Holds the direction of the data byte transfer.

volatile bool	restart
	Holds whether or not the restart should be issued when done.

volatile bool	err
	Tracks whether or not an error occurred during processing.

volatile bool	restarted
	Tracks whether or not a restart was issued during the previous transfer.

volatile bool	dummy_read_completed
	Tracks whether the dummy read is performed.

volatile bool	activation_on_rxi
	Tracks whether the transfer is activated on RXI interrupt.

volatile bool	activation_on_txi
	Tracks whether the transfer is activated on TXI interrupt.

volatile bool	address_restarted
	Tracks whether the restart condition is send on 10 bit read.

◆ iic_master_extended_cfg_t

struct iic_master_extended_cfg_t

R_IIC extended configuration

Data Fields
iic_master_timeout_mode_t	timeout_mode	Timeout Detection Time Select: Long Mode = 0 and Short Mode = 1.
iic_master_timeout_scl_low_t	timeout_scl_low	Allows timeouts to occur when SCL is held low.
iic_master_clock_settings_t	clock_settings	I2C Clock settings.

Enumeration Type Documentation

◆ iic_master_timeout_mode_t

enum iic_master_timeout_mode_t

I2C Timeout mode parameter definition

Enumerator
IIC_MASTER_TIMEOUT_MODE_LONG	Timeout Detection Time Select: Long Mode -> TMOS = 0.
IIC_MASTER_TIMEOUT_MODE_SHORT	Timeout Detection Time Select: Short Mode -> TMOS = 1.

◆ iic_master_timeout_scl_low_t

enum iic_master_timeout_scl_low_t

Enumerator
IIC_MASTER_TIMEOUT_SCL_LOW_DISABLED	Timeout detection during SCL low disabled.
IIC_MASTER_TIMEOUT_SCL_LOW_ENABLED	Timeout detection during SCL low enabled.

Function Documentation

◆ R_IIC_MASTER_Open()

fsp_err_t R_IIC_MASTER_Open	(	i2c_master_ctrl_t *const	p_ctrl,
		i2c_master_cfg_t const *const	p_cfg
	)

Opens the I2C device.

Return values

FSP_SUCCESS	Requested clock rate was set exactly.
FSP_ERR_ALREADY_OPEN	Module is already open.
FSP_ERR_IP_CHANNEL_NOT_PRESENT	Channel is not available on this MCU.
FSP_ERR_INVALID_ARGUMENT	Invalid input parameter.
FSP_ERR_ASSERTION	Parameter check failure due to one or more reasons below: p_ctrl or p_cfg is NULL. extended parameter is NULL. Callback parameter is NULL. Invalid IRQ number assigned

◆ R_IIC_MASTER_Read()

fsp_err_t R_IIC_MASTER_Read	(	i2c_master_ctrl_t *const	p_ctrl,
		uint8_t *const	p_dest,
		uint32_t const	bytes,
		bool const	restart
	)

Performs a read from the I2C device. The caller will be notified when the operation has completed (successfully) by an I2C_MASTER_EVENT_RX_COMPLETE in the callback.

Return values

FSP_SUCCESS	Function executed without issue.
FSP_ERR_ASSERTION	p_ctrl, p_dest or bytes is NULL.
FSP_ERR_IN_USE	Bus busy condition. Another transfer was in progress.
FSP_ERR_NOT_OPEN	Handle is not initialized. Call R_IIC_MASTER_Open to initialize the control block.

◆ R_IIC_MASTER_Write()

fsp_err_t R_IIC_MASTER_Write	(	i2c_master_ctrl_t *const	p_ctrl,
		uint8_t *const	p_src,
		uint32_t const	bytes,
		bool const	restart
	)

Performs a write to the I2C device. The caller will be notified when the operation has completed (successfully) by an I2C_MASTER_EVENT_TX_COMPLETE in the callback.

Return values

FSP_SUCCESS	Function executed without issue.
FSP_ERR_ASSERTION	p_ctrl or p_src is NULL.
FSP_ERR_IN_USE	Bus busy condition. Another transfer was in progress.
FSP_ERR_NOT_OPEN	Handle is not initialized. Call R_IIC_MASTER_Open to initialize the control block.

◆ R_IIC_MASTER_Abort()

fsp_err_t R_IIC_MASTER_Abort ( i2c_master_ctrl_t *const p_ctrl )

Safely aborts any in-progress transfer and forces the IIC peripheral into ready state.

Return values

FSP_SUCCESS	Channel was reset successfully.
FSP_ERR_ASSERTION	p_ctrl is NULL.
FSP_ERR_NOT_OPEN	Handle is not initialized. Call R_IIC_MASTER_Open to initialize the control block.

Note: A callback will not be invoked in case an in-progress transfer gets aborted by calling this API.

◆ R_IIC_MASTER_SlaveAddressSet()

fsp_err_t R_IIC_MASTER_SlaveAddressSet	(	i2c_master_ctrl_t *const	p_ctrl,
		uint32_t const	slave,
		i2c_master_addr_mode_t const	addr_mode
	)

Sets address and addressing mode of the slave device. This function is used to set the device address and addressing mode of the slave without reconfiguring the entire bus.

Return values

FSP_SUCCESS	Address of the slave is set correctly.
FSP_ERR_ASSERTION	Pointer to control structure is NULL.
FSP_ERR_IN_USE	Another transfer was in-progress.
FSP_ERR_NOT_OPEN	Handle is not initialized. Call R_IIC_MASTER_Open to initialize the control block.

◆ R_IIC_MASTER_Close()

fsp_err_t R_IIC_MASTER_Close ( i2c_master_ctrl_t *const p_ctrl )

Closes the I2C device. May power down IIC peripheral. This function will safely terminate any in-progress I2C transfers.

Return values

FSP_SUCCESS	Device closed without issue.
FSP_ERR_ASSERTION	p_ctrl is NULL.
FSP_ERR_NOT_OPEN	Handle is not initialized. Call R_IIC_MASTER_Open to initialize the control block.

Note: A callback will not be invoked in case an in-progress transfer gets aborted by calling this API.

◆ R_IIC_MASTER_CallbackSet()

fsp_err_t R_IIC_MASTER_CallbackSet	(	i2c_master_ctrl_t *const	p_ctrl,
		void()(i2c_master_callback_args_t )	p_callback,
		void const *const	p_context,
		i2c_master_callback_args_t *const	p_callback_memory
	)

Updates the user callback and has option of providing memory for callback structure. Implements i2c_master_api_t::callbackSet

Return values

FSP_SUCCESS	Callback updated successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.

◆ R_IIC_MASTER_StatusGet()

fsp_err_t R_IIC_MASTER_StatusGet	(	i2c_master_ctrl_t *const	p_ctrl,
		i2c_master_status_t *	p_status
	)

Provides driver status.

Return values

FSP_SUCCESS	Status stored in p_status.
FSP_ERR_ASSERTION	NULL pointer.

Functions

Detailed Description

Overview

Features

Configuration

Build Time Configurations for r_iic_master

Configurations for Connectivity > I2C Master (r_iic_master)

Clock Configuration

Pin Configuration

Usage Notes

Interrupt Configuration

IIC Master Rate Calculation

Enabling DMAC with the IIC

Multiple Devices on the Bus

Multi-Master Support

Restart

Examples

Basic Example

Multiple Slave devices on the same channel (bus)

Data Structures

Enumerations

Data Structure Documentation

◆ iic_master_clock_settings_t

◆ iic_master_instance_ctrl_t

Data Fields

◆ iic_master_extended_cfg_t

Enumeration Type Documentation

◆ iic_master_timeout_mode_t

◆ iic_master_timeout_scl_low_t

Function Documentation

◆ R_IIC_MASTER_Open()

◆ R_IIC_MASTER_Read()

◆ R_IIC_MASTER_Write()

◆ R_IIC_MASTER_Abort()

◆ R_IIC_MASTER_SlaveAddressSet()

◆ R_IIC_MASTER_Close()

◆ R_IIC_MASTER_CallbackSet()

◆ R_IIC_MASTER_StatusGet()