cy_scb_ezi2c_8h

Provides EZI2C API declarations of the SCB driver.

Version

2.80

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0
Copyright

Copyright 2016-2021 Cypress Semiconductor Corporation SPDX-License-Identifier: Apache-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Defines

CY_SCB_EZI2C_STATUS_READ1

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

The error condition status bit must be checked to ensure that the Read transfer was completed successfully.

CY_SCB_EZI2C_STATUS_WRITE1

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

The buffer content was modified. The error condition status bit must be checked to ensure that the Write transfer was completed successfully.

CY_SCB_EZI2C_STATUS_READ2

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

The error condition status bit must be checked to ensure that the Read transfer was completed successfully.

CY_SCB_EZI2C_STATUS_WRITE2

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

The buffer content was modified. The error condition status bit must be checked to ensure that the Write transfer was completed successfully.

CY_SCB_EZI2C_STATUS_BUSY

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

The status bit is set after an address match and cleared on a Stop or ReStart condition.

CY_SCB_EZI2C_STATUS_ERR

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

The sources of the error are: a misplaced Start or Stop condition or lost arbitration while the slave drives SDA. When CY_SCB_EZI2C_STATUS_ERR is set, the slave buffer may contain an invalid byte. Discard the buffer content in this case.

CY_SCB_EZI2C_DEFAULT_TX

This value is returned by the slave when the buffer is not configured or the master requests more bytes than are available in the buffer.

Enums

enum cy_en_scb_ezi2c_status_t

cy_en_scb_ezi2c_status_t: EZI2C slave status codes.

Values:

enumerator CY_SCB_EZI2C_SUCCESS

Operation completed successfully.

enumerator CY_SCB_EZI2C_BAD_PARAM

One or more of input parameters are invalid.

enum cy_en_scb_ezi2c_num_of_addr_t

cy_en_scb_ezi2c_num_of_addr_t: Number of Addresses.

Values:

enumerator CY_SCB_EZI2C_ONE_ADDRESS

Only one address.

enumerator CY_SCB_EZI2C_TWO_ADDRESSES

Two addresses.

enum cy_en_scb_ezi2c_sub_addr_size_t

cy_en_scb_ezi2c_sub_addr_size_t: Size of Sub-Address.

Values:

enumerator CY_SCB_EZI2C_SUB_ADDR8_BITS

Sub-address is 8 bits.

enumerator CY_SCB_EZI2C_SUB_ADDR16_BITS

Sub-address is 16 bits.

Functions

cy_en_scb_ezi2c_status_t Cy_SCB_EZI2C_Init(CySCB_Type *base, cy_stc_scb_ezi2c_config_t const *config, cy_stc_scb_ezi2c_context_t *context)

Initializes the SCB for the EZI2C operation.

note

Ensure that the SCB block is disabled before calling this function.

Parameters
  • base – The pointer to the EZI2C SCB instance.

  • config – The pointer to the configuration structure cy_stc_scb_ezi2c_config_t.

  • context – The pointer to the context structure cy_stc_scb_ezi2c_context_t allocated by the user. The structure is used during the EZI2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

cy_en_scb_ezi2c_status_t

void Cy_SCB_EZI2C_DeInit(CySCB_Type *base)

De-initializes the SCB block, returns the register values to default.

note

Ensure that the SCB block is disabled before calling this function.

Parameters

base – The pointer to the EZI2C SCB instance.

__STATIC_INLINE void Cy_SCB_EZI2C_Enable (CySCB_Type *base)

Enables the SCB block for the EZI2C operation.

Parameters

base – The pointer to the EZI2C SCB instance.

void Cy_SCB_EZI2C_Disable(CySCB_Type *base, cy_stc_scb_ezi2c_context_t *context)

Disables the SCB block and clears the context statuses.

Note that after the block is disabled, the TX and RX FIFOs and hardware statuses are cleared. Also, the hardware stops driving the output and ignores the input.

note

Calling this function while EZI2C is busy (the slave has been addressed and is communicating with the master), may cause transaction corruption because the hardware stops driving the output and ignores the input. Ensure that the EZI2C slave is not busy before calling this function.

