Skip to content

Feature/ksym backtrace - #11768

Open
liulangrenaaa wants to merge 3 commits into
RT-Thread:masterfrom
liulangrenaaa:feature/ksym-backtrace
Open

Feature/ksym backtrace#11768
liulangrenaaa wants to merge 3 commits into
RT-Thread:masterfrom
liulangrenaaa:feature/ksym-backtrace

Conversation

@liulangrenaaa

@liulangrenaaa liulangrenaaa commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

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

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

当前 RT-Thread 通用 backtrace 主要输出原始 PC 地址，并提示用户使用
addr2line 进行解析。在 exception、assert、panic 等现场，通常没有
完整 ELF/DWARF 环境，定位函数名称不够方便。

本 PR 增加一个可选的内核函数符号表，使 backtrace 可以直接输出函数名、
函数内偏移和函数大小，例如：

0x60043e90 <ksym_test_level3+0xc/0x14>
0x60043e7c <ksym_test_level2+0xc/0x14>
0x60043e68 <ksym_test_level1+0xc/0x14>

该功能默认关闭，不影响未启用配置的 ROM 和原有 backtrace 行为。

本 PR 包含三个 commit：

1. kernel: add optional ksym table
    - 增加通用 kernel symbol table 和 rt_ksym_lookup() API
    - 增加 GCC/ELF 符号生成器及 SCons 多阶段构建流程

2. kernel: symbolize backtraces
    - 将公共 backtrace 输出接入 kernel symbol resolver
    - 保留原始 PC，并在解析失败时回退为地址输出

3. libcpu: add Cortex-A ksym backtrace
    - 将 Cortex-A backtrace 接入公共格式化输出
    - 增加 ARM32 和 AArch64 的静态函数回溯测试

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

新增 RT_USING_KSYMS 配置项，默认值为 n。

在 native SCons GCC/ELF 构建中，构建流程会从预链接 ELF 中提取函数符号，
生成紧凑的只读 kernel symbol table，然后重新链接最终 ELF：

objects
  -> rtthread.pre1.elf
  -> generate ksym table
  -> rtthread.pre2.elf
  -> generate final ksym table
  -> rtthread.elf
  -> verify final symbol addresses

符号表包含：

- global function
- local/static function
- weak function
- symbol start address
- symbol name
- symbol size

运行时使用无锁二分查找，不使用 heap、mutex 或动态内存。符号表使用相对地址、
name offset 和共享字符串表，以减少存储开销。

地址解析规则：

- 支持 duplicate-address aliases
- 使用下一个不同地址的 symbol 计算函数范围
- 支持最后一个 symbol 和 zero-sized symbol
- 32-bit ARM 仅清除 Thumb bit
- AArch64 和 RISC-V 不进行 Thumb address normalization
- 未找到 symbol 时保留原始 PC 并回退为地址输出
- RT_USING_KSYMS=n 时保留原有 addr2line 使用方式

该版本第一阶段仅支持 GCC/ELF/native SCons 构建。其他工具链和
--target=makefile 等生成项目在启用 RT_USING_KSYMS 时会直接报错。

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

- BSP:
    - bsp/qemu-vexpress-a9
    - bsp/qemu-virt64-aarch64
    - bsp/qemu-virt64-riscv：完成 KSYMS 构建和 ELF 验证测试

- .config:

  CONFIG_RT_USING_KSYMS=y
  CONFIG_RT_USING_UTEST=y
  CONFIG_RT_UTEST_KSYMS=y

  其中：

  CONFIG_RT_USING_KSYMS=n

  为默认配置，不启用时保持原有行为。

- action:

  https://github.com/liulangrenaaa/rt-thread/actions/workflows/manual_dist.yml

  PR branch:

  feature/ksym-backtrace

#### 测试结果

1. Python generator tests

   python3 -m unittest tools.testcases.test_gen_ksym

   ......
   ----------------------------------------------------------------------
   Ran 6 tests in 0.001s

   OK

   另外通过：

   python3 -m py_compile \
       tools/gen_ksym.py \
       tools/ksym.py \
       tools/testcases/test_gen_ksym.py

