RT-Thread CAN 框架正在重构:为什么要改、相比旧版好在哪里,以及邀请社区一起验证

摘要:RT-Thread CAN 框架重构 PR #12054 移除 Generic TX 软件队列,明确邮箱所有权与发送终态,补充 Abort、Drain 和重配置保护。对比旧版设计,介绍已提交的适配,并邀请各 BSP 参与实机验证。

在这里插入图片描述

[TOC]

CAN(Controller Area Network,控制器局域网)广泛用于工业控制、车辆电子和嵌入式设备通信。多个节点通过 CAN 总线交换带标识符(CAN ID)的数据帧;发送端先将帧提交给 CAN 控制器的发送资源,再由控制器参与总线仲裁和实际发送。RT-Thread 的 Generic CAN Framework 位于应用/协议栈与芯片厂商 CAN 驱动之间,向上提供统一设备接口,向下调用 BSP 的硬件操作,并接收中断上报。框架负责什么、上层负责什么,直接决定了发送拥塞、错误恢复和动态重配置时能否准确管理尚未完成的报文。[S1][S2]

近期的 CAN 框架重构 PR #12054 正在尝试解决这一问题。这里讨论的是尚在评审中的代码,不是已经发布到 RT-Thread 正式版本的功能。截至 2026 年 11 月 15 日,PR 仍处于 Open 状态;本文按其当前提交 cbc5cbab53a4d9a63fb8f745deb96473f6948b6f 介绍。[S1]

为什么已有 CAN 框架还需要重构?

原有框架已经支持 CAN 收发,也有 Blocking(阻塞)和 Nonblocking(非阻塞)发送接口。问题不在于“完全不能用”,而在于:同一组硬件发送邮箱,由框架内部两套不同的资源和排队机制管理;需求一旦涉及发送取消、超时和运行时重配置,两套状态便很难保持一致。[S2][S7]

1. Blocking 和 Nonblocking 曾经是两套发送管理机制

旧版 Blocking 发送由 _can_int_tx() 等路径管理。框架为发送邮箱建立链表形式的空闲表(freelist),配合信号量、每邮箱 completion 和发送状态,选中资源后调用 BSP 的 sendmsg(),再等待终态事件。[S2]

旧版 Nonblocking 则走 _can_nonblocking_tx():先调用 sendmsg_nonblocking(),如果硬件暂时无法接收,还可以把帧放进 Generic CAN 自己维护的 nb_tx_rb 软件环形缓冲区。后续 TX 中断再取帧、重新尝试提交。由此,框架同时承担了驱动设备抽象和发送排队/补发调度两种角色。[S2]

这意味着:Blocking 管理的是“哪个邮箱归谁、谁在等结果”,Nonblocking 还要管理“哪些帧仍在软件队列里、何时重新送到硬件”。它们最终使用同一套硬件资源,却有不同的生命周期和并发路径。继续往上叠加新功能,往往需要同时修改两套逻辑。

2. Nonblocking 返回成功,不代表硬件已经接收该帧

这是一处影响应用设计的语义差异。

过去,非阻塞写入返回成功,可能只表示帧已经进入 nb_tx_rb;帧当时尚未占用任何硬件邮箱。应用和协议栈难以仅凭这一返回结果确定,待发送帧究竟还在软件队列、已经交给控制器,还是正在总线上仲裁。[S2]

对于普通连续发送,这层缓冲能吸收短暂突发;但在以下场景,它又成了需要额外管理的状态:

  • CANopen LSS 动态切换波特率:上层停止产生新帧后,旧的软件队列和硬件邮箱里仍可能有待发送帧;
  • Bus-off 恢复、控制器重新初始化:需要知道哪些报文仍属本次控制器运行周期;
  • 协议复位或设备关闭:不希望重新启用发送后,历史队列又把旧帧发出去;
  • 实时控制:排队的旧控制指令可能不如直接丢弃旧值、优先发送新值更合适。

其中,CANopen LSS 的 TX 静默窗口正是此前 Full Flush / Hardware Abort 需求讨论 的直接动机。[S7]

3. 发送终态与邮箱所有权必须是一回事

CAN 控制器接受一帧后,最终还应通过 TX_DONE(发送成功)或 TX_FAIL(发送失败、被取消等)上报该次发送的结束。软件等待超时并不等于硬件停止发送;提交 Abort 请求也不等于硬件已完成取消。[S3][S4]

