rt-thread/components/rust/README.md

RT-Thread Rust Component

RT-Thread's general-purpose Rust component for the RTOS, with automatic detection of multiple architectures.

Features

• Multi-architecture support: automatically detects ARM, AArch64, and RISC-V target architectures.
• Zero configuration: no manual platform target setup required.
• Modular design: core modules and example code are clearly separated.
• RT-Thread integration: full access to RT-Thread kernel APIs.

Project Layout

rust/
├── README.md                    # Project documentation
├── Kconfig                      # Configuration options
├── SConscript                   # Top-level build script
├── core/                        # Core Rust library
│   ├── Cargo.toml               # Rust project config
│   ├── SConscript               # Core library build script
│   ├── rust_cmd.c               # MSH command registration
│   └── src/                     # Source directory
│       ├── lib.rs               # Library entry
│       ├── init.rs              # Component initialization
│       ├── allocator.rs         # Memory allocator
│       ├── panic.rs             # Panic handler
│       ├── bindings/            # RT-Thread API FFI bindings
│       ├── api/                 # RT-Thread API Rust wrappers
│       ├── prelude/             # Common imports
│       ├── thread.rs            # Thread operations
│       ├── mutex.rs             # Mutex
│       ├── sem.rs               # Semaphore
│       ├── queue.rs             # Message queue
│       ├── time.rs              # Time functions
│       ├── fs.rs                # Filesystem
│       ├── libloader.rs         # Dynamic library loading
│       ├── param.rs             # Parameter passing
│       └── out.rs               # Output functions
├── rt_macros/                   # Rust procedural macros
│   ├── Cargo.toml               # Macros crate config
│   └── src/                     # Macros source
│       ├── lib.rs               # Macros crate entry
│       └── macros/              # Macro implementations
│           ├── mod.rs           # Module definitions
│           ├── main.rs          # main macro
│           ├── component.rs     # component export macro
│           ├── app.rs           # application export macro
│           └── cmd.rs           # command export macro
├── examples/                    # Example code
│   ├── Kconfig                  # Examples config
│   ├── SConscript               # Examples build scripts
│   ├── application/             # Application examples
│   ├── component/               # Component examples
│   └── modules/                 # Dynamic module examples
├── docs/                        # Detailed documentation
└── tools/                       # Build tools
    ├── build_support.py        # Build support functions
    ├── build_component.py      # Component build tool
    ├── build_usrapp.py         # User app build tool
    ├── feature_config_component.py  # Component feature config
    └── feature_config_examples.py   # Example feature config

Quick Start

Prerequisites

1. Install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. Add target platforms (choose according to your architecture):

# RISC-V64 (soft-float)
rustup target add riscv64imac-unknown-none-elf

# ARM Cortex-M4
rustup target add thumbv7em-none-eabi

# Add other targets that match your toolchain/ABI as needed

For ARM targets whose C toolchain uses -fshort-wchar, RT-Thread uses the nightly-only build-std feature to rebuild Rust core and alloc from source, keeping the Rust ARM EABI wchar size aligned with the C toolchain. Install rust-src and the corresponding target for the same nightly toolchain. From the RT-Thread repository root, set a directory-local nightly override so that the plain cargo and rustc commands invoked by SCons use this toolchain throughout the repository:

rustup toolchain install nightly --profile minimal --component rust-src
rustup target add --toolchain nightly <target-name>
rustup override set nightly

Build

# Enable the Rust component in menuconfig
scons --menuconfig
# Navigate to: Rust Component Support → Enable

# Build
scons

# Clean
scons -c

Supported Architectures

Architecture	Target	Auto-detect
Cortex-M3	thumbv7m-none-eabi	✓
Cortex-M4/M7	thumbv7em-none-eabi	✓
Cortex-M4F/M7F	thumbv7em-none-eabihf	✓
ARMv7-A	armv7a-none-eabi	✓
AArch64	aarch64-unknown-none	✓
RISC-V32	riscv32ima[f]c-unknown-none-elf	✓
RISC-V64	riscv64[gc/imac]-unknown-none-elf	✓

The build system will automatically determine the correct target from the RT-Thread configuration.

Example MSH Commands

• rust_param_demo — Parameter passing demo
• rust_thread_demo — Thread demo
• rust_mutex_demo — Mutex demo
• rust_queue_demo — Queue demo
• rust_sem_demo — Semaphore demo
• rust_dl_demo — Dynamic module loading demo
• rust_fs_demo — File and logging operations demo (requires logging component)

Configuration Options

Available in menuconfig:

• RT_USING_RUST - Enable/disable the Rust component
• RT_RUST_CORE - Enable/disable the core support library
• RUST_INIT_COMPONENT - Initialize automatically at startup
• RT_USING_RUST_EXAMPLES
  • RT_RUST_BUILD_APPLICATIONS: Enable/disable user applications
  • RT_RUST_BUILD_COMPONENTS: Enable/disable components
  • RT_RUST_BUILD_MODULES: Enable/disable building dynamic modules
• RUST_DEBUG_BUILD - Enable/disable debug build

Technical Details

• No-std: embedded-friendly #![no_std] environment.
• FFI: seamless C/Rust interoperability.
• Static linking: produces .a library files.
• Memory safety: compile-time guarantees from Rust.
• Zero-cost abstractions: performance comparable to C.

Use Cases

• Safety-critical code: leverage Rust's memory-safety guarantees.
• Complex algorithms: use Rust's advanced abstraction capabilities.
• Device drivers: type-safe hardware abstractions.
• Network protocol stacks: safe packet handling.
• Cryptography libraries: secure implementations that help prevent memory leaks.

Troubleshooting

Linker Error

If you encounter the error "can't link double-float modules with soft-float modules":

• The build system should auto-detect the correct ABI.
• Check whether the compiler -mabi flag matches the Rust target.

Target Not Installed

If a target is reported as not installed:

rustup target add <target-name>

Detection Failed

If the target architecture cannot be detected:

• Verify that the RT-Thread configuration is correct.
• Inspect compiler flags in rtconfig.py.

License

Apache-2.0

References

• https://docs.rust-embedded.org/
• https://www.rt-thread.org/document/site/
• https://doc.rust-lang.org/nomicon/ffi.html
• https://riscv.org/technical/specifications/