2. ARM32 qemu-vexpress-a9
    - GCC/ELF 三阶段链接通过
    - gen_ksym.py --verify 通过
    - build/ksym/ 中间文件生成正常
    - QEMU 启动正常
    - core.ksym 测试通过
    - 静态函数 backtrace 解析正常

   实际输出：

   0x60043e90 <ksym_test_level3+0xc/0x14>
   0x60043e7c <ksym_test_level2+0xc/0x14>
   0x60043e68 <ksym_test_level1+0xc/0x14>

   [  PASSED  ] testcase (core.ksym)
   [  PASSED  ] 1 tests.

3. AArch64 qemu-virt64-aarch64
    - GCC/ELF 三阶段链接通过
    - 使用 --exec-path 指定工具链目录
    - 工具链目录不在宿主系统 PATH 中
    - generator 和 final verify 均能正确继承 SCons 环境
    - QEMU 启动正常
    - core.ksym 测试通过
    - AArch64 未进行错误的 Thumb bit normalization

   实际输出：

   0x40099a44 <ksym_test_level3+0x8/0x18>

   [  PASSED  ] testcase (core.ksym)

4. RISC-V64 qemu-virt64-riscv
    - 三阶段 KSYMS 构建通过
    - gen_ksym.py --verify 通过
    - 符号 resolver 可以正确输出函数名称：

   0x802430e6 <_query+0x9a/0x178>

   后续失败发生在现有 RISC-V frame-pointer unwind 路径中。
   unwind 访问非法 frame 地址 0x10，随后触发嵌套异常。
   该问题发生在 symbol lookup 之后，与 rt_ksym_lookup() 和 KSYMS
   表生成无关。

5. --exec-path 验证

   使用以下方式完成 AArch64 构建：

   scons --pyconfig-silent \
       --exec-path=/opt/rtthread-aarch64-none-elf/bin

   scons -j2 \
       --exec-path=/opt/rtthread-aarch64-none-elf/bin

   构建过程确认：

   LINK build/ksym/rtthread.pre1.elf
   CC build/ksym/rtthread.pre1.o
   LINK build/ksym/rtthread.pre2.elf
   CC build/ksym/rtthread.final.o
   LINK rtthread.elf
   verify_final(["rtthread.elf"], ...)

6. 代码检查
    - git diff --check 通过
    - Python generator tests 通过
    - Python syntax check 通过
    - 三个 commit 保持独立职责
    - 生成的中间文件均位于 build/ksym/
    - RT_USING_KSYMS 默认关闭


`action` 


[
<!-- 这段方括号里的内容是您**必须填写并替换掉**的，否则PR不可能被合并。**方括号外面的内容不需要修改，但请仔细阅读。**
The content in this square bracket must be filled in and replaced, otherwise, PR can not be merged. The contents outside square brackets need not be changed, but please read them carefully.

请在这里填写您的PR描述，可以包括以下之一的内容：为什么提交这份PR；解决的问题是什么，你的解决方案是什么；
Please fill in your PR description here, which can include one of the following items: why to submit this PR; what is the problem solved and what is your solution;

并确认并列出已经在什么情况或板卡上进行了测试。
And confirm in which case or board has been tested. -->

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


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



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

<!-- 请填写验证bsp目录下面的目录比如bsp/stm32/stm32l496-st-nucleo

Please provide the path of verfied bsp. Like bsp/stm32/stm32l496-st-nucleo  bsp/ESP32_C3 -->

- BSP:

<!-- 请填写.config 文件中需要改动的config

Please provide the changed config of .config file to how to verify the PR file like CONFIG_BSP_USING_I2C CONFIG_BSP_USING_WDT -->

- .config:

<!-- 请提供自己仓库的PR branch的action的编译链接相关PR文件成功的链接：

Please provide the link of action triggered by your own repo's action  

https://github.com/RT-Thread/rt-thread/actions/workflows/manual_dist.yml -->

- action:

]

<!-- 以下的内容不应该在提交PR时的message修改，修改下述message，PR会被直接关闭。请在提交PR后，浏览器查看PR并对以下检查项逐项check，没问题后逐条在页面上打钩。
The following content must not be changed in the submitted PR message. Otherwise, the PR will be closed immediately. After submitted PR, please use a web browser to visit PR, and check items one by one, and ticked them if no problem. -->

