PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

Functions
General
PDL API Reference » I3C (I3C) » Functions

## General Description

## Functions
cy_en_i3c_status_t | Cy_I3C_Init (I3C_CORE_Type *base, cy_stc_i3c_config_t const *config, cy_stc_i3c_context_t *context)
| Initializes the I3C block. More...
void | Cy_I3C_DeInit (I3C_CORE_Type *base, cy_stc_i3c_context_t *context)
| Deinitializes the I3C block. More...
void | Cy_I3C_Enable (I3C_CORE_Type *base, cy_stc_i3c_context_t *context)
| Enables the I3C block. More...
void | Cy_I3C_Disable (I3C_CORE_Type *base, cy_stc_i3c_context_t *context)
| Disables the I3C block. More...
void | Cy_I3C_Resume (I3C_CORE_Type *base, cy_stc_i3c_context_t *context)
| Resumes the I3C Controller after an error state. More...
bool | Cy_I3C_IsBusBusy (I3C_CORE_Type const *base)
| Indicates the whether the bus is busy or not. More...
bool | Cy_I3C_IsController (I3C_CORE_Type const *base)
| indicates primary controllership status. More...
cy_en_i3c_status_t | Cy_I3C_Reset (I3C_CORE_Type *base, cy_stc_i3c_config_t const *config, cy_stc_i3c_context_t *context)
| Reset for I3C. More...
cy_en_i3c_status_t | Cy_I3C_SoftReset (I3C_CORE_Type const *base)
| Soft reset for I3C. More...
cy_en_i3c_mode_t | Cy_I3C_GetMode (I3C_CORE_Type const *base)
| Provides the mode of the device. More...
void | Cy_I3C_Interrupt (I3C_CORE_Type *base, cy_stc_i3c_context_t *context)
| This is an I3C interrupt handler helper function. More...
void | Cy_I3C_RegisterEventCallback (I3C_CORE_Type const *base, cy_cb_i3c_handle_events_t callback, cy_stc_i3c_context_t *context)
| Registers an event handler callback function of type cy_cb_i3c_handle_events_t which will be invoked by the PDL to indicate i3c events and results. More...
void | Cy_I3C_RegisterIbiCallback (I3C_CORE_Type const *base, cy_cb_i3c_handle_ibi_t callback, cy_stc_i3c_context_t *context)
| Registers an IBI handler callback function of type cy_cb_i3c_handle_ibi_t which will be invoked when an IBI event is triggered on bus. More...
__STATIC_INLINE uint32_t | Cy_I3C_GetInterruptStatus (I3C_CORE_Type *base)
| Returns the interrupt request register. More...
__STATIC_INLINE void | Cy_I3C_ClearInterrupt (I3C_CORE_Type *base, uint32_t interruptMask)
| Clears the interrupt sources in the interrupt request register. More...
__STATIC_INLINE void | Cy_I3C_SetInterrupt (I3C_CORE_Type *base, uint32_t interruptMask)
| Sets interrupt sources in the interrupt request register. More...
__STATIC_INLINE uint32_t | Cy_I3C_GetInterruptMask (I3C_CORE_Type *base)
| Returns the interrupt signal enable register. More...
__STATIC_INLINE void | Cy_I3C_SetInterruptMask (I3C_CORE_Type *base, uint32_t interruptMask)
| Writes the I3C interrupt signal enable register. More...
__STATIC_INLINE uint32_t | Cy_I3C_GetInterruptStatusMask (I3C_CORE_Type *base)
| Returns the interrupt status enable register. More...
__STATIC_INLINE void | Cy_I3C_SetInterruptStatusMask (I3C_CORE_Type *base, uint32_t interruptMask)
| Writes the I3C interrupt status enable register. More...
__STATIC_INLINE void | Cy_I3C_WriteIntoDeviceAddressTable (I3C_CORE_Type *base, uint8_t index, uint32_t value)
| Writes the value into the specified location of the DAT. More...
__STATIC_INLINE uint32_t | Cy_I3C_ReadFromDeviceAddressTable (I3C_CORE_Type *base, uint8_t index)
| Returns the complete DAT entry of given index. More...
__STATIC_INLINE uint32_t | Cy_I3C_ReadDynAddrFromDAT (I3C_CORE_Type *base, uint8_t index)
| Returns the dynamic address of the I3C device stored in the DAT. More...
__STATIC_INLINE uint32_t | Cy_I3C_ReadStaticAddrFromDAT (I3C_CORE_Type *base, uint8_t index)
| Returns the static address of the I2C device stored in the DAT. More...
__STATIC_INLINE void | Cy_I3C_ReadFromDevCharTable (I3C_CORE_Type *base, uint8_t index, cy_stc_i3c_device_t *i3cDevice)
| Populates the i3c device defined by cy_stc_i3c_device_t with the DCR, BCR, PID and dynamic address information from the DCT. More...
__STATIC_INLINE void | Cy_I3C_UpdateI3CDevInList (cy_stc_i3c_device_t *i3cDevice, uint8_t pos, cy_stc_i3c_context_t *context)
| Adds the I3C device to the list of devices cy_stc_i3c_controller_devlist_t present on the bus. More...
__STATIC_INLINE void | Cy_I3C_UpdateI2CDevInList (cy_stc_i2c_device_t *i2cDevice, uint8_t pos, cy_stc_i3c_context_t *context)
| Adds the I2C device to the list of devices cy_stc_i3c_controller_devlist_t present on the bus. More...
__STATIC_INLINE uint32_t | Cy_I3C_ReadRxFIFO (I3C_CORE_Type *base)
| Reads a data element directly out of the RX FIFO. More...
__STATIC_INLINE void | Cy_I3C_WriteTxFIFO (I3C_CORE_Type *base, uint32_t data)
| Writes data directly into the TX FIFO. More...
__STATIC_INLINE uint32_t | Cy_I3C_GetFreeEntriesInTxFifo (I3C_CORE_Type *base)
| Provides the number of empty locations in the TX FIFO. More...
__STATIC_INLINE uint32_t | Cy_I3C_GetFreeEntriesInRxFifo (I3C_CORE_Type *base)
| Provides the number of empty locations in the RX FIFO. More...
__STATIC_INLINE void | Cy_I3C_SetRxFifoLevel (I3C_CORE_Type *base, uint32_t level)
| Sets the RX FIFO level. More...
__STATIC_INLINE uint32_t | Cy_I3C_GetRxFifoLevel (I3C_CORE_Type const *base)
| Returns the RX FIFO level. More...
__STATIC_INLINE void | Cy_I3C_SetTxEmptyThldLevel (I3C_CORE_Type const *base, uint32_t level)
| Sets the TX FIFO level. More...