Parameters
  • base – The pointer to the EZI2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_ezi2c_context_t allocated by the user. The structure is used during the EZI2C operation for internal configuration and data retention. The user must not modify anything in this structure.

void Cy_SCB_EZI2C_SetAddress1(CySCB_Type *base, uint8_t addr, cy_stc_scb_ezi2c_context_t *context)

Sets the primary EZI2C slave address.

Parameters
  • base – The pointer to the EZI2C SCB instance.

  • addr – The 7-bit right justified slave address.

  • context – The pointer to the context structure cy_stc_scb_ezi2c_context_t allocated by the user. The structure is used during the EZI2C operation for internal configuration and data retention. The user must not modify anything in this structure.

uint32_t Cy_SCB_EZI2C_GetAddress1(CySCB_Type const *base, cy_stc_scb_ezi2c_context_t const *context)

Returns the primary the EZI2C slave address.

Parameters
  • context – The pointer to the context structure cy_stc_scb_ezi2c_context_t allocated by the user. The structure is used during the EZI2C operation for internal configuration and data retention. The user must not modify anything in this structure.

  • base – The pointer to the EZI2C SCB instance.

Returns

The 7-bit right justified slave address.

void Cy_SCB_EZI2C_SetAddress2(CySCB_Type *base, uint8_t addr, cy_stc_scb_ezi2c_context_t *context)

Sets the secondary EZI2C slave address.

note

Calling this function when the EZI2C slave is configured for one-address operation leads to unexpected behavior because it updates the address mask.

Parameters
  • base – The pointer to the EZI2C SCB instance.

  • addr – The 7-bit right justified slave address.

  • context – The pointer to the context structure cy_stc_scb_ezi2c_context_t allocated by the user. The structure is used during the EZI2C operation for internal configuration and data retention. The user must not modify anything in this structure.

uint32_t Cy_SCB_EZI2C_GetAddress2(CySCB_Type const *base, cy_stc_scb_ezi2c_context_t const *context)

Returns the secondary EZI2C slave address.

Parameters
  • base – The pointer to the EZI2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_ezi2c_context_t allocated by the user. The structure is used during the EZI2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

The 7-bit right justified slave address.

void Cy_SCB_EZI2C_SetBuffer1(CySCB_Type const *base, uint8_t *buffer, uint32_t size, uint32_t rwBoundary, cy_stc_scb_ezi2c_context_t *context)

Sets up the data buffer to be exposed to the I2C master on the primary slave address request.

note

  • This function is not interrupt-protected and to prevent a race condition, it must be protected from the EZI2C interruption in the place where it is called.

  • Calling this function in the middle of a transaction intended for the secondary slave address leads to unexpected behavior.

Parameters
  • base – The pointer to the EZI2C SCB instance.

  • buffer – The pointer to the data buffer.

  • size – The size of the buffer in bytes.

  • rwBoundary – The number of data bytes starting from the beginning of the buffer with Read and Write access. The data bytes located at rwBoundary or greater are read only.

  • context – The pointer to the context structure cy_stc_scb_ezi2c_context_t allocated by the user. The structure is used during the EZI2C operation for internal configuration and data retention. The user must not modify anything in this structure.

void Cy_SCB_EZI2C_SetBuffer2(CySCB_Type const *base, uint8_t *buffer, uint32_t size, uint32_t rwBoundary, cy_stc_scb_ezi2c_context_t *context)

Sets up the data buffer to be exposed to the I2C master on the secondary slave address request.

note

  • This function is not interrupt-protected. To prevent a race condition, it must be protected from the EZI2C interruption in the place where it is called.

  • Calling this function in the middle of a transaction intended for the secondary slave address leads to unexpected behavior.

Parameters
  • base – The pointer to the EZI2C SCB instance.

  • buffer – The pointer to the data buffer.

  • size – The size of the buffer in bytes.

  • rwBoundary – The number of data bytes starting from the beginning of the buffer with Read and Write access. The data bytes located at rwBoundary or greater are read only.

  • context – The pointer to the context structure cy_stc_scb_ezi2c_context_t allocated by the user. The structure is used during the EZI2C operation for internal configuration and data retention. The user must not modify anything in this structure.

