Getting started: Set up the device interface - Qualcomm Dragonwing Documentation

Before you begin, set up your infrastructure as described in the Qualcomm Linux Build Guide.

Figure : Interface workflow

Identify the interface status

The default interface status indicates the status of the interfaces during bootup. To identify the interface status, successfully register the interfaces and obtain the list of enabled interfaces.

Obtain the bootup logs

To obtain the bootup logs of the device, do the following:

Open the SSH shell in permissive mode or use the ADB shell. For more information about how to run SSH, see the Use SSH section.

Obtain the logs of the enabled interfaces by running the following command.

dmesg

Output:

 
[    0.434365] msm_serial: driver initialized
[    0.799123] 994000.serial: ttyMSM0 at MMIO 0x994000 (irq = 139, base_baud = 0) is a MSM
[    0.801937] 99c000.serial: ttyHS1 at MMIO 0x99c000 (irq = 140, base_baud = 0) is a MSM
[    0.804563] serial serial0: tty port ttyHS1 registered
 
[ 0.720945] usbhub_rest_vreg GPIO handle specifies active low - ignored
[    0.815241] dwc3-qcom 8c00000.usb: Adding to iommu group 4
[    5.195974] dwc3-qcom a600000.usb: Adding to iommu group 18
[    5.229464] qcom_pmic_glink pmic-glink: Failed to create device link (0x180) with a600000.usb
[    6.195825] usb usb2: We don't know the algorithms for LPM for this host, disabling LPM.
[    6.450338] usb 1-1: new high-speed USB device number 2 using xhci_hcd
[    6.664583] usbcore: registered new device driver onboard-usb-hub
[    6.730998] usb 2-1: new SuperSpeed USB device number 2 using xhci_hcd
[    7.083668] usb 2-1.1: new SuperSpeed USB device number 3 using xhci_hcd
[    7.217287] ax88179_178a 2-1.1:1.0 eth0: register 'ax88179_178a' at usb-0001:04:00.0-1.1, ASIX AX88179 USB 3.0 Gigabit Ethernet, 02:fe:ee:05:44:23
[    7.217415] usbcore: registered new interface driver ax88179_178a
[   10.223140] dwc3-qcom a600000.usb: request 0000000000000000 was not queued to ep0ou

Connect the UART serial port to log in to the console.

List enabled interfaces on devices

To obtain the list of the enabled interfaces, do the following:

For UART, run the following command.

ls /dev/tty*

Output:

/dev/tty    /dev/tty21 /dev/tty35  /dev/tty49  /dev/tty62   /dev/ttyp4
/dev/tty0   /dev/tty22 /dev/tty36  /dev/tty5   /dev/tty63   /dev/ttyp5
/dev/tty1   /dev/tty23 /dev/tty37  /dev/tty50  /dev/tty7    /dev/ttyp6
/dev/tty10  /dev/tty24 /dev/tty38  /dev/tty51  /dev/tty8    /dev/ttyp7
/dev/tty11  /dev/tty25 /dev/tty39  /dev/tty52  /dev/tty9    /dev/ttyp8
/dev/tty12  /dev/tty26 /dev/tty4   /dev/tty53  /dev/ttyMSM0 /dev/ttyp9
/dev/tty13  /dev/tty27 /dev/tty40  /dev/tty54  /dev/ttyS0   /dev/ttypa
/dev/tty14  /dev/tty28 /dev/tty41  /dev/tty55  /dev/ttyS1   /dev/ttypb
/dev/tty15  /dev/tty29 /dev/tty42  /dev/tty56  /dev/ttyS2   /dev/ttypc
/dev/tty16  /dev/tty3  /dev/tty43  /dev/tty57  /dev/ttyS3   /dev/ttypd
/dev/tty17  /dev/tty30 /dev/tty44  /dev/tty58  /dev/ttynull /dev/ttype
/dev/tty18  /dev/tty31 /dev/tty45  /dev/tty59  /dev/ttyp0   /dev/ttypf
/dev/tty19  /dev/tty32 /dev/tty46  /dev/tty6   /dev/ttyp1
/dev/tty2   /dev/tty33 /dev/tty47  /dev/tty60  /dev/ttyp2
/dev/tty20  /dev/tty34 /dev/tty48  /dev/tty61  /dev/ttyp3