## Function Documentation

## ◆ Cy_I3C_Init()

cy_en_i3c_status_t Cy_I3C_Init | ( | I3C_CORE_Type * | base,
|  | cy_stc_i3c_config_t const * | config,
|  | cy_stc_i3c_context_t * | context
| ) |  |

Initializes the I3C block.

Parameters

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

Returns
  cy_en_i3c_status_t

Note
  For I3C target operations pin mux IO lines to GPIO before calling this API using Cy_GPIO_SetHSIOM, and then pin mux IO lines to I3C functionality after this API call.

## ◆ Cy_I3C_DeInit()

void Cy_I3C_DeInit | ( | I3C_CORE_Type * | base,
|  | cy_stc_i3c_context_t * | context
| ) |  |

Deinitializes the I3C block.

Parameters

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

## ◆ Cy_I3C_Enable()

void Cy_I3C_Enable | ( | I3C_CORE_Type * | base,
|  | cy_stc_i3c_context_t * | context
| ) |  |

Enables the I3C block.

Parameters

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

## ◆ Cy_I3C_Disable()

void Cy_I3C_Disable | ( | I3C_CORE_Type * | base,
|  | cy_stc_i3c_context_t * | context
| ) |  |

Disables the I3C block.

Parameters

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

Note
  The I3C controller will complete any pending bus transaction before it gets disabled.

## ◆ Cy_I3C_Resume()

void Cy_I3C_Resume | ( | I3C_CORE_Type * | base,
|  | cy_stc_i3c_context_t * | context
| ) |  |

Resumes the I3C Controller after an error state.

Parameters

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

Note
  When the controller enters any error condition it pauses all operation until user resumes manually. User must call this API once error status is returned for any I3C bus transactions like Read/Write or other operations.

## ◆ Cy_I3C_IsBusBusy()

bool Cy_I3C_IsBusBusy | ( | I3C_CORE_Type const * | base | ) |

Indicates the whether the bus is busy or not.

Parameters

  base | The pointer to the I3C instance.

Returns
  true: if bus is BUSY. false: if bus is IDLE.

## ◆ Cy_I3C_IsController()

bool Cy_I3C_IsController | ( | I3C_CORE_Type const * | base | ) |

