Synergy Software Package User's Manual
I2C Slave Driver

Table of Contents

I2C Slave HAL Module Introduction

The I2C Slave HAL Module provides a high-level API for I2C slave applications and uses the RIIC peripheral on the Synergy MCU. Callbacks are provided to signal read/write request received from master and transfer completion events.

I2C Slave HAL Module Features

  • Support for I2C Slave operations
  • Support transactions with a I2C master device
    • Read
    • Write
  • Callback support
    • Transmit Request (notifies when a write operation is expected from slave)
    • Receive Request (notifies when a read operation is expected from slave)
    • Transmit more request (notifies when master requests more data than configured in slave write operation. Also provides number of bytes transmitted)
    • Receive more request (notifies when master tries to write more data than configured in slave read operation. Also provides number of bytes received)
    • Transmit complete (provides number of bytes transmitted)
    • Receive complete (provides number of bytes received)
I2C_Slave_BD.png
I2C Slave HAL Module Block Diagram

RIIC Slave Hardware support details

RIIC Slave driver supported features:

Legend:

Symbol Meaning
✓ Available (Tested)
⌧ Not Available (Not tested/not functional or both)
N/A Not supported by MCU 

 

MCU Group I2C Format SMBus Format Master Mode Slave Mode Fast Mode
Plus 		Selectable
duty cycle
S124 ✓ ⌧ ⌧ ✓ N/A ⌧
S128 ✓ ⌧ ⌧ ✓ N/A ⌧
S1JA ✓ ⌧ ⌧ ✓ N/A ⌧
S3A1 ✓ ⌧ ⌧ ✓ N/A ⌧
S3A3 ✓ ⌧ ⌧ ✓ N/A ⌧
S3A6 ✓ ⌧ ⌧ ✓ N/A ⌧
S3A7 ✓ ⌧ ⌧ ✓ N/A ⌧
S5D3 ✓ ⌧ ⌧ ✓ ✓ ⌧
S5D5 ✓ ⌧ ⌧ ✓ ✓ ⌧
S5D9 ✓ ⌧ ⌧ ✓ ✓ ⌧
S7G2 ✓ ⌧ ⌧ ✓ ✓ ⌧
MCU Group Configurable
to up to three
different slave
addresses 		7- and 10-
bit address
formats 		General call
address,
Device ID
address and
SMBus host
address
detectable 		Automatic
loading of the
acknowledge
bit 		SDA
output
delay
function 		Selectable
Wait
functions
(8/9 or 9/1)
S124 One slave address 7 and 10-bit ⌧ ✓ ⌧ ⌧
S128 One slave address 7 and 10-bit ⌧ ✓ ⌧ ⌧
S1JA One slave address 7 and 10-bit ⌧ ✓ ⌧ ⌧
S3A1 One slave address 7 and 10-bit ⌧ ✓ ⌧ ⌧
S3A3 One slave address 7 and 10-bit ⌧ ✓ ⌧ ⌧
S3A6 One slave address 7 and 10-bit ⌧ ✓ ⌧ ⌧
S3A7 One slave address 7 and 10-bit ⌧ ✓ ⌧ ⌧
S5D3 One slave address 7 and 10-bit ⌧ ✓ ⌧ ⌧
S5D5 One slave address 7 and 10-bit ⌧ ✓ ⌧ ⌧
S5D9 One slave address 7 and 10-bit ⌧ ✓ ⌧ ⌧
S7G2 One slave address 7 and 10-bit ⌧ ✓ ⌧ ⌧
MCU Group Full Arbitration Support Internal Detect Time-Out Programmable
Digital Noise Filters 		Support all Interrupt
Sources 		Event link
function
through
ELC HAL
driver
S124 Slave, NACK arbitration ✓ ⌧ ✓ ⌧
S128 Slave, NACK arbitration ✓ ⌧ ✓ ⌧
S1JA Slave, NACK arbitration ✓ ⌧ ✓ ⌧
S3A1 Slave, NACK arbitration ✓ ⌧ ✓ ⌧
S3A3 Slave and NACK
arbitration 		✓ ⌧ ✓ ⌧
S3A6 Slave and NACK
arbitration 		✓ ⌧ ✓ ⌧
S3A7 Slave, NACK arbitration ✓ ⌧ ✓ ⌧
S5D3 Slave, NACK arbitration ✓ ⌧ ✓ ⌧
S5D5 Slave, NACK arbitration ✓ ⌧ ✓ ⌧
S5D9 Slave, NACK arbitration ✓ ⌧ ✓ ⌧
S7G2 Slave and NACK
arbitration 		✓ ⌧ ✓ ⌧

