> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速入门：设置设备接口

export const tdA = {
  border: "1px solid #ddd",
  padding: "10px 14px",
  textAlign: "left",
  verticalAlign: "top"
};
export const thA1 = {
  border: "1px solid #ddd",
  padding: "10px 14px",
  textAlign: "center",
  backgroundColor: "#f5f5f5",
  fontWeight: "600",
  color: "#333",
  width: "20%"
};
export const thA2 = {
  border: "1px solid #ddd",
  padding: "10px 14px",
  textAlign: "center",
  backgroundColor: "#f5f5f5",
  fontWeight: "600",
  color: "#333",
  width: "80%"
};
export const thAeq = {
  border: "1px solid #ddd",
  padding: "10px 14px",
  textAlign: "center",
  backgroundColor: "#f5f5f5",
  fontWeight: "600",
  color: "#333"
};
export const tblA = {
  borderCollapse: "collapse",
  width: "100%",
  fontSize: "14px",
  tableLayout: "fixed"
};

在开始之前，请按照 [Qualcomm Linux 构建指南](https://dragonwingdocs.qualcomm.com/Key-Documents/Firmware-Guide/build-firmware)中的说明设置您的基础设施。

<img src="https://mintcdn.com/qualcomm-prod/rpHTx_a6zriKQll9/System/Interfaces/images/interface_workflow.png?fit=max&auto=format&n=rpHTx_a6zriKQll9&q=85&s=02e7c3483aec5a220e797dc04eb528f8" alt="接口工作流程" width="724" height="187" data-path="System/Interfaces/images/interface_workflow.png" />

<p align="center"><strong>***图：接口工作流程***</strong></p>

## **识别接口状态**

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

### **获取启动日志**

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

1. 在 permissive 模式下打开 SSH shell，或使用 ADB shell。有关如何运行 SSH 的更多信息，请参阅[使用 SSH](https://docs.qualcomm.com/doc/80-80021-254/topic/how_to.html) 部分。
2. 运行以下命令获取已启用接口的日志。
   ```text theme={null}
   dmesg
   ```
   输出：
   ```text theme={null}
    
   [    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
   ```
3. 连接 UART 串口以登录控制台。
   <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/System/Interfaces/images/usb_Connector.png" alt="USB 连接器" />

### **列出设备上已启用的接口**

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

* 对于 UART，运行以下命令。
  ```text theme={null}
  ls /dev/tty*
  ```
  输出：
  ```text theme={null}
  /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，运行以下命令。
  ```text theme={null}
  ls /dev/i2c*
  ```
  将显示以下输出。
  ```text theme={null}
  /dev/i2c-0  /dev/i2c-1 /dev/i2c-16
  ```
* 默认情况下，SPI 未启用。要启用 SPI，请参阅 [SPI 软件设备树配置](https://dragonwingdocs.qualcomm.com/System/Interfaces/spi#spi-software-device-tree-configuration)。要验证 SPI 是否已启用，请运行以下命令。
  ```text theme={null}
  ls /dev/spi*
  ```
  将显示以下输出。
  ```text theme={null}
  spidev14.0
  ```
* 对于 PCIe，获取枚举日志。有关 PCIe 探测日志的更多信息，请参阅 [PCIe 相关配置](https://dragonwingdocs.qualcomm.com/System/Interfaces/pcie#pcie-related-configurations)和 [QPS615 交换机支持](https://docs.qualcomm.com/doc/80-80021-8/topic/pcie.html?product=895724676033554725\&facet=Interfaces\&version=2.0-rc2#pcie-software-support-feature-for-qps615__section_nmw_5jd_l1c)。

## **使用 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 拥有所有串行引擎。

```text theme={null}
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*。

1. 在以下文件中启用 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`
2. 通过检查平台设备树中的串行引擎节点来识别可用的串行引擎。典型的 SE 编号：SE0、SE1、SE2、...、SE15（因平台而异）。

   ```text theme={null}
   grep -r "qupv3_se" arch/arm64/boot/dts/qcom/
   ```

   <Note>
     **注意**

     您可以根据接口需求选择所需的协议。

     * **I2C**：传感器、EEPROM、PMIC
     * **SPI**：显示屏、闪存、ADC
     * **UART**：控制台、GPS、蓝牙
   </Note>
3. 通过在设备树文件中添加或修改串行引擎节点来配置设备树。
   * I2C 配置示例：
     ```text theme={null}
     &qupv3_se5_i2c {
         status = "okay";
         clock-frequency = <400000>; /* 400 KHz */
         sensor@48 {
             compatible = "vendor,sensor";
             reg = <0x48>;
         };
     };
     ```
   * SPI 配置示例：
     ```text theme={null}
     &qupv3_se6_spi {
         status = "okay";
         spi-max-frequency = <50000000>; /* 50 MHz */
         flash@0 {
             compatible = "vendor,spi-flash";
             reg = <0>;
             spi-max-frequency = <25000000>;
         };
     };
     ```
   * UART 配置示例：
     ```text theme={null}
     &qupv3_se7_uart {
         status = "okay";
         /delete-property/ interrupts;
         interrupts-extended = <&intc GIC_SPI 608 IRQ_TYPE_LEVEL_HIGH>;
     };
     ```
     可选：为高吞吐量设备启用 GSI DMA。
     ```text theme={null}
     qcom,enable-gsi-dma;
     ```
4. 切换串行引擎协议。例如，从 I2C 切换到 SPI。

   1. 原始 I2C 配置：
      ```text theme={null}
      &qupv3_se5_i2c {
          status = "disabled";
      };
      &qupv3_se5_spi {
          status = "okay";
          flash@0 {
              compatible = "vendor,flash";
              reg = <0>;
          };
      };
      ```
   2. 新配置（SPI）
      ```text theme={null}
      /* 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>;
          };
      };
      ```

   <Note>
     **注意**

     重启设备以使更改生效。
   </Note>

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

* 驱动程序实现的主要补丁系列：
  * [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/)
  * 主要更改：固件加载基础设施、GSI DMA 支持、协议初始化、错误处理改进
* 设备树绑定和示例：
  * [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/)
  * 包括：设备树绑定文档、平台特定示例、迁移指南

**表：设备树属性**

<table style={tblA}>
  <thead>
    <tr>
      <th style={thAeq}>属性</th>
      <th style={thAeq}>类型</th>
      <th style={thAeq}>描述</th>
      <th style={thAeq}>是否必需</th>
    </tr>
  </thead>

  <tbody>
    <tr><td style={tdA}>`status`</td><td style={tdA}>string</td><td style={tdA}>启用/禁用 SE（`okay`/`disabled`）</td><td style={tdA}>是</td></tr>
    <tr><td style={tdA}>`qcom,enable-gsi-dma`</td><td style={tdA}>boolean</td><td style={tdA}>启用 GSI DMA 模式</td><td style={tdA}>否</td></tr>
    <tr><td style={tdA}>`clock-frequency`</td><td style={tdA}>u32</td><td style={tdA}>I2C 时钟频率（Hz）</td><td style={tdA}>否</td></tr>
    <tr><td style={tdA}>`spi-max-frequency`</td><td style={tdA}>u32</td><td style={tdA}>SPI 最大频率（Hz）</td><td style={tdA}>否</td></tr>
    <tr><td style={tdA}>`pinctrl-names`</td><td style={tdA}>string array</td><td style={tdA}>引脚控制状态名称</td><td style={tdA}>建议</td></tr>
    <tr><td style={tdA}>`pinctrl-0`</td><td style={tdA}>phandle</td><td style={tdA}>默认引脚配置</td><td style={tdA}>建议</td></tr>
  </tbody>
</table>

**常见时钟频率**

* 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 模式特性**

<table style={tblA}>
  <thead>
    <tr>
      <th style={thAeq}>属性</th>
      <th style={thAeq}>FIFO 模式</th>
      <th style={thAeq}>GSI DMA 模式</th>
    </tr>
  </thead>

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

**GSI 模式配置示例**

* 采用 GSI DMA 模式的 I2C
  ```text theme={null}
  &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
  ```text theme={null}
  &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>;
      };
  };
  ```

### **用例**

* 使用不同协议的多个串行引擎
  ```text theme={null}
  /* 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
  ```text theme={null}
  /* QUP0 SE5 */
  &qupv3_0_se5_i2c {
      status = "okay";
  };
  /* QUP1 SE5 */
  &qupv3_1_se5_i2c {
      status = "okay";
  };
  ```
* 引脚复用：确保正确的引脚配置：
  ```text theme={null}
  &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;
          };
      };
  };
  ```
* 性能优化

  **表：模式选择**

  <table style={tblA}>
    <thead>
      <tr>
        <th style={thA1}>模式</th>
        <th style={thA2}>何时使用</th>
      </tr>
    </thead>

    <tbody>
      <tr><td style={tdA}>GSI DMA 模式（`qcom,enable-gsi-dma;`）</td><td style={tdA}>传输大小经常 > 32 字节、高吞吐量设备（触摸屏、显示屏）、批量数据传输、对 CPU 效率要求高</td></tr>
      <tr><td style={tdA}>FIFO 模式</td><td style={tdA}>小规模、频繁的传输，低延迟要求，可用 DMA 通道有限，简单的设备通信</td></tr>
    </tbody>
  </table>

### **故障排除**

* 调试命令
  ```text theme={null}
  # 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*
  ```
* 内核日志
  ```text theme={null}
  # 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
  ```
* 设备树验证
  ```text theme={null}
  # Check compiled device tree
  dtc -I fs /sys/firmware/devicetree/base | grep -A 20 qupv3
  ```

下表列出了故障排除过程中发现的常见问题。

**表：常见问题及解决方案**

<table style={tblA}>
  <thead>
    <tr>
      <th style={thAeq}>问题</th>
      <th style={thAeq}>症状</th>
      <th style={thAeq}>解决方案</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={tdA}>固件加载失败</td>
      <td style={tdA}>`qcom-geni-se`: firmware request failed</td>
      <td style={tdA}><ol><li>验证固件文件是否存在。`ls -la /lib/firmware/qcom/`</li><li>检查内核配置。`CONFIG_FW_LOADER=y` `CONFIG_FW_LOADER_USER_HELPER=y`</li><li>验证驱动程序中的固件路径。</li></ol></td>
    </tr>

    <tr>
      <td style={tdA}>串行引擎未探测到</td>
      <td style={tdA}><ul><li>未创建设备节点</li><li>驱动程序未加载</li></ul></td>
      <td style={tdA}><ol><li>检查设备树状态。`status = "okay";`</li><li>验证 compatible 字符串与驱动程序匹配。</li><li>检查内核日志。`dmesg | grep -i qup` `dmesg | grep -i geni`</li></ol></td>
    </tr>

    <tr>
      <td style={tdA}>协议冲突</td>
      <td style={tdA}>`qcom-geni-se`: serial engine is already in use</td>
      <td style={tdA}>确保每个串行引擎仅启用一种协议。</td>
    </tr>

    <tr>
      <td style={tdA}>DMA 分配失败</td>
      <td style={tdA}>`qcom-geni-se`: GSI DMA allocation failed</td>
      <td style={tdA}><ol><li>检查可用的 DMA 通道。</li><li>从某些串行引擎中移除 `qcom,enable-gsi-dma;`。</li><li>对不太关键的设备使用 FIFO 模式。</li></ol></td>
    </tr>

    <tr>
      <td style={tdA}>引脚复用冲突</td>
      <td style={tdA}><ul><li>通信失败</li><li>设备无响应</li></ul></td>
      <td style={tdA}><ol><li>验证引脚配置。`cat /sys/kernel/debug/pinctrl/*/pinmux-pins`</li><li>检查与其他外设的引脚冲突。</li><li>确保在 `pinctrl` 中选择了正确的功能。</li></ol></td>
    </tr>
  </tbody>
</table>

## **启用所需接口**

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

* 对于 UART，请参阅 [UART 软件设备树配置](https://dragonwingdocs.qualcomm.com/System/Interfaces/uart#uart-software-device-tree-configuration)部分。
* 对于 SPI，请参阅 [SPI 软件设备树配置](https://dragonwingdocs.qualcomm.com/System/Interfaces/spi#spi-software-device-tree-configuration)部分。
* 对于 I2C，请参阅 [I2C 软件设备树配置](https://dragonwingdocs.qualcomm.com/System/Interfaces/i2-c#i2c-software-device-tree-configuration)部分。
* 对于 PCIe，请参阅 [PCIe 软件驱动程序配置](https://dragonwingdocs.qualcomm.com/System/Interfaces/pcie#pcie-software-driver-configuration)部分。
* 对于 USB，请参阅[配置 USB 引导加载程序](https://dragonwingdocs.qualcomm.com/System/Interfaces/usb#configure-usb-boot-loader)部分。

## **验证接口状态**

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

* 对于 UART，请参阅[验证 UART 接口](https://dragonwingdocs.qualcomm.com/System/Interfaces/uart#verify-uart-interface)部分。
* 对于 SPI，请参阅 [SPI 验证](https://dragonwingdocs.qualcomm.com/System/Interfaces/spi#spi-verification)部分。
* 对于 I2C，请参阅[验证 I2C 接口](https://dragonwingdocs.qualcomm.com/System/Interfaces/i2-c#verify-i2c-interface)部分。
* 对于 PCIe，使用以下命令验证已连接的端点。

  ```text theme={null}
  lspci
  ```

  将显示以下输出。

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

  <Note>
    **注意**

    输出可能因底层硬件而异。
  </Note>
* 对于 USB，加载 USB 固件以检测设备连接，并按如下方式验证设备和主机：
  * 设备：连接 USB Type-C 端口，并通过主机 PC 验证枚举日志。
    ```text theme={null}
    adb devices
    ```
    将显示以下输出。
    ```text theme={null}
    List of devices attached
    541eb4ba        device
    ```
  * 主机：连接鼠标或 U 盘等 USB 设备，并使用以下命令验证设备检测。
    ```text theme={null}
    lsusb
    ```
    将显示以下输出。
    ```text theme={null}
    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
    ```