Renesas I2C Framework Application Note
Application Note
Renesas Synergy™ Platform
I²C Framework Module Guide
Introduction
This module guide will enable you to effectively use a module in your own design. Upon completion of this
guide, you will be able to add this module to your own design, configure it correctly for the target application
and write code, using the included application project code as a reference and efficient starting point .
References to more detailed API descriptions a nd suggestions of other application projects that il l ustrat e
more advanced uses of the module are available on the Renesas Synergy Knowledge Base (as described in
the References section at the end of this document) and should be valuable resources for creating more
complex designs.
2
C Framework module provides a ThreadX®-aware high-level API for I2C industry standard serial
The I
device communications and configures the I
by the framework. The I
2
C Framework module uses the I2C and SCI peripherals on the Synergy MCU.
Contents
1. I²C Framework Module Features ............................................................................................... 2
2. I²C Framework Module APIs Overview ..................................................................................... 3
3. I²C Framework Module Operational Overview .......................................................................... 4
2
C peripheral in order to enable serial communic ation to be used
3.1 I²C Framework Module Important Operational N otes and Limitations .................................................... 5
3.1.1 I²C Framework Module Operational Notes ............................................................................................ 5
3.1.2 I²C Framework Module Limitations ....................................................................................................... 5
4. Including the I²C Framework Module in an Application ............................................................. 5
5. Configuring the I²C Framework Module ..................................................................................... 6
5.1 Configuration Settings for the I²C Framework Lower-Level Modules ..................................................... 7
5.2 I²C Framework Module Clock Configuration ......................................................................................... 11
5.3 I²C Framework Module Pin Configuration ............................................................................................. 12
5.4 I²C Framework Module Other Settings .................................................................................................. 13
6. Using the I²C Framework Module in an Application ................................................................ 13
6.1 Implementation Steps for Two Slave Devices on the Same Shared Bus ............................................. 13
6.2 Adding Another Shared Bus .................................................................................................................. 17
6.3 The typical steps in using the Framework module in a n application ..................................................... 18
7. The I²C Framework Module Application Project ...................................................................... 19
8. Customizing the I²C Framework Module for a Target Application ........................................... 22
9. Running the I²C Framework Module Application Project ......................................................... 22
10. I²C Framework Module Conclusion ......................................................................................... 25
11. I²C Framework Module Next Steps ......................................................................................... 25
12. I²C Framework Module Reference Information ....................................................................... 25
Revision History .............................................................................................................................. 27
R11AN0098EU0102 Rev.1.02 Page 1 of 27
Jan.07.19
Renesas Synergy™ Platform I²C Framework Module Guide
Page 2
I2C Framework
sf_i 2c
Framework
Application
BSP
ThreadX®
RTOS
I2C Framework Sh ared Bu s
sf _i 2c
Framework
Transfer Driver
R_DTC Event SCI0 TXI
HAL D rivers
Transfer Driver
R_DTC Ev ent S CI 0 RXI
Transfer Driver
R_DTC Ev ent I I C0 TX I
I2 C Ma s ter Dr iver
R_SC I_I 2C
HAL D rivers
I2 C Ma s ter
Driver
R_I IC
Transfer Driver
R_DTC Even t IIC0 RXI
1. I²C Framework Module Features
• ThreadX-aware framework
• Handles integration and synchronization of multiple I²C peripherals on the I²C bus
• Provides a single interface to access both SCI I²C and RIIC drivers
• The I²C framework module configures I²C communication in master mode
• The I²C framework module supports three data rates: 100 k Hz, 400 kHz, and 1 MHz
• The I²C framework module supports both 7-bit addressing and 10-bit addressing
• The I²C framework module also provides support for callbacks internally. User defined callback is not
used. The callback functions are called with the following events i2c_event_t:
Transfer aborted
Transmit complete
Receive complete.
The callback structure i2c_callback_args_t also provides the number of bytes that were sent or
received
Implemented by:
Simple I²C on SCI
RIIC.
Figure 1. I²C Framework Module Block Diagram
R11AN0098EU0102 Rev.1.02 Page 2 of 27
Jan.07.19
Renesas Synergy™ Platform I²C Framework Module Guide
Function Name
Example API Call and Definition
open
g_sf_i2c_device.p_api->open (g_sf_i2c_device.p_ctrl,
Opens a designated I²C device on the bus.
close
g_sf_i2c_device.p_api->close (g_sf_i2c_device.p_ctrl);
used by the bus if no devices are connected to the bus.
read
g_sf_i2c_device.p_api->read (g_sf_i2c_device.p_ctrl,
Receives data from I²C device.
write
g_sf_i2c_device.p_api->write (g_sf_i2c_device.p_ctrl, &source,
Transmits data to I²C device.
lock
g_sf_i2c_device.p_api->lock (g_sf_i2c_device.p_ctrl);
several reads and writes without interrupt.
unlock
g_sf_i2c_device.p_api->unlock (g_sf_i2c_device.p_ctrl);
Unlocks the bus from a particular device and makes it available for other devices.
reset
g_sf_i2c_device.p_api->reset (g_sf_i2c_device.p_ctrl, timeout);
Aborts any in-progress transfer and forces the I²C peripheral into ready state.
versionGet
g_sf_i2c_device.p_api->version(version);
Retrieves the version information using the version pointer.
lockWait
g_sf_i2c_device.p_api->lockWait(g_sf_i2c_device.p_ctrl,
Name
Description
SSP_SUCCESS
I²C function performed successfully
SSP_ERR_INVALID_MODE
Illegal I²C mode is specified
SSP_ERR_IP_CHANNEL_NOT_PRESENT
Omitted I²C channel is specified
SSP_ERR_IN_USE
I²C channel has already been opened
SSP_ERR_INVALID_ARGUMENT
Argument is not one of the predefined values
SSP_ERR_INTERNAL
Internal error has occurred
SSP_ERR_ASSERTION
A critical assertion has failed, or Null pointer(s) is(are) given
SSP_ERR_NOT_OPEN
Device instance not opened
SSP_ERR_TRANSFER_ABORTED
The data transfer was aborted
SSP_ERR_INVALID_RATE
The requested rate cannot be set
SSP_ERR_TIMEOUT
Timeout error occurs
2. I²C Framework Module APIs Overview
The I²C Framework interface defines APIs for opening, closing, reading, writing, locking, unlocking, and
resetting the bus using the I²C Framework. A com plete list of the available APIs, an example API call and a
short description of each can be found in the following table. A table of status return values follows the A P I
summary table.
Table 1. I²C Framework Module API Summary
g_sf_i2c_device.p_cfg)
Disables the I²C device designated by control handle. Closes the RTOS services
&destination, no_of_bytes_to_read, restart, timeout);
no_of_bytes_to_write, restart, timeout);
Locks the bus for a device. Locking the bus reserves it until unlocking and allows
timeout);
Locks the bus for a device. Locking the bus reserves it until unlocking and allows
several reads and writes without intervention f rom ot her devices on the same I
Timeout value is user configurable.
Note: For more complete descriptions of operation and definitions for the function data structures, typedefs,
defines, API data, API structures, and function variables, review the SSP User’s Manual API
References for the associated module.
Table 2. Status Return Values
2
C bus.
Note: Lower-level drivers may return common er ror codes. Refer to the SSP User’s Manual API References
for the associated module for a definition of all relev ant status return values.
R11AN0098EU0102 Rev.1.02 Page 3 of 27
Jan.07.19
Renesas Synergy™ Platform I²C Framework Module Guide
3. I²C Framework Module Operational Overview
The I²C Framework module complies with the lay ered driver architecture of the SSP. It uses the lower-level
I²C HAL modules to communicate with the I²C peripherals and controls the I²C-capable peripheral s on a
Synergy microcontroller, as configured by a user. With the I²C Framework module, one or more I² C buses
can be created and multiple I²C peripherals can be connected to each I²C bus. The I²C Framework module
APIs use a ThreadX-mutex to acquire and release t he shared bus for I²C slave devices. In the I²C
Framework module, acquire and release are implem ented by lock (or lockWait) and unlock APIs,
respectively.
As the I²C framework module configures I²C comm unication in master mode, this allows the user to:
• Initialize the driver
• Read from a slave device
• Write to a slave device
• Reset the I²C peripheral
• Lock the I²C bus
• Unlock the I²C bus.
The I²C Framework module works with the Synergy MCU I²C hardware modules, the RIIC and SCI HAL
modules. Both I²C modules support the I²C fast-mode with bit rates of up to 400 kHz. The IIC peripheral and
the RIIC HAL module support fast-mode plus with 1-MHz bit-rates. The module supports only master mode
for both implementations.
Multiple Slave Devices on the Same Bus
The I²C Framework module uses a bus and device on bus architecture. If multiple salves are connected t o
the I²C bus, each slave communicates with an ass ociated and separate SF_I2C module instance. Each
SF_I2C instance is created in a separate thread. Every slave device is linked to the bus to which it will be
connected and share the bus with all other slave devices. The user must configure the framework share dbus and the lower-level I²C HAL layer for each framework device connecting to the bus. The user can add
the existing framework shared-bus when configuring multiple devices on the same bus. A common start and
stop procedure is used for all I²C data-transfer operations. Only one device is configured to the lower level
and the remaining devices perform read or write operations by switching the device address within t he
framework.
All I²C Framework devices on the same bus must use the same lower-level con fi guration sett ings (for
example, the I²C HAL module), except for the slave address and addressing mode. The framework uses the
configuration of the first device that it opens in the a pplication to configure the bus. This means that al l I²C
Framework devices on the same bus must have the same lower-level configuration settings (except for the
slave address and addressing mode). If different configurations are used, proper operation cannot be
guaranteed.
Bus Locking
The I²C Framework supports bus-locking funct ional i ty, meaning that the bus can be locked for a given
peripheral. The locking allows devices to reserve a bus to themselves for a given time period (between loc k
and unlock). This allows devices to complete sev eral reads and writes on the bus without interrupti on (which
is required in some instances).
The I²C bus is locked when lock or lockWait APIs are call ed. This API locks the I²C bus by acquiring the
mutex for the thread in which the I²C Framework device is used. Once locked, the I²C bus can only be
utilized by the associated device. The other I²C Framework device, or same I
2
C framework device from othe r
threads, cannot acquire the mutex, so they won’t be able to access the bus. Once the bus is unlocked by
calling the unlock API from the sf_i2c device that l ocked it, the mutex is released and the bus becomes
available for other sf_i2c devices. The lockWait and lock API are similar, except the lock API provides the
2
user with an option to set timeout value. The lockWait API waits for the specified timeout period if the I
is already locked by another device. In case of the lock API, the thread waits forever, if the I
2
C bus is not
C bus
released by the other device.
R11AN0098EU0102 Rev.1.02 Page 4 of 27
Jan.07.19
Renesas Synergy™ Platform I²C Framework Module Guide
Resource
ISDE Tab
Stacks Selection Sequence
g_sf_i2c_device0 I2C
Threads
New Stack> Framework> Con ne cti v it y > I²C Framework
3.1 I²C Framework Module Important Operational Notes and Limitations
3.1.1 I²C Framework Module Operational Notes
• The closest possible baud rate that can be achieved (less than or e qual t o t he requested rate) at the
current PCLKB settings is calculated and used. If a valid clock rate could not be calculated, an error is
returned.
• The I²C can trigger the start of other peripherals available from the ELC. See the ELC Module Guide for
further information.
• The I²C Framework can support multiple I²C devices on the same bus if the clock rate remains the same
for all the devices. That means multiple devices can b e opened in the same bus if they are of the same
clock rate. If devices have different clock rates, only one device can be opened at a time.
• SDA and SCL output pin type should be n-channel open drain wh en using I²C on SCI.
• Shared bus can be used by multiple slave devices with the respective configuration. The framework also
handles mutual exclusion in lock and unlock API s when multiple devices are using the same I²C channel.
• To configure multiple I²C devices on the same bus, add and configure the following modules for each
device to be connected to the bus:
I²C Framework device module
Configure the I²C shared bus module for the first dev ice being configured, then use the same bus for
the remaining devices
I²C HAL module
DTC module (optional)
• Lock functionality will be effective for devices from different t hreads. If multiple devices connected to the
bus are from the same thread, the I²C bus will be lock ed for all devices from that thread. In such case s,
even if the bus is locked, all devices from the same t hread can access the bus.
• In case a device is being used from multiple threads, and the dev ice locks the I²C bus from one thread,
the same device cannot access the I²C bus from other threads.
Note: Configure each I²C Framework device with a unique name in the ISDE configurator. Provide the same
configuration settings for devices connected on the same bus (except the slave address and
addressing modes).
3.1.2 I²C Framework Module Limitations
The I²C framework module does not currently support the use of DMA. Refer to the latest SSP Release Notes for any
additional operational limitations for this module.
4. Including the I²C Framework Module in an Application
This section describes how to include the I²C Framewor k module in an application using the SSP
configurator.
Note: It is assumed you are familiar with creating a project, adding threads, adding a stack to a thread, and
configuring a block within the stack. If you are unfami l i ar wit h any of these items, refer to the first few
chapters of the SSP User’s Manual to learn how to manage each of these important steps in creating
To add the I²C Framework module to an application, simply add it to a thread using the stacks selection
sequence given in the following table. (The default name for the I²C Framework Module is
g_sf_i2c_device0. This name can be changed in the associated Properties window.)
Table 3. I²C Framework Module Selection Sequence
The following figure shows when the I²C Framewo rk m odul e on sf_i2c is added to the thread stack, the
configurator automatically adds any needed low er-level modules. Any drivers that need additional
configuration information are box text highlighted in Red. Modules with a Gray band are individual modules
SSP-based applications.
Framework on sf_i2c
Device on sf_i2c
R11AN0098EU0102 Rev.1.02 Page 5 of 27
Jan.07.19
Renesas Synergy™ Platform I²C Framework Module Guide
Parameter
Value
Description
Parameter Checking
BSP, Enabled, Disabled
(Default: Enabled)
Enable or disable parameter error checking.
Name
g_sf_i2c_device0
Give a name to identify the I²C Framework device.
based on this name.
Slave Address
0x00
Specify the address of the I²C slave device.
that stand alone. Modules with a Blue band are sh ared or common and need only be added once and can be
used by multiple stacks.
Figure 2. I²C Framework Module Stack
5. Configuring the I²C Framework Module
The I²C Framework module must be configured by y ou for the desired operation. The SSP configuration
window automatically identifies (by highlighting the block in red) any required configurat i on selections, such
as interrupts or operating modes, which must be configured for lower-level modules for successful operation.
Only those properties that can be changed without causing conflicts are available for modificat ion. Other
properties are ‘locked’ and unavailable for chang es. They are identified with a lock icon for the ‘locked’
property in the Properties window in the ISDE. Thi s appro ach simplifies the configuration process and mak es
it much less error-prone than previous ‘manual’ approaches to configuration. The available configuration
settings and defaults for all the user-accessible properties are given in the Properties tab within the S SP
configurator and are shown in the following table s f or easy ref erence.
Note: You may want to open your ISDE, create the module, and explore the property settings in parallel
with reviewing the following configuration table settings. This help to orient you and can be a useful
hands-on approach to learning the ins and outs of developing with SSP.
Table 4. Configuration Settings for the I²C Frame work Module Device on sf_i2c
R11AN0098EU0102 Rev.1.02 Page 6 of 27
Jan.07.19
API, Config and Control instances will be created
Renesas Synergy™ Platform I²C Framework Module Guide
Parameter
Value
Description
Address Mode
7-Bit, 10-Bit
(Default: 7-Bit)
Select the I²C address mode.
ISDE Property
Value
Description
Name
g_sf_i2c_bus0
Module name.
ISDE Property
Value
Description
Parameter Checking
BSP, Enabled, Disabled
(Default: BSP)
Enable or disable parameter error
Name
g_i2c0
Module name.
Channel
0
Specify the SCI channel to be used with
this configuration.
Rate
Standard, Fast-mode
(Default: Standard)
Select the I²C data rate.
Slave Address
0
Address of the slave device.
Address Mode
7-Bit, 10-Bit
(Default: 7-Bit)
Only 7-bit addresses are currently
SDA Output Delay
(nano seconds)
300
SDA output delay in nanoseconds.
Bit Rate Modulation
Enable, Disable
(Default: Enable)
Enables bitrate modulation function.
Callback
NULL
A user callback function can be registered
system.
Receive Interrupt
Priority 0 (highest), Priority 1:14,
(Default: Priority 12)
Receive interrupt priority selection.
Note: The example values and defaults are for a project using the Synergy S7G2 MCU. Other MCUs may
In some cases, settings other than the defaults for lower-level modules can be desirable. For example, i t
might be useful to select different address mode or set different slave address. The configurable properties
for the lower-level modules are given in the following s ecti ons for completeness and as a reference.
Note: Most of the property settings for lower-level modules are intuitive and can usually be determined by
have different default values and available configuration settings.
inspection of the associated Properties window with the SSP configurator.
5.1 Configuration Settings for the I²C Framework Lower-Level Modules
Typically, only a small number of settings must be modified from the default for lower-level dri vers as
indicated by the red text in the thread stack block. Notice that some of the configuration properti es must be
set to a certain value for proper framework operati on and will be locked to prevent user modification. The
following table identifies all the settings within the pr operties section for the module:
Table 5. Configuration Settings for the I²C Framework Shared Bus on sf_i2c
Note: The example values and defaults are for a project using the Synergy S7G2 MCU. Other MCUs may
Table 6. Configuration Settings for the I²C Master Driver on r_sci_i2c
have different default values and available confi guration settings.
Enable
checking.
supported.
in i2c_api_master_t::open. If this callback
function is provided, it will be called from
the interrupt service routine (ISR) for each
of the conditions defined in i2c_event_t.
Warning: Since the callback is called from
an ISR, do not use blocking calls or lengthy
processing. Spending excessive time in an
ISR can affect the responsiveness of the
Priority
R11AN0098EU0102 Rev.1.02 Page 7 of 27
Jan.07.19
Priority 15 (lowest - not valid if
using ThreadX)
Renesas Synergy™ Platform I²C Framework Module Guide
ISDE Property
Value
Description
Transmit Interrupt
Priority 0 (highest), Priority 1:14,
(Default: Priority 12)
Transmit interrupt priority selection.
Transmit End Interrupt
Priority 0 (highest), Priority 1:14,
Transmit end interrupt priority selection.
ISDE Property
Value
Description
Parameter Checking
BSP, Enabled, Disabled
(Default: BSP)
Enable or disable parameter error
Name
g_i2c0
Module name
Channel
0
Specify the IIC channel to be used with
this configuration.
Rate
Standard, Fast-mode, Fast-mode plus
Standard, Fast and Fast-plus. (See IIC
Slave Address
0
Set the address of the slave device the
I²C master will be communicating with.
Address Mode
7-Bit, 10-Bit
Only 7-bit addresses are currently
Timeout Mode
Short Mode, Long Mode
(Default: Short Mode)
Select the timeout mode.
Callback
NULL
A user callback function can be
Receive Interrupt
Priority 0 (highest), Priority 1:14,
(Default: Priority 12)
Receive interrupt priority selection
Transmit Interrupt
Priority 0 (highest), Priority 1:14,
Transmit interrupt priority selection
Transmit End Interrupt
Priority 0 (highest), Priority 1:14,
(Default: Priority 12)
Transmit end interrupt priority selection
Error Interrupt Priority
Priority 0 (highest), Priority 1:14,
Error interrupt priority selection
Priority
Priority
Note: The example values and defaults are for a project using the Synergy S7G2 MCU. Other MCUs may
have different default values and available configuration settings.
Table 7. Configuration Settings for the I²C Master Driver on r_riic
Priority 15 (lowest - not valid if
using ThreadX)
Priority 15 (lowest - not valid if
using ThreadX)
(Default: Priority 12)
Default: Standard
(Default: 7-Bit)
checking
Rate Calculation.)
supported.
Priority
Priority
Priority
registered in i2c_api_master_t::open. If
this callback function is provided, it will
be called from the interrupt service
routine (ISR) for each of the conditions
defined in i2c_event_t.
Warning: Since the callback is called
from an ISR, do not use blocking calls
or lengthy processing. Spending
excessive time in an ISR can affect the
responsiveness of the system.
Priority 15 (lowest - not valid if using
ThreadX)
Priority 15 (lowest - not valid if using
ThreadX)
(Default: Priority 12)
Priority 15 (lowest - not valid if using
ThreadX)
Priority 15 (lowest - not valid if using
ThreadX)
(Default: Priority 12)
R11AN0098EU0102 Rev.1.02 Page 8 of 27
Jan.07.19
Renesas Synergy™ Platform I²C Framework Module Guide
ISDE Property
Value
Description
Parameter Checking
BSP, Enabled, Disabled
(Default: BSP)
Selects if code for parameter checking
Software Start
Enabled, Disabled
Software start selection.
Linker section to keep
DTC vector table
.ssp_dtc_vector_table
Linker section to keep DTC vector
table.
Name
g_transfer0
Module name
Mode
Normal
Mode selection
Transfer Size
1 Byte
Transfer size selection
Destination Address
Mode
Fixed
Destination address mode selection
Source Address Mode
Incremented
Source address mode selection
Repeat Area (Unused
in Normal Mode
Source
Repeat area selection
Interrupt Frequency
After all transfers have completed
Interrupt frequency selection
Destination Pointer
NULL
Destination pointer selection
Source Pointer
NULL
Source pointer selection
Number of Transfers
0
Number of transfers selection
Number of Blocks
0
Number of blocks selection
Activation Source
(Must enable IRQ)
Event SCI0 TXI
Activation source selection
Auto Enable
FALSE
Auto enable selection
Callback (Only valid
with Software start)
NULL
Callback selection
ELC Software Event
Priority 0 (highest), Priority 1:14,
ELC software event interrupt priority
ISDE Property
Value
Description
Parameter Checking
BSP, Enabled, Disabled
(Default: BSP)
Selects if code for parameter checking
Software Start
Enabled, Disabled
Software start selection
Linker section to keep
DTC vector table
.ssp_dtc_vector_table
Linker section to keep DTC vector
table.
Name
g_transfer1
Module name
Mode
Normal
Mode selection
Transfer Size
1 Byte
Transfer size selection
Destination Address
Mode
Incremented
Destination address mode selection
Source Address Mode
Fixed
Source address mode selection
Repeat Area (Unused
in Normal Mode
Destination
Repeat area selection
Note: The example values and defaults are for a project using the Synergy S7G2 MCU. Other MCUs may
have different default values and available configuration settings.
Table 8. Configuration Settings for the Transfer Driver on r_dtc Event SCI0 TXI
is to be included in the build
(Default: Disabled)
(Valid only in Block
Mode)
Interrupt Priority
Note: The example values and defaults are for a project using the Synergy S7G2 MCU. Other MCUs may
have different default values and available configuration settings.
Table 9. Configuration Settings for the Transfer Driver on r_dtc Event SCI0 RXI
Priority 15 (lowest - not valid if using
ThreadX), Disabled
(Default: Disabled)
(Default: Disabled)
selection.
is to be included in the build
R11AN0098EU0102 Rev.1.02 Page 9 of 27
Jan.07.19
Loading...