From a8ba833cdeffc6ac9fb8cac289eadf61573e4513 Mon Sep 17 00:00:00 2001
From: Huang Qi <huangqi3@xiaomi.com>
Date: Thu, 9 Jan 2025 10:42:27 +0800
Subject: [PATCH] Documentation: Add Rust integration guide for NuttX

Add a new guide documenting how to integrate Rust with NuttX, including:
- Prerequisites and supported platforms
- Setup instructions for Rust toolchain
- Required NuttX configurations
- Example build and run instructions for RISCV32 target

The guide provides an experimental but working example of running
a Rust application on NuttX using the rv-virt:nsh board.

Signed-off-by: Huang Qi <huangqi3@xiaomi.com>
---
 Documentation/guides/index.rst |  1 +
 Documentation/guides/rust.rst  | 90 ++++++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+)
 create mode 100644 Documentation/guides/rust.rst

diff --git a/Documentation/guides/index.rst b/Documentation/guides/index.rst
index 04910b978d..7a4f691b72 100644
--- a/Documentation/guides/index.rst
+++ b/Documentation/guides/index.rst
@@ -69,4 +69,5 @@ Guides
   ram_rom_disks.rst
   reading_can_msgs.rst
   remove_device_drivers_nsh.rst
+  rust.rst
 
diff --git a/Documentation/guides/rust.rst b/Documentation/guides/rust.rst
new file mode 100644
index 0000000000..e7f5d5f0d2
--- /dev/null
+++ b/Documentation/guides/rust.rst
@@ -0,0 +1,90 @@
+===============
+Rust in NuttX
+===============
+
+.. warning::
+    This guide is under development. Rust support in NuttX is experimental.
+
+Introduction
+============
+NuttX is exploring Rust integration to provide memory safety guarantees and modern
+language features while maintaining its small footprint and real-time capabilities.
+
+This guide covers:
+
+- Setting up Rust toolchain for NuttX development
+- Building Rust components with NuttX
+- Interoperability between Rust and C
+- Testing Rust components
+
+Prerequisites
+=============
+- Rust toolchain installed (rustup recommended)
+- NuttX build environment configured
+- Basic knowledge of Rust and NuttX development
+
+Supported Platforms
+===================
+- AArch64 (WIP)
+- ARMv7-A (WIP)
+- ARMv6-M
+- ARMv7-M
+- ARMv8-M
+- RISCV32
+- RISCV64
+
+Getting Started
+===============
+1. Install Rust toolchain and switch to nightly
+
+Please refer to the official Rust installation guide for more details: https://www.rust-lang.org/tools/install
+
+.. code-block:: bash
+
+    rustup toolchain install nightly
+    rustup default nightly
+
+2. Prepare NuttX build environment
+
+Please ensure that you have a working NuttX build environment, and with the following PR merged or cherry-picked:
+- https://github.com/apache/nuttx-apps/pull/2487
+- https://github.com/apache/nuttx/pull/15469
+
+3. Enable essential kernel configurations
+
+Pleae enable the following configurations in your NuttX configuration:
+- CONFIG_SYSTEM_TIME64
+- CONFIG_FS_LARGEFILE
+- CONFIG_TLS_NELEM = 16
+- CONFIG_DEV_URANDOM
+
+The `rv-virt:nsh` board using make as the build system is recommended for testing Rust applications as it has been verified to work with this configuration.
+
+For `rv-virt:nsh` board, you should disable `CONFIG_ARCH_FPU` configuration since RISCV32 with FPU is not supported yet.
+
+4. Enable sample application
+
+Please enable the sample application in your NuttX configuration:
+- CONFIG_EXAMPLES_HELLO_RUST_CARGO
+
+5. Build and run the sample application
+
+Build the NuttX image and run it on your target platform:
+
+.. code-block:: bash
+
+    qemu-system-riscv32 -semihosting -M virt,aclint=on -cpu rv32 -smp 8 -bios nuttx/nuttx -nographic
+
+    NuttShell (NSH) NuttX-12.8.0
+    nsh> hello_rust_cargo
+    {"name":"John","age":30}
+    {"name":"Jane","age":25}
+    Deserialized: Alice is 28 years old
+    Pretty JSON:
+    {
+    "name": "Alice",
+    "age": 28
+    }
+    Hello world from tokio!
+
+Congratulations! You have successfully built and run a Rust application on NuttX.