[serial] fix: handle RT_SERIAL_EVENT_RX_TIMEOUT in the v1 receive path by Yunlk · Pull Request #11909 · RT-Thread/rt-thread

Yunlk · 2026-10-20T16:15:25Z

拉取/合并请求描述：(PR description)

[

为什么提交这份PR (why to submit this PR)

关联 issue #8143。

RT_SERIAL_EVENT_RX_TIMEOUT（0x05）在 components/drivers/include/drivers/dev_serial.h 里已经定义，但 rt_hw_serial_isr() 的 switch 只处理 0x01~0x04，且没有 default 分支。所以驱动发出这个事件时，框架不做任何事——事件被静默丢弃。

仓库里正好有两个驱动依赖它，都是拿芯片的接收空闲超时中断来切分数据帧：

/* bsp/wch/arm/ch579m/board/drv_uart.c:335 */
case UART_II_RECV_TOUT:         // 接收超时，暂时一帧数据接收完成
    rt_hw_serial_isr(serial, RT_SERIAL_EVENT_RX_TIMEOUT);
    break;

/* bsp/synwit/libraries/SWM341_drivers/drv_uart.c:287 */
if(UART_INTStat(uart_cfg->UARTx, UART_IT_RX_TOUT))
{
    UART_INTClr(uart_cfg->UARTx, UART_IT_RX_TOUT);
    rt_hw_serial_isr(serial_device, RT_SERIAL_EVENT_RX_TIMEOUT);
}

这两个 BSP（bsp/wch/arm/ch579m、bsp/synwit/swm341-mini）都用 V1 框架，结果是"一帧收完"的通知永远到不了应用层，帧边界实际丢失，只能退化成按 FIFO 水位由 RX_IND 上报。

你的解决方案是什么 (what is your solution)

把超时事件并入 RX_IND 分支处理：排空硬件 FIFO，然后按软件 FIFO 中已缓存的长度回调 rx_indicate。这正是"用超时作为帧结束标志"的驱动所期望的语义，也与我之前在 issue 里建议的方案 A 一致。

只改了 components/drivers/serial/dev_serial.c 一行 case（+5 行含注释），没有新增字段、不改 ABI。

关于 V2

V2 框架未做改动，原因是我在编译验证时确认：

components/drivers/include/drivers/dev_serial_v2.h 只定义了 0x01~0x04，没有 RT_SERIAL_EVENT_RX_TIMEOUT
V2 下驱动引用该宏会直接编译失败，因此不可能发出这个事件（我试着在 V2 的 isr 里加 case，编译报 'RT_SERIAL_EVENT_RX_TIMEOUT' undeclared，已撤回）

也就是说这个坑纯粹存在于 V1。V2 若将来需要该语义，应当走它自己的读侧超时机制（RT_SERIAL_CTRL_SET_RX_TIMEOUT），那是另一个话题。

请提供验证的bsp和config (provide the config and bsp)

BSP: bsp/qemu-vexpress-a9（V1，RT_USING_SERIAL_V1）；另用 bsp/renesas/ra6m3-hmi-board（V2）做回归，确认未影响 V2 编译
.config: 均为 BSP 默认配置，未改动
action: 本地编译（xpack arm-none-eabi-gcc 15.2.1），未使用 GitHub Actions

验证情况：

项目	结果
V1 编译（vexpress-a9）	通过
V2 编译（ra6m3-hmi-board）	通过，未受影响
行为验证	已完成，见下

行为验证一开始做不了：这个事件由芯片的接收空闲超时中断触发，QEMU 的 pl011 没有该中断，我也没有 ch579m / SWM341 硬件。

后续改为用伪 serial 设备绕开硬件依赖，新增 utest components.drivers.serial.v1.uart_rx_timeout：注册伪设备并用 RT_DEVICE_FLAG_INT_RX 打开，让框架自己分配软件 FIFO，伪 getc() 从脚本缓冲区模拟硬件 FIFO，直接调用 rt_hw_serial_isr 注入事件。

同一个用例在 master 与本分支上的结果相反：

master 1c801efa : RX_TIMEOUT -> callbacks=0（事件被丢弃），用例 FAILED
本 PR          : RX_TIMEOUT -> callbacks=1, size=9，三个场景全部 PASSED

边界结论：缓冲区为空时超时事件不回调（实现并入 RX_IND 分支，该分支仅在 rx_length != 0 时上报）。

这个用例已经补上了（commit dcadd964），不依赖硬件、可直接进 CI。如果维护者认为"超时事件等价于一次 RX_IND"这个语义方向不对（比如希望超时走独立回调、或空超时也应回调），请直接说明，我按结论调整或撤回。

]

