PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

API Reference
I3C (I3C)
PDL API Reference

## General Description

Driver API for I3C Bus Peripheral.

I3C - The Improved Inter-Integrated Circuit (I3C) bus is a MIPI industry-standard.

The functions and other declarations used in this part of the driver are in cy_i3c.h. You can also include cy_pdl.h to get access to all functions and declarations in the PDL.

The I3C peripheral driver provides an API to implement I3C in Target, Main-Controller, or Secondary-Controller roles based on the DW I3C hardware block. This I3C bus is capable of supporting I3C as well as I2C target devices as defined in the specification. I2C targets are supported with Fast-mode, and Fast-mode Plus with external 50ns spike filter as per I3C specification.

Features:

- An industry-standard I3C bus interface
- Supports target, main controller, and secondary controller operation
- SCL frequency up to 12.5MHz (SDR data rate 12.5Mbps, HDR-DDR data rate at 25Mbps)
- In controller mode, number of addressable target devices is 11
- Works in active power mode only
- Does not support I3C HDR-TSP/TSR modes
- Does not support I3C CDR (clock data recovery)
- Does not support I3C address arbitration optimizations
- Does not support I3C IBI with data
- Does not support I3C time stamping
- Does not support vendor specific CCCs
- Does not support I2C target role

# Configuration Considerations

The I3C driver configuration can be divided to number of sequential steps listed below:

- Configure i3c
- Assign and Configure Pins
- Assign Clock Divider
- Configure Data Rate
- Configure Interrupt
- Enable I3C

## Configure i3c

To set up the I3C driver, provide the configuration parameters in the cy_stc_i3c_config_t structure. Provide i3cMode to the select operation mode target, controller or secondary controller-target. To initialize the driver, call Cy_I3C_Init function providing a pointer to the populated cy_stc_i3c_config_t structure and the allocated cy_stc_i3c_context_t structure.

For I3C target setup read and write buffer before enabling its operation using Cy_I3C_TargetConfigReadBuf and Cy_I3C_TargetConfigWriteBuf appropriately. Note that the controller reads data from the target read buffer and writes data into the target write buffer.

## Assign and Configure Pins

Only dedicated pins can be used for I3C operation. The HSIOM register must be configured to connect dedicated I3C pins to the block. Also the open-drain enable pin for I3C must be configured in open-drain with internal pull up enabled (this pin configuration implies usage of external pull-up resistors)

## Assign Clock Divider

A clock source must be connected to the block to oversample input and output signals, in this document this clock will be referred as clk_i3c. You must use one of the 8-bit or 16-bit dividers. Use the SysClk (System Clock) driver API to do this.

## Configure Data Rate

To get I3C target operation with the desired data rate, the clk_i3c must be fast enough to provide sufficient oversampling. Use the SysClk (System Clock) driver API to do this.

To get I3C controller operation with the desired data rate, the source clock frequency and SCL low and high phase duration must be configured. Use the SysClk (System Clock) driver API to configure source clock frequency. Then call Cy_I3C_SetDataRate to set the SCL low, high phase duration This function sets SCL low and high phase settings based on source clock frequency.

## Configure Interrupt

The interrupt is mandatory for I3C operation. The driver provides three interrupt functions: Cy_I3C_Interrupt, Cy_I3C_TargetInterrupt, and Cy_I3C_ControllerInterrupt. One of these functions must be called in the interrupt handler for the selected instance. Call Cy_I3C_TargetInterrupt when I3C is configured to operate as a target, Cy_I3C_ControllerInterrupt when I3C is configured to operate as a controller and Cy_I3C_Interrupt when I3C is configured to operate as controller and target. Using the target- or controller-specific interrupt function allows reducing the flash consumed by the I3C driver. Also this interrupt must be enabled in the NVIC otherwise it will not work.

Note
  The I3C driver documentation refers to the Cy_I3C_Interrupt function when interrupt processing is mandatory for the operation. This is done to simplify the readability of the driver's documentation. The application should call the target- or controller-specific interrupt functions Cy_I3C_TargetInterrupt or Cy_I3C_ControllerInterrupt, when appropriate.

## Enable I3C

Finally, enable the I3C operation by calling Cy_I3C_Enable. Then I3C target starts respond to the assigned address and I3C controller ready to execute transfers.

# Common Use Cases

## Controller Operation

Call Cy_I3C_ControllerRead or Cy_I3C_ControllerWrite to communicate with the target. These functions do not block and only start a transaction. After a transaction starts, the Cy_I3C_Interrupt handles further data transaction until its completion (successfully or with error occurring). To monitor the transaction, use Cy_I3C_GetBusStatus or register callback function using Cy_I3C_RegisterEventCallback to be notified about I3C Callback Events.

## Target Operation

Target operation requires the Cy_I3C_Interrupt be called inside the interrupt handler. The read and write buffers must be provided for the target to enable communication with the controller. Use Cy_I3C_TargetConfigReadBuf and Cy_I3C_TargetConfigWriteBuf for this purpose. Note that after transaction completion the buffer must be configured again. Otherwise, the same buffer is used starting from the point where the controller stopped a previous transaction. For example: The read buffer is configured to be 10 bytes and the controller reads 8 bytes. If the read buffer is not configured again, the next controller read will start from the 9th byte. To monitor the transaction status, use Cy_I3C_GetBusStatus or use Cy_I3C_RegisterEventCallback to register a callback function to be notified about I3C Callback Events.

Note
  I3C supports only Primary Controller mode in PSE84A0. Secondary controller mode and Target mode are supported in PSE84B0.

# Low Power Support

The I3C driver provides callback functions to handle power mode transition. The callback Cy_I3C_DeepSleepCallback must be called during execution of Cy_SysPm_CpuEnterDeepSleep Cy_I3C_HibernateCallback must be called during execution of Cy_SysPm_SystemEnterHibernate. To trigger the callback execution, the callback must be registered before calling the power mode transition function. Refer to SysPm (System Power Management) driver for more information about power mode transitions and callback registration.

## API Reference
| Macros
| Enumerated Types
| Data Structures
| Functions