Hardware Abstraction Layer (HAL)
EZI2C (Inter-Integrated Circuit)

General Description

High level interface for interacting with the Cypress EZ Inter-Integrated Circuit (EZI2C).

The EZI2C driver implements an I2C slave device that emulates a common I2C EEPROM interface between the external master and your application code. EZI2C Slave buffers can be set up as any variable, array, or structure in your code without worrying about the I2C protocol. I2C related transactions and processing of data from the I2C master are handled by the driver through internal interrupt routine, reducing application involvement to maintain the I2C buffer.

Features

Quick Start

Initialize EZI2C by using cyhal_ezi2c_init and selecting the sda and scl pins. Setup one or two memory buffers and read/write boundaries using the EZI2C configuration structure cyhal_ezi2c_cfg_t. See Snippet 1: EZI2C Initialization and Configuration

Note
The clock parameter clk is optional and can be set to NULL to generate and use an available clock resource.

Code snippets

Snippet 1: EZI2C Initialization and Configuration

The following snippet shows how to initialize and configure an EZI2C and assign the pins to the sda and scl lines. The clk need not be provided (NULL), in which case a clock resource is assigned.

const uint8_t SLAVE_ADDRESS = 0x08;
// Allocate buffer for EZI2C Operation
#define BUFF_SIZE (8u)
// Number of bytes from the beginning of buffer that provides read and write access for the
// master
const uint32_t BUFFER_RW_BOUNDARY = 8u;
uint8_t buf[BUFF_SIZE];
// Declare variables
cy_rslt_t rslt;
cyhal_ezi2c_t ezi2c_obj;
// Populate slave configuration structure slave_config1
cyhal_ezi2c_slave_cfg_t slave_config1 = { SLAVE_ADDRESS, buf, BUFF_SIZE, BUFFER_RW_BOUNDARY };
// Assign values to configuration structure slave_config2 if dual port addressing is needed
cyhal_ezi2c_slave_cfg_t slave_config2 = { 0, NULL, 0, 0 };
// Populate the EZI2C configuration structure
cyhal_ezi2c_cfg_t ezi2c_config =
{
false,
true,
CYHAL_EZI2C_DATA_RATE_400KHZ,
slave_config1,
slave_config2,
};
// Initialize EZI2C
rslt = cyhal_ezi2c_init(&ezi2c_obj, CYBSP_I2C_SDA, CYBSP_I2C_SCL, NULL, &ezi2c_config);
cy_rslt_t cyhal_ezi2c_init(cyhal_ezi2c_t *obj, cyhal_gpio_t sda, cyhal_gpio_t scl, const cyhal_clock_t *clk, const cyhal_ezi2c_cfg_t *cfg)
Initialize the EZI2C (slave), and configures its specified pins and clock.
@ CYHAL_EZI2C_SUB_ADDR8_BITS
Sub-address is 8 bits
Definition: cyhal_ezi2c.h:112
Initial EZI2C configuration.
Definition: cyhal_ezi2c.h:162
Initial EZI2C sub configuration.
Definition: cyhal_ezi2c.h:146
EZI2C object.
Definition: cyhal_hw_types.h:787
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:426

Snippet 2: Register Callback function

The following snippet shows how to use the cyhal_ezi2c_register_callback function. The callback parameter refers to the handler which will be invoked when an event triggers.

