3. 设备树中SPI节点的描述

在嵌入式Linux系统中，SPI外设的硬件拓扑与驱动绑定完全通过设备树（Device Tree）描述。设备树节点分为两层：SPI控制器节点（定义主机端SPI总线能力）和SPI从设备子节点（定义挂载在总线上的具体外设）。正确配置这两层节点的属性，是SPI驱动正常工作的前提。

3.1 SPI控制器节点属性

SPI控制器节点通常位于SoC的soc或amba总线节点下，其compatible属性匹配对应的SPI主机驱动。以下为典型控制器节点属性清单：

以下为完整的SPI控制器节点示例（以Rockchip RK3399为例）：

spi0: spi@ff1c0000 {
    compatible = "rockchip,rk3399-spi";
    reg = <0xff1c0000 0x1000>;
    interrupts = ;
    clocks = <&cru SCLK_SPI0>, <&cru PCLK_SPI0>;
    clock-names = "spi", "apb_pclk";
    dmas = <&dmac 0>, <&dmac 1>;
    dma-names = "tx", "rx";
    #address-cells = <1>;
    #size-cells = <0>;
    status = "disabled";
    /* 子节点在此处添加 */
};

3.2 SPI从设备子节点属性

每个挂载在SPI总线上的外设，在控制器节点内以一个子节点表示。子节点的reg属性指定片选编号，compatible属性匹配具体设备驱动。以下为关键属性详解：

3.2.1 reg属性——片选编号

reg在SPI子节点中表示片选线索引（CS index），从0开始。控制器根据该值驱动对应的GPIO或硬件片选信号。一个控制器最多支持多个片选，具体数量由硬件决定。

/* 片选0上的温度传感器 */
temp_sensor: sensor@0 {
    reg = <0>;          /* CS0 */
    compatible = "ti,lm70";
    spi-max-frequency = <5000000>;
};

/* 片选1上的ADC */
adc_device: adc@1 {
    reg = <1>;          /* CS1 */
    compatible = "ti,ads7950";
    spi-max-frequency = <10000000>;
};

3.2.2 compatible属性——驱动匹配

格式为"厂商,型号"，内核SPI设备驱动通过of_match_table匹配该字符串。支持多级兼容（如"ti,lm70", "ti,lm71"），驱动优先匹配第一个。

3.2.3 spi-max-frequency属性——最大通信速率

指定该从设备支持的最大SPI时钟频率（单位Hz）。控制器驱动在初始化时会根据该值配置SCLK分频系数。实际通信速率不得超过该值，否则可能导致数据错误。

3.2.4 SPI模式属性

通过以下布尔属性配置SPI模式（CPOL/CPHA组合）：

模式组合示例：

/* SPI模式3：CPOL=1, CPHA=1 */
flash@0 {
    reg = <0>;
    compatible = "jedec,spi-nor";
    spi-max-frequency = <80000000>;
    spi-cpol;      /* 空闲高电平 */
    spi-cpha;      /* 第二个边沿采样 */
};

3.3 完整设备树节点示例

以下展示一个包含两个从设备的完整SPI控制器节点：

&spi0 {
    status = "okay";
    pinctrl-names = "default";
    pinctrl-0 = <&spi0_clk &spi0_csn0 &spi0_mosi &spi0_miso>;

    /* 从设备1：SPI NOR Flash */
    flash@0 {
        reg = <0>;
        compatible = "jedec,spi-nor";
        spi-max-frequency = <50000000>;
        spi-cpol;
        spi-cpha;
        m25p,fast-read;
        partitions {
            compatible = "fixed-partitions";
            #address-cells = <1>;
            #size-cells = <1>;
            partition@0 {
                label = "bootloader";
                reg = <0x0 0x100000>;
            };
            partition@100000 {
                label = "kernel";
                reg = <0x100000 0x300000>;
            };
        };
    };

    /* 从设备2：SPI温度传感器 */
    temp@1 {
        reg = <1>;
        compatible = "ti,lm70";
        spi-max-frequency = <5000000>;
        spi-3wire;          /* 三线模式 */
    };
};

3.4 常见配置错误与排查