当前拉取/合并请求的状态 Intent for your PR

必须选择一项 Choose one (Mandatory):

本拉取/合并请求是一个草稿版本 This PR is for a code-review and is intended to get feedback
本拉取/合并请求是一个成熟版本 This PR is mature, and ready to be integrated into the repo

代码质量 Code Quality：

我在这个拉取/合并请求中已经考虑了 As part of this pull request, I've considered the following:

已经仔细查看过代码改动的对比 Already check the difference between PR and old code
代码风格正确，包括缩进空格，命名及其他风格 Style guide is adhered to, including spacing, naming and other styles
没有垃圾代码，代码尽量精简，不包含#if 0代码，不包含已经被注释了的代码 All redundant code is removed and cleaned up
所有变更均有原因及合理的，并且不会影响到其他软件组件代码或BSP All modifications are justified and not affect other components or BSP
对难懂代码均提供对应的注释 I've commented appropriately where code is tricky
代码是高质量的 Code in this PR is of high quality
已经使用clang-format 源码格式化工具确保格式符合RT-Thread代码规范 This PR has been formatted with clang-format and complies with RT-Thread code specification
如果是新增bsp, 已经添加ci检查到.github/ALL_BSP_COMPILE.json 详细请参考链接BSP自查

RT_SERIAL_EVENT_RX_TIMEOUT has been defined in dev_serial.h, but rt_hw_serial_isr() never had a case for it and the switch has no default branch, so a driver emitting the event was silently ignored. Two in-tree drivers rely on it to delimit a frame by the hardware idle-line timeout: bsp/wch/arm/ch579m/board/drv_uart.c UART_II_RECV_TOUT bsp/synwit/libraries/SWM341_drivers/drv_uart.c UART_IT_RX_TOUT Both BSPs build against the v1 framework, so the "frame finished" notification never reached the application. Handle the timeout like a receive indication: drain the hardware FIFO and report the bytes buffered in the software FIFO, which is what a driver using the timeout as a frame delimiter expects. The v2 framework is deliberately untouched. dev_serial_v2.h does not define the event at all (only 0x01..0x04) and its interrupt handler drops unknown events through "default:", so a v2 driver cannot emit it in the first place. Refs RT-Thread#8143

github-actions · 2026-10-20T16:15:37Z

👋 感谢您对 RT-Thread 的贡献！Thank you for your contribution to RT-Thread!

为确保代码符合 RT-Thread 的编码规范，请在你的仓库中执行以下步骤运行代码格式化工作流（如果格式化CI运行失败）。
To ensure your code complies with RT-Thread's coding style, please run the code formatting workflow by following the steps below (If the formatting of CI fails to run).

🛠 操作步骤 | Steps

前往 Actions 页面 | Go to the Actions page
点击进入工作流 → | Click to open workflow →
点击 Run workflow | Click Run workflow

Use workflow from 保持默认分支（通常为 master）
Keep the default branch (usually master) in Use workflow from
在 branch 输入框填写 PR 分支 fix/serial-rx-timeout
Enter PR branch fix/serial-rx-timeout in the branch field
设置需排除的文件/目录（目录请以"/"结尾）
Set files/directories to exclude (directories should end with "/")

等待工作流完成 | Wait for the workflow to complete
格式化后的代码将作为独立提交推送至你的分支。
The formatting changes will be pushed to your branch as a separate commit.

完成后，提交将自动更新至 fix/serial-rx-timeout 分支，关联的 Pull Request 也会同步更新。
Once completed, commits will be pushed to the fix/serial-rx-timeout branch automatically, and the related Pull Request will be updated.

如有问题欢迎联系我们，再次感谢您的贡献！💐
If you have any questions, feel free to reach out. Thanks again for your contribution!

github-actions · 2026-10-20T16:15:40Z