indicates primary controllership status.

Parameters

  base | The pointer to the I3C instance.

Returns
  true: if IP is current active controller. false: otherwise.

## ◆ Cy_I3C_Reset()

cy_en_i3c_status_t Cy_I3C_Reset | ( | I3C_CORE_Type * | base,
|  | cy_stc_i3c_config_t const * | config,
|  | cy_stc_i3c_context_t * | context
| ) |  |

Reset for I3C.

It resets complete I3C peripheral while retaining assigned dynamic address in target mode.

Parameters

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

Returns
  reset successful status - CY_I3C_TIMEOUT / CY_I3C_SUCCESS.

Note
  After calling Cy_I3C_Reset, I3C target needs few SCL clock cycle to come out of reset state. This may cause first transaction after reset to be NACKed.

## ◆ Cy_I3C_SoftReset()

cy_en_i3c_status_t Cy_I3C_SoftReset | ( | I3C_CORE_Type const * | base | ) |

Soft reset for I3C.

It resets all buffers: Transmit, Receive, command, Response.

Parameters

  base | The pointer to the I3C instance.

Returns
  reset successful status - CY_I3C_TIMEOUT / CY_I3C_SUCCESS.

## ◆ Cy_I3C_GetMode()

cy_en_i3c_mode_t Cy_I3C_GetMode | ( | I3C_CORE_Type const * | base | ) |

Provides the mode of the device.

Parameters

  base | The pointer to the I3C instance.

Returns
  cy_en_i3c_mode_t

## ◆ Cy_I3C_Interrupt()

void Cy_I3C_Interrupt | ( | I3C_CORE_Type * | base,
|  | cy_stc_i3c_context_t * | context
| ) |  |

This is an I3C interrupt handler helper function.

This function must be called inside the user-defined interrupt service.

Parameters

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

## ◆ Cy_I3C_RegisterEventCallback()

void Cy_I3C_RegisterEventCallback | ( | I3C_CORE_Type const * | base,
|  | cy_cb_i3c_handle_events_t | callback,
|  | cy_stc_i3c_context_t * | context
| ) |  |

Registers an event handler callback function of type cy_cb_i3c_handle_events_t which will be invoked by the PDL to indicate i3c events and results.

Parameters

  base | The pointer to the I3C instance.
  callback | The pointer to a callback function. See cy_cb_i3c_handle_events_t for the function prototype.
  context | The pointer to the context structure cy_stc_i3c_context_t allocated by the user. The structure is used during the I3C operation for internal configuration and data retention. The user must not modify anything in this structure.

Note
  To remove the callback, pass NULL as the pointer to the callback function.

## ◆ Cy_I3C_RegisterIbiCallback()

void Cy_I3C_RegisterIbiCallback | ( | I3C_CORE_Type const * | base,
|  | cy_cb_i3c_handle_ibi_t | callback,
|  | cy_stc_i3c_context_t * | context
| ) |  |

Registers an IBI handler callback function of type cy_cb_i3c_handle_ibi_t which will be invoked when an IBI event is triggered on bus.

Parameters

  base | The pointer to the I3C instance.
  callback | The pointer to a callback function. See cy_cb_i3c_handle_events_t for the function prototype.
  context | The pointer to the context structure cy_stc_i3c_context_t allocated by the user. The structure is used during the I3C operation for internal configuration and data retention. The user must not modify anything in this structure.

Note
  To remove the callback, pass NULL as the pointer to the callback function.

## ◆ Cy_I3C_GetInterruptStatus()

__STATIC_INLINE uint32_t Cy_I3C_GetInterruptStatus | ( | I3C_CORE_Type * | base | ) |

Returns the interrupt request register.

This register contains the current status of the interrupt sources.

Parameters

  base | The pointer to the I3C instance.

Returns
  The current status of the interrupt sources. Each constant is a bit field value. The value returned may have multiple bits set to indicate the current status.

## ◆ Cy_I3C_ClearInterrupt()

__STATIC_INLINE void Cy_I3C_ClearInterrupt | ( | I3C_CORE_Type * | base,
|  | uint32_t | interruptMask
| ) |  |

Clears the interrupt sources in the interrupt request register.

Parameters

  base | The pointer to the I3C instance.
  interruptMask | Interrupt sources to be cleared.

## ◆ Cy_I3C_SetInterrupt()

__STATIC_INLINE void Cy_I3C_SetInterrupt | ( | I3C_CORE_Type * | base,
|  | uint32_t | interruptMask
| ) |  |

