[Discussion][CAN] RT-Thread CAN Framework 重构方案

[wdfk-prog]

https://club.rt-thread.org/ask/question/e1d2904dcdff1591.html

[Discussion][CAN] RT-Thread CAN Framework 重构方案：统一 TX Engine、Mailbox Ownership 与 Lifecycle

摘要：统一 CAN TX/RX 核心、发送事务与邮箱所有权，解决乱序、超时、Flush、关闭重配置和中断并发问题，并保持旧 BSP ISR 接口兼容。

这是一份面向 RT-Thread CAN Framework 的重构讨论方案。目标不是针对某一个 BSP 修补问题，而是把近几年 blocking/non-blocking TX、发送顺序、timeout、full flush、bus-off/recovery、CAN FD 和多厂商 BSP 暴露出来的问题收敛到一套统一的 Framework contract 中。

本文先给出一套完整方案用于讨论。已经确认的总体方向直接作为 proposal，不再逐项讨论“要不要做”；希望社区重点评估的是兼容边界、接口细节、资源成本以及分阶段落地方式。

1. 当前实现中需要解决的结构性问题

当前 components/drivers/can/dev_can.c 中 TX 实际存在两套路径：

• blocking TX：_can_int_tx() / _can_int_tx_priv() 使用 sendmsg()、TX mailbox freelist、semaphore、completion 和 status.sndchange；
• non-blocking TX：_can_nonblocking_tx() 使用 sendmsg_nonblocking()，硬件忙时进入 nb_tx_rb；
• RT_CAN_EVENT_TX_DONE / TX_FAIL 中断处理里还会直接从 nb_tx_rb 取下一帧并再次调用 sendmsg_nonblocking()；
• 当 ISR refill 失败时，当前实现使用 rt_ringbuffer_put_force() 放回消息，这会改变 FIFO 顺序，并且在空间不足时具备覆盖旧数据的语义。

这导致 blocking/non-blocking 不只是 API 行为不同，而是 Framework 内部维护了不同的发送资源、排队方式和完成方式。随着 runtime bitrate reconfiguration、TX flush/abort、CAN FD 和 SMP 等需求增加，继续在现有结构上增加状态位和分支会越来越难维护。

相关讨论和问题包括：

• Non-blocking TX 引入：feat(can): 实现非阻塞发送机制并增强CAN驱动功能 #10712
• 连续发送顺序问题：fix(can): 连续多包发送，使传输顺序与应用层调用一致 #11270
• TX Full Flush / Hardware Abort 需求：[Feature][CAN] 支持 TX Full Flush 与 Hardware Abort 能力 #11759
• CAN 断线、错误与恢复问题：[bsp][stm32]CAN发送时拔插can总线，导致后续发送显示失败 #6506
• 高负载/断线场景下 CAN 异常：RT-Thread v4.1.1 CAN驱动接收中断在两个设备互发消息时热插拔会导致系统卡死 #7471

当前主线代码：

• dev_can.c: https://github.com/RT-Thread/rt-thread/blob/master/components/drivers/can/dev_can.c
• dev_can.h: https://github.com/RT-Thread/rt-thread/blob/master/components/drivers/include/drivers/dev_can.h

2. 重构目标

目标 Framework 收敛为以下原则：

1. blocking / non-blocking 共用一个 TX Engine；
2. 所有 TX 先成为 Framework 管理的 TX Request；
3. 使用预分配 TX Request Descriptor Pool，不在 ISR 中动态分配；
4. software TX queue 保持严格 FIFO；
5. Framework 显式维护 mailbox -> request ownership；
6. BSP 统一通过 sendmsg(can, msg, mailbox) 提交硬件发送；
7. 启用 non-blocking TX 的 driver，其 sendmsg() 必须 ISR-safe；
8. 不引入 deferred scheduler、CAN worker thread 或 workqueue；
9. blocking wait timeout 不等价于硬件 transaction 已结束；
10. TX terminal event exactly-once；
11. Lifecycle State 与 CAN Bus State 分离；
12. TX/RX 使用独立 irq-safe spinlock；
13. RX 保留现有 node pool 思路，只重构 synchronization/ownership/lifecycle；
14. rt_hw_can_isr(can, event) 和现有 BSP ISR 调用方式第一阶段保持兼容；
15. 第一阶段保持 rt_device_read/write/control 和 struct rt_can_msg 兼容；
16. struct rt_can_core 直接嵌入 struct rt_can_device，不增加二次动态分配；
17. 不增加 RT_CAN_USING_RX / RT_CAN_USING_TX 这种基础裁剪项，CAN 默认同时具备 RX/TX；
18. Kconfig 只裁剪 blocking、non-blocking、callback、trace 和 request pool 等真正影响 RAM/Flash 的功能。