📌 Code Review Assignment

🏷️ Tag: components

Reviewers: @Maihuanyi

Changed Files (Click to expand)

components/drivers/serial/dev_serial.c
components/drivers/serial/utest/Kconfig
components/drivers/serial/utest/v1/SConscript
components/drivers/serial/utest/v1/uart_rx_timeout.c

📊 Current Review Status (Last Updated: 2026-10-21 13:55 CST)

⌛ @Maihuanyi Pending Review

📝 Review Instructions

维护者可以通过单击此处来刷新审查状态: 🔄 刷新状态
Maintainers can refresh the review status by clicking here: 🔄 Refresh Status
确认审核通过后评论 LGTM/lgtm
Comment LGTM/lgtm after confirming approval
PR合并前需至少一位维护者确认
PR must be confirmed by at least one maintainer before merging

ℹ️ 刷新CI状态操作需要具备仓库写入权限。
ℹ️ Refresh CI status operation requires repository Write permission.

CLAassistant · 2026-10-20T16:16:28Z

All committers have signed the CLA.

Yunlk · 2026-10-20T17:44:15Z

@Rbb666 同样需要批准 workflow（首次从 fork 贡献）：utest_auto_run 与 RT-Thread BSP Static Build Check。

本改动只有 V1 的一行 case。已用 qemu-vexpress-a9(V1) 与 ra6m3-hmi-board(V2) 做双框架编译验证；行为验证需要带接收空闲超时中断的硬件（ch579m / SWM341），我这边没有条件，正文里已明确说明未做。

若认可"超时事件等价于一次 RX_IND"这个语义，我可以补一个不依赖硬件的 utest（伪 serial 设备直接调 rt_hw_serial_isr，校验 rx_indicate 的次数与长度）。

Cover the event handled by the previous commit with a unit test that does not need any real hardware. The test registers a fake serial device and opens it with RT_DEVICE_FLAG_INT_RX, so the v1 framework allocates the software RX FIFO itself. The fake getc() serves bytes from a scripted buffer, standing in for the hardware FIFO, and rx_indicate records the reported length. Three scenarios: 1. RX_IND with 4 bytes -> one callback, length 4 2. RX_TIMEOUT with 5 more bytes -> one callback, length 9 (4 + 5 buffered) 3. RX_TIMEOUT with an empty FIFO -> no callback, nothing to report Scenario 3 documents the boundary decision: a timeout with no buffered data stays silent, matching the RX_IND path which only calls rx_indicate when the buffered length is non-zero. Verified on bsp/qemu-vexpress-a9 (RT_USING_SERIAL_V1): master 1c801ef : scenario 2 fails, callbacks=0 (event dropped) this branch : all three scenarios pass The v1 test group is new; components/drivers/serial/utest only had bypass/ and v2/ before. It is registered through a new RT_UTEST_SERIAL_V1 Kconfig option that depends on RT_USING_SERIAL_V1. Refs RT-Thread#8143 Refs RT-Thread#11909

Yunlk · 2026-10-21T05:55:55Z

已补上不依赖硬件的 utest（commit dcadd964），并做了修复前/后对照。

用例设计

不接真实串口、不需要输入激励：注册一个伪 serial 设备并用 RT_DEVICE_FLAG_INT_RX 打开，让 V1 框架自己分配软件 FIFO；伪 getc() 从脚本缓冲区吐字节，模拟硬件 FIFO；rx_indicate 记录回调次数与上报长度。

components/drivers/serial/utest/ 之前只有 bypass/ 和 v2/，V1 这组是新建的：

新增 v1/uart_rx_timeout.c 与 v1/SConscript
新增 Kconfig 项 RT_UTEST_SERIAL_V1（depends on RT_USING_SERIAL_V1），已有自动注册机制会拾取子目录

三个场景与边界结论

场景	master `1c801ef`（无修复）	本 PR（含修复）
RX_IND，4 字节	callbacks=1, size=4	callbacks=1, size=4
RX_TIMEOUT，再来 5 字节	callbacks=0, size=0（事件被丢弃）	callbacks=1, size=9
RX_TIMEOUT，缓冲区为空	—	callbacks=0

