I3C - Qualcomm Dragonwing Documentation

The Improved Inter-Integrated Circuit (I3C) interface provides a fast, low-cost, low-power, 2-wire digital interface for connected I3C devices.

I3C is supported for aDSP sensor communication only. It is not supported for Linux use cases.

Overview

Bus Characteristics

2-wire serial interface (SDA + SCL) supporting up to 12.5 MHz
Backward compatible with legacy I2C devices on the same bus
Address phase: 400 kHz
Data phase: 12.5 MHz

Advanced Features

In-band interrupt (IBI) support
Hot-join (dynamic device addition)
Synchronous timing and asynchronous timestamping
8-bit data parity during write operations
Dynamic addressing of targets
Single Data Rate (SDR) mode
CCC (Common Command Codes) per MIPI I3C specification

Data Phase Modes

Mode	Usage
Push-pull	I3C-capable devices
Open-drain	Mixed bus with I2C devices

Packet Frame Structure

Component	Description
S / Sr	Start or Repeat Start condition
I3C Dynamic Address	7-bit dynamic address assigned during enumeration
R/W	Direction bit (1=Read, 0=Write)
ACK	Acknowledge (SDA low)
Data	8-bit data payload
T	Transition bit (alternative to ACK/NACK)
P	Stop condition

Bus Initialization

Controller Initialization

The I3C controller driver initializes the controller, including firmware loading and configuration settings.

Configuration and Device Database Reading

The driver reads the I3C configuration and device database:

List of I2C static address devices
List of I3C static address devices
Expected I3C dynamic devices (vendor ID, device ID, predefined dynamic address, associated drivers)
Optional hot-join allowed devices

Device Enumeration

The driver enumerates devices on the bus and assigns local addresses.

Bus Configuration

The driver writes bus configuration to the controller:

Operation frequency
Pure/legacy I2C mode
SDR/HDR enable/disable
IBI-capable devices and expected data bytes

Client Software Configuration

Client software receives the device list and configuration for I2C/I3C devices and hot-join devices.

Software Configuration

Firmware Loading

I3C firmware for the QUP v3 serial engine loads with SSC QUP during aDSP bootup. Configuration files:

/ADSP.HT.5.5.c8/adsp_proc/core/settings/buses/qup_fw/config/<chipset>/fw_devcfg.c
/ADSP.HT.5.5.c8/adsp_proc/core/settings/buses/qup_fw/config/<chipset>/fw_devcfg.xml

Serial engine configuration example:

se_cfg se0_cfg = { 0x80000, SE_PROTOCOL_I3C, GSI, TRUE, TRUE };
se_cfg se1_cfg = { 0x84000, SE_PROTOCOL_I3C, GSI, TRUE, TRUE };

GPIO Configuration

Default GPIO configuration is set per serial engine in:

/ADSP.HT.5.5.c8/adsp_proc/core/settings/buses/qup_common/config/<chipset>/adsp/ssc/qup_instance_mapping.c

Override example:

{
  .instance_id = 1,
  .qup = QUP_SSC,
  .se_index = 0,
  .se_data = NULL,
  .protocol_io_cfg = {
    TLMM_MAP(TLMM_GPIO_KEEPER,  TLMM_GPIO_2MA, TLMM_GPIO_KEEPER),   // SLEEP
    TLMM_MAP(TLMM_GPIO_NO_PULL, TLMM_GPIO_6MA, TLMM_GPIO_KEEPER),   // SPI
    TLMM_MAP(TLMM_GPIO_NO_PULL, TLMM_GPIO_2MA, TLMM_GPIO_NO_PULL),  // UART
    TLMM_MAP(TLMM_GPIO_PULL_UP, TLMM_GPIO_2MA, TLMM_GPIO_NO_PULL),  // I2C
    TLMM_MAP(TLMM_GPIO_PULL_UP, TLMM_GPIO_2MA, TLMM_GPIO_KEEPER)    // I3C
  },
  .se_exclusive = TRUE,
}

TLMM_MAP(active_pull, drive_strength, sleep_pull) — I3C uses pull-up active, 2 mA drive, keeper sleep.

APIs

