|
fsp_err_t | R_SAU_I2C_Open (i2c_master_ctrl_t *const p_api_ctrl, i2c_master_cfg_t const *const p_cfg) |
|
fsp_err_t | R_SAU_I2C_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_SAU_I2C_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_SAU_I2C_Abort (i2c_master_ctrl_t *const p_api_ctrl) |
|
fsp_err_t | R_SAU_I2C_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_SAU_I2C_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_SAU_I2C_StatusGet (i2c_master_ctrl_t *const p_api_ctrl, i2c_master_status_t *p_status) |
|
fsp_err_t | R_SAU_I2C_Close (i2c_master_ctrl_t *const p_api_ctrl) |
|
fsp_err_t | R_SAU_I2C_Start (sau_i2c_instance_ctrl_t *const p_ctrl) |
|
fsp_err_t | R_SAU_I2C_Stop (sau_i2c_instance_ctrl_t *const p_ctrl) |
|
Driver for the SAU peripheral on RA MCUs. This module implements the I2C Master Interface.
Overview
The Simple I2C master on SAU HAL module supports transactions with an I2C Slave device. Callbacks must be provided which would be invoked when a transmission or receive has been completed. The callback arguments 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.
- 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.
Configuration
Build Time Configurations for r_sau_i2c
The following build time configurations are defined in fsp_cfg/r_sau_i2c_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. |
Enable Critical Section |
| Disabled | Critical section needs to be enabled if multiple channels on the same SAU unit are configured for I2C |
Manual Start-Stop |
| Disabled | If enabled, users need to manually call the R_SAU_I2C_Start/R_SAU_I2C_Stop functions to generate the I2C start and stop conditions. |
Enable Single Channel |
| Disabled | Enable single channel to reduce code size if only one channel (00, 11, or 20) is to be configured for SAU I2C. |
I2C Restart |
| Enable | Select whether to include code for the I2C restart (repeated start) condition in the build. Set to 'Disable' to reduce code size when all I2C slaves used by all SAU instances do not use I2C restart. |
DTC Support |
| Disable | Enable DTC support for the SAU I2C module. |
Configurations for Connectivity > I2C Master (r_sau_i2c)
This module can be added to the Stacks tab via New Stack > Connectivity > I2C Master (r_sau_i2c).
Configuration | Options | Default | Description |
General |
Name | Name must be a valid C symbol | g_i2c0 | Module name. |
Channel | MCU Specific Options | | Select the SAU channel. |
Operation clock |
| CK0 | Select the I2C operation clock. Use the Clocks tab to set the operation clock divider. |
Slave Address | Value must be a non-negative integer | 0x00 | Specify the slave address. |
Rate |
-
Standard
-
Fast mode
-
Fast mode plus
| Standard | Select the I2C data rate.
If the requested rate cannot be achieved, adjust the operation clock frequency until the rate is achievable. The calculated rate is printed in a comment in the generated sau_i2c_extended_cfg_t structure. |
Delay time (Microseconds) | Value must be a non-negative integer | 5 | Hold SDA (or SCK) for delay time to meet the I2C start (or stop) condition. Needs to be specified according to slave devices. |
Callback | Name must be a valid C symbol | sau_i2c_master_callback | A user callback function can be provided. If this callback function is provided, it will be called from the interrupt service routine (ISR). |
Transfer end interrupt priority | MCU Specific Options | | Select transfer end interrupt priority. This is set for TEI interrupt. |
Clock Configuration
The SAU clock is based on the peripheral module clock which is the system clock (ICLK).
Pin Configuration
The SAU I2C 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
Enabling Single Channel By User With The SAU I2C
- The Common > Single Channel property is used for reducing code size when only 1 SAU channel is to be configured for SAU I2C.
- Single Channel is configurable and disabled by default in the driver code.
- Note: Not all SAU channels are available on all pin layouts. Check the Hardware User Manual for your device to confirm available function assignment for each SAU channel.
Enabling Start/Stop Condition By User With The SAU I2C
- Manual triggering of I2C start/stop conditions is configurable and disabled by default.
- The delay time between the rising edge of SCL and the rising edge of SDA (stop condition) or the falling edge of SDA and the falling edge of SCL (start condition) is blocking. If blocking in the ISR for the length of the delay time is not suitable for the application, users can decide the appropriate calling time for start/stop conditions by enabling manual triggering and calling R_SAU_I2C_Start/R_SAU_I2C_Stop from the application context.
- When manual triggering is disabled, the driver will generate the stop condition after data transmission from the ISR context.
Interrupt Configuration
- Transmit end interrupt (TEI) for the selected channel used must be enabled in the properties of the selected device.
SAU I2C Master Rate Calculation
- The RA Configuration editor calculates the internal baud-rate setting based on the configured transfer rate and operating clock. The closest possible baud-rate that can be achieved (less than or equal to the requested rate) at the current PCLK 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 SAU I2C
- DTC transfer support is configurable and is disabled from the build by default. The SAU I2C driver uses a single DTC instance for transmission and reception.
- 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.
- If DTC is not used by any SAU instance, set Common > DTC Support to disabled to reduce code size.
- For further details on DTC please refer Transfer (r_dtc)
Multiple Channels Being Used In Same Unit
- When multiple channels on the same SAU unit are used for any serial function (I2C, UART, and/or SPI), then the Common > Enable Critical Section property needs to be set to enabled for all SAU serial drivers.
- This is because some SAU registers are shared for SAU channels on the same unit. Therefore any read-modify-write operations to those registers must be protected by a critical section.
I2C Restart Support
- I2C Restart (repeated start) is required by some, but not all slave devices.
- If no slave devices used by any SAU I2C instance require repeated start, then the Common > I2C Restart property can be set to disabled to reduce code size.
- When I2C Restart is disabled, even if
restart=true
is passed to the read
or write
APIs, the restart condition is not issued.
Multiple Devices On The Bus
- A single SAU I2C instance can be used to communicate with multiple slave devices on the same channel by using the R_SAU_I2C_SlaveAddressSet API.
Limitations
- Overrun error detection is not supported
- SAU I2C does not support clock stretching, I2C slave mode, or arbitration loss detection
Examples
Basic Example
This is a basic example of minimal use of the r_sau_i2c in an application. This example shows how this driver can be used for basic read and write operations.
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_SAU_I2C_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_SAU_I2C_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);
}
}
Enabling Start/Stop Condition By User
This example demonstrates how to write code for SAU I2C communication when the call start/stop condtion by user is enabled.
void manual_trigger_condition_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_SAU_I2C_Write(&g_i2c_device_ctrl_1, &g_i2c_tx_buffer[0], I2C_BUFFER_SIZE_BYTES,
false);
assert(FSP_SUCCESS == err);
assert(FSP_SUCCESS == err);
{
timeout_ms--;;
}
{
__BKPT(0);
}
assert(FSP_SUCCESS == err);
timeout_ms = I2C_TRANSACTION_BUSY_DELAY;
err =
R_SAU_I2C_Read(&g_i2c_device_ctrl_1, &g_i2c_rx_buffer[0], I2C_BUFFER_SIZE_BYTES,
false);
assert(FSP_SUCCESS == err);
assert(FSP_SUCCESS == err);
{
timeout_ms--;;
}
assert(FSP_SUCCESS == err);
{
__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 SAU I2C driver can be used to communicate with different slave devices which are on the same channel.
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_SAU_I2C_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] = (uint8_t) I2C_EXAMPLE_DATA_1;
g_i2c_tx_buffer[1] = (uint8_t) I2C_EXAMPLE_DATA_2;
timeout_ms = I2C_TRANSACTION_BUSY_DELAY;
err =
R_SAU_I2C_Write(&g_i2c_device_ctrl_2, &g_i2c_tx_buffer[0], 2U,
false);
assert(FSP_SUCCESS == err);
{
timeout_ms--;;
}
{
__BKPT(0);
}
}
◆ sau_i2c_clock_settings_t
struct sau_i2c_clock_settings_t |
◆ sau_i2c_instance_ctrl_t
struct sau_i2c_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 | open |
| Flag to determine if the device is open.
|
|
R_SAU0_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 | loaded |
| Tracks the number of data 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 | restarted |
| Tracks whether or not a restart was issued during the previous transfer.
|
|
volatile bool | do_dummy_read |
| Tracks whether a dummy read is issued on the first RX.
|
|
uint8_t | slave |
| The address of the slave device.
|
|
◆ sau_i2c_extended_cfg_t
struct sau_i2c_extended_cfg_t |
SAU I2C extended configuration
Data Fields |
sau_i2c_clock_settings_t |
clock_settings |
I2C clock settings. |
uint8_t |
delay_time |
The delay time of the slave device. |
uint8_t |
i2c_unit |
The SAU unit corresponding to the selected channel. |
◆ sau_i2c_operation_clock_t
Operation clock
Enumerator |
---|
SAU_I2C_MASTER_OPERATION_CLOCK_CK0 | Operating clock select CK0.
|
SAU_I2C_MASTER_OPERATION_CLOCK_CK1 | Operating clock select CK1.
|
◆ R_SAU_I2C_Open()
Opens the SAU device.
- Return values
-
FSP_SUCCESS | Requested clock rate was set exactly. |
FSP_ERR_ALREADY_OPEN | Module is already open. |
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.
- Clock rate requested is greater than 400KHz
- Invalid IRQ number assigned
|
◆ R_SAU_I2C_Read()
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 | The parameter p_api_ctrl, p_dest is NULL, bytes is 0. |
FSP_ERR_INVALID_SIZE | Provided number of bytes more than uint16_t size (65535) while DTC is used for data transfer. |
FSP_ERR_NOT_OPEN | Instance control block is not open. |
◆ R_SAU_I2C_Write()
Performs a write to the I2C device.
This function will fail if there is already an in-progress I2C transfer on the associated channel. Otherwise, the I2C write operation will begin. The write operation is non-blocking and the caller will be notified when the operation has finished by an I2C_EVENT_TX_COMPLETE in the callback.
- Return values
-
FSP_SUCCESS | Function executed without issue. |
FSP_ERR_ASSERTION | p_api_ctrl, 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_NOT_OPEN | Instance control block is not open. |
◆ R_SAU_I2C_Abort()
Aborts any in-progress transfer and forces the I2C peripheral into a ready state.
This function will safely terminate any in-progress I2C transfer with the device. If a transfer is aborted, the user will be notified via callback with an abort event.
- Return values
-
FSP_SUCCESS | Transaction was aborted without issue. |
FSP_ERR_ASSERTION | p_ctrl is NULL. |
FSP_ERR_NOT_OPEN | Instance control block is not open. |
◆ R_SAU_I2C_SlaveAddressSet()
Sets address of the slave device.
This function is used to set the device address of the slave without reconfiguring the entire bus.
- Return values
-
FSP_SUCCESS | Address of the slave is set correctly. |
FSP_ERR_ASSERTION | p_ctrl or address is NULL. |
FSP_ERR_NOT_OPEN | Instance control block is not open. |
FSP_ERR_IN_USE | An I2C Transaction is in progress. |
◆ R_SAU_I2C_CallbackSet()
Updates the user callback.
- Note
- p_callback_memory is not used in this implementation and can be set to NULL.
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_SAU_I2C_StatusGet()
Provides driver status.
- Return values
-
FSP_SUCCESS | Status stored in p_status. |
FSP_ERR_ASSERTION | NULL pointer. |
◆ R_SAU_I2C_Close()
Closes the I2C device. Power down I2C peripheral.
This function will safely terminate any in-progress I2C transfer with the device. If a transfer is aborted, the user will be notified via callback with an abort event.
- Return values
-
FSP_SUCCESS | Device closed without issue. |
FSP_ERR_ASSERTION | The parameter p_ctrl is NULL. |
FSP_ERR_NOT_OPEN | Instance control block is not open. |
◆ R_SAU_I2C_Start()
This function starts/restarts the IIC condition.
- Parameters
-
[in] | p_ctrl | Instance control structure. |
◆ R_SAU_I2C_Stop()
This function stops the IIC condition.
- Parameters
-
[in] | p_ctrl | Instance control structure. |