EZI2C (Inter-Integrated Circuit)¶

group group_hal_ezi2c

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

EZI2C Slave functionality
Configurable standard data rates of 100/400/1000 kbps - cyhal_ezi2c_data_rate_t
Supports one or two addresses with independent memory buffers - cyhal_ezi2c_cfg_t
Memory buffers provide configurable read/write and read only regions - cyhal_ezi2c_cfg_t
8 or 16-bit sub-addressing - cyhal_ezi2c_sub_addr_size_t
Configurable interrupt and callback assignment from EZI2C events - cyhal_ezi2c_event_t

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,
        CYHAL_EZI2C_SUB_ADDR8_BITS
    };

    // Initialize EZI2C
    rslt = cyhal_ezi2c_init(&ezi2c_obj, CYBSP_I2C_SDA, CYBSP_I2C_SCL, NULL, &ezi2c_config);

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);
    cyhal_ezi2c_status_t status;

    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
    }
}


void 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,
        CYHAL_EZI2C_SUB_ADDR8_BITS
    };

    // Initialize EZI2C
    rslt = cyhal_ezi2c_init(&ezi2c_obj, CYBSP_I2C_SDA, CYBSP_I2C_SCL, NULL, &ezi2c_config);
    CY_ASSERT(CY_RSLT_SUCCESS == rslt);

    // Register I2C slave event callback
    cyhal_ezi2c_register_callback(&ezi2c_obj, handle_ezi2c_events, NULL);
}

Defines

CYHAL_EZI2C_EVENT_NONE¶: 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.

Enums

enum cyhal_ezi2c_sub_addr_size_t¶

cyhal_ezi2c_sub_addr_size_t: Size of Sub-Address.

Values:

enumerator CYHAL_EZI2C_SUB_ADDR8_BITS¶: Sub-address is 8 bits.

enumerator CYHAL_EZI2C_SUB_ADDR16_BITS¶: Sub-address is 16 bits.

enum cyhal_ezi2c_data_rate_t¶

cyhal_ezi2c_data_rate_t: Data rate of the slave.

Values:

enumerator CYHAL_EZI2C_DATA_RATE_100KHZ¶

enumerator CYHAL_EZI2C_DATA_RATE_400KHZ¶

enumerator CYHAL_EZI2C_DATA_RATE_1MHZ¶

enum cyhal_ezi2c_status_t¶

cyhal_ezi2c_status_t: Return codes of ezi2c.

Values:

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

enumerator CYHAL_EZI2C_STATUS_READ1¶: The Read transfer intended for the primary slave address is complete.

enumerator CYHAL_EZI2C_STATUS_WRITE1¶: The Write transfer intended for the primary slave address is complete.

enumerator CYHAL_EZI2C_STATUS_READ2¶: The Read transfer intended for the secondary slave address is complete.

enumerator CYHAL_EZI2C_STATUS_WRITE2¶: The Write transfer intended for the secondary slave address is complete.

enumerator CYHAL_EZI2C_STATUS_BUSY¶: A transfer intended for the primary address or secondary address is in progress.

enumerator CYHAL_EZI2C_STATUS_ERR¶: An error occurred during a transfer intended for the primary or secondary slave address.

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.

See Snippet 1: EZI2C Initialization and Configuration

Parameters

obj – [out] Pointer to an EZI2C object. The caller must allocate the memory for this object but the init function will initialize its contents.
sda – [in] The sda pin
scl – [in] The scl pin
clk – [in] The clock to use can be shared, if NULL a new clock will be allocated
cfg – [in] The ezi2c configuration (refer to cyhal_ezi2c_cfg_t for details)

Returns

The status of the init request

void cyhal_ezi2c_free(cyhal_ezi2c_t *obj)¶

Deinitialize the ezi2c object.

Parameters: obj – [inout] The ezi2c object

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: obj – [in] The EZI2C object
Returns: The status of the EZI2C (see cyhal_ezi2c_status_t for details)

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

obj – [in] The EZI2C object
callback – [in] The callback handler which will be invoked when an event triggers
callback_arg – [in] Generic argument that will be provided to the callback when called

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

obj – [in] The EZI2C object
event – [in] The EZI2C event type
intr_priority – [in] The priority for NVIC interrupt events
enable – [in] True to turn on interrupts, False to turn off

struct cyhal_ezi2c_slave_cfg_t¶

#include <>

Initial EZI2C sub configuration.

Public Members

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

struct cyhal_ezi2c_cfg_t¶

#include <>

Initial EZI2C configuration.

Public Members

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.