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

# 概述

本指南介绍 Qualcomm Dragonwing IQ-8275 SoC 中使用的低速和高速 I/O 外设接口子系统。

**低速接口**（通过 QUP v3 串行引擎）：

* UART、SPI、I2C、I3C

**高速接口：**

* PCIe、USB

## IQ-8275 接口概览

| 2× QUP v3 串行引擎 | QUP0\_V3 | QUP1\_V3 | QUP2\_V3 |
| -------------- | -------- | -------- | -------- |
| 应用处理器串行引擎实例数   | 7        | 7        | 1        |

| 3× USB 控制器 | 0xa600000          | 0xa800000          | 0xa400000          |
| ---------- | ------------------ | ------------------ | ------------------ |
| 最大速率       | USB 3.x SuperSpeed | USB 3.x SuperSpeed | USB 2.0 High Speed |

| 2× PCIe 控制器 | RC1                | RC0                |
| ----------- | ------------------ | ------------------ |
| 速率          | Gen4 2L（8 GT/s）    | Gen4 4L（8 GT/s）    |
| 配置空间        | 0x40100000（1 MB）   | 0x60100000（1 MB）   |
| BAR 空间      | 0x40300000（509 MB） | 0x60300000（509 MB） |
| 电源管理        | ASPM（L1/L1ss、L0s）  | ASPM（L1/L1ss、L0s）  |

## QUP v3 协议与 GPIO 映射

### QUP0（SE0–SE5）

| QUP\_SE（地址）          | SPI-M | I2C-M | UART  | HS UART | GPIO 映射        |
| -------------------- | ----- | ----- | ----- | ------- | -------------- |
| qup0\_se0 (0x980000) | spi0  | i2c0  | uart0 | —       | 20, 21, 22, 23 |
| qup0\_se1 (0x984000) | spi1  | i2c1  | uart1 | —       | 24, 25, 26, 27 |
| qup0\_se2 (0x988000) | spi2  | i2c2  | uart2 | uart2   | 36, 37, 38, 39 |
| qup0\_se3 (0x98c000) | spi3  | i2c3  | uart3 | uart3   | 28, 29, 30, 31 |
| qup0\_se4 (0x990000) | spi4  | i2c4  | uart4 | —       | 32, 33, 34, 35 |
| qup0\_se5 (0x994000) | spi5  | i2c5  | uart5 | —       | 36, 37, 38, 39 |

### QUP1（SE0–SE6）

| QUP\_SE（地址）          | SPI-M | I2C-M | UART   | HS UART | GPIO 映射        |
| -------------------- | ----- | ----- | ------ | ------- | -------------- |
| qup1\_se0 (0xa80000) | spi7  | i2c7  | uart7  | —       | 40, 41, 42, 43 |
| qup1\_se1 (0xa84000) | spi8  | i2c8  | uart8  | —       | 42, 43, 40, 41 |
| qup1\_se2 (0xa88000) | spi9  | i2c9  | uart9  | uart9   | 46, 47, 44, 45 |
| qup1\_se3 (0xa8c000) | spi10 | i2c10 | uart10 | uart10  | 44, 45, 46, 47 |
| qup1\_se4 (0xa90000) | spi11 | i2c11 | uart11 | —       | 48, 49, 50, 51 |
| qup1\_se5 (0xa94000) | spi12 | i2c12 | uart12 | —       | 52, 53, 54, 55 |
| qup1\_se6 (0xa9c000) | —     | i2c13 | uart13 | —       | 56, 57, 56, 57 |

### QUP2（SE0–SE6）

| QUP\_SE（地址）          | SPI-M | I2C-M | UART   | HS UART | GPIO 映射            |
| -------------------- | ----- | ----- | ------ | ------- | ------------------ |
| qup2\_se0 (0x880000) | spi14 | i2c14 | uart14 | —       | 80, 81, 82, 83     |
| qup2\_se1 (0x884000) | spi15 | i2c15 | uart15 | —       | 84, 85, 99, 100    |
| qup2\_se2 (0x888000) | spi16 | i2c16 | uart16 | uart16  | 86, 87, 88, 89, 90 |
| qup2\_se3 (0x88c000) | spi17 | i2c17 | uart17 | uart17  | 91, 92, 93, 94     |
| qup2\_se4 (0x890000) | spi18 | i2c18 | uart18 | —       | 95, 96, 97, 98     |
| qup2\_se5 (0x894000) | spi19 | i2c19 | uart19 | —       | 99, 100, 95, 96    |
| qup2\_se6 (0x898000) | spi20 | i2c20 | uart20 | —       | 97, 98, 95, 96     |

<Note>
  SPI-M = SPI 主机（Master）
</Note>

### QUP 通道到功能映射

| 接口      | L0   | L1   | L2   | L3    | L4    | L5    |
| ------- | ---- | ---- | ---- | ----- | ----- | ----- |
| UART    | CTS  | RFR  | Tx   | Rx    |       |       |
| HS UART | CTS  | RFR  | Tx   | Rx    |       |       |
| I2C     | SDA  | SCL  |      |       |       |       |
| SPI 主机  | MISO | MOSI | SCLK | CS\_0 | CS\_1 | CS\_2 |

## 设置设备接口

### 获取启动日志

```bash theme={null}
dmesg
```

### 列出已启用的接口

```bash theme={null}
# UART
ls /dev/tty*

# I2C
ls /dev/i2c*
```

## 加载 QUP v3 固件