### 当前拉取/合并请求的状态 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](https://clang.llvm.org/docs/ClangFormat.html) 源码格式化工具确保格式符合[RT-Thread代码规范](https://github.com/RT-Thread/rt-thread/blob/master/documentation/7.contribution/coding_style_cn.md) This PR has been formatted with clang-format and complies with [RT-Thread code specification](https://github.com/RT-Thread/rt-thread/blob/master/documentation/7.contribution/coding_style_en.md)
- [ ] 如果是新增bsp, 已经添加ci检查到[.github/ALL_BSP_COMPILE.json](https://github.com/RT-Thread/rt-thread/blob/master/.github/ALL_BSP_COMPILE.json)  详细请参考链接[BSP自查](https://www.rt-thread.org/document/site/#/rt-thread-version/rt-thread-standard/development-guide/bsp-selfcheck/bsp_selfcheck)

@liulangrenaaa
kernel: add optional ksym table
be19256 
Add optional symbol lookup for native SCons GCC/ELF builds.

The generated table includes local, global, and weak functions in a
compact relative-address format with a shared string table and
per-symbol sizes.

Use a lock-free binary search, preserve raw addresses, and canonicalize
Thumb addresses only for 32-bit ARM. Verify generated addresses after
the multi-pass link.

Keep artifacts under build/ksym and pass the toolchain environment to
the generators. The option remains disabled by default because the
embedded function names and entries consume read-only memory.
@liulangrenaaa
kernel: symbolize backtraces
9bff3b5 
Use the kernel symbol resolver from the common backtrace printers
when RT_USING_KSYMS is enabled.

Keep the raw program counter in every line and fall back to the
address-only format when no symbol is found. Retain the existing
addr2line guidance when the option is disabled.
@liulangrenaaa
libcpu: add Cortex-A ksym backtrace
3a46112 
Route Cortex-A unwind frames through the common formatted printer
when kernel symbols are enabled.

Disable the legacy Cortex-A function-name path in that mode to avoid
duplicate output while retaining the existing unwind behavior. Add
static-function lookup and backtrace coverage for ARM32 and AArch64.
@github-actions

github-actions Bot commented Aug 28, 2026

Copy link
Copy Markdown

👋 感谢您对 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

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

  2. 点击 Run workflow | Click Run workflow

  • Use workflow from 保持默认分支（通常为 master）
    Keep the default branch (usually master) in Use workflow from
  • 在 branch 输入框填写 PR 分支 feature/ksym-backtrace
    Enter PR branch feature/ksym-backtrace in the branch field
  • 设置需排除的文件/目录（目录请以"/"结尾）
    Set files/directories to exclude (directories should end with "/")
  1. 等待工作流完成 | Wait for the workflow to complete
    格式化后的代码将作为独立提交推送至你的分支。
    The formatting changes will be pushed to your branch as a separate commit.

完成后，提交将自动更新至 feature/ksym-backtrace 分支，关联的 Pull Request 也会同步更新。
Once completed, commits will be pushed to the feature/ksym-backtrace 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 github-actions Bot added Kernel PR has src relate code tools libcpu labels Aug 28, 2026
@github-actions

github-actions Bot commented Aug 28, 2026

Copy link
Copy Markdown

📌 Code Review Assignment

🏷️ Tag: kernel

Reviewers: @GorrayLi @ReviewSun @hamburger-os @lianux-mm @wdfk-prog @xu18838022837

Changed Files (Click to expand)
  • src/Kconfig
  • src/kservice.c
  • src/ksym.c
  • src/utest/Kconfig
  • src/utest/SConscript
  • src/utest/ksym_tc.c

📊 Current Review Status (Last Updated: 2026-08-29 02:52 CST)

📝 Review Instructions

  1. 维护者可以通过单击此处来刷新审查状态: 🔄 刷新状态
    Maintainers can refresh the review status by clicking here: 🔄 Refresh Status

  2. 确认审核通过后评论 LGTM/lgtm
    Comment LGTM/lgtm after confirming approval

  3. PR合并前需至少一位维护者确认
    PR must be confirmed by at least one maintainer before merging

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

@github-actions

github-actions Bot commented Aug 28, 2026

Copy link
Copy Markdown

MemBrowse Memory Report

nordic-nrf51822

  • FLASH: .text +4 B (+0.0%, 52,012 B / 262,144 B, total: 20% used)

raspberry-pico-rp2040

  • FLASH: .text +8 B (+0.0%, 114,112 B / 2,097,152 B, total: 5% used)

simulator

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

Kernel PR has src relate code libcpu tools

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@liulangrenaaa