For I2C, run the following command.
ls /dev/i2c*
The following output is displayed.
/dev/i2c-0 /dev/i2c-1 /dev/i2c-16
By default, SPI isn’t enabled. To enable SPI, see SPI software device tree configuration. To verify if SPI is enabled, run the following command.
ls /dev/spi*
The following output is displayed.
spidev14.0
For PCIe, obtain the enumeration log. For more information about PCIe probe logs, see PCIe-related configurations and QPS615 switch support.

Load QUP v3 serial engine firmware using Linux kernel

This document explains the QUP v3 serial engine firmware loading mechanism using the Linux kernel. It describes the transition from a TrustZone-based architecture—which had fixed protocol assignments and limited flexibility—to a Linux-based approach that enables dynamic protocol assignment, easier debugging, and simplified development through device tree configuration. QUP v3 contains multiple serial engines that can be configured as follows:

I2C
SPI
UART

Default configuration

The default configuration for each serial engine, including the selected mode of data transmission and ownership, is in the _/TZ.XF.5.0/core.tz/2.0/settings/buses/qup\_accesscontrol/qupv3/config/lemans/QUPAC\_Access.c_ file. In the default configuration, Linux owns all the serial engines.

const QUPv3_se_security_permissions_type qupv3_perms_default =
{
  /*   PeriphID,         ProtocolID,               Mode,      NsOwner,         bAllowFifo, bLoad, bModExcl  */
  /*QUPV3_0_SE0*/
  /*QUPV3_0_SE1*/
  /*QUPV3_0_SE2*/
  { QUPV3_0_SE3, QUPV3_PROTOCOL_UART_4W,   QUPV3_MODE_FIFO,   AC_HLOS,            TRUE,  TRUE, FALSE }, // BT UART (2nd Hastings)
  { QUPV3_0_SE4, QUPV3_PROTOCOL_UART_2W,   QUPV3_MODE_FIFO,   AC_HLOS,            TRUE,  TRUE, FALSE }, // VIP UART/SPI (SOC SLAVE)
  /*QUPV3_0_SE5*/                                                                                       // Spare
  { QUPV3_1_SE0, QUPV3_PROTOCOL_I2C,       QUPV3_MODE_FIFO,   AC_HLOS,            TRUE,  TRUE, FALSE }, // I2C Carplay
  /*QUPV3_1_SE1*/
  { QUPV3_1_SE2, QUPV3_PROTOCOL_UART_2W,   QUPV3_MODE_FIFO,   AC_HLOS,            TRUE,  TRUE, FALSE }, // Tuner
  { QUPV3_1_SE3, QUPV3_PROTOCOL_UART_2W,   QUPV3_MODE_FIFO,   AC_HLOS,            TRUE, FALSE, FALSE }, // Debug UART
  { QUPV3_1_SE4, QUPV3_PROTOCOL_I2C,       QUPV3_MODE_FIFO,   AC_HLOS,            TRUE,  TRUE, FALSE }, // I2C A2B Controller & Audio port expander
  { QUPV3_1_SE5, QUPV3_PROTOCOL_UART_2W,   QUPV3_MODE_FIFO,   AC_HLOS,            TRUE,  TRUE, FALSE }, // GNSS
  /*QUPV3_1_SE6*/
  { QUPV3_2_SE0, QUPV3_PROTOCOL_SPI,       QUPV3_MODE_FIFO,   AC_HLOS,            TRUE,  TRUE, FALSE }, // FPGA
  { QUPV3_2_SE1, QUPV3_PROTOCOL_I2C,       QUPV3_MODE_FIFO,   AC_HLOS,            TRUE,  TRUE, FALSE }, // PCIe I2C MUX
  { QUPV3_2_SE2, QUPV3_PROTOCOL_SPI,       QUPV3_MODE_FIFO,   AC_HLOS,            TRUE,  TRUE, FALSE }, // SPI - Audio
  { QUPV3_2_SE3, QUPV3_PROTOCOL_UART_4W,   QUPV3_MODE_FIFO,   AC_HLOS,            TRUE,  TRUE, FALSE }, // BT UART
  { QUPV3_2_SE4, QUPV3_PROTOCOL_I2C,       QUPV3_MODE_FIFO,   AC_HLOS,            TRUE,  TRUE, FALSE }, // I2C Display 1
  { QUPV3_2_SE5, QUPV3_PROTOCOL_I2C,       QUPV3_MODE_FIFO,   AC_HLOS,            TRUE,  TRUE, FALSE }, // I2C Sensor
  /*QUPV3_2_SE6 */
  { QUPV3_3_SE0,  QUPV3_PROTOCOL_SPI,       QUPV3_MODE_FIFO,   AC_HLOS,           TRUE,  FALSE, FALSE }, // SPI
};