3. 目标 Framework 结构

flowchart TD
    APP["Application / ISR"] --> API["rt_device_write / rt_can_send_async"]
    API --> TXQ["TX Request Pool + FIFO Queue"]
    TXQ --> SCH["TX Scheduler"]
    SCH --> OWN["TX mailbox ownership"]
    OWN --> SEND["ops->sendmsg(can, msg, mailbox)"]
    SEND --> HW["CAN Controller"]
    HW --> ISR["existing rt_hw_can_isr"]
    ISR --> TERM["TX terminal handler"]
    TERM --> SCH
    TERM --> WAIT["blocking completion"]
    TERM --> CB["async callback"]

    HW --> RXISR["RX event"]
    RXISR --> RXCORE["RX node pool + RX spinlock"]
    RXCORE --> READ["rt_device_read"]

    LC["Lifecycle Core"] --> TXQ
    LC --> RXCORE
    BUS["Bus State"] --> LC

Loading

Scheduler 不是独立线程，也不是后台任务。它只是一个“尝试把 pending TX Request 推进到硬件 mailbox”的短函数。

它主要由三个事件触发：

1. 新 TX Request 入队；
2. TX_DONE / TX_ERROR / TX_ABORTED 释放 mailbox；
3. controller recover / reconfigure 完成后重新允许 TX。

本方案不使用 deferred scheduling。

4. 统一 blocking / non-blocking TX Engine

blocking 与 non-blocking 的区别只保留在“调用者是否等待 terminal result”。

统一数据流：

CAN frame
   ↓
TX Request
   ↓
FIFO pending queue
   ↓
TX Scheduler
   ↓
TX mailbox
   ↓
ops->sendmsg()
   ↓
CAN hardware
   ↓
TX terminal event

blocking：

enqueue request
→ schedule
→ wait completion
→ terminal result
→ return

non-blocking：

enqueue request
→ schedule
→ accepted 后立即返回
→ terminal event 后 callback / auto retire

因此 BSP 不再区分“blocking send function”和“non-blocking send function”。blocking 是 Framework 的等待策略，不是 BSP 的发送方式。

5. sendmsg() 作为唯一 BSP TX submit 接口

现有很多 BSP 的 sendmsg(can, msg, box_num) 本质已经是“把一帧写入指定发送资源并立即返回”，它本身并不负责 blocking。

目标 contract 建议明确为：

/**
 * Submit one CAN frame to the specified hardware TX mailbox.
 *
 * The function only performs hardware submission. It must not wait for
 * transmission completion. Blocking/non-blocking semantics are owned by
 * the CAN framework.
 *
 * When RT_CAN_USING_TX_NONBLOCKING is enabled for the driver, this callback
 * must be safe to call from ISR context.
 *
 * @return
 * - RT_EOK: frame accepted by the selected mailbox;
 * - -RT_EBUSY: selected mailbox/resource is temporarily unavailable;
 * - other error: controller/parameter failure.
 */
rt_ssize_t (*sendmsg)(struct rt_can_device *can,
                      const void *buf,
                      rt_uint32_t mailbox);

这里的 ISR-safe 至少意味着：

- 不 sleep；
- 不 take blocking mutex/semaphore；
- 不等待 TX complete；
- 不依赖只能在线程上下文运行的服务；
- 执行时间应保持为硬件 submit 所需的短路径。

为什么 non-blocking driver 必须满足 ISR-safe sendmsg()

当前 Framework 本来就在 TX_DONE ISR 中调用 sendmsg_nonblocking() refill software queue。

新 Framework 不再保留第二套 non-blocking hardware submit path，因此：

TX_DONE
   ↓
release mailbox
   ↓
TX Scheduler
   ↓
ops->sendmsg(next_request, mailbox)

会直接发生在 ISR context。

如果这里不允许调用 sendmsg()，又禁止 deferred/workqueue，那么 pending non-blocking queue 就可能在第一帧完成后停止推进。

因此本方案把能力关系定义得更直接：