# 本 PR
[I/utest] RX_IND   -> callbacks=1, last_size=4 (expect 1 / 4)
[I/utest] RX_TIMEOUT -> callbacks=1, last_size=9 (expect 1 / 9)
[I/utest] RX_TIMEOUT (empty) -> callbacks=0 (expect 0)
[I/utest] [  PASSED  ] [ result   ] testcase (components.drivers.serial.v1.uart_rx_timeout)

# master
[I/utest] RX_IND   -> callbacks=1, last_size=4 (expect 1 / 4)
[I/utest] RX_TIMEOUT -> callbacks=0, last_size=0 (expect 1 / 9)
[E/utest] [  ASSERT  ] ... msg: ((_ind_count) not == (1))
[E/utest] [  FAILED  ] [ result   ] testcase (components.drivers.serial.v1.uart_rx_timeout)

边界结论：缓冲区为空时，超时事件不回调。因为实现是并入 RX_IND 分支，而该分支只在 rx_length != 0 时才调用 rx_indicate。我认为这与"超时表示一帧收完"的语义一致——没数据就没有可上报的帧；如果维护者认为空超时也应该回调（用于通知"本次边界"而非"有数据"），那需要另行区分，请指出。

验证环境

BSP: bsp/qemu-vexpress-a9，RT_USING_SERIAL_V1
.config: CONFIG_RT_USING_UTEST=y、CONFIG_RT_USING_UTESTCASES=y、CONFIG_RT_UTEST_SERIAL_V1=y、CONFIG_RT_USING_CI_ACTION=y、CONFIG_UTEST_THR_STACK_SIZE=8192
QEMU 11.0.0 + xpack arm-none-eabi-gcc 15.2.1
新文件已过仓库 .clang-format 校验（零差异）

这个用例不依赖任何硬件，理论上可以直接进 utest_auto_run 的 kernel 用例集；是否要把它加进 .github/utest/configs/kernel/ 下的某个 cfg，请维护者定。

PR 正文里"仅编译验证、未做行为验证"的说法已经过时，我同步更新。

Ryan-CW-Code · 2026-10-22T02:11:23Z

V2版本已经推出很长时间了，长时间并行维护V1和V2版本是个坑，个人感觉应该冻结V1版本仅作为历史兼容，串口重心往V2靠，否则V2的意义是什么呢
现在AI时代，适配V2驱动已经变得很简单了，直接参考stm32就可以实现
目前RTT的各类夏令营和入门培训依然是配套V1版本，不知道RTT官方如何看待这部分

Yunlk · 2026-10-22T05:00:18Z

@Ryan-CW-Code 这个问题确实决定了我这个 PR 该怎么落地，先补两个可能影响判断的事实（都在当前 master 上核对过）：

1. 这个事件宏只存在于 V1 的头文件。

dev_serial.h:168 定义了 RT_SERIAL_EVENT_RX_TIMEOUT (0x05)；而 dev_serial_v2.h 根本没有这个宏，只有 0x01~0x04：

dev_serial_v2.h:197 RT_SERIAL_EVENT_RX_IND 0x01 dev_serial_v2.h:198 RT_SERIAL_EVENT_TX_DONE 0x02 dev_serial_v2.h:199 RT_SERIAL_EVENT_RX_DMADONE 0x03 dev_serial_v2.h:200 RT_SERIAL_EVENT_TX_DMADONE 0x04

V2 下驱动引用它会直接编译失败，所以不存在"V2 里被静默丢弃"这回事。V2 处理接收超时用的是另一套机制：RT_SERIAL_CTRL_SET_RX_TIMEOUT（读侧 deadline，dev_serial_v2.h:206）。

2. 树内发出该事件的两个驱动，都不是 V2 的。

bsp/wch/arm/ch579m 与 bsp/synwit/swm341-mini，两者的 rtconfig 实测都是 RT_USING_SERIAL_V1。

所以这个 PR 的性质不是"给 V1 加新功能"，而是"让 V1 里已经声明的 API 名副其实"——宏在那儿，两个驱动的调用也在那儿，行为却是空操作。

不过你的顾虑我认同：即便只是补一个 case，也是给 V1 增加了一份要长期维护的行为。

