PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

Functions
Master High-Level
PDL API Reference » SCB (Serial Communication Block) » I2C (SCB) » Functions

## General Description

## Functions
cy_en_scb_i2c_status_t | Cy_SCB_I2C_MasterWrite (CySCB_Type *base, cy_stc_scb_i2c_master_xfer_config_t *xferConfig, cy_stc_scb_i2c_context_t *context)
| This function configures the master to automatically write an entire buffer of data to a slave device. More...
void | Cy_SCB_I2C_MasterAbortWrite (CySCB_Type *base, cy_stc_scb_i2c_context_t *context)
| This function requests the master to abort write operation by generating a Stop condition. More...
cy_en_scb_i2c_status_t | Cy_SCB_I2C_MasterRead (CySCB_Type *base, cy_stc_scb_i2c_master_xfer_config_t *xferConfig, cy_stc_scb_i2c_context_t *context)
| This function configures the master to automatically read an entire buffer of data from the slave device. More...
void | Cy_SCB_I2C_MasterAbortRead (CySCB_Type *base, cy_stc_scb_i2c_context_t *context)
| This function requests master to abort read operation by NAKing the next byte and generating a Stop condition. More...
uint32_t | Cy_SCB_I2C_MasterGetStatus (CySCB_Type const *base, cy_stc_scb_i2c_context_t const *context)
| Returns the current I2C master status. More...
uint32_t | Cy_SCB_I2C_MasterGetTransferCount (CySCB_Type const *base, cy_stc_scb_i2c_context_t const *context)
| Returns the number of bytes transferred since the last call of Cy_SCB_I2C_MasterWrite or Cy_SCB_I2C_MasterRead function. More...

## Function Documentation

## ◆ Cy_SCB_I2C_MasterWrite()

cy_en_scb_i2c_status_t Cy_SCB_I2C_MasterWrite | ( | CySCB_Type * | base,
|  | cy_stc_scb_i2c_master_xfer_config_t * | xferConfig,
|  | cy_stc_scb_i2c_context_t * | context
| ) |  |

This function configures the master to automatically write an entire buffer of data to a slave device.

After the transaction is initiated by this function it returns and Cy_SCB_I2C_Interrupt manages further data transfer.

When a write transaction is completed (requested number of bytes are written or error occurred) the CY_SCB_I2C_MASTER_BUSY status is cleared and the CY_SCB_I2C_MASTER_WR_CMPLT_EVENT event is generated.

Parameters

  base | The pointer to the I2C SCB instance.
  xferConfig | Master transfer configuration structure cy_stc_scb_i2c_master_xfer_config_t.
  context | The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns
  cy_en_scb_i2c_status_t

Note
  - The buffer must not be modified and must stay allocated until data has been copied into the TX FIFO.
  - Cy_SCB_I2C_MasterWrite requests the SCB hardware to generate a start condition when there is no pending transfer and returns (does not wait until hardware generate a start condition). If the I2C bus is busy the hardware will not generate the until bus becomes free. The SCB hardware sets the busy status after the Start detection, and clears it on the Stop detection. Noise caused by the ESD or other events may cause an erroneous Start condition on the bus. Then, the master will never generate a Start condition because the hardware assumes the bus is busy. If this occurs, the Cy_SCB_I2C_MasterGetStatus returns CY_SCB_I2C_MASTER_BUSY status and the transaction will never finish. The option is to implement a timeout to detect the transfer completion. If the transfer never completes, the SCB needs a reset by calling the Cy_SCB_I2C_Disable and Cy_SCB_I2C_Enable functions. The Cy_SCB_I2C_MasterAbortWrite function will not work, the block must be reset.

## ◆ Cy_SCB_I2C_MasterAbortWrite()

void Cy_SCB_I2C_MasterAbortWrite | ( | CySCB_Type * | base,
|  | cy_stc_scb_i2c_context_t * | context
| ) |  |

This function requests the master to abort write operation by generating a Stop condition.

The function does not wait until this action is completed. Therefore next write operation can be initiated only after the CY_SCB_I2C_MASTER_BUSY is cleared.