Load firmware

The firmware files are at /lib/firmware/qcom/<target-name>/qupv3fw.elf.

Identify available serial engines by checking the platform device tree for serial engine nodes. Serial engine names and numbering vary by platform. Use the node labels defined by the platform; for example:
grep -r -E "&(i2c|spi|uart)[0-9]+" arch/arm64/boot/dts/qcom/
NoteYou can choose the required protocol based on your interface requirements.
- I2C: Sensors, EEPROMs, PMICs
- SPI: Displays, flash memory, ADCs
- UART: Console, GPS, Bluetooth

Configure device tree by adding or modifying serial engine nodes to the device tree file.

Sample I2C configuration:

&i2c5 {
    status = "okay";
    clock-frequency = <400000>; /* 400 KHz */
    sensor@48 {
        compatible = "vendor,sensor";
        reg = <0x48>;
    };
};

Sample SPI configuration:

&spi6 {
    status = "okay";
    spi-max-frequency = <50000000>; /* 50 MHz */
    flash@0 {
        compatible = "vendor,spi-flash";
        reg = <0>;
        spi-max-frequency = <25000000>;
    };
};

Sample UART configuration:

&uart7 {
    status = "okay";
    /delete-property/ interrupts;
    interrupts-extended = <&intc GIC_SPI 608 IRQ_TYPE_LEVEL_HIGH>;
};

Optional: Enable GSI DMA for high-throughput devices.

qcom,enable-gsi-dma;

Switch the serial engine protocol. For example, I2C to SPI.

Original I2C configuration:

&i2c5 {
    status = "okay";
    sensor@48 {
        compatible = "vendor,sensor";
        reg = <0x48>;
    };
};

New configuration (SPI)

/* Disable I2C5 */
&i2c5 {
    status = "disabled";
};

/* Enable SPI5 */
&spi5 {
    status = "okay";

    flash@0 {
        compatible = "vendor,flash";
        reg = <0>;
    };
};

Disable the original I2C node before enabling SPI because a serial engine can use only one protocol at a time.

NoteRebuild and deploy the software image with the updated device tree, then boot the device with the updated image.

For more information about the patch series, see the following resources:

Main patch series for driver implementation:
- https://lore.kernel.org/all/20250911043256.3523057-1-viken.dadhaniya@oss.qualcomm.com/
- Key changes: Firmware loading infrastructure, GSI DMA support, protocol initialization, error handling improvements
Device tree bindings and examples:
- https://lore.kernel.org/all/20250923161107.3541698-1-viken.dadhaniya@oss.qualcomm.com/
- https://lore.kernel.org/all/20250925042605.1388951-1-viken.dadhaniya@oss.qualcomm.com/
- https://lore.kernel.org/all/20250924035409.3976652-1-viken.dadhaniya@oss.qualcomm.com/
- Includes: Device tree binding documentation, Platform-specific examples, migration guides

Table : Device tree properties

Property	Type	Description	Required
`status`	string	Enable/disable SE (`okay`/`disabled`)	Yes
`qcom,enable-gsi-dma`	boolean	Enable GSI DMA mode	No
`clock-frequency`	u32	I2C clock frequency (Hz)	No
`spi-max-frequency`	u32	SPI max frequency (Hz)	No
`pinctrl-names`	string array	Pin control state names	Recommended
`pinctrl-0`	phandle	Default pin configuration	Recommended

Common clock frequencies

I2C
- Standard mode: 100 kHz
- Fast mode: 400 kHz
- Fast mode plus: 1 MHz
SPI
- Low speed: 1–10 MHz
- Medium speed: 10–50 MHz
- High speed: 50–100 MHz

Data transfer modes

QUP v3 serial engines support two main data transfer modes: FIFO mode and GSI DMA mode. FIFO mode is the default and is best suited for small, frequent transfers with minimal configuration. Generic software interface (GSI) DMA mode leverages DMA channels for bulk data transfers with additional configuration. The table below summarizes the key features and conditions for each mode. Table : FIFO and GSI DMA mode features

