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

# SPI

串行外设接口(SPI)是一种同步、全双工的 4 线串行总线。

<img src="https://mintcdn.com/qualcomm-prod/jy6NQT2Y7J_sAxdX/Linux/images/peripheral-interfaces/spi_protocol.png?fit=max&auto=format&n=jy6NQT2Y7J_sAxdX&q=85&s=2fdb35af0b47a2602919297e94b0200b" width="724" height="426" data-path="Linux/images/peripheral-interfaces/spi_protocol.png" />

## 信号

| 信号       | 说明                      |
| -------- | ----------------------- |
| **MOSI** | 控制器数据输出,目标设备数据输入        |
| **MISO** | 控制器数据输入,目标设备数据输出        |
| **SCLK** | 由控制器生成的时钟               |
| **CS**   | 片选(低电平有效);每条总线最多 4 条片选线 |

## 各子系统的传输模式

| 子系统       | 传输模式             | 最高速率   | 备注                  |
| --------- | ---------------- | ------ | ------------------- |
| **Linux** | FIFO、CPU DMA、GSI | 50 MHz | 每字 4–32 位;最多 4 个 CS |
| **Boot**  | 仅 FIFO           | 50 MHz | 轮询模式;不支持 GSI        |
| **aDSP**  | 全/半双工,同步         | 50 MHz | 原始位级传输;无成帧或错误校验     |

## 接口组件

### 设备树源文件

| 平台                 | 文件                                      |
| ------------------ | --------------------------------------- |
| Dragonwing IQ-8275 | `arch/arm64/boot/dts/qcom/qcs8300.dtsi` |

### API

| 子系统   | 头文件                                                         |
| ----- | ----------------------------------------------------------- |
| Linux | `include/uapi/linux/spi/spidev.h`、`include/linux/spi/spi.h` |
| Boot  | `boot_images/boot/QcomPkg/Include/SpiApi.h`                 |
| aDSP  | `adsp_proc/core/api/buses/spi_api.h`                        |

## 软件配置

### Linux 设备树示例

```dts theme={null}
spi@a98000 {
    compatible = "qcom,geni-spi";
    reg = <0 0x00a98000 0 0x4000>;
    clocks = <&gcc GCC_QUPV3_WRAP1_S6_CLK>;
    clock-names = "se";
    pinctrl-names = "default";
    pinctrl-0 = <&qup_spi14_data_clk>, <&qup_spi14_cs>;
    interrupts = <GIC_SPI 368 IRQ_TYPE_LEVEL_HIGH>;
    #address-cells = <1>;
    #size-cells = <0>;
    power-domains = <&rpmhpd SA8295P_CX>;
    dmas = <&gpi_dma1 0 6 QCOM_GPI_SPI>,
           <&gpi_dma1 1 6 QCOM_GPI_SPI>;
    dma-names = "tx", "rx";
    status = "disabled";
};
```

### QUPAC 访问控制

```c theme={null}
{ QUPV3_0_SE3, QUPV3_PROTOCOL_SPI, QUPV3_MODE_FIFO, AC_HLOS, TRUE,  TRUE, FALSE },
{ QUPV3_1_SE3, QUPV3_PROTOCOL_SPI, QUPV3_MODE_FIFO, AC_HLOS, FALSE, TRUE, TRUE  },
{ QUPV3_1_SE4, QUPV3_PROTOCOL_SPI, QUPV3_MODE_GSI,  AC_TZ,   FALSE, TRUE, TRUE  },
{ QUPV3_1_SE6, QUPV3_PROTOCOL_SPI, QUPV3_MODE_GSI,  AC_HLOS, FALSE, TRUE, FALSE },
```

## 配置步骤

<Steps>
  <Step title="启用内核配置">
    编辑 `kernel_platform/kernel/arch/arm64/configs/qcom_defconfig`:

    ```
    CONFIG_QCOM_GENI_SE=y
    CONFIG_SPI_QCOM_GENI=m
    CONFIG_SPI_SPIDEV=m
    CONFIG_QCOM_GPI_DMA=m
    ```
  </Step>

  <Step title="在设备树中启用 SPI 节点">
    ```dts theme={null}
    &spi1 {
        status = "okay";
    };
    ```
  </Step>

  <Step title="编译并烧录">
    编译内核和设备树的更改,然后将镜像加载到设备。
  </Step>
</Steps>

## 验证

<Steps>
  <Step title="将 spidev_test 传输到设备">
    ```bash theme={null}
    scp spidev_test root@<IP address>:/usr
    chmod 777 /usr/spidev_test
    ```
  </Step>

  <Step title="运行测试">
    ```bash theme={null}
    ./spidev_test -D /dev/spidev1.0
    ```

    **预期输出:**

    ```
    spi mode: 0x0
    bits per word: 8
    max speed: 500000 Hz (500 KHz)
    ```
  </Step>
</Steps>

## 调试

```bash theme={null}
sudo su
mount -t debugfs none /sys/kernel/debug
echo -n "file spi-geni-qcom.c +p" > /sys/kernel/debug/dynamic_debug/control
echo -n "file spidev.c +p" > /sys/kernel/debug/dynamic_debug/control
echo -n "file gpi.c +p" > /sys/kernel/debug/dynamic_debug/control
```

## 故障排除

<AccordionGroup>
  <Accordion title="未检测到 SPI 设备">
    ```bash theme={null}
    zcat /proc/config.gz | grep -E 'CONFIG_SPI_SPIDEV|CONFIG_SPI_QCOM_GENI'
    dmesg | grep -i spi
    ```

    * 确认设备树中 SPI 节点状态为 `"okay"`
    * 确认 `QUPAC_Access.c` 中设置了 `QUPV3_PROTOCOL_SPI`、`AC_HLOS`、`bLoad=TRUE`
  </Accordion>

  <Accordion title="SPI 传输失败">
    ```bash theme={null}
    ./spidev_test -D /dev/spidev1.0 -s 1000000
    ```

    * 检查 GPIO 驱动强度和上下拉配置
    * 确认时钟相位和极性与目标设备匹配
  </Accordion>

  <Accordion title="GSI/DMA 模式不工作">
    * 确认 `CONFIG_QCOM_GPI_DMA=m`
    * 检查设备树中的 `dmas` 和 `dma-names`
    * 确认 `QUPAC_Access.c` 中设置了 `QUPV3_MODE_GSI`
  </Accordion>
</AccordionGroup>

## 资源

* [SPI 驱动源码](https://github.com/torvalds/linux/blob/master/drivers/spi/spi-geni-qcom.c)
* [SPI 设备树绑定](https://github.com/torvalds/linux/blob/master/Documentation/devicetree/bindings/spi/qcom%2Cspi-geni-qcom.yaml)
* [SPI 用户 API](https://github.com/torvalds/linux/blob/master/include/uapi/linux/spi/spidev.h)