入门：设置设备接口 - Qualcomm Dragonwing Documentation

在开始之前，请按照 Qualcomm Linux Build Guide 中的说明设置您的基础设施。

图：接口工作流

识别接口状态

默认接口状态表示启动期间各接口的状态。要识别接口状态，请成功注册接口并获取已启用接口的列表。

获取启动日志

要获取设备的启动日志，请执行以下操作：

在 permissive 模式下打开 SSH shell，或使用 ADB shell。有关如何运行 SSH 的更多信息，请参阅 Use SSH 部分。

通过运行以下命令获取已启用接口的日志。

dmesg

输出：

 
[    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

连接 UART 串行端口以登录控制台。

列出设备上已启用的接口

要获取已启用接口的列表，请执行以下操作：

对于 UART，运行以下命令。

ls /dev/tty*

输出：

/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

对于 I2C，运行以下命令。
ls /dev/i2c*
将显示以下输出。
/dev/i2c-0 /dev/i2c-1 /dev/i2c-16
默认情况下，SPI 未启用。要启用 SPI，请参阅 SPI software device tree configuration。要验证 SPI 是否已启用，请运行以下命令。
ls /dev/spi*
将显示以下输出。
spidev14.0
对于 PCIe，请获取枚举日志。有关 PCIe 探测日志的更多信息，请参阅 PCIe-related configurations 和 QPS615 switch support。

使用 Linux 内核加载 QUP v3 串行引擎固件

本文档介绍使用 Linux 内核的 QUP v3 串行引擎固件加载机制。它描述了从基于 TrustZone 的架构（协议分配固定且灵活性有限）到基于 Linux 的方式的转变，后者通过设备树配置实现动态协议分配、更轻松的调试和简化的开发。QUP v3 包含多个串行引擎，可配置为以下协议：

I2C
SPI
UART

默认配置

每个串行引擎的默认配置（包括所选的数据传输模式和所有权）位于 _/TZ.XF.5.0/core.tz/2.0/settings/buses/qup\_accesscontrol/qupv3/config/lemans/QUPAC\_Access.c_ 文件中。在默认配置中，Linux 拥有所有串行引擎。

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
};

加载固件

固件文件位于 /lib/firmware/qcom/<target-name>/qupv3fw.elf。

通过检查平台设备树中的串行引擎节点来识别可用的串行引擎。串行引擎的名称和编号因平台而异。请使用平台定义的节点标签；例如：
grep -r -E "&(i2c|spi|uart)[0-9]+" arch/arm64/boot/dts/qcom/
注意您可以根据接口需求选择所需的协议。
- I2C：传感器、EEPROM、PMIC
- SPI：显示屏、闪存、ADC
- UART：控制台、GPS、蓝牙

通过在设备树文件中添加或修改串行引擎节点来配置设备树。

I2C 配置示例：

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

SPI 配置示例：

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

UART 配置示例：

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

可选：为高吞吐量设备启用 GSI DMA。

qcom,enable-gsi-dma;

切换串行引擎协议。例如，从 I2C 切换到 SPI。

原始 I2C 配置：

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

新配置（SPI）

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

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

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

在启用 SPI 之前请先禁用原有的 I2C 节点，因为一个串行引擎同一时间只能使用一种协议。

注意请使用更新后的设备树重新构建并部署软件镜像，然后使用更新后的镜像启动设备。

有关补丁系列的更多信息，请参阅以下资源：

驱动程序实现的主要补丁系列：
- https://lore.kernel.org/all/20250911043256.3523057-1-viken.dadhaniya@oss.qualcomm.com/
- 主要更改：固件加载基础设施、GSI DMA 支持、协议初始化、错误处理改进
设备树绑定和示例：
- 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/
- 包括：设备树绑定文档、特定平台示例、迁移指南

表：设备树属性

属性	类型	说明	是否必需
`status`	字符串	启用/禁用 SE（`okay`/`disabled`）	是
`qcom,enable-gsi-dma`	布尔值	启用 GSI DMA 模式	否
`clock-frequency`	u32	I2C 时钟频率（Hz）	否
`spi-max-frequency`	u32	SPI 最大频率（Hz）	否
`pinctrl-names`	字符串数组	引脚控制状态名称	建议
`pinctrl-0`	phandle	默认引脚配置	建议

常见时钟频率

I2C
- 标准模式：100 kHz
- 快速模式：400 kHz
- 快速模式增强版（Fast mode plus）：1 MHz
SPI
- 低速：1–10 MHz
- 中速：10–50 MHz
- 高速：50–100 MHz

数据传输模式

QUP v3 串行引擎支持两种主要的数据传输模式：FIFO 模式和 GSI DMA 模式。FIFO 模式是默认模式，最适合小型、频繁的传输，配置需求极少。通用软件接口（GSI）DMA 模式利用 DMA 通道进行批量数据传输，需要额外配置。下表总结了每种模式的主要特性和适用条件。 表：FIFO 和 GSI DMA 模式特性