// Declare variables
cyhal_ezi2c_t ezi2c_obj;
// Interrupt handler for EZI2C
void handle_ezi2c_events(void* callback_arg, cyhal_ezi2c_event_t event)
{
CY_UNUSED_PARAMETER(event);
CY_UNUSED_PARAMETER(callback_arg);
status = cyhal_ezi2c_get_activity_status(&ezi2c_obj);
if (0 != (CYHAL_EZI2C_STATUS_READ1 & status))
{
// User code for operations to be performed after read complete
}
if (0 != (CYHAL_EZI2C_STATUS_WRITE1 & status))
{
// User code for operations to be performed after write complete
}
if (0 != (CYHAL_EZI2C_STATUS_ERR & status))
{
// User code for operations to be performed if an error occurs
}
}
cy_rslt_t snippet_cyhal_ezi2c_handler()
{
const uint8_t SLAVE_ADDRESS = 0x08;
// Allocate buffer for EZI2C Operation
#define BUFFER_SIZE (8u)
// Number of bytes from the beginning of buffer that provides read and write access for the
// master
const uint32_t BUFFER_RW_BOUNDARY = 6u;
uint8_t buf[BUFFER_SIZE];
cy_rslt_t rslt;
// Populate slave configuration structure slave_config1
cyhal_ezi2c_slave_cfg_t slave_config1 = { SLAVE_ADDRESS, buf, BUFFER_SIZE, BUFFER_RW_BOUNDARY };
// Assign values to configuration structure slave_config2 if dual port addressing is needed
cyhal_ezi2c_slave_cfg_t slave_config2 = { 0, NULL, 0, 0 };
// Populate the EZI2C configuration structure
cyhal_ezi2c_cfg_t ezi2c_config =
{
false,
true,
CYHAL_EZI2C_DATA_RATE_400KHZ,
slave_config1,
slave_config2,
};
// Initialize EZI2C
rslt = cyhal_ezi2c_init(&ezi2c_obj, CYBSP_I2C_SDA, CYBSP_I2C_SCL, NULL, &ezi2c_config);
// Register I2C slave event callback
if (CY_RSLT_SUCCESS == rslt)
{
cyhal_ezi2c_register_callback(&ezi2c_obj, handle_ezi2c_events, NULL);
}
return rslt;
}
cyhal_ezi2c_status_t
Return codes of ezi2c.
Definition: cyhal_ezi2c.h:126
void cyhal_ezi2c_register_callback(cyhal_ezi2c_t *obj, cyhal_ezi2c_event_callback_t callback, void *callback_arg)
Register a EZI2C event callback handler.
cyhal_ezi2c_status_t cyhal_ezi2c_get_activity_status(cyhal_ezi2c_t *obj)
EZI2C slave get activity status This function returns a non-zero value ( cyhal_ezi2c_status_t) if an ...
@ CYHAL_EZI2C_STATUS_ERR
An error occurred during a transfer intended for the primary or secondary slave address.
Definition: cyhal_ezi2c.h:134
@ CYHAL_EZI2C_STATUS_WRITE1
The Write transfer intended for the primary slave address is complete.
Definition: cyhal_ezi2c.h:130
@ CYHAL_EZI2C_STATUS_READ1
The Read transfer intended for the primary slave address is complete.
Definition: cyhal_ezi2c.h:129
#define CY_RSLT_SUCCESS
cy_rslt_t return value indicating success
Definition: cy_result.h:453

API Reference

 EZI2C HAL Results
 EZI2C specific return codes.
 

Data Structures

struct  cyhal_ezi2c_slave_cfg_t
 Initial EZI2C sub configuration. More...
 
struct  cyhal_ezi2c_cfg_t
 Initial EZI2C configuration. More...
 

Macros

#define CYHAL_EZI2C_EVENT_NONE   CYHAL_EZI2C_STATUS_OK
 CYHAL_EZI2C_EVENT_NONE event is deprecated and that CYHAL_EZI2C_STATUS_OK should be used instead.
 

Typedefs

typedef cyhal_ezi2c_status_t cyhal_ezi2c_event_t
 This type is deprecated and that cyhal_ezi2c_status_t should be used instead.
 
typedef void(* cyhal_ezi2c_event_callback_t) (void *callback_arg, cyhal_ezi2c_status_t event)
 Handler for I2C events.
 

Enumerations

enum  cyhal_ezi2c_sub_addr_size_t {
  CYHAL_EZI2C_SUB_ADDR8_BITS ,
  CYHAL_EZI2C_SUB_ADDR16_BITS
}
 Size of Sub-Address. More...
 
enum  cyhal_ezi2c_data_rate_t {
  CYHAL_EZI2C_DATA_RATE_100KHZ = 100000 ,
  CYHAL_EZI2C_DATA_RATE_400KHZ = 400000 ,
  CYHAL_EZI2C_DATA_RATE_1MHZ = 1000000
}
 Data rate of the slave.
 