Attribute	FIFO mode	GSI DMA mode
Data path	Uses internal FIFO buffers	Uses GSI DMA mode
Best for	Small, frequent transfers; simple device communication	Large or bulk transfers; high-throughput devices (touchscreen, display)
Overhead	Lower overhead	Higher setup overhead, but offloads CPU for large transfers
Configuration	Default mode; no special configuration needed	Requires `qcom,enable-gsi-dma;` property in device tree
DMA channel use	Not required	Requires available DMA channels; limited by platform
Performance	Lower throughput for large data; low latency	Higher throughput for large data; CPU efficient
When to use	When DMA channels are limited, or for low-latency/small transfers	For transfer size > 32 bytes, or for bulk/high-speed data
Limitations	Not optimal for large or high-speed transfers	Limited by number of DMA channels; not all SEs may support GSI DMA
Device tree example	Omit `qcom,enable-gsi-dma;` property	Add `qcom,enable-gsi-dma;` property
Debugging	Standard Linux debugging tools; kernel logs	Similar to FIFO, but also includes DMA allocation logs

Sample GSI mode configurations

I2C with GSI DMA mode

&i2c8 {
    status = "okay";
    qcom,enable-gsi-dma;
    
    /* I2C devices that benefit from DMA */
    touchscreen@38 {
        compatible = "vendor,touchscreen";
        reg = <0x38>;
    };
};

SPI with GSI DMA mode

&spi9 {
    status = "okay";
    qcom,enable-gsi-dma;
    
    /* SPI devices with large data transfers */
    display@0 {
        compatible = "vendor,display";
        reg = <0>;
        spi-max-frequency = <50000000>;
    };
};

Use cases

Multiple serial engines with different protocols

/* I2C for sensors (FIFO mode) */
&i2c5 {
    status = "okay";
    clock-frequency = <400000>;
    
    sensor@48 {
        compatible = "vendor,sensor";
        reg = <0x48>;
    };
};

/* SPI for display (FIFO mode) */
&spi6 {
    status = "okay";
    spi-max-frequency = <50000000>;
    
    display@0 {
        compatible = "vendor,display";
        reg = <0>;
    };
};

/* UART for console */
&uart7 {
    status = "okay";
};

/* I2C for touchscreen (GSI DMA mode) */
&i2c8 {
    status = "okay";
    qcom,enable-gsi-dma;
    
    touchscreen@38 {
        compatible = "vendor,touchscreen";
        reg = <0x38>;
    };
};

/* SPI for high-speed flash (GSI DMA mode) */
&spi9 {
    status = "okay";
    qcom,enable-gsi-dma;
    
    flash@0 {
        compatible = "vendor,flash";
        reg = <0>;
        spi-max-frequency = <100000000>;
    };
};

Multiple QUP instances: QUP instance names and serial engine assignments vary by platform. Refer to the platform device tree for the correct node labels.
/* Example serial engine node */ &i2c5 { status = "okay"; };

Pin Multiplexing Ensure correct pin configuration:

&i2c5 {
    status = "okay";
    
    pinctrl-names = "default", "sleep";
    pinctrl-0 = <&qup_i2c5_default>;
    pinctrl-1 = <&qup_i2c5_sleep>;
};
&tlmm {
    qup_i2c5_default: qup-i2c5-default {
        mux {
            pins = "gpio25", "gpio26";
            function = "qup5";
        };
        
        config {
            pins = "gpio25", "gpio26";
            drive-strength = <2>;
            bias-disable;
        };
    };
    
    qup_i2c5_sleep: qup-i2c5-sleep {
        mux {
            pins = "gpio25", "gpio26";
            function = "gpio";
        };
        
        config {
            pins = "gpio25", "gpio26";
            drive-strength = <2>;
            bias-pull-up;
        };
    };
};

Performance optimization Table : Mode selection

Mode	When to use
GSI DMA mode (`qcom,enable-gsi-dma;`)	Transfer sizes > 32 bytes regularly, High-throughput devices (touchscreens, displays), Bulk data transfers, CPU efficiency is critical
FIFO mode	Small, frequent transfers, Low-latency requirements, Limited DMA channels available, Simple device communication

