ThreadX Development Setup

Guide for developing and testing nano-ros on ThreadX (Eclipse ThreadX) + NetX Duo, with two targets: Linux simulation and QEMU RISC-V 64-bit virt machine.

Prerequisites

Linux Simulation

• Linux host with /dev/net/tun and persistent user-owned TAP interfaces (created by just qemu setup-network). No CAP_NET_RAW or other capabilities needed on the test binaries.
• Rust nightly toolchain

QEMU RISC-V 64-bit

• qemu-system-riscv64 (QEMU with RISC-V system emulation)
• riscv64-unknown-elf-gcc (RISC-V bare-metal cross-compiler)
• Rust nightly toolchain with riscv64gc-unknown-none-elf target

# Install cross-compiler (Ubuntu/Debian)
sudo apt install qemu-system-misc gcc-riscv64-unknown-elf

# Install Rust target
rustup target add riscv64gc-unknown-none-elf
rustup component add --toolchain nightly rust-src

Or use just setup which installs Rust targets automatically.

ThreadX + NetX Duo Sources

Download ThreadX, NetX Duo, and the Linux simulation samples:

just setup threadx_linux     # Linux simulation SDK
just setup threadx_riscv64   # QEMU RISC-V SDK

This shallow-clones:

• ThreadX kernel → third-party/threadx/kernel/
• NetX Duo → third-party/threadx/netxduo/

Override paths if sources are elsewhere:

Building Examples

Linux Simulation

just threadx_linux build-examples

Builds all Linux simulation examples natively. The board crate’s build.rs compiles ThreadX kernel (Linux port), NetX Duo, and the Linux raw socket network driver via the cc crate.

QEMU RISC-V 64-bit

just threadx_riscv64 build-examples

Cross-compiles all QEMU RISC-V examples for riscv64gc-unknown-none-elf. The board crate’s build.rs compiles ThreadX kernel (RISC-V port), NetX Duo, and the virtio-net NetX Duo driver.

Available Examples

Examples are in examples/threadx-linux/rust/ and examples/rv-virt-threadx/rust/; select the RMW at build time.

Testing

just threadx_linux test    # Linux sim
just threadx_riscv64 test  # QEMU RISC-V
just threadx_linux test    # Linux simulation only
just threadx_riscv64 test  # QEMU RISC-V only

Linux Simulation Tests

Linux simulation tests use TAP networking via /dev/net/tun. The ThreadX Linux port runs the full kernel as pthreads on the host and attaches to persistent user-owned TAP interfaces, so no CAP_NET_RAW or root privilege is needed on the test binaries themselves. The TAP interfaces and bridge must exist (one-time setup, requires sudo):

just qemu setup-network         # Create qemu-br + tap-tx0 + tap-tx1 (one-time)
just threadx_linux test    # Run tests

QEMU RISC-V Tests

QEMU tests use TAP networking with virtio-net. Each QEMU instance connects to the host via a TAP device, communicating through a bridge running zenohd:

┌─────────────────────────────────────────────────┐
│  Host (Linux)                                    │
│  zenohd (192.0.3.1)  QEMU talker  QEMU listener │
│       │                   │              │        │
│  ─────┴───────────────────┴──────────────┴────── │
│       br-qemu         tap-qemu0      tap-qemu1   │
└─────────────────────────────────────────────────┘

Architecture

Linux Simulation

User Application (Executor + Node + Pub/Sub)
        │
nros-node (Executor)
        │
nros-rmw-zenoh → zpico-sys (zenoh-pico + C shim)
        │                       │
        │          zenoh-pico POSIX platform
        │          (pthreads, BSD sockets)
        │
Board Crate (nros-board-threadx-linux)
├── ThreadX kernel (Linux port — tx_thread via pthreads)
├── NetX Duo (BSD sockets)
└── TAP network driver (packages/drivers/tap-netx)

QEMU RISC-V 64-bit

User Application (Executor + Node + Pub/Sub)
        │
nros-node (Executor)
        │
nros-rmw-zenoh → zpico-sys (zenoh-pico + C shim)
        │                       │
        │          zenoh-pico ThreadX platform
        │          (tx_thread, tx_mutex, BSD sockets)
        │
Board Crate (nros-board-threadx-qemu-riscv64)
├── ThreadX kernel (RISC-V port — real preemptive scheduling)
├── NetX Duo (BSD sockets over virtio-net)
└── virtio-net NetX Duo driver (virtio MMIO)

Key Design Points

• Multi-threaded: ThreadX provides real threads/mutexes. zenoh-pico uses background read/lease tasks.
• NetX Duo BSD sockets: POSIX-compatible socket()/connect()/select() — same code path as zenoh-pico’s POSIX platform.
• Build via cc crate: ThreadX kernel + NetX Duo compiled in the board crate’s build.rs (no external CMake needed).
• Two targets: Linux simulation for fast iteration, QEMU RISC-V for real ThreadX scheduling validation.

Safety Certifications

ThreadX holds the highest level of safety certifications:

• IEC 61508 SIL 4 — functional safety for industrial systems
• IEC 62304 Class C — medical device software
• ISO 26262 ASIL D — automotive functional safety

NetX Duo is certified to the same IEC 61508 SIL 4 standard. Combined with nano-ros’s Kani/Verus formal verification, this creates a layered safety argument for safety-critical deployments.