Sets interrupt sources in the interrupt request register.

Parameters

  base | The pointer to the I3C instance.
  interruptMask | The interrupt sources to set in the interrupt request register.

## ◆ Cy_I3C_GetInterruptMask()

__STATIC_INLINE uint32_t Cy_I3C_GetInterruptMask | ( | I3C_CORE_Type * | base | ) |

Returns the interrupt signal enable register.

This register specifies which bits from the interrupt request register can trigger an interrupt event.

Parameters

  base | The pointer to the I3C instance.

Returns
  Enabled interrupt sources.

## ◆ Cy_I3C_SetInterruptMask()

__STATIC_INLINE void Cy_I3C_SetInterruptMask | ( | I3C_CORE_Type * | base,
|  | uint32_t | interruptMask
| ) |  |

Writes the I3C interrupt signal enable register.

This register specifies which bits from the I3C interrupt request register can trigger an interrupt event.

Parameters

  base | The pointer to the I3C instance.
  interruptMask | Enabled interrupt sources.

## ◆ Cy_I3C_GetInterruptStatusMask()

__STATIC_INLINE uint32_t Cy_I3C_GetInterruptStatusMask | ( | I3C_CORE_Type * | base | ) |

Returns the interrupt status enable register.

This register specifies which bits from the interrupt request register can generate interrupt.

Parameters

  base | The pointer to the I3C instance.

Returns
  Enabled interrupt sources.

## ◆ Cy_I3C_SetInterruptStatusMask()

__STATIC_INLINE void Cy_I3C_SetInterruptStatusMask | ( | I3C_CORE_Type * | base,
|  | uint32_t | interruptMask
| ) |  |

Writes the I3C interrupt status enable register.

This register specifies which bits from the I3C interrupt request register can trigger an interrupt event.

Parameters

  base | The pointer to the I3C instance.
  interruptMask | Enabled I3C interrupt sources.

## ◆ Cy_I3C_WriteIntoDeviceAddressTable()

__STATIC_INLINE void Cy_I3C_WriteIntoDeviceAddressTable | ( | I3C_CORE_Type * | base,
|  | uint8_t | index,
|  | uint32_t | value
| ) |  |

Writes the value into the specified location of the DAT.

Parameters

  base | The pointer to the I3C instance.
  index | The offset from the base of the DAT.
  value | The value to be written at the specified location in the DAT.

## ◆ Cy_I3C_ReadFromDeviceAddressTable()

__STATIC_INLINE uint32_t Cy_I3C_ReadFromDeviceAddressTable | ( | I3C_CORE_Type * | base,
|  | uint8_t | index
| ) |  |

Returns the complete DAT entry of given index.

Parameters

  base | The pointer to the I3C instance.
  index | The offset from the base of the DAT.

Returns
  The dynamic address of the I3C device.

## ◆ Cy_I3C_ReadDynAddrFromDAT()

__STATIC_INLINE uint32_t Cy_I3C_ReadDynAddrFromDAT | ( | I3C_CORE_Type * | base,
|  | uint8_t | index
| ) |  |

Returns the dynamic address of the I3C device stored in the DAT.

Parameters

  base | The pointer to the I3C instance.
  index | The offset from the base of the DAT.

Returns
  The dynamic address of the I3C device.

## ◆ Cy_I3C_ReadStaticAddrFromDAT()

__STATIC_INLINE uint32_t Cy_I3C_ReadStaticAddrFromDAT | ( | I3C_CORE_Type * | base,
|  | uint8_t | index
| ) |  |

Returns the static address of the I2C device stored in the DAT.

Parameters

  base | The pointer to the I3C instance.
  index | The offset from the base of the DAT.

Returns
  The static address of the I2C device.

## ◆ Cy_I3C_ReadFromDevCharTable()

__STATIC_INLINE void Cy_I3C_ReadFromDevCharTable | ( | I3C_CORE_Type * | base,
|  | uint8_t | index,
|  | cy_stc_i3c_device_t * | i3cDevice
| ) |  |

Populates the i3c device defined by cy_stc_i3c_device_t with the DCR, BCR, PID and dynamic address information from the DCT.

Parameters

  base | The pointer to the I3C instance.
  index | The offset from the base of the DAT.
  i3cDevice | The pointer to the i3c device description structure cy_stc_i3c_device_t.

## ◆ Cy_I3C_UpdateI3CDevInList()

