From 97f9d2ad26f4c4aefd61ac40d4e9e6da368b5dc5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 24 Oct 2025 23:04:51 +0000 Subject: [PATCH 1/4] Initial plan From c379f1714858b21a155e349a83284c8a7ad4bbf1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 24 Oct 2025 23:13:31 +0000 Subject: [PATCH 2/4] Add comprehensive Rust component directory structure proposal Co-authored-by: BernardXiong <1241087+BernardXiong@users.noreply.github.com> --- docs/rust-component-structure-proposal.md | 514 ++++++++++++++++++ ...rust-component-structure-recommendation.md | 372 +++++++++++++ 2 files changed, 886 insertions(+) create mode 100644 docs/rust-component-structure-proposal.md create mode 100644 docs/rust-component-structure-recommendation.md diff --git a/docs/rust-component-structure-proposal.md b/docs/rust-component-structure-proposal.md new file mode 100644 index 00000000..016f0fac --- /dev/null +++ b/docs/rust-component-structure-proposal.md @@ -0,0 +1,514 @@ +# RT-Thread Rust组件目录结构设计方案 + +## 概述 + +本文档提供RT-Thread集成Rust语言支持的目录结构设计方案，遵循RT-Thread的松耦合、模块化设计理念。 + +## 一、总体目录结构 + +建议在`rt-thread/components/`下创建`rust`组件，整体结构如下： + +``` +rt-thread/components/rust/ +├── Kconfig # Rust组件配置选项 +├── SConscript # SCons构建脚本 +├── README.md # 组件说明文档 +├── docs/ # 详细文档目录 +│ ├── api_reference.md # API参考文档 +│ ├── abi_compatibility.md # ABI兼容性说明 +│ └── performance_report.md # 性能测试报告 +├── core/ # Rust核心支持库 +│ ├── Cargo.toml # Rust项目配置 +│ ├── build.rs # 构建脚本 +│ ├── src/ +│ │ ├── lib.rs # 库入口 +│ │ ├── bindings/ # C接口绑定 +│ │ │ ├── mod.rs +│ │ │ ├── kernel.rs # 内核API绑定 +│ │ │ ├── thread.rs # 线程相关API +│ │ │ ├── ipc.rs # IPC机制绑定 +│ │ │ ├── memory.rs # 内存管理API +│ │ │ └── device.rs # 设备驱动API +│ │ ├── rt_prelude.rs # RT-Thread预导入模块 +│ │ ├── allocator.rs # 内存分配器实现 +│ │ ├── panic.rs # panic处理器 +│ │ └── macros/ # 宏定义 +│ │ ├── mod.rs +│ │ ├── thread_entry.rs # 线程入口宏 +│ │ └── msh_export.rs # Shell命令导出宏 +│ └── cbindgen.toml # C头文件生成配置 +├── runtime/ # Rust运行时支持 +│ ├── Cargo.toml +│ ├── src/ +│ │ ├── lib.rs +│ │ ├── no_std_support.rs # no_std模式支持 +│ │ ├── start.rs # 启动代码 +│ │ └── lang_items.rs # 语言项实现 +│ └── linker/ # 链接脚本 +│ └── rust_module.ld +├── msh/ # Shell命令支持 +│ ├── Cargo.toml +│ ├── src/ +│ │ ├── lib.rs +│ │ └── commands.rs # Rust命令实现 +│ └── SConscript +├── examples/ # 示例代码目录 +│ ├── README.md # 示例说明文档 +│ ├── applications/ # 应用程序示例 +│ │ ├── hello_world/ +│ │ │ ├── Cargo.toml +│ │ │ └── src/ +│ │ │ └── main.rs # 简单应用示例 +│ │ ├── thread_sync/ +│ │ │ ├── Cargo.toml +│ │ │ └── src/ +│ │ │ └── main.rs # 线程同步示例 +│ │ └── device_io/ +│ │ ├── Cargo.toml +│ │ └── src/ +│ │ └── main.rs # 设备IO示例 +│ ├── components/ # 组件/软件包示例 +│ │ ├── logger/ +│ │ │ ├── Cargo.toml +│ │ │ └── src/ +│ │ │ └── lib.rs # 日志组件示例 +│ │ ├── sensor_driver/ +│ │ │ ├── Cargo.toml +│ │ │ └── src/ +│ │ │ └── lib.rs # 传感器驱动示例 +│ │ └── protocol_stack/ +│ │ ├── Cargo.toml +│ │ └── src/ +│ │ └── lib.rs # 协议栈示例 +│ └── modules/ # 内核动态模块示例 +│ ├── simple_module/ +│ │ ├── Cargo.toml +│ │ ├── module.ld # 模块链接脚本 +│ │ └── src/ +│ │ └── lib.rs # 简单内核模块 +│ └── device_module/ +│ ├── Cargo.toml +│ ├── module.ld +│ └── src/ +│ └── lib.rs # 设备驱动模块 +├── tools/ # 工具脚本 +│ ├── build_rust.py # Rust构建辅助脚本 +│ ├── gen_bindings.sh # 生成绑定脚本 +│ └── cargo_wrapper.py # Cargo包装脚本 +└── tests/ # 测试代码 + ├── integration/ # 集成测试 + └── unit/ # 单元测试 +``` + +## 二、各模块详细说明 + +### 2.1 核心支持库 (core/) + +**目标**: 提供Rust与RT-Thread内核交互的基础设施。 + +**关键文件**: + +- `bindings/`: 使用bindgen或手工编写的C API安全封装 + - 按功能模块划分（thread, ipc, memory, device等） + - 提供类型安全的Rust接口 + +- `rt_prelude.rs`: 类似于std::prelude，预导入常用类型和trait + ```rust + // 示例 + pub use crate::bindings::thread::*; + pub use crate::bindings::ipc::*; + pub use crate::macros::*; + ``` + +- `allocator.rs`: 实现`GlobalAlloc` trait，对接RT-Thread的内存管理 + ```rust + #[global_allocator] + static ALLOCATOR: RTThreadAllocator = RTThreadAllocator; + ``` + +- `macros/`: 提供便利宏 + - `thread_entry!`: 将Rust函数标记为线程入口点 + - `msh_cmd_export!`: 导出shell命令 + ```rust + // 使用示例 + #[msh_cmd_export] + fn my_command(argc: i32, argv: &[&str]) { + // 命令实现 + } + ``` + +### 2.2 运行时支持 (runtime/) + +**目标**: 提供no_std环境下的Rust运行时。 + +**关键实现**: + +- `no_std_support.rs`: + - 实现`#![no_std]`环境所需的基础功能 + - 提供panic handler + - 实现必要的语言项(lang_items) + +- `start.rs`: + - 提供应用程序启动代码 + - 处理main函数到RT-Thread线程的转换 + ```rust + #[no_mangle] + pub extern "C" fn rust_main_wrapper(arg: *mut c_void) { + // 初始化Rust环境 + // 调用用户main函数 + } + ``` + +### 2.3 Shell命令支持 (msh/) + +**目标**: 简化Rust程序导出shell命令的过程。 + +**功能**: +- 提供`MSH_CMD_EXPORT`宏的Rust版本 +- 自动处理参数解析 +- 支持命令帮助信息 + +### 2.4 示例代码 (examples/) + +#### 2.4.1 应用程序示例 (applications/) + +展示如何使用Rust编写RT-Thread应用： + +1. **hello_world**: 最简单的Rust应用 + - 演示基础线程创建 + - 演示打印输出 + +2. **thread_sync**: 线程同步示例 + - 演示互斥锁、信号量使用 + - 演示消息队列通信 + +3. **device_io**: 设备IO示例 + - 演示设备打开/读写 + - 演示中断处理 + +#### 2.4.2 组件/软件包示例 (components/) + +展示如何使用Rust开发可复用组件： + +1. **logger**: 日志组件 + - 实现类似log crate的功能 + - 对接RT-Thread的ulog + +2. **sensor_driver**: 传感器驱动 + - 演示设备驱动框架使用 + - 演示I2C/SPI通信 + +3. **protocol_stack**: 协议栈 + - 演示网络组件开发 + - 演示零拷贝优化 + +#### 2.4.3 内核模块示例 (modules/) + +展示如何开发动态加载的内核模块： + +1. **simple_module**: 简单模块 + - 演示模块初始化/清理 + - 演示符号导出 + +2. **device_module**: 设备驱动模块 + - 演示动态加载设备驱动 + - 演示热插拔支持 + +## 三、构建系统集成 + +### 3.1 Kconfig配置 + +```kconfig +menuconfig RT_USING_RUST + bool "Rust Language Support" + default n + help + Enable Rust language support for RT-Thread. + +if RT_USING_RUST + + config RT_RUST_CORE + bool "Enable Rust Core Library" + default y + help + Core Rust bindings for RT-Thread kernel. + + config RT_RUST_RUNTIME + bool "Enable Rust Runtime Support" + default y + select RT_RUST_CORE + help + Runtime support for no_std Rust applications. + + config RT_RUST_MSH_SUPPORT + bool "Enable Rust MSH Command Support" + default y + depends on RT_USING_FINSH + help + Support exporting Rust functions to RT-Thread shell. + + config RT_RUST_ALLOCATOR + bool "Enable Rust Global Allocator" + default y + depends on RT_USING_HEAP + help + Use RT-Thread memory allocator for Rust heap allocations. + + menu "Rust Examples" + config RT_RUST_EXAMPLES_APPS + bool "Build Application Examples" + default n + + config RT_RUST_EXAMPLES_COMPONENTS + bool "Build Component Examples" + default n + + config RT_RUST_EXAMPLES_MODULES + bool "Build Module Examples" + default n + depends on RT_USING_LWP && RT_USING_MODULE + endmenu + + config RT_RUST_TOOLCHAIN_PATH + string "Rust Toolchain Path" + default "" + help + Path to Rust toolchain. Leave empty to use system default. + + choice RT_RUST_TARGET_ARCH + prompt "Rust Target Architecture" + default RT_RUST_TARGET_AUTO + + config RT_RUST_TARGET_AUTO + bool "Auto Detect" + + config RT_RUST_TARGET_RISCV64 + bool "riscv64gc-unknown-none-elf" + + config RT_RUST_TARGET_AARCH64 + bool "aarch64-unknown-none" + + config RT_RUST_TARGET_ARM + bool "armv7a-none-eabi" + endchoice + +endif +``` + +### 3.2 SConscript集成 + +主`SConscript`文件应处理： + +1. Cargo项目构建 +2. 生成的.a库链接 +3. C绑定头文件生成 + +```python +from building import * +import os + +cwd = GetCurrentDir() +src = [] +CPPPATH = [cwd] + +if GetDepend(['RT_USING_RUST']): + # 构建Rust核心库 + if GetDepend(['RT_RUST_CORE']): + os.system('cd ' + cwd + '/core && cargo build --release --target=...') + src += ['core/target/release/librt_rust_core.a'] + + # 构建运行时 + if GetDepend(['RT_RUST_RUNTIME']): + os.system('cd ' + cwd + '/runtime && cargo build --release --target=...') + src += ['runtime/target/release/librt_rust_runtime.a'] + + # 构建示例 + if GetDepend(['RT_RUST_EXAMPLES_APPS']): + src += SConscript('examples/applications/SConscript') + +group = DefineGroup('Rust', src, depend=['RT_USING_RUST'], CPPPATH=CPPPATH) + +Return('group') +``` + +## 四、使用方式示例 + +### 4.1 编写简单的Rust应用 + +```rust +// examples/applications/hello_world/src/main.rs +#![no_std] +#![no_main] + +use rt_rust_core::prelude::*; + +#[rt_thread_main] +fn main() { + rt_println!("Hello from Rust!"); + + // 创建线程 + let thread = Thread::create("rust_thread", thread_entry, 0, 2048, 20); + thread.startup(); +} + +fn thread_entry(_parameter: *mut c_void) { + loop { + rt_println!("Rust thread running"); + Thread::delay(1000); + } +} + +// 导出shell命令 +#[msh_cmd_export] +fn hello_rust(_argc: i32, _argv: &[&str]) { + rt_println!("Hello from Rust command!"); +} +``` + +### 4.2 编写Rust组件 + +```rust +// examples/components/logger/src/lib.rs +#![no_std] + +use rt_rust_core::prelude::*; + +pub struct RustLogger; + +impl RustLogger { + pub fn log(&self, level: LogLevel, msg: &str) { + // 实现日志功能 + } +} + +// 导出C接口供C代码使用 +#[no_mangle] +pub extern "C" fn rust_logger_init() -> *mut RustLogger { + Box::into_raw(Box::new(RustLogger)) +} +``` + +### 4.3 编写内核模块 + +```rust +// examples/modules/simple_module/src/lib.rs +#![no_std] + +use rt_rust_core::module::*; + +#[module_init] +fn module_init() -> i32 { + rt_println!("Rust module loaded!"); + 0 +} + +#[module_exit] +fn module_exit() { + rt_println!("Rust module unloaded!"); +} + +module_info! { + name: "rust_simple_module", + author: "RT-Thread", + license: "Apache-2.0", +} +``` + +## 五、关键设计考虑 + +### 5.1 ABI兼容性 + +- 使用`extern "C"`确保函数调用兼容 +- 使用`#[repr(C)]`确保结构体布局兼容 +- 提供bindgen配置自动生成绑定 + +### 5.2 内存安全 + +- 全局分配器对接RT-Thread内存管理 +- 提供安全的所有权模型包装 +- 处理FFI边界的内存管理 + +### 5.3 无标准库支持 + +- 实现no_std环境必需的trait +- 提供自定义panic handler +- 实现必要的语言项 + +### 5.4 性能优化 + +- 零成本抽象设计 +- 内联关键函数 +- 避免不必要的边界检查 + +### 5.5 文档和测试 + +- 提供详细的API文档 +- 包含丰富的示例代码 +- 编写集成测试和单元测试 + +## 六、开发路线图 + +### 阶段一：基础设施 (1-2个月) +- [ ] 完成核心绑定库 +- [ ] 实现基本运行时支持 +- [ ] 完成构建系统集成 +- [ ] 编写hello_world示例 + +### 阶段二：API完善 (2-3个月) +- [ ] 完善线程、IPC、设备API +- [ ] 实现全局分配器 +- [ ] 完善宏系统 +- [ ] 编写应用示例 + +### 阶段三：高级功能 (2-3个月) +- [ ] 支持动态模块 +- [ ] 完善shell命令支持 +- [ ] 编写组件示例 +- [ ] 性能测试和优化 + +### 阶段四：文档和生态 (持续) +- [ ] 完善文档 +- [ ] 编写教程 +- [ ] 建立测试体系 +- [ ] 社区推广 + +## 七、与现有组件的交互 + +### 7.1 与libc的关系 + +Rust组件可以与RT-Thread的libc共存： +- 在no_std模式下，Rust有自己的核心库 +- 需要时可以通过FFI调用libc函数 +- 避免符号冲突 + +### 7.2 与libdl的关系 + +对于内核模块支持： +- 扩展libdl以支持Rust编译的.so文件 +- 处理Rust特定的符号和初始化 +- 实现模块加载钩子 + +### 7.3 与设备驱动框架的关系 + +Rust可以实现设备驱动： +- 提供设备驱动trait +- 封装设备注册接口 +- 支持中断处理 + +## 八、参考资料 + +1. RT-Thread组件开发指南 +2. Rust嵌入式开发手册 +3. Linux内核Rust支持项目 +4. Zephyr RTOS的Rust集成 + +## 九、总结 + +本设计方案遵循RT-Thread的设计哲学： + +1. **松耦合**: Rust组件作为独立模块，可选择启用 +2. **模块化**: 清晰的目录结构，功能分离 +3. **面向对象**: 使用Rust的trait和结构体体现OOP思想 +4. **可扩展**: 提供丰富的示例和文档，便于扩展 + +通过这个结构，Rust可以无缝集成到RT-Thread中，为开发者提供内存安全和高性能的开发体验。 diff --git a/docs/rust-component-structure-recommendation.md b/docs/rust-component-structure-recommendation.md new file mode 100644 index 00000000..8a3d59f6 --- /dev/null +++ b/docs/rust-component-structure-recommendation.md @@ -0,0 +1,372 @@ +# RT-Thread Rust组件目录结构建议 + +## 回复Issue：当加入rust组件支持时的目录结构 + +基于对RT-Thread现有组件架构的分析（如fal、vbus、utilities等组件），我为Rust组件支持提出以下目录结构建议。 + +## 一、推荐的目录结构 + +建议在 `rt-thread/components/rust/` 下创建以下结构： + +``` +rt-thread/components/rust/ +├── Kconfig # 组件配置 +├── SConscript # 构建脚本 +├── README.md # 组件说明 +├── docs/ # 文档 +│ ├── api_reference.md +│ ├── abi_compatibility.md +│ └── performance_report.md +├── core/ # 核心支持库 +│ ├── Cargo.toml +│ ├── src/ +│ │ ├── lib.rs +│ │ ├── bindings/ # C接口绑定 +│ │ │ ├── kernel.rs # 内核API +│ │ │ ├── thread.rs # 线程API +│ │ │ ├── ipc.rs # IPC机制 +│ │ │ ├── memory.rs # 内存管理 +│ │ │ └── device.rs # 设备API +│ │ ├── rt_prelude.rs # 预导入模块 +│ │ ├── allocator.rs # 内存分配器 +│ │ ├── panic.rs # panic处理 +│ │ └── macros/ # 宏支持 +│ │ ├── thread_entry.rs # 线程入口宏 +│ │ └── msh_export.rs # Shell命令导出宏 +├── runtime/ # 运行时支持 +│ ├── Cargo.toml +│ ├── src/ +│ │ ├── no_std_support.rs # no_std模式 +│ │ ├── start.rs # 启动代码 +│ │ └── lang_items.rs # 语言项 +│ └── linker/ +│ └── rust_module.ld # 链接脚本 +├── msh/ # Shell命令支持 +│ ├── Cargo.toml +│ └── src/ +│ └── commands.rs +├── examples/ # 示例代码 +│ ├── README.md +│ ├── applications/ # 应用示例 +│ │ ├── hello_world/ +│ │ ├── thread_sync/ +│ │ └── device_io/ +│ ├── components/ # 组件示例 +│ │ ├── logger/ +│ │ ├── sensor_driver/ +│ │ └── protocol_stack/ +│ └── modules/ # 内核模块示例 +│ ├── simple_module/ +│ └── device_module/ +├── tools/ # 工具脚本 +│ ├── build_rust.py +│ ├── gen_bindings.sh +│ └── cargo_wrapper.py +└── tests/ # 测试 + ├── integration/ + └── unit/ +``` + +## 二、各部分功能说明 + +### 2.1 核心支持库 (core/) + +**提供Rust本身的基础支持和RT-Thread系统服务绑定：** + +1. **bindings/** - C接口的安全封装 + - 按功能模块划分（kernel、thread、ipc、memory、device） + - 使用bindgen自动生成或手工编写 + - 提供类型安全的Rust接口 + +2. **rt_prelude.rs** - 预导入模块 + - 类似std::prelude，导入常用类型和trait + - 简化Rust代码编写 + +3. **allocator.rs** - 全局内存分配器 + - 实现`GlobalAlloc` trait + - 对接RT-Thread的内存管理系统 + +4. **macros/** - 宏定义 + - `thread_entry!` - 标记线程入口函数 + - `msh_cmd_export!` - 导出shell命令的宏 + - 简化在no_std模式下的开发 + +### 2.2 运行时支持 (runtime/) + +**解决no_std模式下的运行时问题：** + +- **no_std_support.rs** - no_std环境支持 +- **start.rs** - 启动代码，处理main函数到RT-Thread线程的转换 +- **lang_items.rs** - 必要的语言项实现 +- **linker/** - 链接脚本，用于模块加载 + +### 2.3 Shell命令支持 (msh/) + +**导出Rust命令到RT-Thread shell：** + +- 提供`MSH_CMD_EXPORT`宏的Rust版本 +- 自动处理参数解析 +- 与finsh组件集成 + +### 2.4 示例代码 (examples/) + +**包含三类示例：** + +1. **applications/** - 使用Rust编写应用 + - `hello_world/` - 基础示例 + - `thread_sync/` - 线程同步示例 + - `device_io/` - 设备IO示例 + +2. **components/** - 使用Rust编写组件/软件包 + - `logger/` - 日志组件 + - `sensor_driver/` - 传感器驱动 + - `protocol_stack/` - 协议栈 + +3. **modules/** - 使用Rust编写内核动态模块 + - `simple_module/` - 简单模块示例 + - `device_module/` - 设备驱动模块示例 + +## 三、构建系统集成 + +### 3.1 Kconfig配置示例 + +```kconfig +menuconfig RT_USING_RUST + bool "Rust Language Support" + default n + +if RT_USING_RUST + config RT_RUST_CORE + bool "Enable Rust Core Library" + default y + + config RT_RUST_RUNTIME + bool "Enable Rust Runtime Support" + default y + select RT_RUST_CORE + + config RT_RUST_MSH_SUPPORT + bool "Enable Rust MSH Command Support" + default y + depends on RT_USING_FINSH + + menu "Rust Examples" + config RT_RUST_EXAMPLES_APPS + bool "Build Application Examples" + default n + + config RT_RUST_EXAMPLES_COMPONENTS + bool "Build Component Examples" + default n + + config RT_RUST_EXAMPLES_MODULES + bool "Build Module Examples" + default n + depends on RT_USING_LWP && RT_USING_MODULE + endmenu +endif +``` + +### 3.2 SConscript集成 + +```python +from building import * +import os + +cwd = GetCurrentDir() +src = [] +CPPPATH = [cwd] + +if GetDepend(['RT_USING_RUST']): + if GetDepend(['RT_RUST_CORE']): + # 构建Rust核心库 + os.system('cd ' + cwd + '/core && cargo build --release') + src += ['core/target/release/librt_rust_core.a'] + + if GetDepend(['RT_RUST_RUNTIME']): + # 构建运行时 + os.system('cd ' + cwd + '/runtime && cargo build --release') + src += ['runtime/target/release/librt_rust_runtime.a'] + +group = DefineGroup('Rust', src, depend=['RT_USING_RUST'], CPPPATH=CPPPATH) +Return('group') +``` + +## 四、使用示例 + +### 4.1 简单的Rust应用 + +```rust +#![no_std] +#![no_main] + +use rt_rust_core::prelude::*; + +#[rt_thread_main] +fn main() { + rt_println!("Hello from Rust!"); + + let thread = Thread::create("rust_thread", thread_entry, 0, 2048, 20); + thread.startup(); +} + +fn thread_entry(_parameter: *mut c_void) { + loop { + rt_println!("Rust thread running"); + Thread::delay(1000); + } +} + +#[msh_cmd_export] +fn hello_rust(_argc: i32, _argv: &[&str]) { + rt_println!("Hello from Rust command!"); +} +``` + +### 4.2 Rust组件示例 + +```rust +#![no_std] + +use rt_rust_core::prelude::*; + +pub struct RustLogger; + +impl RustLogger { + pub fn log(&self, level: LogLevel, msg: &str) { + // 实现日志功能 + } +} + +#[no_mangle] +pub extern "C" fn rust_logger_init() -> *mut RustLogger { + Box::into_raw(Box::new(RustLogger)) +} +``` + +### 4.3 内核模块示例 + +```rust +#![no_std] + +use rt_rust_core::module::*; + +#[module_init] +fn module_init() -> i32 { + rt_println!("Rust module loaded!"); + 0 +} + +#[module_exit] +fn module_exit() { + rt_println!("Rust module unloaded!"); +} + +module_info! { + name: "rust_simple_module", + author: "RT-Thread", + license: "Apache-2.0", +} +``` + +## 五、设计理念 + +本方案遵循RT-Thread的设计理念： + +### 5.1 松耦合 +- Rust组件作为可选模块，通过Kconfig控制 +- 不影响现有C代码 +- 可独立开发和测试 + +### 5.2 面向对象 +- 使用Rust的trait体现接口抽象 +- 通过模块划分体现对象特征 +- 清晰的职责分离 + +### 5.3 文件/目录结构反映组件特点 +- **core/** - 核心功能层 +- **runtime/** - 运行时层 +- **msh/** - shell集成层 +- **examples/** - 按应用场景分类的示例 + - applications/ - 应用层 + - components/ - 组件层 + - modules/ - 模块层 + +### 5.4 可扩展性 +- 提供丰富的示例 +- 文档完善 +- 易于添加新功能 + +## 六、与现有组件的关系 + +### 6.1 与libdl的集成 + +对于内核模块支持，需要扩展 `rt-thread/components/libc/posix/libdl`： + +1. 添加对Rust编译的.so文件的支持 +2. 处理Rust特定的符号和初始化 +3. 实现模块加载钩子 + +建议在libdl中添加： +``` +rt-thread/components/libc/posix/libdl/ +├── dlrust.c # Rust模块加载支持 +└── dlrust.h # 相关头文件 +``` + +### 6.2 与其他组件的交互 + +- **finsh** - 通过msh子模块集成shell命令 +- **drivers** - 通过bindings/device.rs封装设备驱动接口 +- **libc** - 在需要时通过FFI调用libc函数 +- **lwp** - 支持Rust编写的用户态程序 + +## 七、实施路线图 + +### 阶段一：基础设施 +1. 创建core/目录，实现基本的C接口绑定 +2. 实现runtime/，支持no_std模式 +3. 完成构建系统集成 +4. 实现hello_world示例 + +### 阶段二：功能完善 +1. 完善线程、IPC、设备API绑定 +2. 实现全局分配器 +3. 实现msh命令导出 +4. 添加应用示例 + +### 阶段三：高级功能 +1. 扩展libdl支持Rust模块 +2. 实现模块加载示例 +3. 添加组件示例 +4. 性能测试和优化 + +### 阶段四：文档和生态 +1. 编写详细文档 +2. 添加更多示例 +3. 建立测试体系 +4. 社区推广 + +## 八、参考实现 + +可以参考PR #12中的部分实现，以及以下开源项目： + +1. [Linux内核Rust支持](https://github.com/Rust-for-Linux/linux) +2. [Zephyr RTOS的Rust集成](https://github.com/zephyrproject-rtos/zephyr/tree/main/samples/rust) +3. [嵌入式Rust示例](https://github.com/rust-embedded/rust-embedded) + +## 总结 + +这个目录结构设计： + +✅ **符合RT-Thread理念** - 松耦合、模块化、面向对象 +✅ **结构清晰** - 按功能层次划分目录 +✅ **易于扩展** - 提供丰富示例和文档 +✅ **完整覆盖** - 包含应用、组件、模块三个层次 +✅ **构建友好** - 与SCons构建系统良好集成 + +希望这个建议对RT-Thread的Rust支持有所帮助！ + +--- + +详细的设计文档请参考：[docs/rust-component-structure-proposal.md](docs/rust-component-structure-proposal.md) From d7c7139af1979769c03e9134d9cbd10c9dc2827e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 24 Oct 2025 23:14:51 +0000 Subject: [PATCH 3/4] Add docs README and update main README with links Co-authored-by: BernardXiong <1241087+BernardXiong@users.noreply.github.com> --- README.md | 14 +++++----- docs/README.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 78 insertions(+), 6 deletions(-) create mode 100644 docs/README.md diff --git a/README.md b/README.md index aa23f9ff..d0c78c27 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,11 @@ ``` . -├── machines # 支持的板卡移植 -├── tutorials # 教程文档 -└── ... +├── machines # 支持的板卡移植 +├── tutorials # 教程文档 +├── course-projects # 课程设计题目 +├── docs # 技术文档和设计方案 +└── rt-thread # RT-Thread内核(submodule) ``` ## 板卡支持计划 @@ -50,9 +52,9 @@ $ ./qemu-nographic.sh # 执行 ## 教学资源 -- 教程文档 -- 课题方向 -- 比赛题目 +- [教程文档](tutorials/) +- [课题方向](course-projects/) +- [技术文档](docs/) - 包括Rust组件集成设计方案 ## 贡献指南 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..8d9337ae --- /dev/null +++ b/docs/README.md @@ -0,0 +1,70 @@ +# RT-Thread Rust支持文档 + +本目录包含关于在RT-Thread中集成Rust语言支持的设计文档和建议。 + +## 文档列表 + +### [Rust组件目录结构建议](rust-component-structure-recommendation.md) + +**简介版本** - 针对Issue的直接回复文档，包含： +- 推荐的目录结构概览 +- 各模块功能说明 +- 构建系统集成方案 +- 使用示例 +- 实施路线图 + +适合快速了解Rust组件的整体架构设计。 + +### [Rust组件目录结构详细设计方案](rust-component-structure-proposal.md) + +**详细版本** - 完整的技术设计文档，包含： +- 详细的目录结构说明 +- 各模块深入设计 +- 完整的Kconfig和SConscript示例 +- 详细的使用示例和代码片段 +- 关键设计考虑（ABI兼容性、内存安全、性能优化等） +- 开发路线图 +- 与现有组件的交互关系 +- 参考资料 + +适合实际开发时参考。 + +## 背景 + +这些文档是针对Issue [当加入rust组件支持时的目录结构](https://github.com/RT-Thread/qemu-edu/issues/XX) 的设计建议，目标是为RT-Thread提供： + +1. **Rust本身的基础支持** + - RT-Thread操作系统的系统服务绑定 + - no_std模式下的运行时支持 + - 宏定义简化开发 + +2. **Shell命令集成** + - 导出Rust函数到RT-Thread shell + +3. **丰富的示例** + - 使用Rust编写应用的示例 + - 使用Rust编写组件或软件包的示例 + - 使用Rust编写内核动态模块的示例 + +## 设计理念 + +遵循RT-Thread的核心理念： +- ✅ **松耦合** - Rust作为可选组件，不影响现有代码 +- ✅ **模块化** - 清晰的目录结构，功能分离 +- ✅ **面向对象** - 通过文件、目录结构反映组件特点 + +## 相关资源 + +- [RT-Thread官方文档](https://www.rt-thread.org/document/site/) +- [Rust嵌入式开发手册](https://rust-embedded.github.io/book/) +- [课程项目：支持Rust构建RT-Thread安全组件](../course-projects/01-rust-extension.md) +- PR #12: RT-Thread Rust支持的部分实现 + +## 贡献 + +欢迎对这些设计方案提出建议和改进意见。请通过Issue或Pull Request参与讨论。 + +--- + +**最后更新**: 2025-10-24 +**维护者**: RT-Thread开源社区 From 53ca94f89a4e0b11c8070e663f33e33ffd9a2ab6 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 24 Oct 2025 23:26:46 +0000 Subject: [PATCH 4/4] Fix broken links and rename msh/ to shell/ per review feedback Co-authored-by: BernardXiong <1241087+BernardXiong@users.noreply.github.com> --- docs/rust-component-structure-proposal.md | 10 +++++----- docs/rust-component-structure-recommendation.md | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/rust-component-structure-proposal.md b/docs/rust-component-structure-proposal.md index 016f0fac..96e2701b 100644 --- a/docs/rust-component-structure-proposal.md +++ b/docs/rust-component-structure-proposal.md @@ -46,7 +46,7 @@ rt-thread/components/rust/ │ │ └── lang_items.rs # 语言项实现 │ └── linker/ # 链接脚本 │ └── rust_module.ld -├── msh/ # Shell命令支持 +├── shell/ # Shell命令支持 │ ├── Cargo.toml │ ├── src/ │ │ ├── lib.rs @@ -159,7 +159,7 @@ rt-thread/components/rust/ } ``` -### 2.3 Shell命令支持 (msh/) +### 2.3 Shell命令支持 (shell/) **目标**: 简化Rust程序导出shell命令的过程。 @@ -498,9 +498,9 @@ Rust可以实现设备驱动： ## 八、参考资料 1. RT-Thread组件开发指南 -2. Rust嵌入式开发手册 -3. Linux内核Rust支持项目 -4. Zephyr RTOS的Rust集成 +2. [Rust嵌入式开发手册](https://github.com/rust-embedded/book) +3. [Linux内核Rust支持项目](https://github.com/Rust-for-Linux/linux) +4. [Zephyr RTOS](https://github.com/zephyrproject-rtos/zephyr) ## 九、总结 diff --git a/docs/rust-component-structure-recommendation.md b/docs/rust-component-structure-recommendation.md index 8a3d59f6..ccb3951f 100644 --- a/docs/rust-component-structure-recommendation.md +++ b/docs/rust-component-structure-recommendation.md @@ -41,7 +41,7 @@ rt-thread/components/rust/ │ │ └── lang_items.rs # 语言项 │ └── linker/ │ └── rust_module.ld # 链接脚本 -├── msh/ # Shell命令支持 +├── shell/ # Shell命令支持 │ ├── Cargo.toml │ └── src/ │ └── commands.rs @@ -100,7 +100,7 @@ rt-thread/components/rust/ - **lang_items.rs** - 必要的语言项实现 - **linker/** - 链接脚本，用于模块加载 -### 2.3 Shell命令支持 (msh/) +### 2.3 Shell命令支持 (shell/) **导出Rust命令到RT-Thread shell：** @@ -286,7 +286,7 @@ module_info! { ### 5.3 文件/目录结构反映组件特点 - **core/** - 核心功能层 - **runtime/** - 运行时层 -- **msh/** - shell集成层 +- **shell/** - shell集成层 - **examples/** - 按应用场景分类的示例 - applications/ - 应用层 - components/ - 组件层 @@ -352,8 +352,8 @@ rt-thread/components/libc/posix/libdl/ 可以参考PR #12中的部分实现，以及以下开源项目： 1. [Linux内核Rust支持](https://github.com/Rust-for-Linux/linux) -2. [Zephyr RTOS的Rust集成](https://github.com/zephyrproject-rtos/zephyr/tree/main/samples/rust) -3. [嵌入式Rust示例](https://github.com/rust-embedded/rust-embedded) +2. [Zephyr RTOS](https://github.com/zephyrproject-rtos/zephyr) +3. [Rust嵌入式开发手册](https://github.com/rust-embedded/book) ## 总结