一个 driver 如果支持新的 non-blocking TX，就必须保证统一的 sendmsg() 是 ISR-safe 的。

不再增加单独的 TX_SEND_ISR_SAFE flag，也不在 Framework 中维护两套 scheduler。

sendmsg_nonblocking() 如何处理

第一阶段建议仍保留 struct rt_can_ops 中现有 sendmsg_nonblocking 成员，使旧 BSP 的静态 initializer 和源码继续编译。

但是新的 TX Core 不再依赖该接口。

Target TX path:
    sendmsg(can, msg, mailbox)

Legacy member:
    sendmsg_nonblocking(...)
    → retained temporarily for source compatibility
    → not part of the new TX Engine contract

对于希望继续支持 non-blocking 的旧 BSP，需要把现有 sendmsg_nonblocking() 中的 ISR-safe 硬件 submit 能力合并到 sendmsg(can, msg, mailbox) 中。

这一迁移只涉及 BSP 的发送实现；现有 BSP ISR 调用 rt_hw_can_isr() 的代码不需要修改。

6. TX Request Descriptor Pool

软件队列不再只保存裸 rt_can_msg，而是保存完整发送事务。

enum rt_can_tx_req_state
{
    RT_CAN_TX_REQ_FREE = 0,
    RT_CAN_TX_REQ_QUEUED,
    RT_CAN_TX_REQ_SUBMITTING,
    RT_CAN_TX_REQ_HW_PENDING,
    RT_CAN_TX_REQ_ABORTING,

    RT_CAN_TX_REQ_DONE,
    RT_CAN_TX_REQ_ERROR,
    RT_CAN_TX_REQ_ABORTED,
    RT_CAN_TX_REQ_CANCELLED,
};

建议 descriptor：

typedef void (*rt_can_tx_done_cb)(struct rt_can_device *can,
                                  const struct rt_can_msg *msg,
                                  rt_err_t result,
                                  void *arg);

struct rt_can_tx_request
{
    rt_list_t node;

    struct rt_can_msg msg;

    enum rt_can_tx_req_state state;
    rt_err_t result;

    /* -1 means no hardware mailbox is currently owned. */
    rt_int16_t mailbox;

#ifdef RT_CAN_USING_TX_BLOCKING
    rt_bool_t waiter_attached;
    struct rt_completion completion;
#endif

#ifdef RT_CAN_USING_TX_CALLBACK
    rt_can_tx_done_cb callback;
    void *callback_arg;
#endif

#ifdef RT_CAN_USING_TX_TRACE
    rt_uint32_t sequence;
#endif
};

这里不再增加通用 flags 字段。发送生命周期由 state 表示，其它需要独立语义的内容使用明确字段，避免形成 state + flags 两套状态源。

request_count 与 sequence

request_count 是 TX Request Pool 的容量：

rt_uint16_t request_count;

例如 request_count = 16 表示最多同时存在 16 个尚未 retire 的 TX Request。

sequence 只是可选 trace/debug 编号，不参与 ownership、FIFO 或 terminal correctness。

如果启用 trace，rt_uint32_t sequence 允许自然回绕：

0xFFFFFFFE
0xFFFFFFFF
0x00000000
0x00000001

不需要为溢出建立额外状态，因为真正的 request identity 和 mailbox ownership 由 descriptor 指针维护。

7. TX Core 与 Mailbox Ownership

不为只有一个成员的 mailbox 再增加独立结构体。

建议：

struct rt_can_tx_core
{
    struct rt_spinlock lock;

    rt_list_t free_list;
    rt_list_t pending_list;

    struct rt_can_tx_request *requests;
    rt_uint16_t request_count;

    /*
     * Array size uses existing can->config.sndboxnumber.
     * mailbox_owner[n] == RT_NULL means mailbox n has no framework owner.
     */
    struct rt_can_tx_request **mailbox_owner;

    /* Protected by tx.lock; prevents scheduler re-entry. */
    rt_bool_t scheduling;
};

继续复用现有：

can->config.sndboxnumber

作为 mailbox 数量，不再增加重复的 mailbox_count。

Mailbox 是什么

这里的 mailbox 沿用 RT-Thread 当前概念。

对于 STM32 bxCAN：

mailbox 0 = sTxMailBox[0]
mailbox 1 = sTxMailBox[1]
mailbox 2 = sTxMailBox[2]

其它 controller 可能叫 TX Buffer / TX FIFO Element，但 Generic Framework 仍把“可以独立产生 TX terminal event 的发送资源编号”统一称为 mailbox。