如果某个邮箱刚完成旧帧、终态中断却尚未被框架结算,软件就把该邮箱交给新帧,那么迟到的旧终态就可能错误地结束新帧的所有权。重构要消除的,正是这类“硬件状态变化”和“框架状态结算”之间的歧义。

新方案的核心思路:框架只管理硬件资源,不替协议决定发送策略

早期重构讨论 #11767 曾提出统一 TX Request Pool、软件 FIFO 和 Scheduler(调度器)的方案。但 PR #12054 最终选择了更轻量的方向:Generic CAN 不再保存待提交的 TX 软件队列,硬件邮箱/发送缓冲资源成为 Generic CAN 可见的唯一待发送资源。[S1][S7]

1
2
3
4
5
6
7
flowchart LR
A["应用 / 协议栈:按需缓存与重试"] --> B["rt_device_write()"]
B --> C["Generic CAN:发送接纳与邮箱所有权"]
C --> D["BSP:立即尝试硬件提交"]
D --> E["CAN 控制器发送资源"]
E --> F["TX_DONE / TX_FAIL 事件"]
F --> G["Generic CAN:终态结算与资源回收"]

这里需要区分两个时间点:提交成功只是硬件接受了待发送帧,发送完成仍须等待控制器上报终态。Generic CAN 负责把两者正确关联;上层若需要缓存、限流、优先级、覆盖旧命令或失败重试,则在自己的协议或应用层决定。[S3][S4]

这样的职责划分尤其适合行为差异很大的业务:CANopen 已有自身发送管理机制;电机控制可能偏向“最新指令优先”;诊断应用可能需要严格 FIFO;网关可能需要按 ID 或业务级别限流。统一设备框架不必为所有场景强制选择一种 TX 队列策略。

但这不是无代价的优化。 过去依赖 Generic CAN 自动缓存突发报文的应用,在新框架下可能直接遇到 -RT_EBUSY。业务不能简单假设“连续写入总会被框架排队”,需要根据实际需求选择阻塞等待、上层缓存、限速、重试或丢弃。[S3][S4]

与旧版相比,具体有什么变化?

对比维度 重构前 PR #12054 的新设计
Blocking TX 资源管理 邮箱链表 freelist、信号量、completion 等组合管理 一个框架可见邮箱对应一个固定 slot,记录状态与 completion
Nonblocking TX 硬件忙时可进入 Generic 的 nb_tx_rb BSP 仅尝试一次;硬件忙则向上返回 -RT_EBUSY,不做软件排队
Nonblocking 返回成功 可能仅表示进入 Generic 软件队列 表示本次调用已被硬件提交接口接受;不代表总线发送成功
TX 软件缓存与重试策略 Generic 内置一套非阻塞缓冲和中断 refill 机制 留给应用或 CANopen 等上层协议栈
邮箱所有权 多套状态配合,取消和迟到终态处理复杂 每邮箱独立 slot;终态与对应邮箱关联,超时不擅自释放硬件所有权
Abort / Drain 缺少与所有发送状态自然对应的统一事务语义 新增按邮箱 Abort、批量 Abort、Drain 等基础管理能力
控制器重配置 与 TX/RX 正在运行的资源边界不够集中 先关闭新 TX 接纳、检查空闲,再暂停 RX 并处理重配置
RX 缓存 维护软件 RX FIFO 继续保留 RX FIFO,并补强 ISR/回调生命周期同步
BSP 接入 部分非阻塞回调无法明确返回所选硬件邮箱 sendmsg_nonblocking() 改为通过输出参数报告实际邮箱编号

以上是设计与实现方式的对照,不等于“所有场景下性能都会提高”或“所有旧应用无需修改”。本次改动主要改善的是职责清晰度、可观测的错误语义以及资源生命周期管理;RAM、CPU 使用量与高负载性能仍应由不同 MCU/BSP 实测比较。[S2][S3][S4][S5]

Blocking:等待不会抹掉硬件所有权

新版 Blocking TX 会扫描固定邮箱槽位,通过 BSP 的 sendmsg(can, msg, mailbox) 尝试提交;指定邮箱忙时返回 -RT_EBUSY,框架根据邮箱状态变化通知重新尝试。RT_CANSND_MSG_TIMEOUT 是每帧的一份总超时预算,覆盖等待邮箱与等待发送终态的时间,而不是每个阶段分别重新计时。[S3][S4]

如果等待已经超时,而硬件尚未上报终态,slot 进入超时但仍待结算的状态;硬件所有权不会被软件超时直接释放。只有之后的 TX_DONE/TX_FAIL 到来,或满足明确前置条件的控制器停止流程完成,才能妥善收尾。这比“线程不等了,就认为邮箱空了”更符合硬件事务的实际情况。