Header	Purpose
`api/buses/i2c_api.h`	I3C/I2C API
`api/buses/qup_common.h`	QUP common API

Debugging

Enable Debug Logging

mount -t debugfs none /sys/kernel/debug

echo -n "file i3c_master.c +p" > /sys/kernel/debug/dynamic_debug/control
echo -n "file qup_i3c.c +p" > /sys/kernel/debug/dynamic_debug/control
echo -n "file qup_common.c +p" > /sys/kernel/debug/dynamic_debug/control

dmesg | grep -i "i3c\|qup\|ssc"

Check Device Enumeration

ls -la /sys/bus/i3c/devices/
cat /sys/bus/i3c/devices/*/name
cat /sys/bus/i3c/devices/*/address

Check GPIO and Clocks

cat /sys/kernel/debug/pinctrl/*/pinmux-pins | grep -A 5 "i3c"
cat /sys/kernel/debug/gpio

Enable I3C Tracing

echo 1 > /sys/kernel/debug/tracing/events/i3c/enable
cat /sys/kernel/debug/tracing/trace
echo 0 > /sys/kernel/debug/tracing/events/i3c/enable

Troubleshooting

Devices Not Enumerated

Verify SDA/SCL physical connections and pull-up resistors (1–4.7 kΩ)
Check device tree for I3C node configuration
Review dmesg | grep -i i3c for enumeration errors
Confirm vendor ID and device ID match expected values

Address Phase Timing Issues (400 kHz)

Symptom: Devices not responding during enumeration.Verify SCL frequency is 400 kHz during address phase. Adjust clock divider settings in firmware configuration if needed.

Data Phase Timing Issues (12.5 MHz)

Symptom: Data corruption or read/write failures.Check bus capacitance — reduce if necessary. Verify SCL frequency is 12.5 MHz during data phase.

Hot-Join Not Working

Verify hot-join is enabled in configuration
Add device to the hot-join allowed list (vendor ID + device ID)
Check IBI configuration and device power-up sequence

Mixed I2C/I3C Bus Problems

Verify bus mode (pure vs. legacy I2C)
Check for address conflicts between I2C and I3C devices
Confirm open-drain vs. push-pull mode switching is correct

IBI (In-Band Interrupt) Not Received

Enable IBI for the specific device in configuration
Configure the correct number of expected data bytes
Verify interrupt handler registration

Signal Integrity Issues

Symptom: Intermittent communication failures.

Measure rise/fall times on SDA and SCL
Adjust pull-up resistor values
Add series termination resistors
Reduce bus length or capacitance

Common Error Codes

Error	Description	Solution
`ENXIO`	Device not found	Verify connection and enumeration
`ETIMEDOUT`	Transfer timeout	Check clock signals and device power
`EIO`	I/O error	Check signal quality and pull-ups
`EBUSY`	Resource busy	Check for bus arbitration conflicts
`EPROTO`	Protocol error	Verify timing parameters and protocol compliance

Collect Logs for Support

dmesg > i3c_dmesg.log
cat /proc/interrupts > i3c_interrupts.log
lsmod > loaded_modules.log
tar -czf i3c_debug_$(date +%Y%m%d_%H%M%S).tar.gz *.log

Resources

MIPI I3C Specification
Qualcomm Linux Interfaces Guide
QUP v3 Serial Engine Documentation

​Overview

​Bus Characteristics

​Advanced Features

​Data Phase Modes

​Packet Frame Structure

​Bus Initialization

​Software Configuration

​Firmware Loading

​GPIO Configuration

​APIs

​Debugging

​Enable Debug Logging

​Check Device Enumeration

​Check GPIO and Clocks

​Enable I3C Tracing

​Troubleshooting

​Common Error Codes

​Collect Logs for Support

​Resources

Overview

Bus Characteristics

Advanced Features

Data Phase Modes

Packet Frame Structure

Bus Initialization

Software Configuration

Firmware Loading

GPIO Configuration

APIs

Debugging

Enable Debug Logging

Check Device Enumeration

Check GPIO and Clocks

Enable I3C Tracing

Troubleshooting

Common Error Codes

Collect Logs for Support

Resources