# Getting started: Set up the device interface
Source: [https://docs.qualcomm.com/doc/80-70029-8/topic/get-started.html](https://docs.qualcomm.com/doc/80-70029-8/topic/get-started.html)
Before you begin, set up your infrastructure as described in the [Qualcomm Linux Build Guide](https://docs.qualcomm.com/bundle/publicresource/topics/80-70029-254/introduction.html).
Figure : Interface workflow
## Identify the interface status
Source: [https://docs.qualcomm.com/doc/80-70029-8/topic/get-started.html](https://docs.qualcomm.com/doc/80-70029-8/topic/get-started.html)
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
Source: [https://docs.qualcomm.com/doc/80-70029-8/topic/get-started.html](https://docs.qualcomm.com/doc/80-70029-8/topic/get-started.html)
### About this task
To obtain the bootup logs of the device, do the following:
### Procedure
1. Open the SSH shell in permissive mode or use the ADB shell. For more
information about how to run SSH, see the [Use SSH](https://docs.qualcomm.com/bundle/publicresource/topics/80-70029-254/how_to.html#use-ssh) section.
2. Obtain the logs of the enabled interfaces by running the following
command.
dmesgCopy to clipboard
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 ep0ouCopy to clipboard
3. Connect the UART serial port to log in to the console.

### List enabled interfaces on devices
Source: [https://docs.qualcomm.com/doc/80-70029-8/topic/get-started.html](https://docs.qualcomm.com/doc/80-70029-8/topic/get-started.html)
To obtain the list of the enabled interfaces, do the following:
- For UART, run the following
command.
ls /dev/tty*Copy to clipboard
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/ttyp3Copy to clipboard
- For I2C, run the following
command.
ls /dev/i2c*Copy to clipboard
The
following output is
displayed.
/dev/i2c-0 /dev/i2c-1 /dev/i2c-16Copy to clipboard
- By default, SPI isn't enabled. To enable SPI, see [SPI software device tree configuration](https://docs.qualcomm.com/doc/80-70029-8/topic/spi.html#spi_software).
To verify if SPI is enabled, run the following
command.
ls /dev/spi*Copy to clipboard
The
following output is
displayed.
spidev14.0Copy to clipboard
- For PCIe, obtain the enumeration log. For more information about PCIe probe logs,
see [PCIe-related configurations](https://docs.qualcomm.com/doc/80-70029-8/topic/pcie.html#pcie-software-support-feature-for-qps615__section_xbl_hhd_l1c) and [QPS615 switch support](https://docs.qualcomm.com/doc/80-70029-8/topic/pcie.html#pcie-software-support-feature-for-qps615__section_nmw_5jd_l1c).
## Load QUP v3 serial engine firmware using Linux kernel
Source: [https://docs.qualcomm.com/doc/80-70029-8/topic/get-started.html](https://docs.qualcomm.com/doc/80-70029-8/topic/get-started.html)
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
};
Copy to clipboard
### Load firmware
The firmware files are at
/lib/firmware/qcom/<target-name>/qupv3fw.elf.
1. Enable CONFIG\_QUP\_FW\_LOAD in the following files:
- `CONFIG_QCOM_QUP_FW_LOAD=y` in
arch/arm64/configs/qcom\_defconfig
- `CONFIG_QCOM_QUP_FW_LOAD=m` in
arch/arm64/configs/qcom\_vm\_defconfig
2. Identify available serial engines by checking the platform device tree for
serial engine nodes. Typical SE numbering: SE0, SE1, SE2, ..., SE15 (varies by
platform).
grep -r "qupv3_se" arch/arm64/boot/dts/qcom/Copy to clipboard
Note:You can choose the required protocol based on your
interface requirements.
- **I2C**: Sensors, EEPROMs, PMICs
- **SPI**: Displays, flash memory, ADCs
- **UART**: Console, GPS, Bluetooth
3. Configure device tree by adding or modifying serial engine nodes to the device
tree file.
- Sample I2C configuration:
&qupv3_se5_i2c {
status = "okay";
clock-frequency = <400000>; /* 400 KHz */
sensor@48 {
compatible = "vendor,sensor";
reg = <0x48>;
};
};
Copy to clipboard
- Sample SPI configuration:
&qupv3_se6_spi {
status = "okay";
spi-max-frequency = <50000000>; /* 50 MHz */
flash@0 {
compatible = "vendor,spi-flash";
reg = <0>;
spi-max-frequency = <25000000>;
};
};
Copy to clipboard
- Sample UART configuration:
&qupv3_se7_uart {
status = "okay";
/delete-property/ interrupts;
interrupts-extended = <&intc GIC_SPI 608 IRQ_TYPE_LEVEL_HIGH>;
};
Copy to clipboard
Optional: Enable GSI DMA for high-throughput
devices.
qcom,enable-gsi-dma:Copy to clipboard
4. Switch the serial engine protocol. For example, I2C to SPI.
1. Original I2C configuration:
&qupv3_se5_i2c {
status = "disabled";
};
&qupv3_se5_spi {
status = "okay";
flash@0 {
compatible = "vendor,flash";
reg = <0>;
};
};
Copy to clipboard
2. New configuration
(SPI)
/* Disable I2C on SE5 */
&qupv3_se5_i2c {
status = "disabled";
};
/* Enable SPI on SE5 */
&qupv3_se5_spi {
status = "okay";
flash@0 {
compatible = "vendor,flash";
reg = <0>;
};
};Copy to clipboard
Note: Reboot device for changes to take
effect.
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/](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/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/20250925042605.1388951-1-viken.dadhaniya@oss.qualcomm.com/)
- [https://lore.kernel.org/all/20250924035409.3976652-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
- High speed: 3.4 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
&qupv3_se8_i2c {
status = "okay";
qcom,enable-gsi-dma:
/* I2C devices that benefit from DMA */
touchscreen@38 {
compatible = "vendor,touchscreen";
reg = <0x38>;
};
};Copy to clipboard
- SPI with GSI DMA
mode
&qupv3_se9_spi {
status = "okay";
qcom,enable-gsi-dma:
/* SPI devices with large data transfers */
display@0 {
compatible = "vendor,display";
reg = <0>;
spi-max-frequency = <50000000>;
};
};Copy to clipboard
### Use cases
- Multiple serial engines with different
protocols
/* SE5: I2C for sensors (FIFO mode) */
&qupv3_se5_i2c {
status = "okay";
clock-frequency = <400000>;
sensor@48 {
compatible = "vendor,sensor";
reg = <0x48>;
};
};
/* SE6: SPI for display (FIFO mode) */
&qupv3_se6_spi {
status = "okay";
spi-max-frequency = <50000000>;
display@0 {
compatible = "vendor,display";
reg = <0>;
};
};
/* SE7: UART for console */
&qupv3_se7_uart {
status = "okay";
};
/* SE8: I2C for touchscreen (GSI DMA mode) */
&qupv3_se8_i2c {
status = "okay";
qcom,enable-gsi-dma:
touchscreen@38 {
compatible = "vendor,touchscreen";
reg = <0x38>;
};
};
/* SE9: SPI for high-speed flash (GSI DMA mode) */
&qupv3_se9_spi {
status = "okay";
qcom,enable-gsi-dma:
flash@0 {
compatible = "vendor,flash";
reg = <0>;
spi-max-frequency = <100000000>;
};
};Copy to clipboard
- Multiple QUP instances:
- `qupv3_0` (QUP0): SE0-SE7
- `qupv3_1` (QUP1): SE8-SE15
/* QUP0 SE5 */
&qupv3_0_se5_i2c {
status = "okay";
};
/* QUP1 SE5 */
&qupv3_1_se5_i2c {
status = "okay";
};Copy to clipboard
- Pin Multiplexing
Ensure correct pin
configuration:
&qupv3_se5_i2c {
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;
};
};
};
Copy to clipboard
- 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*
Copy to clipboard
- 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
Copy to clipboard
- Device tree verification
# Check compiled device tree
dtc -I fs /sys/firmware/devicetree/base | grep -A 20 qupv3
Copy to clipboard
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 |
ls -la /lib/firmware/qcom/CONFIG_FW_LOADER=y
CONFIG_FW_LOADER_USER_HELPER=ystatus = "okay"; /* Not "ok" or "enable" */
dmesg | grep -i qup
dmesg | grep -i geni
qcom,enable-gsi-dma: from somecat /sys/kernel/debug/pinctrl/*/pinmux-pinspinctrl.