Nonblocking:硬件忙就明确反馈忙

新版 Nonblocking TX 调用 BSP sendmsg_nonblocking(can, msg, &mailbox) 一次。BSP 必须在成功时返回实际选中的框架可见邮箱编号;Generic CAN 据此登记这次硬件提交,等待该邮箱对应的终态。[S3][S4]

如果硬件无法接受,调用方直接得到 -RT_EBUSY,而不是依赖隐式软件队列。这让上层有机会按实际业务选择背压(backpressure)处理方式,但也要求旧应用重新审视突发发送行为。

为什么 RX 仍保留 FIFO?

删除的是 TX 软件队列,不是 RX 软件队列。 收包由硬件中断驱动,应用线程通常无法保证每一帧到来时都立即读取,因此 Generic CAN 仍需要软件 RX FIFO 衔接中断生产与线程消费。[S5]

新版 can_rx.c 还使用 rx_lock 与 rx_active_isr 跟踪正在执行的 RX 中断和回调:管理线程暂停 RX 接纳后,需要等待此前已进入的处理完成,才能安全关闭或重配置相关资源。硬件读取和应用回调不长时间占用 RX 锁,目的是减少长临界区及资源释放竞态。这是实现的并发保护设计,并不意味着所有 SMP/高负载组合已得到板级验证。[S5]

PR #12054 已经提交了哪些改动?

本次 PR 不只是改了一个 dev_can.c。截至上述提交,共涉及 42 个文件,其中 32 个属于 BSP CAN 驱动源码,覆盖 19 个厂商/平台目录;这些数字指的是已修改文件范围,不能据此推断 32 块目标板或 19 家厂商的实机验证已经全部通过。[S1][S6]

1. 把 Generic CAN 按职责拆成独立模块

components/drivers/can/ 中新增或调整以下文件:[S4][S5]

  • dev_can.c:RT-Thread 设备注册、open/close、read/write/control 路由,以及中断事件分发;
  • can_tx.c:固定邮箱 slot、Blocking/Nonblocking 提交、终态结算、Drain 与 Abort;
  • can_rx.c:RX FIFO、硬件过滤相关元数据、RX 中断及回调的生命周期;
  • can_internal.h:这些模块之间共享的内部实现契约。

对上层来说,常用的 rt_device_open()、rt_device_read()、rt_device_write()、rt_device_control() 和 struct rt_can_msg 仍是熟悉的设备编程入口;对 BSP 来说,仍通过 rt_hw_can_isr() 向 Generic CAN 报告事件。但这不等于 ABI/内部结构完全不变:struct rt_can_device 以及 BSP 的非阻塞回调契约已发生改变,需要随此次 PR 对应版本适配。[S3][S5]

2. 增加发送静默与硬件取消所需的基础能力

新版接口包含:[S3][S4]

  • rt_can_tx_drain(can, timeout):等待已交给硬件的发送事务全部结算。它不会停止新的发送生产者,也不会自动 Abort;调用方应先自行停止 TX 生产,并与设备最终 close 串行化;
  • RT_CAN_CMD_ABORT_TX / rt_can_tx_abort():向指定硬件发送邮箱提出取消请求。请求被接受不代表取消已完成;必须等待对应终态(通常为 TX_FAIL),控制器不支持时应明确返回错误;
  • RT_CAN_CMD_ABORT_ALL:逐个请求取消框架可见的硬件 TX 邮箱,仍需根据各 BSP 能力和后续终态判断结果;
  • RT_CAN_CMD_FORCE_STOP:在严格条件下强制停止控制器并处理尚未结算的发送所有权。这不是可随意代替正常 Drain 的通用“清空一切”快捷键,应用需停止生产者并确保没有并行 TX API 调用/等待竞争。

对于运行时波特率切换,应用现在可以选择:先停止上层 TX,等待 Drain 达到静默,或者在确有需要且 BSP 支持的情况下请求硬件 Abort,再等待终态后重配置。这是一组可以按业务组合的基础能力,而不是框架自动提供完整协议级 Full Flush 策略。[S3][S4][S7]

3. 调整控制器生命周期与并发保护

新版重配置路径集中在 dev_can.c 的 _can_reconfigure():先关闭 TX 接纳并检查是否空闲,再暂停 RX 接纳、等待在途 ISR/回调,然后调用 BSP 控制操作,最后按结果恢复相应数据路径。失败时并非无条件自动恢复,部分操作会保留关闭状态,留给上层显式处理。[S5]