enum  cyhal_ezi2c_status_t {
  CYHAL_EZI2C_STATUS_OK = 0x1UL ,
  CYHAL_EZI2C_STATUS_READ1 = 0x2UL ,
  CYHAL_EZI2C_STATUS_WRITE1 = 0x4UL ,
  CYHAL_EZI2C_STATUS_READ2 = 0x8UL ,
  CYHAL_EZI2C_STATUS_WRITE2 = 0x10UL ,
  CYHAL_EZI2C_STATUS_BUSY = 0x20UL ,
  CYHAL_EZI2C_STATUS_ERR = 0x40UL
}
 Return codes of ezi2c. More...
 

Functions

cy_rslt_t cyhal_ezi2c_init (cyhal_ezi2c_t *obj, cyhal_gpio_t sda, cyhal_gpio_t scl, const cyhal_clock_t *clk, const cyhal_ezi2c_cfg_t *cfg)
 Initialize the EZI2C (slave), and configures its specified pins and clock. More...
 
void cyhal_ezi2c_free (cyhal_ezi2c_t *obj)
 Deinitialize the ezi2c object. More...
 
cyhal_ezi2c_status_t cyhal_ezi2c_get_activity_status (cyhal_ezi2c_t *obj)
 EZI2C slave get activity status This function returns a non-zero value ( cyhal_ezi2c_status_t) if an I2C Read or Write cycle has occurred since the last time this function was called. More...
 
void cyhal_ezi2c_register_callback (cyhal_ezi2c_t *obj, cyhal_ezi2c_event_callback_t callback, void *callback_arg)
 Register a EZI2C event callback handler. More...
 
void cyhal_ezi2c_enable_event (cyhal_ezi2c_t *obj, cyhal_ezi2c_status_t event, uint8_t intr_priority, bool enable)
 Configure and Enable or Disable EZI2C Interrupt. More...
 
cy_rslt_t cyhal_ezi2c_init_cfg (cyhal_ezi2c_t *obj, const cyhal_ezi2c_configurator_t *cfg, const cyhal_ezi2c_slave_cfg_t *slave1_cfg, const cyhal_ezi2c_slave_cfg_t *slave2_cfg)
 Initialize the EZI2C peripheral using a configurator generated configuration struct and set up slave address(es) data. More...
 

Data Structure Documentation

◆ cyhal_ezi2c_slave_cfg_t

struct cyhal_ezi2c_slave_cfg_t
Data Fields
uint8_t slave_address The 7-bit right justified primary slave address.
uint8_t * buf A pointer to the data buffer for the primary/secondary slave address.
uint32_t buf_size The size of the buffer assigned to the primary/secondary slave address.
uint32_t buf_rw_boundary The Read/Write boundary within the buffer assigned to the primary/secondary slave address.

This specifies the number of data bytes from the beginning of the buffer with read and write access for the master. Data bytes at this value or greater are read only by the master

◆ cyhal_ezi2c_cfg_t

struct cyhal_ezi2c_cfg_t
Data Fields
bool two_addresses Number of addresses (one or two).

If set "true" - use two addresses otherwise ("false") one

bool enable_wake_from_sleep When set, the slave will wake the device from Deep Sleep on an address match.
cyhal_ezi2c_data_rate_t data_rate Maximum frequency that the I2C Slave bus runs at.

Supports standard data rates of 100/400/1000 kbps

cyhal_ezi2c_slave_cfg_t slave1_cfg Refer to cyhal_ezi2c_slave_cfg_t for details.

This config structure is mandatory.

cyhal_ezi2c_slave_cfg_t slave2_cfg Refer to cyhal_ezi2c_slave_cfg_t for details.

This config structure is optional. Set it if user want to use dual-port addressing otherwise leave blank

cyhal_ezi2c_sub_addr_size_t sub_address_size The size of the sub-address, can either be 8 or 16 bits.

Enumeration Type Documentation

◆ cyhal_ezi2c_sub_addr_size_t

Size of Sub-Address.

Enumerator
CYHAL_EZI2C_SUB_ADDR8_BITS 

Sub-address is 8 bits

CYHAL_EZI2C_SUB_ADDR16_BITS 

