3. Linux SPI子系统架构

Linux SPI子系统采用经典的分层架构设计，将SPI通信栈划分为三个清晰的层次：SPI核心层、SPI控制器驱动层和SPI设备驱动层。这种分层模型实现了硬件无关性与设备复用性，是理解SPI驱动开发的基础。

3.1 三层模型总体架构

下图展示了SPI子系统三层模型的完整结构，以及各层之间的数据流与控制流关系：

3.2 SPI核心层 (SPI Core)

SPI核心层位于drivers/spi/spi.c，是SPI子系统的中枢神经。它负责以下关键职责：

3.3 SPI控制器驱动 (SPI Controller Driver)

控制器驱动直接操作硬件寄存器，是SPI子系统的"执行者"。每个SoC厂商需要为自己的SPI控制器编写驱动，实现核心层定义的回调接口。

控制器驱动的核心数据结构是struct spi_controller（旧内核为struct spi_master），关键回调函数包括：

struct spi_controller {
    struct device   dev;
    struct list_head list;
    u16             bus_num;        /* 总线编号 */
    u16             num_chipselect; /* 片选数量 */
    u32             min_speed_hz;   /* 最小时钟频率 */
    u32             max_speed_hz;   /* 最大时钟频率 */
    u8              mode_bits;      /* 支持的SPI模式位 */
    int             (*transfer_one_message)(struct spi_controller *ctlr,
                                            struct spi_message *mesg);
    int             (*transfer_one)(struct spi_controller *ctlr,
                                    struct spi_device *spi,
                                    struct spi_transfer *transfer);
    int             (*prepare_message)(struct spi_controller *ctlr,
                                       struct spi_message *mesg);
    int             (*unprepare_message)(struct spi_controller *ctlr,
                                         struct spi_message *mesg);
    int             (*setup)(struct spi_device *spi);
    void            (*cleanup)(struct spi_device *spi);
    /* DMA相关 */
    bool            can_dma;
    int             (*dma_map)(struct spi_controller *ctlr,
                               struct spi_transfer *xfer);
    void            (*dma_unmap)(struct spi_controller *ctlr,
                                 struct spi_transfer *xfer);
};

控制器驱动的典型实现流程：

1. probe阶段： 获取硬件资源（时钟、中断、DMA、寄存器基址），初始化SPI控制器硬件，调用spi_register_controller()注册到核心层。
2. setup回调： 根据spi_device的mode、bits_per_word、max_speed_hz配置控制器寄存器。
3. transfer_one_message回调： 遍历消息中的transfer链表，对每个transfer调用transfer_one或直接处理。
4. 传输完成： 在中断或DMA完成回调中调用spi_finalize_current_transfer()通知核心层。

3.4 SPI设备驱动 (SPI Device Driver)

SPI设备驱动是面向具体外设的驱动层，负责实现设备特定的协议解析和数据交换。设备驱动通过核心层提供的API与控制器驱动交互，无需关心底层硬件细节。

设备驱动的核心数据结构与接口：

/* SPI设备驱动结构体 */
struct spi_driver {
    const struct spi_device_id *id_table;
    int (*probe)(struct spi_device *spi);
    int (*remove)(struct spi_device *spi);
    void (*shutdown)(struct spi_device *spi);
    struct device_driver driver;
};

/* SPI设备结构体（由核心层创建） */
struct spi_device {
    struct device       dev;
    struct spi_controller *controller;
    u32                 max_speed_hz;   /* 最大时钟频率 */
    u8                  chip_select;    /* 片选编号 */
    u8                  bits_per_word;  /* 每字位数 */
    u16                 mode;           /* SPI模式标志 */
    int                 irq;            /* 中断号（可选） */
    void                *controller_state;
    void                *controller_data;
    char                modalias[SPI_NAME_SIZE];
};

设备驱动开发的核心步骤：

设备驱动中典型的SPI数据传输模式：

/* 同步传输示例：向SPI设备写入配置寄存器 */
static int spi_device_write_reg(struct spi_device *spi, u8 reg, u8 val)
{
    int ret;
    u8 tx_buf[2] = { reg, val };
    struct spi_transfer transfer = {
        .tx_buf         = tx_buf,
        .len            = 2,
        .speed_hz       = spi->max_speed_hz,
        .bits_per_word  = 8,
        .cs_change      = 0,
        .delay_usecs    = 10,
    };
    struct spi_message msg;

    spi_message_init(&msg);
    spi_message_add_tail(&transfer, &msg);
    ret = spi_sync(spi, &msg);
    return ret;
}

/* 同步读写传输示例：读取SPI ADC转换结果 */
static int spi_device_read_adc(struct spi_device *spi, u8 *rx_data, int len)
{
    int ret;
    u8 tx_dummy = 0xFF;  /* 发送任意字节以产生时钟 */
    struct spi_transfer transfer = {
        .tx_buf         = &tx_dummy,
        .rx_buf         = rx_data,
        .len            = len,
        .speed_hz       = 1000000,  /* 1MHz */
        .bits_per_word  = 8,
    };
    struct spi_message msg;

    spi_message_init(&msg);
    spi_message_add_tail(&transfer, &msg);
    ret = spi_sync(spi, &msg);
    return ret;
}

3.5 三层模型的数据流与消息传递

下图展示了从设备驱动发起传输到硬件信号产生的完整数据流：

3.6 三层模型的关键数据结构关系

理解三层模型需要掌握以下核心数据结构之间的关联：

3.7 设备树与三层模型的交互

在现代嵌入式Linux中，SPI设备信息通常通过设备树（Device Tree）描述。设备树节点与三层模型的对应关系如下：

/* 设备树中的SPI控制器节点 */
&spi1 {
    status = "okay";
    pinctrl-names = "default";
    pinctrl-0 = <&spi1_pins>;
    cs-gpios = <&gpio3 20 GPIO_ACTIVE_LOW>;  /* 片选GPIO */

    /* SPI从设备节点 - 由核心层解析并创建spi_device */
    adc@0 {
        compatible = "ti,ads1256";
        reg = <0>;                    /* 片选编号，对应chip_select */
        spi-max-frequency = <19200000>;
        spi-cpol;                     /* 设置SPI模式为CPOL=1 */
        spi-cpha;                     /* 设置SPI模式为CPHA=1 */
        interrupts = <&gpio1 16 IRQ_TYPE_EDGE_FALLING>;
    };

    flash@1 {
        compatible = "jedec,spi-nor";
        reg = <1>;
        spi-max-frequency = <50000000>;
        spi-tx-bus-width = <4>;       /* 四线输出 */
        spi-rx-bus-width = <4>;       /* 四线输入 */
        m25p,fast-read;
    };
};

设备树解析流程：

1. SPI控制器驱动probe时，调用spi_register_controller()注册控制器。
2. 核心层在注册过程中调用of_spi_register_devices()，遍历控制器节点下的子节点。
3. 对每个子节点，核心层解析reg（片选号）、spi-max-frequency、spi-cpol/spi-cpha等属性。
4. 核心层创建spi_device实例，并添加到SPI总线。
5. SPI总线匹配spi_driver的id_table或of_match_table，调用匹配驱动的probe函数。

3.8 三层模型常见问题与排查思路