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

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


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

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

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

enum 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

enum 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]	obj	Pointer to an EZI2C object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]	sda	The sda pin
[in]	scl	The scl pin
[in]	clk	The clock to use can be shared, if NULL a new clock will be allocated
[in]	cfg	The 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]

obj

The 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]

obj

The 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]	obj	The EZI2C object
[in]	callback	The callback handler which will be invoked when an event triggers
[in]	callback_arg	Generic 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]	obj	The EZI2C object
[in]	event	The EZI2C event type
[in]	intr_priority	The priority for NVIC interrupt events
[in]	enable	True 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]	obj	The EZI2C peripheral to configure
[in]	cfg	Configuration structure generated by a configurator.
[in]	slave1_cfg	Primary slave address configuration
[in]	slave2_cfg	Secondary slave address configuration (can be NULL)

Returns

The status of the operation