Sub-address is 16 bits.

◆ cyhal_ezi2c_status_t

Return codes of ezi2c.

Enumerator
CYHAL_EZI2C_STATUS_OK 

Each EZI2C slave status is encoded in a separate bit, therefore multiple bits may be set to indicate the current status.

Operation completed successfully

CYHAL_EZI2C_STATUS_READ1 

The Read transfer intended for the primary slave address is complete.

CYHAL_EZI2C_STATUS_WRITE1 

The Write transfer intended for the primary slave address is complete.

CYHAL_EZI2C_STATUS_READ2 

The Read transfer intended for the secondary slave address is complete.

CYHAL_EZI2C_STATUS_WRITE2 

The Write transfer intended for the secondary slave address is complete.

CYHAL_EZI2C_STATUS_BUSY 

A transfer intended for the primary address or secondary address is in progress.

CYHAL_EZI2C_STATUS_ERR 

An error occurred during a transfer intended for the primary or secondary slave address.

Function Documentation

◆ cyhal_ezi2c_init()

cy_rslt_t cyhal_ezi2c_init ( cyhal_ezi2c_t obj,
cyhal_gpio_t  sda,
cyhal_gpio_t  scl,
const cyhal_clock_t clk,
const cyhal_ezi2c_cfg_t cfg 
)

Initialize the EZI2C (slave), and configures its specified pins and clock.

See Snippet 1: EZI2C Initialization and Configuration

Parameters
[out]objPointer to an EZI2C object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]sdaThe sda pin
[in]sclThe scl pin
[in]clkThe clock to use can be shared, if NULL a new clock will be allocated
[in]cfgThe ezi2c configuration (refer to cyhal_ezi2c_cfg_t for details)
Returns
The status of the init request

◆ cyhal_ezi2c_free()

void cyhal_ezi2c_free ( cyhal_ezi2c_t obj)

Deinitialize the ezi2c object.

Parameters
[in,out]objThe ezi2c object

◆ cyhal_ezi2c_get_activity_status()

cyhal_ezi2c_status_t cyhal_ezi2c_get_activity_status ( cyhal_ezi2c_t obj)

EZI2C slave get activity status This function returns a non-zero value ( cyhal_ezi2c_status_t) if an I2C Read or Write cycle has occurred since the last time this function was called.

See Snippet 2: Register Callback function

Parameters
[in]objThe EZI2C object
Returns
The status of the EZI2C (see cyhal_ezi2c_status_t for details)

◆ cyhal_ezi2c_register_callback()

void cyhal_ezi2c_register_callback ( cyhal_ezi2c_t obj,
cyhal_ezi2c_event_callback_t  callback,
void *  callback_arg 
)

Register a EZI2C event callback handler.

See Snippet 2: Register Callback function

Parameters
[in]objThe EZI2C object
[in]callbackThe callback handler which will be invoked when an event triggers
[in]callback_argGeneric argument that will be provided to the callback when called

◆ cyhal_ezi2c_enable_event()

void cyhal_ezi2c_enable_event ( cyhal_ezi2c_t obj,
cyhal_ezi2c_status_t  event,
uint8_t  intr_priority,
bool  enable 
)

Configure and Enable or Disable EZI2C Interrupt.

Parameters
[in]objThe EZI2C object
[in]eventThe EZI2C event type
[in]intr_priorityThe priority for NVIC interrupt events
[in]enableTrue to turn on interrupts, False to turn off

◆ cyhal_ezi2c_init_cfg()

cy_rslt_t cyhal_ezi2c_init_cfg ( cyhal_ezi2c_t obj,
const cyhal_ezi2c_configurator_t cfg,
const cyhal_ezi2c_slave_cfg_t slave1_cfg,
const cyhal_ezi2c_slave_cfg_t slave2_cfg 
)

Initialize the EZI2C peripheral using a configurator generated configuration struct and set up slave address(es) data.

Parameters
[in]objThe EZI2C peripheral to configure
[in]cfgConfiguration structure generated by a configurator.
[in]slave1_cfgPrimary slave address configuration
[in]slave2_cfgSecondary slave address configuration (can be NULL)
Returns
The status of the operation