I2C Slave HAL Module APIs Overview

The I2C RIIC Slave HAL Module defines APIs for reading and writing to a master I2C device. A complete 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 API summary table.

I2C Slave HAL Module API Summary

Function Name Example API Call and Description
open g_i2c.p_api->open(g_i2c.p_ctrl, g_i2c.p_cfg);
Open the instance and initialize the hardware.
close g_i2c.p_api->close(g_i2c.p_ctrl);
Closes the driver and releases the I2C device.
masterWriteSlaveRead g_i2c.p_api->masterWriteSlaveRead(g_i2c.p_ctrl, &destination, bytes);
Performs a read operation on an I2C device.
masterReadSlaveWrite g_i2c.p_api->masterReadSlaveWrite(g_i2c.p_ctrl, &source, bytes);
Performs a write operation on an I2C device.
versionGet g_i2c.p_api->versionGet(&version);
Retrieve the API version with the version pointer.
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.

Status Return Values

Name Description
SSP_SUCCESS API Call Successful.
SSP_ERR_INVALID_POINTER Pointer is NULL.
SSP_ERR_IN_USE Attempted to open an already open device instance.
SSP_ERR_ABORTED Device was closed while a transfer was in progress.
SSP_ERR_INVALID_ARGUMENT Parameter has invalid value.
Note
Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

I2C Slave HAL Module Operational Overview

The I2C RIIC Slave HAL Module supports transfers to an I2C Master device. Callbacks are provided to enable the application identify the occurrence of any of the following events.

  • Read/write request with the slave address match is detected from master.
  • Master requests more data than slave configured in read/write API.
  • An ongoing transfer has been aborted.
  • An ongoing transfer has completed.

I2C Slave HAL Module Important Operational Notes and Limitations

I2C Slave HAL Module Operational Notes

  • The RIIC 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 BSP irrespective of whether the user wants to use callbacks.
  • Set equal priority levels for all the interrupts mentioned above. Setting the interrupts to different priority levels could result in improper operation.
  • If using RIIC and RIIC_Slave modules on the same board, it is suggested to set equal interrupt priority for TXI, TEI and EI and set RXI interrupt priority higher than these.

I2C Slave HAL Module Limitations

This is the initial version of I2C RIIC Slave Driver with only basic functionality implemented. The following limitations are known:

  1. For the driver provide to the application any information regarding the type of request received, the application has to implement/register for the appropriate callback. This limits in usage of the events provided by the driver in application. These events help in real-time master request processing.
  2. When the driver is used in blocking mode, slave API has to be invoked with same number of bytes as configured in the master.
  3. Any of the supported IIC channels can be configured for either Master or Slave mode operation but not for both.
  • Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the I2C Slave HAL Module in an Application

This section describes how to include the I2C Slave HAL Module in an application using the SSP configurator.

Note
This section assumes 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 unfamiliar with 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 SSP-based applications.

To add the I2C Slave Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the I2C Slave Driver is g_i2c0. This name can be changed in the associated Properties window.)

I2C Slave HAL Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_i2c0 I2C Slave Driver on r_riic_slave Threads New Stack> Driver> Communications> I2C Slave Driver on r_riic_slave

When the I2C Slave Driver on r_riic_slave is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Grayband are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

I2C_Slave_MS.png
I2C Slave HAL Module Stack

Configuring the I2C Slave HAL Module

The I2C Slave HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes 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 SSP Configurator and are shown in the following tables for easy reference.