如果按"冻结 V1、只作历史兼容"的方向，反向的方案其实更自洽：把这个从未实现过的宏从 V1 头文件里删掉，同时改掉 ch579m / swm341-mini 那两处调用（或者标注为需要迁移到 V2）。这样 V1 会更薄，也不必新增我那 210 行的 utest。我个人倾向这个方向更贴合你说的路线——前提是这两个 BSP 是否还有人在维护，这一点我判断不了。

顺带一个 V2 侧的同类隐患，供一起讨论：V2 的 rt_hw_serial_isr 对未知事件走 default: break; 静默丢弃。如果 V2 是未来，建议把"V2 允许哪些事件"明确下来，并让未知事件显式报出来（断言或至少一行日志），否则驱动写错事件号时很难排查。

最终怎么落地请维护者定：保留当前实现（V1 补 case + utest），还是改成"删宏 + 改驱动"，两种我都能执行，给结论我就动。

Rbb666 · 2026-10-22T05:35:25Z

V2版本已经推出很长时间了，长时间并行维护V1和V2版本是个坑，个人感觉应该冻结V1版本仅作为历史兼容，串口重心往V2靠，否则V2的意义是什么呢现在AI时代，适配V2驱动已经变得很简单了，直接参考stm32就可以实现目前RTT的各类夏令营和入门培训依然是配套V1版本，不知道RTT官方如何看待这部分

保留V1是因为BSP中还有很多BSP是依赖并使用V1的，因为有些BSP只是为了把串口当成MSH功能即可（可以满足最基础的需求了），并没有很深度的使用串口，所以是有历史遗留的。

我认为后续的BSP可以主动引导贡献者去优先适配V2版本的，像瑞萨这些BSP已经适配了V2

github-actions Bot added Component component: drivers/serial component: drivers labels Oct 20, 2026

Yunlk mentioned this pull request Oct 20, 2026

serial组件中的超时事件RT_SERIAL_EVENT_RX_TIMEOUT 仅做了定义但是为什么不给实现呢 #8143

Open

Yunlk marked this pull request as ready for review October 20, 2026 17:32

style: format code with clang-format

87b851b

Navigation Menu

Repository navigation

[serial] fix: handle RT_SERIAL_EVENT_RX_TIMEOUT in the v1 receive path - #11909

[serial] fix: handle RT_SERIAL_EVENT_RX_TIMEOUT in the v1 receive path#11909
Yunlk wants to merge 3 commits into
RT-Thread:masterfrom
Yunlk:fix/serial-rx-timeout

Yunlk commented Oct 20, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 20, 2026

Uh oh!

github-actions Bot commented Oct 20, 2026 •

edited

Loading

Uh oh!

CLAassistant commented Oct 20, 2026 •

edited

Loading

Uh oh!

Yunlk commented Oct 20, 2026

Uh oh!

Yunlk commented Oct 21, 2026

Uh oh!

Ryan-CW-Code commented Oct 22, 2026

Uh oh!

Yunlk commented Oct 22, 2026

Uh oh!

Rbb666 commented Oct 22, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

Yunlk commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

拉取/合并请求描述：(PR description)

为什么提交这份PR (why to submit this PR)

你的解决方案是什么 (what is your solution)

关于 V2

请提供验证的bsp和config (provide the config and bsp)

当前拉取/合并请求的状态 Intent for your PR

代码质量 Code Quality：

Uh oh!

github-actions Bot commented Oct 20, 2026

🛠 操作步骤 | Steps

Uh oh!

github-actions Bot commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📌 Code Review Assignment

🏷️ Tag: components

📊 Current Review Status (Last Updated: 2026-10-21 13:55 CST)

📝 Review Instructions

Uh oh!

CLAassistant commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Yunlk commented Oct 20, 2026

Uh oh!

Yunlk commented Oct 21, 2026

用例设计

三个场景与边界结论

验证环境

Uh oh!

Ryan-CW-Code commented Oct 22, 2026

Uh oh!

Yunlk commented Oct 22, 2026

Uh oh!

Rbb666 commented Oct 22, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Yunlk commented Oct 20, 2026 •

edited

Loading

github-actions Bot commented Oct 20, 2026 •

edited

Loading

CLAassistant commented Oct 20, 2026 •

edited

Loading