Parameters

  base | The pointer to the I2C SCB instance.
  context | The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Side Effects
  If the TX FIFO is used, it is cleared before Stop generation. The TX FIFO clear operation also clears shift register. Thus, the shifter could be cleared in the middle of a data element transfer, corrupting it. The remaining bits to transfer within corrupted data element are complemented with ones.
  If the clear operation is requested while the master transmits the address, the direction of transaction is changed to read and one byte is read before Stop is issued. This byte is discarded.

## ◆ Cy_SCB_I2C_MasterRead()

cy_en_scb_i2c_status_t Cy_SCB_I2C_MasterRead | ( | CySCB_Type * | base,
|  | cy_stc_scb_i2c_master_xfer_config_t * | xferConfig,
|  | cy_stc_scb_i2c_context_t * | context
| ) |  |

This function configures the master to automatically read an entire buffer of data from the slave device.

After the transaction is initiated by this function it returns and Cy_SCB_I2C_Interrupt manages further data transfer.

When a read transaction is completed (requested number of bytes are read or error occurred) the CY_SCB_I2C_MASTER_BUSY status is cleared and the CY_SCB_I2C_MASTER_RD_CMPLT_EVENT event is generated.

Note that the master must read at least one byte.

Parameters

  base | The pointer to the I2C SCB instance.
  xferConfig | Master transfer configuration structure cy_stc_scb_i2c_master_xfer_config_t.
  context | The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns
  cy_en_scb_i2c_status_t

Note
  - The buffer must not be modified and must stay allocated until read operation completion.
  - Cy_SCB_I2C_MasterRead requests the SCB hardware to generate a start condition when there is no pending transfer and returns (does not wait until hardware generate a start condition). If the I2C bus is busy the hardware will not generate the until bus becomes free. The SCB hardware sets the busy status after the Start detection, and clears it on the Stop detection. Noise caused by the ESD or other events may cause an erroneous Start condition on the bus. Then, the master will never generate a Start condition because the hardware assumes the bus is busy. If this occurs, the Cy_SCB_I2C_MasterGetStatus returns CY_SCB_I2C_MASTER_BUSY status and the transaction will never finish. The option is to implement a timeout to detect the transfer completion. If the transfer never completes, the SCB needs a reset by calling the Cy_SCB_I2C_Disable and Cy_SCB_I2C_Enable functions. The Cy_SCB_I2C_MasterAbortRead function will not work, the block must be reset.

## ◆ Cy_SCB_I2C_MasterAbortRead()

void Cy_SCB_I2C_MasterAbortRead | ( | CySCB_Type * | base,
|  | cy_stc_scb_i2c_context_t * | context
| ) |  |

This function requests master to abort read operation by NAKing the next byte and generating a Stop condition.

The function does not wait until these actions are completed. Therefore the next operation can be initiated only after the CY_SCB_I2C_MASTER_BUSY is cleared.

Parameters

  base | The pointer to the I2C SCB instance.
  context | The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

## ◆ Cy_SCB_I2C_MasterGetStatus()

uint32_t Cy_SCB_I2C_MasterGetStatus | ( | CySCB_Type const * | base,
|  | cy_stc_scb_i2c_context_t const * | context
| ) |  |

Returns the current I2C master status.

This status is a bit mask and the value returned may have multiple bits set.

Parameters

  base | The pointer to the I2C SCB instance.
  context | The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns
  I2C Master Status. Note that not all I2C master statuses are returned by this function. Refer to more details of each status.

Note
  Status is cleared by calling Cy_SCB_I2C_MasterRead or Cy_SCB_I2C_MasterWrite.

## ◆ Cy_SCB_I2C_MasterGetTransferCount()

uint32_t Cy_SCB_I2C_MasterGetTransferCount | ( | CySCB_Type const * | base,
|  | cy_stc_scb_i2c_context_t const * | context
| ) |  |

Returns the number of bytes transferred since the last call of Cy_SCB_I2C_MasterWrite or Cy_SCB_I2C_MasterRead function.

Parameters

  base | The pointer to the I2C SCB instance.
  context | The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns
  Number of bytes read or written by the master.

Note
  - This function returns an invalid value if read or write transaction was aborted or any listed event occurs during the transaction: CY_SCB_I2C_MASTER_ARB_LOST, CY_SCB_I2C_MASTER_BUS_ERR or CY_SCB_I2C_MASTER_ABORT_START.
  - This number is updated only when the transaction completes, either through an error or successfully.