关键 ownership 不变量

1. 一个 mailbox 同一时刻最多只有一个 owner；
2. HW_PENDING / ABORTING request 必须能反查到自己的 mailbox；
3. mailbox_owner[n] 未清空前，对应 request descriptor 不得复用；
4. stale / duplicate TX IRQ 不得修改新的 request；
5. status.sndchange 不再作为 ownership correctness 的依据。

8. TX Scheduler

Scheduler 是 TX Engine 的中心推进函数，但不是线程。

基本流程：

flowchart TD
    KICK["TX schedule kick"] --> LOCK["tx.lock"]
    LOCK --> CHECK["check lifecycle / scheduling"]
    CHECK --> HEAD["take pending queue HEAD"]
    HEAD --> BOX["select available mailbox"]
    BOX --> RESERVE["mailbox_owner = request; state = SUBMITTING"]
    RESERVE --> UNLOCK["tx.unlock"]
    UNLOCK --> SEND["ops->sendmsg()"]
    SEND --> RET{"return"}
    RET -- "RT_EOK" --> PEND["HW_PENDING"]
    RET -- "-RT_EBUSY" --> RESTORE["restore exact queue HEAD"]
    RET -- "error" --> ERR["terminal ERROR"]

Loading

Driver/HAL 调用必须位于 tx.lock 外。

也就是说采用：

reserve
→ unlock
→ driver submit
→ lock
→ commit / rollback

而不是：

spinlock
→ HAL/driver
→ unlock

-RT_EBUSY 的处理

如果指定 mailbox 临时不可用：

Request = QUEUED
mailbox_owner = NULL
request 恢复到 pending queue HEAD

不再执行：

pop
→ send fail
→ put_force 到 tail

这样不会改变原始 FIFO 顺序，也不会覆盖旧 request。

9. Wire Transmission Order

本方案把目标定义为：

对同一个 rt_can_device，Framework 接受的 TX Request 应保持应用提交顺序，并在 Generic fallback 下保证本节点的 wire transmission order。

例如：

Application: A → B → C
Wire order:  A → B → C

其它 CAN 节点仍然可以通过总线仲裁插入 A/B/C 之间，这不属于本节点 Framework 的顺序问题。

多 mailbox Controller

如果同时 preload：

A → mailbox 0
B → mailbox 1
C → mailbox 2

某些 controller 可能按照 CAN ID priority 或自己的 mailbox policy 决定发送顺序。

Generic Framework 因此默认采用严格模式：

如果不能证明多个 mailbox 可以保持 submit order，
同一时刻最多允许一个 TX Request 进入 hardware pending。

如果某个 controller 明确支持 ordered multi-mailbox，可以通过 capability 允许多 mailbox preload，例如：

#define RT_CAN_CAP_TX_ORDERED_MAILBOX    (1UL << 0)

这样 strict order 是 Generic correctness baseline，多 mailbox 是 driver capability optimization。

10. Blocking timeout 不等于 TX 已结束

这是新 TX ownership 最重要的语义之一。

Request A
   ↓
HW_PENDING
   ↓
blocking thread waits
   ↓
wait timeout

timeout 只说明：

调用线程不再继续等待。

不能说明：

hardware 已经停止发送 Request A。

因此 timeout 后：

- mailbox ownership 不释放；
- descriptor 不复用；
- request 仍等待 TX_DONE / TX_ERROR / TX_ABORTED；
- waiter_attached = false；
- terminal event 到达后 Framework 自动 retire。

这可以避免旧 transaction 的 late IRQ 修改已经复用给新 transaction 的 slot/request。

11. 统一 TX terminal event

所有 TX transaction 最终只允许进入一次 terminal 状态：

enum rt_can_tx_result
{
    RT_CAN_TX_RESULT_OK = 0,
    RT_CAN_TX_RESULT_ERROR,
    RT_CAN_TX_RESULT_ABORTED,
    RT_CAN_TX_RESULT_CANCELLED,
};

所有来源最终汇入同一处理函数：

TX_DONE
TX_FAIL
hardware abort complete
full flush cancel
close cancel

例如：

static void _can_tx_complete(struct rt_can_device *can,
                             struct rt_can_tx_request *req,
                             enum rt_can_tx_result result);

规则：

non-terminal → terminal

只能成功一次。