这项设计的价值不是“所有异常都自动修好”,而是让何时允许重配置、哪些发送仍被硬件占有、哪些接收回调仍在执行有清楚的判断边界。硬件过滤器在控制器重初始化后是否保留,仍取决于 BSP;应用可能需要再次配置 RT_CAN_CMD_SET_FILTER,框架不承诺自动重放硬件过滤配置。[S3][S5]

4. 更新多厂商 BSP 的发送契约

PR 修改了 STM32 bxCAN/FDCAN,以及 GD32、AT32、APM32、N32、HC32、HPMicro、Nuvoton、NXP、Renesas、WCH 等多个系列的 CAN/CAN FD 驱动。适配重点包括:正确报告被硬件接受的邮箱编号,处理硬件忙返回值,向框架上报对应邮箱的 TX_DONE/TX_FAIL,并处理控制器停止、错误及取消操作的芯片差异。[S6]

以 STM32 bxCAN 为例,适配不仅涉及三个硬件发送邮箱,还需防止旧邮箱完成标志尚未被框架处理就被复用;Abort 使用相应硬件请求位,避免错误清除其他邮箱的完成状态。这属于具体控制器的硬件适配细节,不应机械照搬到 FDCAN、MCAN、FlexCAN 或其他芯片。[S6]

5. 简化 Kconfig,并加入模拟框架测试

components/drivers/can/Kconfig 移除了旧 TX 软件环形缓冲相关的 RT_CAN_NB_TX_FIFO_SIZE 和 RT_CAN_MALLOC_NB_TX_BUFFER,保留 RX FIFO 配置,并调整发送邮箱数量和 Blocking 超时的说明。新增的 RT_UTEST_CAN_FRAMEWORK 可在无真实 CAN 控制器的情况下,以模拟 BSP ops 检查注册、open/close、TX 背压与超时、Nonblocking 终态及 RX FIFO 等框架行为。[S5]

模拟测试有助于保护通用逻辑,但不能证明某个芯片的邮箱索引、硬件标志、IRQ、时钟、引脚及收发器在真实板卡上都正确。这正是此次重构最需要社区参与的部分。

已有验证结果,以及为什么仍然需要社区测试

PR 描述报告:曾以 STM32 bxCAN + Linux SocketCAN/can-utils 搭建 1 Mbit/s 真实 CAN 总线环境,完成 Blocking/CANopenNode SDO Block、通信重置与重开、Nonblocking paced/burst 发送、硬件 Abort 和发送恢复等测试。其中一组 Nonblocking burst 结果为:1000 次尝试中 49 次硬件接纳、951 次返回 -RT_EBUSY;结合 paced 发送,描述中记录的 TX_DONE 与成功接纳总数一致。[S1]

截至 2026 年 11 月 15 日,当前 PR head 对应的 GitHub Actions 查询也显示 RT-Thread BSP Static Build Check、Static code analysis、utest_auto_run 等工作流成功。不过,PR 描述中的具体实测 BSP 路径及完整 .config 仍为待填写项;这些信息不能代替各芯片的独立验证记录。尤其是 CAN FD、不同厂商的硬件发送资源模型、超时边界和设备重启路径,仍需要更多板卡反馈。[S1][S6]

邀请社区一起把不同 BSP 跑通

这次 CAN 重构的覆盖范围较大,仅凭一块 STM32 板卡和 CI 编译成功,无法确认所有控制器适配都具备正确的硬件行为。如果手上有使用 RT-Thread 的 CAN / CAN FD 开发板,非常欢迎试用 PR #12054 的代码,并把结果反馈到 PR 讨论区:参与 CAN 框架重构验证。

尤其希望不同 BSP 的维护者和使用者关注以下实际行为:

  1. 基础收发:Classic CAN 标准帧/扩展帧、收发中断、过滤器,以及具备硬件能力时的 CAN FD/BRS;
  2. 发送资源边界:Blocking、Nonblocking、突发发送、邮箱已满时的 -RT_EBUSY,以及返回值是否符合新的硬件接纳语义;
  3. 终态与恢复:每次成功提交能否正确对应 TX_DONE/TX_FAIL;超时、总线仲裁压力、无 ACK、Bus-off 及恢复后有无卡住或重复结算;
  4. 生命周期:close/reopen、启动/停止、切换波特率或模式、重新配置过滤器,是否能恢复正常收发;
  5. 可选能力:目标 BSP 若实现硬件 Abort,可检查取消终态、邮箱复用与再次发送;若未实现,应明确反馈 -RT_ENOSYS 或相应错误,而不是假定所有控制器都支持;
  6. 资源与兼容性:原应用若依赖 Nonblocking 自动排队,迁移后是否需要上层缓冲;有条件时提供 RAM/CPU/吞吐与旧版的对照。

