快速入门：设置设备接口

在开始之前，请按照 Qualcomm Linux 构建指南中的说明设置您的基础设施。

图：接口工作流程

识别接口状态

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

获取启动日志

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

在 permissive 模式下打开 SSH shell，或使用 ADB shell。有关如何运行 SSH 的更多信息，请参阅使用 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 软件设备树配置。要验证 SPI 是否已启用，请运行以下命令。
ls /dev/spi*
将显示以下输出。
spidev14.0
对于 PCIe，获取枚举日志。有关 PCIe 探测日志的更多信息，请参阅 PCIe 相关配置和 QPS615 交换机支持。

使用 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。

在以下文件中启用 CONFIG_QUP_FW_LOAD：
- 在 arch/arm64/configs/qcom_defconfig 中设置 CONFIG_QCOM_QUP_FW_LOAD=y
- 在 arch/arm64/configs/qcom_vm_defconfig 中设置 CONFIG_QCOM_QUP_FW_LOAD=m
通过检查平台设备树中的串行引擎节点来识别可用的串行引擎。典型的 SE 编号：SE0、SE1、SE2、…、SE15（因平台而异）。
grep -r "qupv3_se" arch/arm64/boot/dts/qcom/
注意您可以根据接口需求选择所需的协议。
- I2C：传感器、EEPROM、PMIC
- SPI：显示屏、闪存、ADC
- UART：控制台、GPS、蓝牙

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

I2C 配置示例：

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

SPI 配置示例：

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

UART 配置示例：

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

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

qcom,enable-gsi-dma;

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

原始 I2C 配置：

&qupv3_se5_i2c {
    status = "disabled";
};
&qupv3_se5_spi {
    status = "okay";
    flash@0 {
        compatible = "vendor,flash";
        reg = <0>;
    };
};

新配置（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>;
    };
};

注意重启设备以使更改生效。

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

驱动程序实现的主要补丁系列：
- 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`	string	启用/禁用 SE（`okay`/`disabled`）	是
`qcom,enable-gsi-dma`	boolean	启用 GSI DMA 模式	否
`clock-frequency`	u32	I2C 时钟频率（Hz）	否
`spi-max-frequency`	u32	SPI 最大频率（Hz）	否
`pinctrl-names`	string array	引脚控制状态名称	建议
`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

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

采用 GSI DMA 模式的 SPI

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

用例

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

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

多个 QUP 实例：

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

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

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

性能优化 表：模式选择

模式	何时使用
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/` 检查内核配置。`CONFIG_FW_LOADER=y` `CONFIG_FW_LOADER_USER_HELPER=y` 验证驱动程序中的固件路径。
串行引擎未探测到	未创建设备节点驱动程序未加载	检查设备树状态。`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 软件设备树配置部分。
对于 SPI，请参阅 SPI 软件设备树配置部分。
对于 I2C，请参阅 I2C 软件设备树配置部分。
对于 PCIe，请参阅 PCIe 软件驱动程序配置部分。
对于 USB，请参阅配置 USB 引导加载程序部分。

验证接口状态

要验证不同接口的功能，请执行以下操作：

对于 UART，请参阅验证 UART 接口部分。
对于 SPI，请参阅 SPI 验证部分。
对于 I2C，请参阅验证 I2C 接口部分。

对于 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 串行引擎固件

​默认配置

​加载固件

​数据传输模式

​用例

​故障排除

​启用所需接口

​验证接口状态

识别接口状态

获取启动日志

列出设备上已启用的接口

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

默认配置

加载固件

数据传输模式

用例

故障排除

启用所需接口

验证接口状态