固件文件位于：

```bash theme={null}
/lib/firmware/qcom/<target-name>/qupv3fw.elf
```

在内核配置中启用：

```
CONFIG_QCOM_QUP_FW_LOAD=y
```

## 设备树配置

IQ-8275 EVK 参考设备树：`arch/arm64/boot/dts/qcom/sa8295p.dtsi`

### 示例配置

<Tabs>
  <Tab title="I2C">
    ```dts theme={null}
    i2c10: i2c@a8c000 {
      compatible = "qcom,geni-i2c";
      reg = <0x0 0xa8c000 0x0 0x4000>;
      clocks = <&gcc GCC_QUPV3_WRAP1_S3_CLK>;
      clock-names = "se";
      power-domains = <&rpmhpd SA8295P_CX>;
      dmas = <&gpi_dma1 0 3 QCOM_GPI_I2C>,
             <&gpi_dma1 1 3 QCOM_GPI_I2C>;
      dma-names = "tx", "rx";
      status = "disabled";
    };
    ```
  </Tab>

  <Tab title="SPI">
    ```dts theme={null}
    spi11: spi@a90000 {
      compatible = "qcom,geni-spi";
      reg = <0x0 0xa90000 0x0 0x4000>;
      clocks = <&gcc GCC_QUPV3_WRAP1_S4_CLK>;
      clock-names = "se";
      power-domains = <&rpmhpd SA8295P_CX>;
      dmas = <&gpi_dma1 0 4 QCOM_GPI_SPI>,
             <&gpi_dma1 1 4 QCOM_GPI_SPI>;
      dma-names = "tx", "rx";
      status = "disabled";
    };
    ```
  </Tab>

  <Tab title="UART">
    ```dts theme={null}
    uart12: serial@a94000 {
      compatible = "qcom,geni-uart";
      reg = <0x0 0x00a94000 0x0 0x4000>;
      clocks = <&gcc GCC_QUPV3_WRAP1_S5_CLK>;
      clock-names = "se";
      power-domains = <&rpmhpd SA8295P_CX>;
      status = "disabled";
    };
    ```
  </Tab>
</Tabs>

## 修改串行引擎节点

<Note>
  第一步，请参阅 [Ubuntu Qualcomm IOT Platform Support](https://www.qualcomm.com/developer/software/ubuntu-on-qualcomm-iot-platforms/support) 中的 "How to build the linux-qcom kernel for Qualcomm platform?" 部分。
</Note>

<Steps>
  <Step title="设置主机">
    ```bash theme={null}
    sudo apt update && sudo apt build-dep -y linux
    sudo apt install build-essential gcc-aarch64-linux-gnu debhelper crossbuild-essential-amd64 dwarves
    sudo snap install rustup --classic && rustup install stable
    ```
  </Step>

  <Step title="确定设备上的内核版本">
    ```bash theme={null}
    uname -a
    ```
  </Step>

  <Step title="下载并检出内核">
    ```bash theme={null}
    git clone https://git.launchpad.net/~canonical-kernel/ubuntu/+source/linux-qcom/+git/noble
    cd noble
    git checkout <kernel-version>
    ```
  </Step>

  <Step title="在设备树中启用接口">
    IQ-8275 EVK 的设备树文件：

    * `qcs8275-iq-8275-evk.dts`
    * `sa8295p.dtsi`

    **示例 — 启用 UART12：**

    ```bash theme={null}
    &uart12 {
        status = "okay";
    };
    ```

    **示例 — 启用 I2C4：**

    ```bash theme={null}
    &i2c4 {
        status = "okay";
    };
    ```
  </Step>

  <Step title="构建与部署">
    ```bash theme={null}
    export ARCH=arm64
    export CROSS_COMPILE=aarch64-linux-gnu-
    fakeroot debian/rules clean
    fakeroot debian/rules binary
    ```

    提取 DTB 并复制到设备，然后重启。
  </Step>
</Steps>

## 切换串行引擎协议

```bash theme={null}
# Disable SPI, enable I2C on same engine
&spi10 { status = "disabled"; };
&i2c10 { status = "okay"; };
```

## 故障排查

```bash theme={null}
dmesg | grep -i qup
dmesg | grep -i geni
ls -la /sys/bus/i2c/devices/
ls -la /sys/bus/spi/devices/
ls -la /dev/ttyHS*
```

<AccordionGroup>
  <Accordion title="固件加载失败">
    ```bash theme={null}
    ls -la /lib/firmware/qcom/
    ```

    确认内核配置中 `CONFIG_FW_LOADER=y`。
  </Accordion>

  <Accordion title="串行引擎未探测到">
    检查设备树：`status = "okay";`

    ```bash theme={null}
    dmesg | grep -i qup
    dmesg | grep -i geni
    ```
  </Accordion>

  <Accordion title="协议冲突">
    确保每个串行引擎仅启用一种协议：

    ```bash theme={null}
    &qupv3_se5_i2c { status = "okay"; };
    &qupv3_se5_spi { status = "disabled"; };
    ```
  </Accordion>
</AccordionGroup>

## 启用所需接口

* **UART** — 参见 [UART 软件设备树配置](./UART)
* **SPI** — 参见 [SPI 软件配置](./SPI)
* **I2C** — 参见 [I2C 软件设备树配置](./I2C)
* **PCIe** — 参见 [PCIe 软件驱动配置](./PCIe)
* **USB** — 参见 [USB 配置指南](./USB)