__STATIC_INLINE void Cy_I3C_UpdateI3CDevInList | ( | cy_stc_i3c_device_t * | i3cDevice,
|  | uint8_t | pos,
|  | cy_stc_i3c_context_t * | context
| ) |  |

Adds the I3C device to the list of devices cy_stc_i3c_controller_devlist_t present on the bus.

Parameters

  i3cDevice | The pointer to the I3C device description structure cy_stc_i3c_device_t.
  pos | The position of the device in the list cy_stc_i3c_controller_devlist_t.
  context | The pointer to the context structure cy_stc_i3c_context_t allocated by the user. The structure is used during the I3C operation for internal configuration and data retention. The user must not modify anything in this structure.

## ◆ Cy_I3C_UpdateI2CDevInList()

__STATIC_INLINE void Cy_I3C_UpdateI2CDevInList | ( | cy_stc_i2c_device_t * | i2cDevice,
|  | uint8_t | pos,
|  | cy_stc_i3c_context_t * | context
| ) |  |

Adds the I2C device to the list of devices cy_stc_i3c_controller_devlist_t present on the bus.

Parameters

  i2cDevice | The pointer to the I2C device description structure cy_stc_i2c_device_t.
  pos | The position of the device in the list cy_stc_i3c_controller_devlist_t.
  context | The pointer to the context structure cy_stc_i3c_context_t allocated by the user. The structure is used during the I3C operation for internal configuration and data retention. The user must not modify anything in this structure.

## ◆ Cy_I3C_ReadRxFIFO()

__STATIC_INLINE uint32_t Cy_I3C_ReadRxFIFO | ( | I3C_CORE_Type * | base | ) |

Reads a data element directly out of the RX FIFO.

This function does not check whether the RX FIFO has data before reading it.

Parameters

  base | The pointer to the I3C instance.

Returns
  Data from RX FIFO.

## ◆ Cy_I3C_WriteTxFIFO()

__STATIC_INLINE void Cy_I3C_WriteTxFIFO | ( | I3C_CORE_Type * | base,
|  | uint32_t | data
| ) |  |

Writes data directly into the TX FIFO.

This function does not check whether the TX FIFO is not full before writing into it.

Parameters

  base | The pointer to the I3C instance.
  data | Data to write to the TX FIFO.

## ◆ Cy_I3C_GetFreeEntriesInTxFifo()

__STATIC_INLINE uint32_t Cy_I3C_GetFreeEntriesInTxFifo | ( | I3C_CORE_Type * | base | ) |

Provides the number of empty locations in the TX FIFO.

Parameters

  base | The pointer to the I3C instance.

Returns
  Transmit buffer empty level value.

## ◆ Cy_I3C_GetFreeEntriesInRxFifo()

__STATIC_INLINE uint32_t Cy_I3C_GetFreeEntriesInRxFifo | ( | I3C_CORE_Type * | base | ) |

Provides the number of empty locations in the RX FIFO.

Parameters

  base | The pointer to the I3C instance.

Returns
  Receive buffer empty level value.

## ◆ Cy_I3C_SetRxFifoLevel()

__STATIC_INLINE void Cy_I3C_SetRxFifoLevel | ( | I3C_CORE_Type * | base,
|  | uint32_t | level
| ) |  |

Sets the RX FIFO level.

When there are more data elements in the RX FIFO than this level, the RX FIFO level interrupt is triggered.

Parameters

  base | The pointer to the I3C instance.
  level | When there are more data elements in the FIFO than this level, the RX level interrupt is triggered.

## ◆ Cy_I3C_GetRxFifoLevel()

__STATIC_INLINE uint32_t Cy_I3C_GetRxFifoLevel | ( | I3C_CORE_Type const * | base | ) |

Returns the RX FIFO level.

When there are more words in the RX FIFO than the threshold level, the RX FIFO level interrupt is triggered.

Parameters

  base | The pointer to the I3C instance.

Returns
  RX FIFO level.

## ◆ Cy_I3C_SetTxEmptyThldLevel()

__STATIC_INLINE void Cy_I3C_SetTxEmptyThldLevel | ( | I3C_CORE_Type const * | base,
|  | uint32_t | level
| ) |  |

Sets the TX FIFO level.

When the number of empty locations in the TX FIFO is greater than this level, the TX FIFO level interrupt is triggered.

Parameters

  base | The pointer to the I3C instance.
  level | When there are more empty locations in the TX FIFO than this level, the TX level interrupt is triggered.