属性	FIFO 模式	GSI DMA 模式
数据路径	使用内部 FIFO 缓冲区	使用 GSI DMA 模式
最适合	小型、频繁的传输；简单的设备通信	大型或批量传输；高吞吐量设备（触摸屏、显示屏）
开销	较低的开销	较高的设置开销，但可为大型传输卸载 CPU 负担
配置	默认模式；无需特殊配置	需要在设备树中添加 `qcom,enable-gsi-dma;` 属性
DMA 通道使用	不需要	需要可用的 DMA 通道；受平台限制
性能	大数据吞吐量较低；低延迟	大数据吞吐量较高；CPU 效率高
何时使用	当 DMA 通道有限，或用于低延迟/小型传输时	用于传输大小 > 32 字节，或批量/高速数据
限制	不适合大型或高速传输	受 DMA 通道数量限制；并非所有 SE 都支持 GSI DMA
设备树示例	省略 `qcom,enable-gsi-dma;` 属性	添加 `qcom,enable-gsi-dma;` 属性
调试	标准 Linux 调试工具；内核日志	与 FIFO 类似，但还包括 DMA 分配日志

GSI 模式配置示例

使用 GSI DMA 模式的 I2C

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

使用 GSI DMA 模式的 SPI

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

使用场景

多个串行引擎使用不同协议

/* 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>;
    };
};

多个 QUP 实例： QUP 实例的名称和串行引擎分配因平台而异。请参考平台设备树以获取正确的节点标签。
/* Example serial engine node */ &i2c5 { status = "okay"; };

引脚复用：确保正确的引脚配置：

&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;
        };
    };
};

性能优化 表：模式选择

模式	何时使用
GSI DMA 模式（`qcom,enable-gsi-dma;`）	经常传输大小 > 32 字节、高吞吐量设备（触摸屏、显示屏）、批量数据传输、CPU 效率至关重要
FIFO 模式	小型、频繁的传输，低延迟要求，可用 DMA 通道有限，简单的设备通信

故障排查

调试命令

# 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*

内核日志

# 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

设备树验证

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

下表列出了故障排查过程中发现的常见问题。 表：常见问题及解决方案

问题	症状	解决方案
固件加载失败	`qcom-geni-se`: firmware request failed	验证固件文件是否存在：`ls -la /lib/firmware/qcom/<target-name>/qupv3fw.elf`。验证驱动程序使用的固件路径。查看内核日志中的其他固件加载错误：`dmesg \| grep -i firmware`。
串行引擎未探测	未创建设备节点驱动程序未加载	检查设备树状态：`status = “okay”;`。验证 compatible 字符串与驱动程序匹配。查看内核日志：`dmesg \| grep -i qup` 和 `dmesg \| grep -i geni`。
协议冲突	`qcom-geni-se`: serial engine is already in use	确保每个串行引擎只启用一种协议。
DMA 分配失败	`qcom-geni-se`: GSI DMA allocation failed	检查可用的 DMA 通道。从一个或多个串行引擎节点中删除 `qcom,enable-gsi-dma;`。对不太关键的设备使用 FIFO 模式。
引脚复用冲突	通信失败设备无响应	验证引脚配置：`cat /sys/kernel/debug/pinctrl/*/pinmux-pins`。检查与其他外设的引脚冲突。确保在 `pinctrl` 中选择了正确的功能。

启用所需接口

要启用接口，请执行以下操作：

对于 UART，请参阅 UART software device tree configuration 部分。
对于 SPI，请参阅 SPI software device tree configuration 部分。
对于 I2C，请参阅 I2C software device tree configuration 部分。
对于 PCIe，请参阅 PCIe software driver configuration 部分。
对于 USB，请参阅 Configure USB boot loader 部分。

验证接口状态

要验证各接口是否正常工作，请执行以下操作：

对于 UART，请参阅 Verify UART interface 部分。
对于 SPI，请参阅 SPI verification 部分。
对于 I2C，请参阅 Verify I2C interface 部分。

对于 PCIe，使用以下命令验证已连接的端点。

lspci

将显示以下输出。

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

注意输出可能因底层硬件而异。

对于 USB，加载 USB 固件以检测设备连接，并按如下方式验证设备和主机：

设备：连接 USB Type-C 端口，并在主机 PC 上验证枚举日志。
adb devices
将显示以下输出。
List of devices attached 541eb4ba device

主机：连接鼠标或 U 盘等 USB 设备，并使用以下命令验证设备检测。

lsusb

将显示以下输出。

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

​识别接口状态

​获取启动日志

​列出设备上已启用的接口

​使用 Linux 内核加载 QUP v3 串行引擎固件

​默认配置

​加载固件

​数据传输模式

​使用场景

​故障排查

​启用所需接口

​验证接口状态

识别接口状态

获取启动日志

列出设备上已启用的接口

使用 Linux 内核加载 QUP v3 串行引擎固件

默认配置

加载固件

数据传输模式

使用场景

故障排查

启用所需接口

验证接口状态