Note
You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the I2C Slave HAL Module on r_riic_slave

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled
Default: BSP 		Enable or disable parameter error checking.
Name g_i2c0 Module name.
Channel 0 Specify the IIC channel to be used with this configuration.
Rate Standard, Fast-mode, Fast-mode plus
Default: Standard 		Transfer rate to which the IIC peripheral should be configured to operate.
Slave Address 0x00 Set the address of the device as the I2C slave address. Both 7-bit and 10-bit addresses are supported.
Address Mode 7-Bit, 10 Bit
Default: 7-Bit 		Address mode selection.
Callback NULL A user callback function can be 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.
Receive Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)
Default: Priority 12 		Receive interrupt priority selection.
Transmit Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)
Default: Priority 12 		Transmit interrupt priority selection.
Transmit End Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)
Default: Priority 12 		Transmit End interrupt priority selection.
Error Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)
Default: Priority 12 		Error interrupt priority selection.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

I2C Slave HAL Module Clock Configuration

The RIIC peripheral module uses PCLKB as its clock source.

I2C Slave HAL Module Pin Configuration

The RIIC 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.  The following table illustrates the method for selecting the pins within the SSP configuration window and the subsequent table illustrates an example selection for the pins:

Note
For some peripherals, the operation mode selection determines what peripheral signals are available and what MCU pins are required.

Pin Selection for the I2C Slave HAL Module on r_riic_slave

Resource ISDE Tab Pin selection Sequence
I2C Pins Select Peripherals> Connectivity: IIC> IIC0.
Note
The selection sequence assumes that IIC0 is the desired hardware target for the driver.

Pin Configuration Settings for the I2C Slave HAL Module on r_riic_slave

Pin Configuration Property Value Description
Pin Group Selection _A only, _B only, Mixed
Default: _A only 		Select Simple I2C as the Operation Mode for I2C on SCI.
Operation Mode Enabled, Disabled
Default: Disabled 		Enable or disable peripheral module.
SDA None, P401, P407
Default: None 		SDA Pin.
SCL None, P400, P204
Default: None 		SCL Pin.
Note
The example settings are for a project using the Synergy S7G2 MCU Group and SK-S7G2 Kit.  Other Synergy kits and MCUs may have different available pin configuration settings.

Using the I2C Slave HAL Module in an Application

The sequence for using the I2C Slave HAL module (blocking mode) in an application is:

1. Initialize and open the I2C Slave HAL Module using the i2c_api_slave_t::open API.

2. Transfer data to the master using the i2c_api_slave_t::masterReadSlaveWrite API.

3. Receive data from the master using the i2c_api_slave_t::masterWriteSlaveRead API.

4. Close the channel using the i2c_api_slave_t::close API.

These steps are illustrated in a typical operational flow diagram in the following figure:

I2C_Slave_TA.png
Flow Diagram of a Typical I2C Slave HAL Module Application without callback

The sequence for using the I2C Slave HAL module (non-blocking mode) in an application is:

  1. Initialize and open the I2C Slave HAL Module using the i2c_api_slave_t::open API.
  2. If callback event i2c_event_t generated indicates transmit request. Transfer data to the master using the i2c_api_slave_t::masterReadSlaveWrite API in callback.
  3. If callback event i2c_event_t generated indicates transmit-more request (master tries to read more data than configured in slave write). Transfer data to the master using the i2c_api_slave_t::masterReadSlaveWrite API in callback with new transmit data buffer.
  4. If callback event i2c_event_t generated indicates receive request. Receive data from the master using the i2c_api_slave_t::masterWriteSlaveRead API in callback.
  5. If callback event i2c_event_t generated indicates a receive-more request (master tries to write more data than configured in slave read). Receive data from the master using the i2c_api_slave_t::masterWriteSlaveRead API in callback with new receive data buffer.
  6. Close the channel using the i2c_api_slave_t::close API.

These steps above with registered callback are illustrated in a typical operational flow diagram in the following figure:

I2C_Slave_TA2.png
Flow Diagram of a Typical I2C Slave HAL Module Application with callback