Abort 和 TX_DONE 发生竞争时，第一个 terminal event 完成 request；后续重复/过期 event 只能记录 diagnostics，不能再次 completion、callback 或 free。

12. Async completion callback 第一阶段直接开放

建议不再只做内部预留，第一阶段直接提供 async completion API：

#ifdef RT_CAN_USING_TX_CALLBACK
rt_err_t rt_can_send_async(struct rt_can_device *can,
                           const struct rt_can_msg *msg,
                           rt_can_tx_done_cb callback,
                           void *arg);
#endif

默认 callback context 与 terminal event context 一致。

如果 TX_DONE 来自 ISR，则 callback 也在 ISR context 调用，但必须在 tx.lock 已释放以后。

因此文档 contract 必须明确 callback 不允许：

sleep
blocking mutex/semaphore
长时间运算
blocking I/O

需要线程上下文的应用可以在 callback 中自行投递 message/event；CAN Core 本身不引入 workqueue。

13. Lifecycle State

建议公共生命周期：

enum rt_can_lifecycle_state
{
    RT_CAN_LC_STOPPED = 0,
    RT_CAN_LC_RUNNING,
    RT_CAN_LC_QUIESCING,
    RT_CAN_LC_QUIESCED,
    RT_CAN_LC_RECONFIGURING,
    RT_CAN_LC_RECOVERING,
    RT_CAN_LC_CLOSING,
};

语义：

STOPPED
    controller/framework 未运行；

RUNNING
    正常允许 TX/RX；

QUIESCING
    已禁止新的 TX Request，正在处理旧 request；

QUIESCED
    TX 已完全静默，可安全进行 reconfigure/stop；

RECONFIGURING
    正在修改 baud/mode/CAN FD 等 controller 配置；

RECOVERING
    正在执行 controller/bus recovery；

CLOSING
    正在停止中断、终止 transaction 并释放 runtime resource。

不增加 admission_open / submit_refcnt

Lifecycle admission 与 TX enqueue 都在 tx.lock 下完成。

TX enqueue：

tx.lock
→ lifecycle == RUNNING ?
→ allocate request
→ enqueue
→ tx.unlock

进入 quiesce：

lifecycle_lock
→ tx.lock
→ RUNNING → QUIESCING
→ tx.unlock

因此一旦状态进入 QUIESCING，新的 TX enqueue 就无法越过状态切换。

不需要额外维护：

admission_open
submit_refcnt

QUIESCED 的严格条件

只有以下条件同时满足时进入：

pending_list empty
没有 SUBMITTING request
所有 mailbox_owner == NULL
没有 ABORTING request
scheduler 已退出

不增加 inflight_count，因为 inflight 可以直接由 mailbox ownership 推导，避免维护重复状态。

14. Quiesce / Drain / Full Flush / Abort

建议把这些语义分开。

enum rt_can_quiesce_policy
{
    RT_CAN_QUIESCE_DRAIN = 0,
    RT_CAN_QUIESCE_DROP_QUEUED,
    RT_CAN_QUIESCE_ABORT_ALL,
};

DRAIN

禁止新 TX
+ queued request 全部正常发送
+ hardware pending 正常完成
→ QUIESCED

DROP_QUEUED

禁止新 TX
+ software queued request → CANCELLED
+ hardware pending 正常完成
→ QUIESCED

ABORT_ALL / Full TX Flush

禁止新 TX
+ software queued request → CANCELLED
+ HW_PENDING → ABORTING
+ driver hardware abort
+ 等所有 mailbox_owner 清空
→ QUIESCED

典型 runtime bitrate reconfiguration：

RUNNING
→ QUIESCING
→ ABORT_ALL
→ QUIESCED
→ RECONFIGURING
→ set bitrate
→ RUNNING

Hardware abort 仍然是可选 driver capability，例如：

#define RT_CAN_CAP_TX_ABORT    (1UL << 1)

abort(mailbox) 调用成功只表示 abort request 已提交，不等价于 transaction 已 terminal；最终仍由 TX_ABORTED / TX_DONE / TX_ERROR 中的一个终态事件结束 request。

15. Bus State 与 Lifecycle 分离

Lifecycle 描述 Framework/controller 操作阶段；Bus State 描述 CAN 协议错误状态。

建议：

