> ## 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-9075 SoC 中使用的低速和高速 I/O 外设接口子系统。

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

* UART、SPI、I2C、I3C

**高速接口：**

* PCIe、USB

## IQ-9075 接口概览

| 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 高速 |

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

### QUP3（SE0）

| QUP\_SE（地址）          | SPI-M | I2C-M | UART   | GPIO 映射                    |
| -------------------- | ----- | ----- | ------ | -------------------------- |
| qup3\_se0 (0xb80000) | spi21 | i2c21 | uart21 | 13, 14, 15, 16, 17, 18, 19 |

<Note>
  SPI-M = SPI 主机
</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 |

## 设置设备接口

<img src="https://mintcdn.com/qualcomm-prod/P0rmO3AZfXx7cgqQ/Ubuntu/images/peripheral-interfaces/setup_infrastructure_interfaces.png?fit=max&auto=format&n=P0rmO3AZfXx7cgqQ&q=85&s=9d27c9e99803621c4c10d4531486f93d" width="1216" height="307" data-path="Ubuntu/images/peripheral-interfaces/setup_infrastructure_interfaces.png" />

### 获取启动日志

```bash theme={null}
# SSH to device, then:
dmesg
```

### 列出已启用的接口

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

# I2C
ls /dev/i2c*
# Expected: /dev/i2c-18  /dev/i2c-19  /dev/i2c-20  /dev/i2c-21  /dev/i2c-22
```

## 加载 QUP v3 固件

应用处理器的串行引擎由 Linux 内核管理。固件文件位于：

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

在内核配置中启用：

```
CONFIG_QCOM_QUP_FW_LOAD=y   # in qcom_defconfig
CONFIG_QCOM_QUP_FW_LOAD=m   # in qcom_vm_defconfig
```

## 设备树配置

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

### 配置示例

<Tabs>
  <Tab title="I2C">
    ```bash theme={null}
    i2c10: i2c@a8c000 {
      compatible = "qcom,geni-i2c";
      reg = <0x0 0xa8c000 0x0 0x4000>;
      interrupts = <GIC_SPI 356 IRQ_TYPE_LEVEL_HIGH>;
      clocks = <&gcc GCC_QUPV3_WRAP1_S3_CLK>;
      clock-names = "se";
      pinctrl-0 = <&qup_i2c10_default>;
      pinctrl-names = "default";
      power-domains = <&rpmhpd SA8775P_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">
    ```bash theme={null}
    spi11: spi@a90000 {
      compatible = "qcom,geni-spi";
      reg = <0x0 0xa90000 0x0 0x4000>;
      interrupts = <GIC_SPI 357 IRQ_TYPE_LEVEL_HIGH>;
      clocks = <&gcc GCC_QUPV3_WRAP1_S4_CLK>;
      clock-names = "se";
      pinctrl-0 = <&qup_spi11_default>;
      pinctrl-names = "default";
      power-domains = <&rpmhpd SA8775P_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">
    ```bash theme={null}
    uart12: serial@a94000 {
      compatible = "qcom,geni-uart";
      reg = <0x0 0x00a94000 0x0 0x4000>;
      interrupts = <GIC_SPI 358 IRQ_TYPE_LEVEL_HIGH>;
      clocks = <&gcc GCC_QUPV3_WRAP1_S5_CLK>;
      clock-names = "se";
      pinctrl-0 = <&qup_uart12_default>;
      pinctrl-names = "default";
      power-domains = <&rpmhpd SA8775P_CX>;
      status = "disabled";
    };
    ```
  </Tab>
</Tabs>

### 设备树属性

| 属性                  | 类型      | 描述                  | 是否必需 |
| ------------------- | ------- | ------------------- | ---- |
| `status`            | 字符串     | `okay` 或 `disabled` | 是    |
| `clock-frequency`   | u32     | I2C 时钟频率（Hz）        | 可选   |
| `spi-max-frequency` | u32     | SPI 最大频率（Hz）        | 可选   |
| `pinctrl-names`     | 字符串数组   | 引脚控制状态名称            | 推荐   |
| `pinctrl-0`         | phandle | 默认引脚配置              | 推荐   |

## 修改串行引擎节点

要启用或更改串行引擎，需修改设备树并重新构建内核。

<Note>
  第一步请参阅 [Ubuntu Qualcomm IOT 平台支持](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
    # Example: Linux ubuntu 6.8.0-1064-qcom ...
    ```
  </Step>

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

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

    * `qcs9075-addons-iq-9075-evk.dts`
    * `qcs9075-iq-9075-evk.dts`
    * `sa8775p.dtsi`

    **示例 — 启用 UART12：**

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

    **示例 — 启用 I2C4：**

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

  <Step title="构建内核">
    ```bash theme={null}
    cd noble
    export ARCH=arm64
    export $(dpkg-architecture -aarm64)
    export CROSS_COMPILE=aarch64-linux-gnu-
    fakeroot debian/rules clean
    fakeroot debian/rules binary
    ```
  </Step>

  <Step title="提取并部署 DTB">
    ```bash theme={null}
    mkdir out
    dpkg-deb -x linux-modules-6.8.0-1064-qcom_6.8.0-1064.65_arm64.deb ./out

    scp out/lib/firmware/6.8.0-1012-qcom/device-tree/qcom/qcs9075-iq-9075-evk.dtb \
      ubuntu@<ip>:/home/ubuntu/

    ssh ubuntu@<ip>
    sudo mv /home/ubuntu/qcs9075-iq-9075-evk.dtb \
      /usr/lib/firmware/6.8.0-1064-qcom/device-tree/qcom/
    sudo reboot
    ```
  </Step>
</Steps>

## 切换串行引擎协议

要将串行引擎从一种协议转换为另一种协议（例如 SPI10 → I2C10）：

```bash theme={null}
# In qcs9075-iq-9075-evk.dts:

# Disable SPI
&spi10 {
    status = "disabled";
};

# Enable I2C
&i2c10 {
    status = "okay";
};
```

## 故障排查

```bash theme={null}
# List I2C buses
ls -la /sys/bus/i2c/devices/

# List SPI buses
ls -la /sys/bus/spi/devices/

# Check UART devices
ls -la /dev/ttyHS*

# QUP-related kernel messages
dmesg | grep -i qup
dmesg | grep -i geni
dmesg | grep -i firmware

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

<AccordionGroup>
  <Accordion title="固件加载失败">
    **症状：** `qcom-geni-se: firmware request failed`

    ```bash theme={null}
    ls -la /lib/firmware/qcom/
    # Verify CONFIG_FW_LOADER=y in kernel config
    ```
  </Accordion>

  <Accordion title="串行引擎未被探测">
    **症状：** 未创建设备节点；驱动未加载。

    检查设备树：`status = "okay";`（而不是 `"ok"` 或 `"enable"`）

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

  <Accordion title="协议冲突">
    **症状：** `qcom-geni-se: serial engine is already in use`

    确保每个串行引擎只启用一种协议：

    ```bash theme={null}
    # WRONG — both enabled
    &qupv3_se5_i2c { status = "okay"; };
    &qupv3_se5_spi { status = "okay"; };

    # CORRECT — only one enabled
    &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)