diff mbox series

[Concept,11/14] doc: ulib: Add Rust examples documentation

Message ID 20250911214425.3687188-12-sjg@u-boot.org
State New
Headers
Series ulib: Add support for Rust main programs |

Commit Message

Simon Glass Sept. 11, 2025, 9:44 p.m. UTC 
  From: Simon Glass <sjg@chromium.org>

Add docs for the Rust examples in the ulib documentation, covering:

- Rust demo programs (dynamic and static linking)
- Build instructions using both Makefile and cargo
- u-boot-sys crate structure and FFI bindings
- Building examples outside the U-Boot tree

This provides parallel documentation to the existing C examples, making
it possible to use either language with ulib.

Co-developed-by: Claude <noreply@anthropic.com>
Signed-off-by: Simon Glass <sjg@chromium.org>
---

 doc/develop/ulib.rst | 61 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
diff mbox series

Patch

diff --git a/doc/develop/ulib.rst b/doc/develop/ulib.rst
index b2510a781aa..56e4e437dbf 100644
--- a/doc/develop/ulib.rst
+++ b/doc/develop/ulib.rst
@@ -180,6 +180,66 @@  The Makefile supports both single-file and multi-object programs through the
 ``demo-objs`` variable. Set this to build from multiple object files, or leave
 empty to build directly from source.
 
+Rust Examples
+-------------
+
+U-Boot also includes Rust examples that demonstrate the same functionality using
+the ``u-boot-sys`` crate:
+
+**Rust Demo Program**
+
+The ``examples/rust`` directory contains Rust examples:
+
+* ``demo`` - Dynamically linked Rust demo program
+* ``demo_static`` - Statically linked Rust version
+
+These Rust examples demonstrate:
+
+* Using the ``u-boot-sys`` crate for FFI bindings
+* Proper library initialization with ``ulib_init()``
+* Using U-Boot OS functions like ``os_open()``, ``os_fgets()``, ``os_close()``
+* Using renamed U-Boot library functions (e.g., ``ub_printf()``)
+* Modular program structure with helper functions in ``rust_helper.rs``
+* Proper cleanup with ``ulib_uninit()``
+
+**Building Rust Examples**
+
+To build and run the Rust examples::
+
+    # Make sure U-Boot itself is built
+    make O=/tmp/b/sandbox sandbox_defconfig all
+
+    cd examples/rust
+    make UBOOT_BUILD=/tmp/b/sandbox srctree=../..
+    ./demo_static
+
+Or using Cargo directly::
+
+    cd examples/rust
+    env UBOOT_BUILD=/tmp/b/sandbox cargo build --release --bin demo
+    LD_LIBRARY_PATH=/tmp/b/sandbox ./target/release/demo
+
+**Rust Crate Structure**
+
+The Rust examples use the ``u-boot-sys`` crate located in ``lib/rust/``, which provides:
+
+* FFI bindings for U-Boot library functions (``ulib_*``)
+* FFI bindings for U-Boot API functions (``ub_*``)  
+* FFI bindings for OS abstraction functions (``os_*``)
+* Proper Rust documentation and module organization
+
+The crate follows Rust ``*-sys`` naming conventions for low-level FFI bindings.
+
+**Building Rust Examples Outside U-Boot Tree**
+
+The Rust examples can be built independently using the ``u-boot-sys`` crate::
+
+    cd examples/rust
+    env UBOOT_BUILD=/path/to/uboot/build cargo build --release
+
+The examples demonstrate both static and dynamic linking approaches compatible
+with the Rust toolchain.
+
 Linking and the Linker Script
 -----------------------------
 
@@ -418,3 +478,4 @@  Future Work
 * Support for calling functions in any U-Boot header, without needing the source
   tree
 * Improved symbol renaming with namespace support
+* Expanded features in the lib/rust library