enum rt_can_bus_state
{
    RT_CAN_BUS_UNKNOWN = 0,
    RT_CAN_BUS_ERROR_ACTIVE,
    RT_CAN_BUS_ERROR_WARNING,
    RT_CAN_BUS_ERROR_PASSIVE,
    RT_CAN_BUS_OFF,
};

合法组合例如：

Lifecycle = RUNNING
Bus State = ERROR_PASSIVE

或：

Lifecycle = RECOVERING
Bus State = BUS_OFF

BUS_OFF 不等于 STOPPED，否则 runtime recovery、queue policy 和 controller lifecycle 会继续混在一起。

第一阶段不新增复杂的 rt_can_bus_status_core 或 rt_can_statistics。现有 rt_can_status 继续承担 observability；新的 transaction correctness 不再依赖 sndchange/rcvchange 等状态字段。

16. RX 重构

RX 也需要重构，但不复制 TX Request state machine。

TX 的复杂性来自：

queue
mailbox ownership
waiter
timeout
abort
terminal
ordering

RX 是单向：

hardware frame
→ recvmsg
→ software RX node
→ RX queue
→ rt_device_read

因此 RX 保留现有 node pool / freelist / uselist 思路，主要收敛四件事。

16.1 RX 独立 spinlock

struct rt_can_rx_core
{
    struct rt_spinlock lock;
    struct rt_can_rx_fifo *fifo;
};

rx.lock 保护：

freelist
uselist / pending list
HDR list membership
node owner
hdr->msgs
RX queue counters

不再散落使用大范围 rt_hw_local_irq_disable() 保护复合状态。

16.2 Driver recvmsg() 仍在 lock 外

当前 recvmsg() 已经由 rt_hw_can_isr() 在 ISR context 调用，因此新 RX Core 保持这一调用上下文。

流程：

RX IRQ
→ existing rt_hw_can_isr()
→ lifecycle fast check
→ ops->recvmsg()
→ rx.lock
→ allocate/update RX node ownership
→ enqueue
→ rx.unlock
→ rx_indicate/filter callback

HAL/driver callback 和用户 callback 都不在 rx.lock 内执行。

16.3 RX overflow policy

建议 pool 满时：

drop current/new incoming frame
+ increment drop counter

不通过覆盖 software queue 中已经入队的旧 frame 来获取空间。

这样 RX software FIFO 的 ownership 和顺序更明确。

16.4 Lifecycle 与 RX close/reconfigure

close/reconfigure 需要保证：

controller RX IRQ/receive path 停止
→ rx.lock
→ detach runtime RX state
→ rx.unlock
→ free resource

不能先 free RX pool，再允许 ISR 继续访问旧指针。

17. TX/RX 公共 Core

TX/RX 不共用同一个 spinlock。

struct rt_can_core
{
    struct rt_mutex lifecycle_lock;

    rt_atomic_t lifecycle_state;
    rt_atomic_t bus_state;

    rt_uint32_t capabilities;

    struct rt_can_tx_core tx;
    struct rt_can_rx_core rx;
};

然后直接嵌入：

struct rt_can_device
{
    struct rt_device parent;

    const struct rt_can_ops *ops;
    struct can_configure config;

    /* Existing compatibility fields as needed. */

    struct rt_can_core core;
};

不使用：

struct rt_can_core *core;

理由是 core 与 CAN device 生命周期一致，直接嵌入更适合 MCU，也避免额外 malloc 和 ownership。

公共部分只包含：

Lifecycle
Bus State
Capabilities
configuration/open/close/recover transaction

TX/RX 各自维护自己的 queue、ownership 和 spinlock。

锁顺序固定为：

lifecycle_lock
    ↓
tx.lock / rx.lock

ISR 永远不会获取 lifecycle_lock。

18. 现有 BSP ISR 必须零修改兼容

第一阶段保留：

void rt_hw_can_isr(struct rt_can_device *can, int event);

保留现有 event 编码和 BSP 调用方式。

例如 BSP 现在：

rt_hw_can_isr(can,
              RT_CAN_EVENT_TX_DONE |
              (mailbox << 8));

不需要修改。

新的 rt_hw_can_isr() 内部改成 compatibility dispatcher：

void rt_hw_can_isr(struct rt_can_device *can, int event)
{
    rt_uint32_t type = event & 0xff;
    rt_uint32_t index = event >> 8;

    switch (type)
    {
    case RT_CAN_EVENT_TX_DONE:
        _can_tx_mailbox_event(can, index, RT_CAN_TX_RESULT_OK);
        break;

    case RT_CAN_EVENT_TX_FAIL:
        _can_tx_mailbox_event(can, index, RT_CAN_TX_RESULT_ERROR);
        break;

    case RT_CAN_EVENT_RX_IND:
        _can_rx_event(can, index);
        break;

    default:
        /* existing compatibility events */
        break;
    }
}

