|
fsp_err_t | R_IIC_B_MASTER_Open (i2c_master_ctrl_t *const p_api_ctrl, i2c_master_cfg_t const *const p_cfg) |
|
fsp_err_t | R_IIC_B_MASTER_Read (i2c_master_ctrl_t *const p_api_ctrl, uint8_t *const p_dest, uint32_t const bytes, bool const restart) |
|
fsp_err_t | R_IIC_B_MASTER_Write (i2c_master_ctrl_t *const p_api_ctrl, uint8_t *const p_src, uint32_t const bytes, bool const restart) |
|
fsp_err_t | R_IIC_B_MASTER_Abort (i2c_master_ctrl_t *const p_api_ctrl) |
|
fsp_err_t | R_IIC_B_MASTER_SlaveAddressSet (i2c_master_ctrl_t *const p_api_ctrl, uint32_t const slave, i2c_master_addr_mode_t const addr_mode) |
|
fsp_err_t | R_IIC_B_MASTER_CallbackSet (i2c_master_ctrl_t *const p_api_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_B_MASTER_StatusGet (i2c_master_ctrl_t *const p_api_ctrl, i2c_master_status_t *p_status) |
|
fsp_err_t | R_IIC_B_MASTER_Close (i2c_master_ctrl_t *const p_api_ctrl) |
|
I2C Driver for the IIC/I3C peripheral on RA MCUs. This module implements the I2C Master Interface.
Overview
The I2C master on IIC/I3C 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.
- Fast Mode Plus Support with up to 1-MHz 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) DTC support for read and write respectively.
- Optional (build time) support for 10-bit slave addressing.
Configuration
Build Time Configurations for r_iic_b_master
The following build time configurations are defined in fsp_cfg/r_iic_b_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. |
DTC on Transmission and Reception |
| Disabled | If enabled, DTC instances will be included in the build for both transmission and reception. |
10-bit slave addressing |
| Disabled | If enabled, the driver will support 10-bit slave addressing mode along with the default 7-bit slave addressing mode. |
Configurations for Connectivity > I2C Master (r_iic_b_master)
This module can be added to the Stacks tab via New Stack > Connectivity > I2C Master (r_iic_b_master). Non-secure callable guard functions can be generated for this module by right clicking the module in the RA Configuration tool and checking the "Non-secure Callable" box.
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. |
Rate |
-
Standard
-
Fast-mode
-
Fast-mode plus
| 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_b_master_extended_cfg_t structure. |
Custom Rate (bps) | Value must be a non-negative integer | 0 | Set a custom bitrate (bps). Set to 0 to use the maximum bitrate for the selected mode.
Standard-mode: up to 100000; Fast-mode: up to 400000; Fast-mode plus: up to 1000000 |
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 | 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 | Select the timeout mode to detect bus hang. |
Timeout during SCL Low |
| 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 | g_iic_b_master0_callback | 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 I3C peripheral module uses the IICCLK or PCLKD (based on the MCU) as its clock source for the bus clock. The actual I2C transfer rate will be calculated and set by the tooling depending on the selected transfer rate. If the clocks are configured in such a manner that the selected internal rate cannot be achieved, an error will be returned.
Pin Configuration
The I3C 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 RA Configuration editor calculates the internal baud-rate setting based on the configured transfer rate.
When the Custom Rate setting is set to 0 the bitrate is fixed to the maximum values shown below. Otherwise, the supplied value is used to generate bitrate settings.
- Standard-mode (Sm) : up to 100 kbps
- Fast-mode (Fm) : up to 400 kbps
- Fast-mode Plus (Fm+) : up to 1 Mbps
- The closest possible baud-rate that can be achieved (less than or equal to the requested rate) at the current IICCLK/PCLKD (based on the MCU) settings is calculated and used.
- If a valid clock rate could not be calculated, an error is returned by the tool.
Enabling DTC with the IIC
- DTC transfer support is configurable and is disabled from the build by default. IIC driver provides two DTC instances for transmission and reception respectively. The DTC instances can be enabled individually during configuration.
- DTC is helpful for minimizing interrupts during large transactions. Many I2C applications have shorter transactions. These applications will likely not see any improvement with DTC. I2C often runs at a much slower speed than the CPU core clock. Some applications with longer transactions may prefer servicing the interrupts at the I2C bitrate to the overhead of bringing in the DTC driver.
- For further details on DTC please refer Transfer (r_dtc)
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 a repeated 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.
{
.slave = I2C_SLAVE_EEPROM,
.p_callback = i2c_callback,
.p_context = &g_i2c_device_ctrl_1,
.p_transfer_tx = NULL,
.p_transfer_rx = NULL,
.p_extend = &g_iic_b_master_cfg_extend
};
{
g_i2c_callback_event = p_args->
event;
}
void basic_example (void)
{
uint32_t i;
uint32_t timeout_ms = I2C_TRANSACTION_BUSY_DELAY;
assert(FSP_SUCCESS == err);
for (i = 0; i < I2C_BUFFER_SIZE_BYTES; i++)
{
g_i2c_tx_buffer[i] = (uint8_t) i;
}
err =
R_IIC_B_MASTER_Write(&g_i2c_device_ctrl_1, &g_i2c_tx_buffer[0], I2C_BUFFER_SIZE_BYTES,
false);
assert(FSP_SUCCESS == err);
{
timeout_ms--;;
}
{
__BKPT(0);
}
timeout_ms = I2C_TRANSACTION_BUSY_DELAY;
err =
R_IIC_B_MASTER_Read(&g_i2c_device_ctrl_1, &g_i2c_rx_buffer[0], I2C_BUFFER_SIZE_BYTES,
false);
assert(FSP_SUCCESS == err);
{
timeout_ms--;;
}
{
__BKPT(0);
}
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.
{
.slave = I2C_SLAVE_TEMP_SENSOR,
.p_callback = i2c_callback,
.p_context = &g_i2c_device_ctrl_2,
.p_transfer_tx = NULL,
.p_transfer_rx = NULL,
.p_extend = &g_iic_b_master_cfg_extend
};
void single_channel_multi_slave (void)
{
uint32_t timeout_ms = I2C_TRANSACTION_BUSY_DELAY;
assert(FSP_SUCCESS == err);
memset(g_i2c_rx_buffer, '0', I2C_BUFFER_SIZE_BYTES);
err =
R_IIC_B_MASTER_Read(&g_i2c_device_ctrl_2, &g_i2c_rx_buffer[0], I2C_BUFFER_SIZE_BYTES,
false);
assert(FSP_SUCCESS == err);
{
timeout_ms--;;
}
{
__BKPT(0);
}
assert(FSP_SUCCESS == err);
g_i2c_tx_buffer[0] = 0xAA;
g_i2c_tx_buffer[1] = 0xBB;
timeout_ms = I2C_TRANSACTION_BUSY_DELAY;
assert(FSP_SUCCESS == err);
{
timeout_ms--;;
}
{
__BKPT(0);
}
}
◆ iic_b_master_clock_settings_t
struct iic_b_master_clock_settings_t |
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. |
uint8_t |
sdod_value |
|
bool |
sdodcs_value |
|
◆ iic_b_master_instance_ctrl_t
struct iic_b_master_instance_ctrl_t |
I2C control structure. DO NOT INITIALIZE.
◆ iic_b_master_extended_cfg_t
struct iic_b_master_extended_cfg_t |
R_IIC_B extended configuration
◆ iic_b_master_timeout_mode_t
I2C Timeout mode parameter definition
Enumerator |
---|
IIC_B_MASTER_TIMEOUT_MODE_LONG | Timeout Detection Time Select: Long Mode -> TMOS = 0.
|
IIC_B_MASTER_TIMEOUT_MODE_SHORT | Timeout Detection Time Select: Short Mode -> TMOS = 1.
|
◆ iic_b_master_timeout_scl_low_t
Enumerator |
---|
IIC_B_MASTER_TIMEOUT_SCL_LOW_DISABLED | Timeout detection during SCL low disabled.
|
IIC_B_MASTER_TIMEOUT_SCL_LOW_ENABLED | Timeout detection during SCL low enabled.
|
◆ R_IIC_B_MASTER_Open()
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_ASSERTION | Parameter check failure due to one or more reasons below:
- p_api_ctrl or p_cfg is NULL.
- extended parameter is NULL.
- Callback parameter is NULL.
- Set the rate to fast mode plus on a channel which does not support it.
- Invalid IRQ number assigned
|
◆ R_IIC_B_MASTER_Read()
fsp_err_t R_IIC_B_MASTER_Read |
( |
i2c_master_ctrl_t *const |
p_api_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_api_ctrl, p_dest or bytes is NULL. |
FSP_ERR_INVALID_SIZE | Provided number of bytes more than uint16_t size (65535) while DTC is used for data transfer. |
FSP_ERR_IN_USE | Bus busy condition. Another transfer was in progress. |
FSP_ERR_NOT_OPEN | Handle is not initialized. Call R_IIC_B_MASTER_Open to initialize the control block. |
◆ R_IIC_B_MASTER_Write()
fsp_err_t R_IIC_B_MASTER_Write |
( |
i2c_master_ctrl_t *const |
p_api_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_api_ctrl or p_src is NULL. |
FSP_ERR_INVALID_SIZE | Provided number of bytes more than uint16_t size (65535) while DTC is used for data transfer. |
FSP_ERR_IN_USE | Bus busy condition. Another transfer was in progress. |
FSP_ERR_NOT_OPEN | Handle is not initialized. Call R_IIC_B_MASTER_Open to initialize the control block. |
◆ R_IIC_B_MASTER_Abort()
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_api_ctrl is NULL. |
FSP_ERR_NOT_OPEN | Handle is not initialized. Call R_IIC_B_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_B_MASTER_SlaveAddressSet()
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_B_MASTER_Open to initialize the control block. |
◆ R_IIC_B_MASTER_CallbackSet()
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. |
FSP_ERR_NO_CALLBACK_MEMORY | p_callback is non-secure and p_callback_memory is either secure or NULL. |
◆ R_IIC_B_MASTER_StatusGet()
Provides driver status.
- Return values
-
FSP_SUCCESS | Status stored in p_status. |
FSP_ERR_ASSERTION | NULL pointer. |
◆ R_IIC_B_MASTER_Close()
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_api_ctrl is NULL. |
FSP_ERR_NOT_OPEN | Handle is not initialized. Call R_IIC_B_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.