Normal operation¶

The following section details the software driver side of the normal operation: issuing data transfers, IBI interrupts, interrupts handling and address assignment procedure.

Data transfers¶

I3C HCI specification allows two data transfer modes: DMA and PIO. In DMA mode the driver populates DMA descriptors to the core via its registers and instructs it to execute a transfer. In PIO mode certain registers are used to access FIFO queues and the driver needs to actively read/write data from/to them.

Our implementation supports PIO mode only.

According to “6.8.1 Transfers in PIO mode” and “6.12.1 PIO Mode” sections of the HCI spec, the driver issues transfers to the core in the following manner:

• If data is to be transmitted to a device, the driver writes it to the Tx data queue by writing to the XFER_DATA_PORT register. Some commands allow providing data as the immediate payload - for those no data needs to be written to the Tx queue.

• The driver writes a command descriptor to the command queue port by writing the COMMAND_PORT register.

• The controller executes the transfer. To indicate transfer completion the core may report an interrupt.

• Once the transfer is complete, the driver reads command status from the response queue and the received data (if any) from the Rx data queue.

Collecting responses and received data:

• A response is provided by the controller to the driver in the following cases:

  • When a transfer is successful and the wroc field is set in the corresponding command descriptor.

  • When a read transfer is successful (denoted by the rnw field).

  • When a transfer generates an error (e.g. a short read request with the short_read_err field set).

• Driver can fetch the response descriptor by issuing a read from the RESPONSE_PORT register.

  • Reaching the response threshold is indicated with the RESP_READY_STAT field by the controller when RESP_READY_STAT_EN is set. A threshold interrupt is raised in accordance to RESP_BUF_THLD.

  • In case of a read request when no response is available, the controller raises an error on the frontend bus interface (AHB / AXI).

  • Upon a successful read from the RESPONSE_PORT, the driver is to decode the response in accordance to the response descriptor definition and verify the tid. The tid should match the tid of a previously enqueued command.

• Received transfer data can be obtained by the driver via a read from the XFER_DATA_PORT register.

  • Reaching the received data threshold is indicated by the controller with the TX_THLD_STAT interrupt if RX_THLD_STAT_EN is set. The RX threshold can be set via RX_BUF_THLD.

  • In case of a read when no RX data is available, the controller raises an error on the frontend bus interface (AHB / AXI).

Note that the XFER_DATA_PORT register is dual-purpose - when writing data is passed to the Tx queue, and when reading data is fetched from the Rx queue.

Section “8.4 Command Descriptor” describes in detail the format of commands for the core. Section “8.5 Response Descriptor” describes the structure of a response from the core.

Command Descriptors¶

Immediate transfer¶

Regular transfer¶

Response descriptor¶

In-band interrupts (IBI) handling¶

IBI are interrupts reported by I3C devices via in-band signaling on the bus (section “6.9.1 IBI Handling in PIO Mode”):

• When the controller receives IBI from a target device, it stores it in the IBI queue. Once the queue occupancy exceeds the threshold set by IBI_STATUS_THLD_STAT of the QUEUE_THLD_CTRL register, an interrupt is triggered.

• IBI descriptors can then be read from the IBI data queue via the IBI_PORT register.

IBI status descriptor structure is described in “8.6 IBI Status Descriptor” chapter of the spec.

Interrupts¶

Events related to transfers trigger certain interrupts in the core that are signaled to the host. Individual interrupt signals can be enabled or disabled via the PIO_INTR_SIGNAL_ENABLE register.

Interrupts status can be read from the PIO_INTR_STATUS register.

Interrupts related to Tx and Rx data queues, namely TX_THLD_SIGNAL_EN and RX_THLD_SIGNAL_EN, are triggered when queue occupancy rises above / falls below a certain threshold. These thresholds are controlled by fields of the DATA_BUFFER_THLD_CTRL register:

• RX_BUF_THLD for the receive queue,

• TX_BUF_THLD for the transmit queue.

For command, response and IBI queues the register QUEUE_THLD_CTRL defines thresholds for interrupt triggering:

• IBI_STATUS_THLD for IBI status queue,

• IBI_DATA_THLD for IBI data queue,

• RESP_BUF_THLD and CMD_EMPTY_BUF_THLD for command response queue.

There’s also the PIO_INTR_FORCE register that allows force triggering certain interrupts for debugging purposes.

Address Assignment¶

Device Management¶

Device Attach, Enumeration, and Initialization¶

The Controller assigns a dynamic address for each device on the I3C Bus. For devices with static addresses, the dynamic address is equal to the static address. Each device must have its entry in the Device Address Table (DAT) before initiating dynamic address assignment. Each DAT entry must contain a field value in either STATIC_ADDRESS (if it is known) or DYNAMIC_ADDRESS. Once the DAT table is set up, the software driver should follow at least one of the following scenarios (while keeping the order):

1. Send the SETDASA CCC to assign a static address for a chosen device or send the SETAASA CCC to assign a static address for all devices with known static address.

2. Send ENTDAA CCC to initiate the procedure of dynamic address assignment for all devices configured in DAT.

After finishing the ENTDAA process, the Device Characteristic Table (DCT) will be updated with values read from the devices configured on the I3C Bus.

The initial bus enumeration process should be performed in the following order:

1. Check sizes of DAT and DCT by reading DAT_SECTION_OFFSET and DCT_SECTION_OFFSET.

2. Set up DAT entries for devices with static addresses and send the SETDASA/SETAASA CCC.

3. Set up DAT entries for devices with dynamic addresses and send the ENTDAA CCC.

