1. 这不是教科书里的“SPI驱动”——而是一份在工厂产线跑过三轮量产的实操手记你搜“Linux下SPI设备驱动编写流程”十有八九会掉进宋宝华《Linux设备驱动开发详解》的章节里或者被CSDN上那些贴了半截代码、没讲清楚spi_sync到底卡在哪一行的博客绕晕。我干这行十年从ST的STM32裸机驱动写到Rockchip平台上的国产AI芯片SPI外设适配光是为AIC8800蓝牙模块调通SPI收发就熬过两个通宵——不是因为协议看不懂而是因为真实世界里spi_sync返回-110ETIMEDOUT时示波器上看到的波形和教科书画的根本不是一回事。这篇东西不讲SPI协议四线六线的理论定义也不复述struct spi_device和struct spi_driver的字段含义。它只回答三个问题你拿到一块新SPI Flash芯片怎么在Linux里让它吐出第一字节数据为什么spi_write_then_read在某些板子上死活不触发片选当spi_sync返回-5EIO时该先查硬件还是先改驱动里的bits_per_word我把去年在某国产工控主板项目上写的SPI驱动从头到尾拆开连dmesg里那行“spi_master spi0: master is unqueued, this is deprecated”警告都给你解释清楚——这不是理论推演是焊台、示波器、逻辑分析仪和printk日志堆出来的经验。如果你正对着/sys/bus/spi/devices/spi0.0目录发愁或者刚在spi_board_info里填完modalias却找不到设备节点这篇文章就是为你写的。2. 整体设计思路为什么必须绕开“字符设备驱动框架”的惯性思维2.1 SPI驱动的本质不是“字符设备”而是“总线控制器设备实例”的双层架构很多人一上来就想套用字符设备驱动那一套register_chrdev→cdev_init→device_create。这是个致命误区。SPI在Linux内核里压根不是按字符设备模型设计的。它的核心是主控制器SPI Master和挂载其上的从设备SPI Slave的分离式架构。主控制器由SoC厂商提供比如rk3399的rockchip-spistm32的spi-stm32负责管理SCK/MOSI/MISO/CS等物理信号线而你的Flash、ADC、蓝牙模块这些只是通过spi_board_info或设备树Device Tree注册到某个Master下的一个实例。驱动开发的起点永远是确认你的硬件连接到了哪个SPI Master通道而不是急着写file_operations。我见过太多新手在drivers/spi/spi-rockchip.c里加了一堆printk结果发现根本没加载——因为设备树里spi0节点被禁用了或者cs-gpios引脚配置错了。所以第一步必须做的是用ls /sys/bus/spi/devices/看有没有spi0.0这类节点没有就说明Master没起来这时候去写设备驱动纯属白费功夫。2.2spi_sync不是万能钥匙它是同步阻塞调用必须配合超时机制和错误重试网络热词里反复出现spi_sync但它常被误用成“保证一次成功”的银弹。真相是spi_sync本质是把SPI传输请求提交给Master的队列然后当前进程睡眠等待完成。如果硬件没响应它就会一直等下去直到超时默认1秒。但问题在于这个超时值是硬编码在spi-core.c里的且无法通过API修改。我在调试ESP32-S3 SPI外设时遇到过典型场景模块上电时序不稳第一次spi_sync必然失败但直接报错退出会导致整个系统初始化卡死。解决方案不是删掉spi_sync而是把它包进一个带重试的循环里int my_spi_transfer(struct spi_device *spi, struct spi_message *msg, int retry_times) { int ret; int i; for (i 0; i retry_times; i) { ret spi_sync(spi, msg); if (ret 0) return 0; // 只对特定错误重试ETIMEDOUT-110、EIO-5 if (ret ! -ETIMEDOUT ret ! -EIO) break; msleep(10); // 每次失败后延时10ms再试 } return ret; }注意这里的关键点不是所有错误都该重试。比如-ENODEV设备不存在或-EINVAL参数非法这种错误重试一百次也没用必须立刻终止并排查配置。而-ETIMEDOUT往往意味着硬件未就绪-EIO则可能是时序参数如max_speed_hz设得太高导致信号完整性出问题。这个重试逻辑是我踩过三次产线重启事故后才加进去的——第一次是因为没重试SPI Flash初始化失败导致系统无法挂载根文件系统第二次重试没加延时高频冲击让MISO线上出现振铃第三次才定型为现在的10ms间隔。2.3 硬件片选Hardware CS与软件片选Software CS的选择直接决定驱动复杂度热搜词里提到“SPI硬件片选与软件片选”这绝非理论空谈。硬件片选由SPI Master控制器自动管理CS引脚驱动只需设置spi_device-mode | SPI_CS_HIGH或SPI_CS_LOW即可而软件片选则需要驱动手动控制GPIO在每次传输前拉低、传输后拉高。选择依据非常实际看你的SPI Master是否支持多路CS输出。以RK3399为例spi0控制器有4路硬件CScs0-cs3但spi1只有1路。如果你的板子上接了两颗SPI Flash一颗挂spi0.0cs0另一颗挂spi0.1cs1那就必须用硬件片选——否则你得在驱动里同时管理两个GPIO还要确保它们不会被其他模块占用。反之如果Master只有一路CS而你需要接多个设备比如FlashADC就必须用软件片选。此时spi_board_info里controller_data字段要传入GPIO号static struct spi_board_info my_spi_devices[] __initdata { { .modalias my_flash, .max_speed_hz 20 * 1000 * 1000, .bus_num 0, .chip_select 0, // 这里只是占位实际CS由GPIO控制 .mode SPI_MODE_0, .controller_data (void *)GPIO_TO_PIN(8, 12), // GPIO8_12作为CS } };然后在驱动probe函数里申请并控制该GPIO。这个细节决定了你后续spi_setup()调用是否成功——如果chip_select设错了spi_setup会直接返回-ENODEV连spi_sync的边都摸不到。3. 核心细节解析从设备树配置到spi_sync调用的每一步陷阱3.1 设备树Device Tree配置spiff110000节点里的五个关键字段很多开发者卡在第一步设备节点根本没出现在/sys/bus/spi/devices/下。根源几乎全在设备树配置。以Rockchip平台为例spiff110000节点必须包含以下五个字段缺一不可#address-cells和#size-cells必须设为1和0。这是SPI子节点寻址的基础设错会导致内核解析失败dmesg里出现“OF: ERROR: of_parse_phandle_with_args() failed”。pinctrl-names和pinctrl-0指定SPI引脚复用状态。比如RK3399的spi0默认复用到GPIO7_A0-A3但如果你的板子把SCK接到GPIO7_B2就必须在pinctrl里重新定义spi0 { pinctrl-names default; pinctrl-0 spi0_pins; status okay; spi0_pins: spi0-pins { pins gpio7b2, gpio7b3, gpio7b4, gpio7b5; function spi0; }; };num-cs声明硬件CS数量。设为4表示支持cs0-cs3四路片选。如果实际只用cs0也必须写1否则内核会认为该Master无效。status okay看似简单却是最常被忽略的。默认是disabled不显式启用节点就不会被加载。子节点的reg属性格式为0、1对应chip_select编号。reg 0即spi0.0reg 1即spi0.1。注意这个数字必须和spi_board_info里的chip_select一致否则spi_new_device会失败。我曾在一个客户项目里花两天时间排查最后发现reg写成了0x0十六进制而内核只认十进制0导致设备根本没注册。这种低级错误在dmesg里没有任何提示只能靠cat /proc/device-tree/spiff110000/手动检查原始DTB二进制内容才能发现。3.2spi_setup()调用时机为什么必须在probe()里而非init()中执行spi_setup()用于配置SPI设备的时序参数max_speed_hz、mode、bits_per_word但它的调用位置极其关键。常见错误是把它放在模块init函数里结果spi_setup返回-ENODEV。原因在于spi_setup必须在SPI设备结构体完全初始化后才能调用而设备结构体是在spi_add_device或spi_new_device时由内核动态创建的。正确的流程是在probe()函数中获取struct spi_device *spi指针调用spi_setup(spi)配置参数仅在此之后才能安全调用spi_sync。如果提前调用spi-master指针可能为空spi_setup会直接返回错误。更隐蔽的问题是spi_setup会根据max_speed_hz和Master的min_speed_hz/max_speed_hz范围自动计算出最终生效的speed_hz并更新spi-max_speed_hz。我调试HC32F460 SPI时发现即使设置了max_speed_hz 10000000实际spi-max_speed_hz却被修正为9600000——因为Master的时钟源分频后无法精确达到10MHz。这个修正值会直接影响spi_sync的传输速率必须用dev_info(spi-dev, actual speed: %d Hz, spi-max_speed_hz)打印出来确认。3.3spi_sync内部流程从spi_message构建到硬件中断的七步链路理解spi_sync的内部流程是解决超时和EIO错误的关键。它并非简单地发一帧数据而是一个涉及内核调度、DMA配置、硬件中断的完整链路消息构建spi_message是SPI传输的容器必须用spi_message_init()初始化并通过spi_message_add_tail()添加一个或多个spi_transfer结构体。每个spi_transfer描述一次物理传输如读1字节、写4字节。Master队列提交spi_sync调用__spi_queued_transfer()将消息加入Master的queue通常是kthread工作队列。线程唤醒Master的kthread被唤醒执行spi_queued_work()开始处理队列。硬件准备调用Master驱动的prepare_message()回调配置寄存器如设置SCK分频、模式、字长。DMA/PIO选择根据传输长度和Master能力自动选择DMA方式大数据量或PIO方式小数据量。spi_sync本身不关心这个但max_speed_hz过低时某些Master会强制走PIO导致CPU占用率飙升。启动传输调用transfer_one_message()真正写入硬件寄存器触发SPI控制器开始移位。中断等待Master在传输完成时触发中断中断处理函数调用complete()唤醒等待的进程spi_sync返回。这个链路中任何一步失败都会导致spi_sync返回错误。比如步骤4失败寄存器配置异常返回-EIO步骤6超时硬件没响应返回-ETIMEDOUT步骤2队列满Master忙返回-EBUSY。因此当spi_sync失败时必须结合dmesg里Master驱动的log如rockchip-spi spi0: transfer timeout来定位具体环节而不是盲目改max_speed_hz。3.4spi_write_then_read的隐藏陷阱它不是原子操作而是两次独立传输spi_write_then_read常被当作“写命令读数据”的快捷方式但它内部其实是两次独立的spi_sync调用先发写命令再发读请求。问题在于两次传输之间没有自动的片选保持。对于需要CS持续拉低的设备如某些SPI Flash这会导致读操作失败。解决方案是手动构造一个包含写读的spi_messagestruct spi_message msg; struct spi_transfer xfers[2]; spi_message_init(msg); xfers[0].tx_buf cmd_buf; // 写命令 xfers[0].len 1; xfers[0].cs_change 0; // CS保持低电平 spi_message_add_tail(xfers[0], msg); xfers[1].rx_buf data_buf; // 读数据 xfers[1].len 4; xfers[1].cs_change 1; // 传输后释放CS spi_message_add_tail(xfers[1], msg); ret spi_sync(spi, msg); // 一次调用完成连续读写cs_change 0是关键它告诉Master在两次传输间不要切换CS电平。这个参数在spi_write_then_read里是不可控的必须用原生spi_message才能实现。我在适配Vivado生成的SPI IP核时就是因为没设cs_change导致读取SPI Flash ID时总是得到0xFF——示波器显示CS在写命令后立刻抬高读周期完全丢失。4. 实操过程从零开始编写一个SPI Flash驱动的完整步骤4.1 环境准备虚拟机、内核源码与交叉编译工具链虽然热搜词里有“虚拟机安装linux系统”、“linux下载matlab24b破解版”但SPI驱动开发必须在真实硬件上验证。虚拟机无法模拟SPI硬件时序spi_sync调用会直接返回-ENODEV。我的标准环境是开发机Ubuntu 22.04安装build-essential、libncurses-dev、bison、flex、libssl-dev目标板Rockchip RK3399 EVB带SPI Flash芯片W25Q32内核版本5.10交叉编译工具链aarch64-linux-gnu-gcc来自Linaro版本需匹配内核要求调试工具Saleae Logic 8逻辑分析仪抓SPI波形串口转USB模块看dmesg。特别注意linux镜像和kali linux手机版完全不适用此场景。Kali是渗透测试系统内核模块编译环境缺失手机版Linux如Termux没有SPI设备节点权限。必须用标准嵌入式Linux发行版如Buildroot生成的rootfs。4.2 第一步确认SPI Master已启用并识别设备登录目标板执行# 查看SPI Master是否注册 cat /proc/interrupts | grep spi # 应看到类似123: 0 0 0 0 spi-rockchip 123 Edge spi0 # 查看设备树是否加载正确 ls /sys/bus/spi/devices/ # 正常应有 spi0.0如果设备树里reg0 # 如果没有spi0.0检查设备树 dtc -I fs /proc/device-tree -O dts -o /tmp/cur.dts # 在/tmp/cur.dts里搜索spi0确认statusokay和reg0若/sys/bus/spi/devices/为空90%概率是设备树问题。此时不要动驱动代码先用fdtput工具临时修改DTB# 将dtb转为dtb修改status再转回 fdtget my.dtb /spiff110000 status fdtput -t s my.dtb /spiff110000 status okay烧写后重启再检查。这一步省掉后面所有代码都是空中楼阁。4.3 第二步编写最小可运行驱动框架创建drivers/spi/spi-myflash.c内容精简到极致#include linux/module.h #include linux/spi/spi.h #include linux/of.h static int myflash_probe(struct spi_device *spi) { dev_info(spi-dev, MyFlash probed successfully); return 0; } static int myflash_remove(struct spi_device *spi) { dev_info(spi-dev, MyFlash removed); return 0; } static const struct spi_device_id myflash_id[] { {my_flash, 0}, {} }; MODULE_DEVICE_TABLE(spi, myflash_id); static const struct of_device_id myflash_of_match[] { { .compatible my,flash }, {} }; MODULE_DEVICE_TABLE(of, myflash_of_match); static struct spi_driver myflash_driver { .driver { .name my_flash, .of_match_table myflash_of_match, }, .id_table myflash_id, .probe myflash_probe, .remove myflash_remove, }; module_spi_driver(myflash_driver); MODULE_LICENSE(GPL);编译进内核CONFIG_SPI_MYFLASHminsmod spi-myflash.ko。dmesg应输出“MyFlash probed successfully”。如果没输出检查modalias是否匹配cat /sys/bus/spi/devices/spi0.0/modalias应为spi:my_flash。不匹配就说明设备树里compatible my,flash和驱动里的.compatible没对上。4.4 第三步实现SPI数据收发核心逻辑在myflash_probe中加入实际传输代码static int myflash_probe(struct spi_device *spi) { int ret; u8 tx_buf[4] {0x9f, 0, 0, 0}; // RDID命令 u8 rx_buf[4] {0}; // 配置SPI参数 spi-max_speed_hz 20 * 1000 * 1000; spi-mode SPI_MODE_0; spi-bits_per_word 8; ret spi_setup(spi); if (ret 0) { dev_err(spi-dev, spi_setup failed: %d\n, ret); return ret; } // 构建消息发送RDID命令读取3字节ID struct spi_message msg; struct spi_transfer xfer { .tx_buf tx_buf, .rx_buf rx_buf, .len 4, .bits_per_word 8, }; spi_message_init(msg); spi_message_add_tail(xfer, msg); ret spi_sync(spi, msg); if (ret 0) { dev_err(spi-dev, spi_sync failed: %d\n, ret); return ret; } dev_info(spi-dev, Flash ID: 0x%02x%02x%02x, rx_buf[1], rx_buf[2], rx_buf[3]); return 0; }编译加载后dmesg应输出Flash ID如0xef4016。如果输出0xff ff ff说明MISO线没接好或max_speed_hz过高如果卡住无输出大概率是spi_sync超时需降低max_speed_hz到1MHz再试。4.5 第四步添加健壮性处理与调试接口生产环境驱动必须包含错误恢复和用户空间交互。在驱动中添加// 添加sysfs接口允许用户触发读ID static ssize_t flash_id_show(struct device *dev, struct device_attribute *attr, char *buf) { struct spi_device *spi to_spi_device(dev); u8 tx_buf[4] {0x9f, 0, 0, 0}; u8 rx_buf[4] {0}; struct spi_message msg; struct spi_transfer xfer {.tx_buftx_buf, .rx_bufrx_buf, .len4}; spi_message_init(msg); spi_message_add_tail(xfer, msg); if (spi_sync(spi, msg) 0) return sprintf(buf, %02x%02x%02x\n, rx_buf[1], rx_buf[2], rx_buf[3]); return -EIO; } static DEVICE_ATTR_RO(flash_id); // probe中添加 ret device_create_file(spi-dev, dev_attr_flash_id); if (ret) dev_warn(spi-dev, Failed to create flash_id sysfs\n); // remove中添加 device_remove_file(spi-dev, dev_attr_flash_id);加载驱动后执行cat /sys/bus/spi/devices/spi0.0/flash_id即可随时读取ID无需重启模块。这个接口在产线测试时极大提升了效率——测试员不用每次改代码、编译、加载直接shell命令就能验证SPI链路。5. 常见问题与排查技巧实录那些示波器和dmesg不会告诉你的事5.1 典型问题速查表现象可能原因排查命令/工具解决方案dmesg无任何SPI相关输出设备树status未设为okay或compatible不匹配cat /proc/device-tree/spiff110000/status修改DTB确保statusokay且compatible与驱动一致spi_sync返回-110ETIMEDOUTmax_speed_hz过高导致信号失真或硬件未上电逻辑分析仪抓SCK波形看是否稳定降低max_speed_hz至1MHz逐步提高检查Flash供电电压spi_sync返回-5EIObits_per_word与硬件不匹配如Flash要求8bit驱动设为16bitdmesg | grep -i spi.*error查阅芯片手册确认bits_per_word必须为8/sys/bus/spi/devices/下无设备节点spi_board_info未注册或chip_select超出num-cs范围cat /proc/interrupts | grep spi检查num-cs是否≥chip_select值确认spi_register_board_info被调用读取数据全为0xffMISO线虚焊或接触不良或spi_setup未调用万用表测MISO对地电阻重新焊接MISO引脚确保spi_setup在spi_sync前调用5.2 独家避坑技巧从产线血泪史中总结的三条铁律提示SPI波形调试必须用逻辑分析仪示波器带宽不够看不清边沿示波器适合测电源和时钟幅度逻辑分析仪才能抓到SCK-MOSI-MISO-CS的精确时序关系。我用过Keysight和Saleae后者性价比更高8通道足够应付SPI四线。注意spi_sync失败后必须调用spi_reset如果Master驱动支持或重启SPI Master某些Master如STM32的spi-stm32在传输错误后会锁死spi_sync后续调用全部失败。此时echo 1 /sys/bus/platform/drivers/rockchip-spi/unbind再echo 1 /sys/bus/platform/drivers/rockchip-spi/bind可软重启Master比整机重启快十倍。警告不要在spi_transfer中使用栈变量作为tx_buf/rx_bufspi_sync可能睡眠栈变量在进程切换后地址失效。必须用kmalloc分配内存或使用全局缓冲区。我曾因此导致系统随机panic花了三天才定位到是栈变量被覆盖。5.3 实战案例AIC8800蓝牙模块SPI收发调试全记录客户提供的AIC8800模块文档极简只说“支持SPI通信”没给时序图。我们按常规SPI_MODE_0配置spi_sync始终返回-EIO。排查过程如下第一步抓波形逻辑分析仪显示SCK有波形但MOSI全是0x00——说明驱动没把数据写进TX FIFO。检查发现spi_transfer.len设为0因为tx_buf指针为空。第二步查时序手册里提到“数据在SCK上升沿采样”但示波器显示实际是下降沿。改为SPI_MODE_2CPOL1, CPHA0后MOSI数据正常发出。第三步解协议发送0x01reset命令后模块应返回0x02但rx_buf全是0x00。发现模块要求CS在传输期间必须保持低电平超过100us而spi_sync默认CS脉冲太短。解决方案用spi_message构造两次传输中间加udelay(100)并设cs_change 0。最终驱动代码片段// 发送reset命令CS保持100us xfers[0].tx_buf reset_cmd; xfers[0].len 1; xfers[0].cs_change 0; spi_message_add_tail(xfers[0], msg); udelay(100); // 强制CS保持 xfers[1].rx_buf resp; xfers[1].len 1; xfers[1].cs_change 1; spi_message_add_tail(xfers[1], msg);这个案例说明SPI驱动不是套公式而是和硬件“对话”。每一个-EIO背后都藏着芯片手册里一行不起眼的时序要求。5.4 性能优化如何让SPI传输速度突破理论瓶颈热搜词里有“vivado spi的使用”、“spi速率”但实际速率受多重制约。理论最大值master_clk / (2 * prescaler)但真实世界里信号完整性PCB走线长度10cm时20MHz以上需加终端电阻。我用RK3399跑40MHz结果MISO信号过冲严重误码率100%。加33Ω串联电阻后稳定跑到33MHz。DMA瓶颈某些Master如Allwinner H3的DMA引擎不支持scatter-gather大数据量传输需拆分成≤4KB的块。CPU调度spi_sync在高负载时可能因进程调度延迟导致CS脉冲不稳。改用spi_asynccompletion机制可将CPU占用率从95%降至15%。优化后的异步传输框架static void async_complete(void *arg) { struct completion *done arg; complete(done); } static int async_spi_read(struct spi_device *spi, u8 *buf, size_t len) { struct completion done; struct spi_message msg; struct spi_transfer xfer {.rx_bufbuf, .lenlen}; init_completion(done); spi_message_init(msg); spi_message_add_tail(xfer, msg); msg.complete async_complete; msg.context done; spi_async(spi, msg); wait_for_completion(done); return 0; }这个方案在某车载T-Box项目中将SPI ADC数据采集吞吐量从12MB/s提升到28MB/s关键就在于绕开了spi_sync的进程睡眠开销。我在实际使用中发现SPI驱动开发最耗时的从来不是写代码而是读懂硬件手册里那张微小的时序图。那些标注着“tCSS: 10ns min”的参数往往就是spi_sync返回-5的根源。与其在网上搜“linux spi驱动教程”不如把示波器探头焊到SCK引脚上亲眼看看波形是不是你期望的样子。毕竟Linux内核不会骗人但芯片手册里的印刷错误可能让你调试三天。