Troubleshooting

Debug commands

# List all I2C buses
ls -la /sys/bus/i2c/devices/
# List all SPI buses
ls -la /sys/bus/spi/devices/
# Check UART devices
ls -la /dev/ttyHS*

Kernel logs

# QUP-related messages
dmesg | grep -i qup
# GENI (Generic Interface) messages
dmesg | grep -i geni
# Firmware loading messages
dmesg | grep -i firmware
# DMA-related messages
dmesg | grep -i dma

Device tree verification

# Check compiled device tree
dtc -I fs /sys/firmware/devicetree/base | grep -A 20 qupv3

The following table lists the common issues noticed during troubleshooting. Table: Common issues and solutions

Issue	Symptoms	Solutions
Firmware loading failed	`qcom-geni-se`: firmware request failed	Verify that the firmware file exists: `ls -la /lib/firmware/qcom/<target-name>/qupv3fw.elf`. Verify the firmware path used by the driver. Check the kernel log for additional firmware-loading errors: `dmesg \| grep -i firmware`.
Serial engine not probing	No device node created Driver not loading	Check the device-tree status: `status = “okay”;`. Verify that the compatible string matches the driver. Check the kernel log: `dmesg \| grep -i qup` and `dmesg \| grep -i geni`.
Protocol conflict	`qcom-geni-se`: serial engine is already in use	Ensure that only one protocol is enabled for each serial engine.
DMA allocation failed	`qcom-geni-se`: GSI DMA allocation failed	Check the available DMA channels. Remove `qcom,enable-gsi-dma;` from one or more serial-engine nodes. Use FIFO mode for less critical devices.
Pin multiplexing conflict	Communication failures No response from devices	Verify the pin configuration: `cat /sys/kernel/debug/pinctrl/*/pinmux-pins`. Check for pin conflicts with other peripherals. Ensure that the correct function is selected in `pinctrl`.

Enable required interfaces

To enable an interface, do the following:

For UART, see the UART software device tree configuration section.
For SPI, see the SPI software device tree configuration section.
For I2C, see the I2C software device tree configuration section.
For PCIe, see the PCIe software driver configuration section.
For USB, see the Configure USB boot loader section.

Verify interface status

To verify the functioning of the different interfaces, do the following:

For UART, see the Verify UART interface section.
For SPI, see the SPI verification section.
For I2C, see the Verify I2C interface section.

For PCIe, verify the connected endpoint with the following command.

lspci

The following output is displayed.

00:00.0 PCI bridge: Qualcomm Device 010b
01:00.0 PCI bridge: Toshiba Corporation Device 0623
02:01.0 PCI bridge: Toshiba Corporation Device 0623
02:02.0 PCI bridge: Toshiba Corporation Device 0623
02:03.0 PCI bridge: Toshiba Corporation Device 0623
04:00.0 USB controller: Renesas Technology Corp. uPD720201 USB 3.0 Host Controller (rev 03)
05:00.0 Ethernet controller: Toshiba Corporation Device 0220
05:00.1 Ethernet controller: Toshiba Corporation Device 0220

NoteThe output may vary depending on the underlying hardware.

For USB, load the USB firmware to detect the device connection, and verify the device and host as follows:

Device: Connect the USB Type-C port and verify the enumerated log with the host PC.
adb devices
The following output is displayed.
List of devices attached 541eb4ba device

Host: Connect a USB device such as a mouse, or a pen drive, and verify device detection with the following command.

lsusb

The following output is displayed.

Bus 002 Device 003: ID 0b95:1790 ASIX Electronics Corp. AX88179 Gigabit Ethernet
Bus 002 Device 002: ID 05e3:0625 Genesys Logic, Inc. USB3.2 Hub
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 002: ID 05e3:0610 Genesys Logic, Inc. Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

​Identify the interface status

​Obtain the bootup logs

​List enabled interfaces on devices

​Load QUP v3 serial engine firmware using Linux kernel

​Default configuration

​Load firmware

​Data transfer modes

​Use cases

​Troubleshooting

​Enable required interfaces

​Verify interface status

Identify the interface status

Obtain the bootup logs

List enabled interfaces on devices

Load QUP v3 serial engine firmware using Linux kernel

Default configuration

Load firmware

Data transfer modes

Use cases

Troubleshooting

Enable required interfaces

Verify interface status