对于没有真实总线环境的开发者,编译结果、模拟测试结果、代码中发现的邮箱映射问题,同样有参考价值,只需标明验证层级,不将 Host/CI 结果写成实机通过。也欢迎指出尚未修改但使用旧 CAN 契约的 BSP。[S6]

反馈时最好附上可复现的关键信息,便于其他人定位和复查:

1
2
3
4
5
6
7
8
9
芯片型号 / 开发板:
BSP 路径 / CAN 控制器类型:
测试的 PR commit:
RT-Thread 配置(.config 或相关配置片段):
测试环境(单板回环 / 双节点 / SocketCAN,收发器型号):
Classic CAN / CAN FD、波特率及测试模式:
已通过项(Blocking / Nonblocking / RX / Abort / Reopen 等):
失败项、复现条件、返回码及关键日志:
验证层级(静态检查 / 编译 / Host / 实际板卡):

不必一次测完所有场景。一份能够明确“哪块板、哪个提交、什么配置、哪个功能通过或失败”的反馈,就能帮助维护者逐步收敛问题。对于真正影响跨 BSP 兼容性的调整,也欢迎直接在 PR 中提供具体修改意见。

CAN 框架要服务于不同 MCU、不同 CAN 控制器和不同协议栈;只有把硬件差异充分验证出来,重构后的统一契约才真正有价值。期待更多 RT-Thread 社区成员参与测试、反馈和完善。

资料来源

[S1] PR #12054 状态、设计说明与测试记录

  • 版本:2026-11-15 查询,PR head cbc5cbab53a4d9a63fb8f745deb96473f6948b6f。
  • 定位:RT-Thread PR #12054:Refactor/can framework。
  • 使用位置:开篇状态、设计取舍、已提交的改动、现有验证结果。
  • 支撑内容:PR 未合并、总体设计和改动规模,以及作者报告的 STM32 bxCAN + SocketCAN 实机测试;最新 head 的 GitHub Actions 状态已核对。硬件测试仅引用 PR 说明,本文未独立复测。

[S2] 重构前的 CAN 框架及配置

[S3] 新版公开 CAN API 与 BSP 回调契约

  • 版本:PR head cbc5cbab53a4d9a63fb8f745deb96473f6948b6f。
  • 定位:components/drivers/include/drivers/dev_can.h。
  • 使用位置:新旧行为对照、Blocking/Nonblocking 语义、Abort/Drain、接口兼容性。
  • 支撑内容:struct rt_can_ops、RT_CAN_CMD_ABORT_TX、RT_CAN_CMD_ABORT_ALL、RT_CAN_CMD_FORCE_STOP、rt_can_tx_drain()、struct rt_can_device 的实际定义和注释。

[S4] 新版 TX 核心与邮箱所有权

  • 版本:PR head cbc5cbab53a4d9a63fb8f745deb96473f6948b6f。
  • 定位:components/drivers/can/can_tx.c、components/drivers/can/can_internal.h。
  • 使用位置:“新方案的核心思路”、Blocking/Nonblocking、Timeout、TX 终态与管理功能。
  • 支撑内容:_tx_blocking_one()、_tx_nonblocking_one()、rt_can_tx_isr_core()、rt_can_tx_drain_core()、rt_can_tx_abort() 的状态、同步和返回值处理。

[S5] 设备管理、RX 生命周期与框架测试

[S6] 32 个 BSP 驱动源码的适配范围

  • 版本:PR head cbc5cbab53a4d9a63fb8f745deb96473f6948b6f。
  • 定位:PR #12054 文件变更列表、bsp/stm32/libraries/HAL_Drivers/drivers/drv_can.c 与 drv_fdcan.c。
  • 使用位置:“PR #12054 已经提交了哪些改动”“邀请社区一起把不同 BSP 跑通”。
  • 支撑内容:19 个厂商/平台目录下的 32 个 BSP CAN 驱动文件被修改,以及代表性 bxCAN/FDCAN 硬件邮箱与终态适配。变更范围不等于实测覆盖。

[S7] 重构动机与先前讨论方案