4. 设备树中SPI节点配置

在Linux内核中，SPI总线设备的硬件拓扑与配置参数通过设备树（Device Tree）进行描述。设备树为驱动提供了与硬件解耦的静态描述机制，使得同一份内核镜像可以适配不同板级配置。SPI设备树节点主要分为两类：SPI控制器节点（描述SoC内部的SPI主机控制器）和SPI从设备节点（描述挂载在SPI总线上的外设）。正确配置这些节点是SPI通信正常工作的前提。

4.1 SPI控制器节点

SPI控制器节点通常位于SoC的soc或ahb总线节点下，描述了SPI主机控制器的寄存器基址、中断号、时钟源、DMA请求线以及Pinctrl配置。控制器节点是SPI子系统的根节点，所有挂载在该控制器下的从设备节点都必须作为其子节点存在。

以下是一个典型的SPI控制器节点示例（以i.MX6ULL为例）：

&ecspi1 {
    pinctrl-names = "default";
    pinctrl-0 = &pinctrl_ecspi1;
    cs-gpios = <&gpio4 9 GPIO_ACTIVE_LOW>;
    status = "okay";

    spidev0: spidev@0 {
        compatible = "spidev";
        reg = <0>;
        spi-max-frequency = <1000000>;
    };
};

控制器节点关键属性说明：

4.2 SPI从设备节点

SPI从设备节点描述了挂载在SPI总线上的具体外设。每个从设备节点必须包含compatible、reg和spi-max-frequency三个核心属性。从设备节点是驱动匹配的入口，内核通过compatible属性查找对应的SPI设备驱动。

从设备节点典型结构：

&ecspi1 {
    status = "okay";

    /* 第一个从设备：温度传感器 */
    temp_sensor: max31865@0 {
        compatible = "maxim,max31865";
        reg = <0>;
        spi-max-frequency = <5000000>;
        spi-cpha;
        spi-cpol;
        status = "okay";
    };

    /* 第二个从设备：ADC转换器 */
    adc_device: ads1256@1 {
        compatible = "ti,ads1256";
        reg = <1>;
        spi-max-frequency = <19200000>;
        interrupts-extended = <&gpio5 19 IRQ_TYPE_EDGE_FALLING>;
        status = "okay";
    };
};

4.3 reg属性详解

reg属性在SPI从设备节点中表示该设备使用的片选（Chip Select, CS）索引号。SPI控制器通常支持多个片选信号（CS0、CS1、CS2...），每个片选对应一条独立的硬件CS线。内核通过解析reg值来确定在发起SPI传输时应该拉低哪条CS线。

4.4 spi-max-frequency属性

spi-max-frequency定义了该从设备支持的最高SPI时钟频率，单位是Hz。内核SPI核心层在初始化传输时会读取该属性，并将其作为SCLK频率的上限。实际传输频率由控制器驱动根据硬件能力向下取整。

频率配置原则：

• 不能超过控制器支持的最高频率：例如i.MX6ULL的ECSPI最高频率为60MHz，设置spi-max-frequency = <100000000>会被内核自动截断。
• 不能超过从设备数据手册规定的最高频率：例如某SPI Flash最高支持50MHz，设置80MHz会导致通信不稳定或数据错误。
• 频率越低，信号完整性越好：在长距离传输或高噪声环境下，适当降低频率可以提高通信可靠性。

/* 频率配置示例 */
/* 低速传感器，最高1MHz */
spi-max-frequency = <1000000>;

/* 高速SPI Flash，最高50MHz */
spi-max-frequency = <50000000>;

/* 调试阶段建议使用较低频率，排除时序问题 */
spi-max-frequency = <500000>;  /* 500KHz，适合调试 */

4.5 SPI模式属性（spi-cpha / spi-cpol）

SPI有四种工作模式，由时钟极性（CPOL）和时钟相位（CPHA）组合决定。设备树通过以下布尔属性配置SPI模式：

/* 模式3配置示例 */
spi-cpol;   /* 时钟空闲时为高电平 */
spi-cpha;   /* 数据在时钟的第二个边沿采样 */

4.6 其他关键属性

除了上述核心属性外，SPI从设备节点还支持以下常用属性：

• spi-cs-high：片选信号高电平有效（默认低电平有效）。某些设备要求CS在高电平时被选中。
• spi-3wire：使用三线制SPI（省略MISO或MOSI），适用于半双工设备。
• spi-lsb-first：数据以LSB（最低有效位）优先传输（默认MSB优先）。
• spi-rx-bus-width 和 spi-tx-bus-width：用于Quad SPI或Dual SPI模式，设置数据线宽度。
• interrupts 或 interrupts-extended：从设备的中断引脚，用于事件通知。

/* 完整配置示例：使用四线SPI的Flash设备 */
spi_flash: flash@0 {
    compatible = "jedec,spi-nor";
    reg = <0>;
    spi-max-frequency = <80000000>;
    spi-rx-bus-width = <4>;   /* Quad SPI读取 */
    spi-tx-bus-width = <4>;   /* Quad SPI写入 */
    spi-cpol;
    spi-cpha;
    m25p,fast-read;
    status = "okay";
};

4.7 常见配置错误与排查方法

设备树SPI节点配置错误会导致驱动无法加载或通信异常。以下汇总了最常见的错误场景及排查方法：