这样新 Core 可以获得 typed internal event，但 BSP 不需要一次性迁移。

19. Kconfig 裁剪

不增加：

RT_CAN_USING_RX
RT_CAN_USING_TX

CAN Framework 默认同时具备 TX/RX。

只对真正影响代码和 RAM 的功能做裁剪，例如：

config RT_CAN_USING_TX_BLOCKING
    bool "Enable CAN blocking TX"

config RT_CAN_USING_TX_NONBLOCKING
    bool "Enable CAN non-blocking TX"
    help
        Drivers providing non-blocking TX must implement sendmsg()
        as an ISR-safe hardware submission callback.

config RT_CAN_USING_TX_CALLBACK
    bool "Enable CAN TX completion callback"
    depends on RT_CAN_USING_TX_NONBLOCKING

config RT_CAN_USING_TX_TRACE
    bool "Enable CAN TX request trace"

config RT_CAN_TX_REQUEST_COUNT
    int "CAN TX request pool size"
    range 1 256

条件编译目标：

blocking disabled
→ remove completion / waiter path

callback disabled
→ remove callback + callback_arg

trace disabled
→ remove sequence + trace code

Request Pool RAM 可以按：

sizeof(rt_can_tx_request) × RT_CAN_TX_REQUEST_COUNT

直接评估。

20. Public API 兼容

第一阶段继续保留：

rt_device_read()
rt_device_write()
rt_device_control()
struct rt_can_msg

包括现有：

msg.nonblocking

作为 compatibility policy 输入。

内部立即转换为统一 Request：

rt_device_write
→ compatibility adapter
→ allocate TX Request
→ unified TX Engine

同时新增 async completion API，但不要求旧应用迁移。

21. 现有字段到新 Core 的迁移关系

当前实现	新 Framework
_can_int_tx blocking 独立路径	Unified TX Engine
_can_nonblocking_tx 独立路径	Unified TX Engine
rt_can_tx_fifo mailbox freelist	TX Request Pool + mailbox ownership
tx_fifo->sem	Request/ownership 生命周期，不再作为 correctness 主体
mailbox slot completion	per-request completion
status.sndchange	不再用于 ownership
nb_tx_rb	删除，改为 TX Request FIFO
sendmsg_nonblocking()	第一阶段保留成员兼容，new core 不依赖
sendmsg(can,msg,box)	唯一 BSP TX submit primitive
TX ISR 中 put_force	删除，失败恢复 queue HEAD
raw local IRQ critical sections	TX/RX 独立 spin_lock_irqsave
RX freelist/uselist	保留，但统一由 rx.lock 保护
rt_hw_can_isr()	完整保留外部 BSP contract，内部适配新 Core

22. 新 Framework 解决的问题对应关系

痛点	方案
blocking/non-blocking 两套发送逻辑	Unified TX Engine
后来的 frame 绕过 software backlog	所有 TX 统一先进入 Request FIFO
put_force 导致 reorder/overwrite	reserve-submit-commit + restore queue HEAD
mailbox ownership 模糊	mailbox_owner[n] -> request
timeout 后 slot/request 过早复用	timeout != terminal
late IRQ 污染新 request	explicit mailbox ownership
duplicate/abort race	exactly-once terminal handler
full flush 无统一语义	QUIESCING + CANCEL + ABORT + QUIESCED
runtime bitrate change race	Lifecycle transaction
close 与 active TX/RX race	Lifecycle + TX/RX lock domain
non-blocking completion 无 identity	TX Request + callback
IRQ-off 范围过大	short TX/RX spinlock critical sections
SMP local IRQ disable 不足	irq-safe spinlock
bus-off 与 stop 混淆	Bus State 与 Lifecycle 分离
RX list/HDR compound state	RX ownership under one lock
大量 BSP 迁移成本	keep rt_hw_can_isr() / public device API

23. 分阶段落地建议

这份 Issue 讨论的是整体目标架构，不建议一个 PR 一次全部完成。

建议后续按以下层次拆分：

PR 1：Core synchronization foundation