4. If any I3C device needs to change the dynamic address, send the SETNEWDA CCC to assign a new address and ensure there is no error on the bus.

In case of incorrect results of the Dynamic Addressing procedure, the software can either send the SETNEWDA CCC to the misconfigured devices or send the RSTDAA CCC to reset all dynamic addresses and then repeat the Dynamic Addressing procedure.

Hot-Join requests from I3C Target Devices should be handled automatically by the Host Controller. The driver should detect the Hot-Join IBI and populate a new entry in the DAT table.

The driver should always refer to a device entry in the DAT table to schedule a transfer. The Controller will use an appropriate address (either static or dynamic) that matches such an entry. For I2C devices, the static address will always be used.

Device Detach, Reset, and Power Management¶

Upon a device detach event, the DAT entry will not be altered. The assigned address is reserved, the software can re-use it by executing an address assignment command targeting the specific DAT entry.

If the detached device re-attaches to the bus, it will use the same DAT entry as before if it was not overwritten.

Once the new device joins the bus, it should wait for the Controller to assign a dynamic address.

Since there can be an offline capable device, it might not respond to directed commands immediately and the driver should allow devices to take time to respond, with retries and/or longer timeout.

Device Context¶

The context of a device on the bus is realized through the DAT and the DCT tables. The DCT table is transient and can be significantly smaller than the DAT, since it is only used during the address assignment procedure (ENTDAA). The software should copy contents of a DCT entry to the internal driver context, on a per-device basis.

The software can disable the Controller Role Request (CRR) and In-Band Interrupt (IBI) for each device in their respective DAT entries. If either CRR or IBI should be re-enabled, the driver should modify the CRR_REJECT/IBI_REJECT field in DAT and send the ENEC CCC to such a device.

If IBIs were disabled using the target IBI credit mechanism, and the target’s credit counter is zero, then the Host Controller will automatically re-enable IBIs for that Target using the ENEC CCC, after the software writes to that Target’s TARGET_CREDIT_N register.

Device Addressing¶

Dynamic Address Assignment with ENTDAA¶

Each I3C target device that supports the ENTDAA procedure and that has not been assigned static addresses should have assigned a dynamic address during the Dynamic Address Assignment procedure based on the DAT table entry. For each DAT entry, software should:

• Set the DEVICE field to indicate the Device’s type

• Set the DYNAMIC_ADDRESS field to indicate the Device’s preferred Dynamic Address

After DAT configuration, the software should:

1. Enqueue one or more Command Descriptors of Address Assignment Command type for the ENTDAA CCC, using the steps listed in Section 8.4.1.1

2. Wait for a response and ensure that the response descriptor indicates a successful result

3. For each successful response: read the PID, BCR and DCR values from the appropriate fields of the indicated entries in the DCT for the assigned Dynamic Address(es) as part of the ENTDAA process: A. Note that these values are transient, so software must read them and save them internally before performing subsequent Address Assignment commands with the ENTDAA CCC B. Each DCT entry for a successful assignment with the ENTDAA modal flow should have the same value in the DYNAMIC_ADDRESS field as the corresponding DYNAMIC_ADDRESS DAT entry that was used for the I3C Device to which this address was assigned

If the address assignment command completes with NACK, it means one of following:

• There are no I3C devices available to participate

• Not all devices were assigned an address, this is indicated by the DATA_LENGTH value in the response descriptor lower than the DEV_COUNT value in the command descriptor

• There were no addresses assigned to any devices (no I3C devices responded), this is indicated by the DATA_LENGTH value in the response descriptor equal to the DEV_COUNT value in the command descriptor

Using Static Addresses¶

For each I3C target device with a known address and each I2C target device, software will write this address to the STATIC_ADDRESS field of the respective DAT table entry. For each such DAT entry, the software will:

• Set the DEVICE field to indicate the Device’s type

• Set the DYNAMIC_ADDRESS field to indicate the Device’s preferred Dynamic Address

After DAT configuration, the software will:

1. For I3C devices configured with the SETDASA CCC: A. Enqueue one or more command descriptors of address assignment command type for the SETDASA CCC, using the steps listed in Section 8.4.1.2 B. Wait for a response and ensure that the response descriptor indicates a successful result

2. For those I3C Devices which will be configured with the SETAASA CCC: A. Enqueue one command descriptor of immediate data transfer command type for the SETAASA Broadcast CCC, as a standard CCC (i.e., not an address assignment command) B. Wait for a response and ensure that the response descriptor indicates a successful result

If the address assignment command for SETDASA completes with NACK, it means that the configured device is not present, or was not ready, or did not detect the SETDASA CCC on the bus.

If the address assignment command for SETAASA completes with NACK, there is no method to determine the status of any individual I3C target device that was asked to assign its own static address as dynamic address.

Grouped Addressing¶

The I3C Controller supports grouping multiple I3C target devices to manage multiple devices at a single address. Since group addresses share the same address space as valid I3C dynamic addresses, the software must avoid assigning conflicting addresses (i.e., dynamic and group addresses having the same value).

Possible operations for group management:

• The Controller may assign the I3C target device to a group address by sending a direct SETGRPA CCC addressed to a dynamic address

• The Controller may assign the I3C target device to a group address by sending a direct RSTGRPA CCC addressed to either a dynamic address or a group address

• The Controller may disband all groups by sending a broadcast RSTGRPA CCC

Each group address must have a dedicated DAT entry which can be accessed from the Controller for write-type transfers. The software should not perform read operations on group addresses.

Linux Kernel¶

• Linux driver for I3C Controller Mode

• Pending patch for adding I3C target mode support in the Linux Kernel