uint32_t Cy_SCB_EZI2C_GetActivity(CySCB_Type const *base, cy_stc_scb_ezi2c_context_t *context)

Returns a non-zero value if an I2C Read or Write cycle has occurred since the last time this function was called.

All flags are reset to zero at the end of this function call, except the CY_SCB_EZI2C_STATUS_BUSY.

Parameters
  • base – The pointer to the EZI2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_ezi2c_context_t allocated by the user. The structure is used during the EZI2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

EZI2C Activity Status.

void Cy_SCB_EZI2C_Interrupt(CySCB_Type *base, cy_stc_scb_ezi2c_context_t *context)

This is the interrupt function for the SCB configured in the EZI2C mode.

This function must be called inside the user-defined interrupt service routine to make the EZI2C slave work.

Parameters
  • base – The pointer to the EZI2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_ezi2c_context_t allocated by the user. The structure is used during the EZI2C operation for internal configuration and data retention. The user must not modify anything in this structure.

cy_en_syspm_status_t Cy_SCB_EZI2C_DeepSleepCallback(cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode)

This function handles the transition of the EZI2C SCB into and out of Deep Sleep mode.

It prevents the device from entering Deep Sleep mode if the EZI2C slave is actively communicating. The following behavior of the EZI2C depends on whether the SCB block is wakeup-capable:

  • Wakeup-capable: on the incoming EZI2C slave address, the slave receives the address and stretches the clock until the device is woken from Deep Sleep mode. If the slave address occurs before the device enters Deep Sleep mode, the device will not enter Deep Sleep mode.

  • Not wakeup-capable: the EZI2C is disabled. It is enabled when the device fails to enter Deep Sleep mode or it is woken from Deep Sleep mode. While the EZI2C is disabled, it stops driving the outputs and ignores the input lines. The slave NACKs all incoming addresses.

This function must be called during execution of Cy_SysPm_CpuEnterDeepSleep. To do this, register this function as a callback before calling Cy_SysPm_CpuEnterDeepSleep : specify CY_SYSPM_DEEPSLEEP as the callback type and call Cy_SysPm_RegisterCallback.

note

Only applicable for rev-08 of the CY8CKIT-062-BLE. For proper operation, when the EZI2C slave is configured to be a wakeup source from Deep Sleep mode, this function must be copied and modified by the user. The EZI2C clock disable code must be inserted in the CY_SYSPM_BEFORE_TRANSITION and clock enable code in the CY_SYSPM_AFTER_TRANSITION mode processing.

Parameters
Returns

cy_en_syspm_status_t

cy_en_syspm_status_t Cy_SCB_EZI2C_HibernateCallback(cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode)

This function handles the transition of the EZI2C SCB block into Hibernate mode.

It prevents the device from entering Hibernate mode if the EZI2C slave is actively communicating. If the EZI2C is ready to enter Hibernate mode, it is disabled. If the device fails to enter Hibernate mode, the EZI2C is enabled. While the EZI2C is disabled, it stops driving the output and ignores the inputs. The slave NACKs all incoming addresses.

This function must be called during execution of Cy_SysPm_SystemEnterHibernate. To do this, register this function as a callback before calling Cy_SysPm_SystemEnterHibernate : specify CY_SYSPM_HIBERNATE as the callback type and call Cy_SysPm_RegisterCallback.

Parameters
Returns

cy_en_syspm_status_t

struct cy_stc_scb_ezi2c_config_t
#include <>

EZI2C slave configuration structure.

Public Members

cy_en_scb_ezi2c_num_of_addr_t numberOfAddresses

The number of supported addresses either.

uint8_t slaveAddress1

The 7-bit right justified primary slave address.

uint8_t slaveAddress2

The 7-bit right justified secondary slave address.

cy_en_scb_ezi2c_sub_addr_size_t subAddressSize

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

bool enableWakeFromSleep

When set, the slave will wake the device from Deep Sleep on an address match (The device datasheet must be consulted to determine which SCBs support this mode)

struct cy_stc_scb_ezi2c_context_t
#include <>

EZI2C slave context structure.

All fields for the context structure are internal. Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.