- TX/RX spinlock domain
- lifecycle 基础状态
- 保持现有 public behavior
- 增加 core-level host/stub tests

PR 2：Unified TX Request + Scheduler

- Request Pool
- FIFO pending queue
- mailbox_owner
- reserve/submit/commit
- blocking/non-blocking unified engine
- remove nb_tx_rb correctness dependency

PR 3：Terminal / timeout correctness

- exactly-once terminal
- timeout waiter detach
- stale/duplicate IRQ handling
- callback API

PR 4：Strict TX order

- generic strict wire order
- ordered multi-mailbox capability
- resolve #11270 class ordering problems

PR 5：Quiesce / Full Flush / Abort

- QUIESCING / QUIESCED
- DRAIN / DROP_QUEUED / ABORT_ALL
- hardware abort capability
- support runtime bitrate reconfiguration

PR 6：Lifecycle / Bus-off / Recovery

- close safety
- reconfigure transaction
- Bus State
- controller recovery

PR 7：RX ownership cleanup and further capability normalization

- RX spinlock migration
- RX overflow policy
- filter/HDR ownership cleanup
- CAN FD / filter capability follow-up

实际拆分可根据 maintainer review 调整，但建议始终保持每个 PR 的 contract 清晰、可独立验证和可回滚。

24. 希望社区重点评估的细节

总体架构按上述 proposal 讨论，希望重点得到以下反馈：

1. sendmsg() 统一为 hardware submit primitive，并要求支持 non-blocking 的 driver 保证 ISR-safe，这个 BSP contract 是否合适；
2. sendmsg_nonblocking() 作为过渡成员保留多久比较合适；
3. Generic strict wire-order 默认串行 hardware pending，对不同 controller 的吞吐影响是否可接受；
4. ordered multi-mailbox capability 的抽象是否足够通用；
5. Request Pool 的默认容量和配置入口应该放在 global Kconfig 还是 can_configure；
6. async completion callback 默认 ISR context 是否符合 RT-Thread driver API 习惯；
7. privmode 在统一 scheduler 下继续使用指定 mailbox 时，是否需要保留现有并行语义；
8. RX pool 满时采用 drop-new 而不是覆盖已排队旧 frame，兼容性是否需要额外考虑；
9. Lifecycle 状态与现有 RT_CAN_CMD_START/STOP/CONFIG control command 的映射方式；
10. 哪些现有 BSP 最适合作为第一批迁移和回归验证对象。

25. 当前建议冻结的架构基线

如果这套方向获得认可，后续实现建议以以下约束作为基线：

1. One Unified TX Engine.
2. Preallocated TX Request Descriptor Pool.
3. FIFO software pending queue.
4. Explicit mailbox -> request ownership.
5. One BSP TX submit API: sendmsg(can, msg, mailbox).
6. Non-blocking capable drivers require ISR-safe sendmsg().
7. No deferred scheduler / worker thread.
8. TX scheduler is kicked by enqueue and terminal events.
9. Generic strict wire-order guarantee.
10. Timeout is not a hardware terminal event.
11. Exactly-once terminal completion.
12. Lifecycle State and Bus State are separate.
13. Full flush is implemented through quiesce + cancel + hardware abort.
14. TX/RX have independent irq-safe spinlocks.
15. RX keeps the existing node-pool model but fixes ownership/synchronization.
16. Existing rt_hw_can_isr() call sites remain unchanged.
17. Existing rt_device API remains compatible in the first stage.
18. No RT_CAN_USING_RX / RT_CAN_USING_TX Kconfig split.
19. Optional blocking/nonblocking/callback/trace features can be compiled out.
20. status/statistics are observability only, not transaction ownership state.

这份 proposal 的核心目标是让 CAN Framework 从“多个发送路径 + 隐式 mailbox 状态 + IRQ critical sections”演进为：

explicit TX transaction ownership
+ ordered scheduler
+ explicit lifecycle
+ clear driver contract
+ independent TX/RX synchronization domains

如果整体 contract 可以达成共识，再进入具体结构体字段、error code、Kconfig 命名、BSP migration 和 PR implementation，会比继续围绕单个 bug 逐项打补丁更容易维护。

[github-actions]

如需认领并处理此 Issue，请评论 /claim。

To claim and work on this issue, comment /claim.

[wdfk-prog]

@BernardXiong @meng-plus @Rbb666 @Guozhanxin @illustriousness @gbcwbz @CYFS3