u-boot/examples/rust/README.md

Technical Notes - Rust U-Boot Integration

This directory contains a simple Rust implementation for using U-Boot's library. Both static and dynamic linking (of libu-boot) are available.

This directory is intended to be used separately from U-Boot's build system, e.g. by copying it somewhere else.

For comprehensive documentation, see :doc:/doc/develop/ulib.

Build System Success

The following components are included:

1. u-boot-sys Crate

The lib/rust/u-boot-sys crate provides FFI bindings organized into modules:

• uboot_lib: Library management functions (ulib_*)
• uboot_api: U-Boot API functions (ub_*)
• os: OS abstraction functions (os_*)

Functions are re-exported at the crate root for convenience.

2. Example Program Structure

• demo.rs: Main program using the u-boot-sys crate
• rust_helper.rs: Helper functions similar to C demo_helper.c
• Modular design with proper separation of concerns

3. Build Configuration

• build.rs configures linking with both static and dynamic libraries
• Uses --whole-archive for static linking to preserve U-Boot linker lists
• Links required system libraries (pthread, dl, rt, SDL2) with proper ordering
• Uses U-Boot's existing stack-protection implementation from stackprot.c

4. Integration

• Makefile can be use standalone or from U-Boot build system
• Cargo project depends on u-boot-sys crate from ../../lib/rust
• Examples are built automatically as part of U-Boot's build system

5. Runtime Execution ✅

• demo (dynamic) and demo-static executables work the same
• Calls library init with ulib_init()
• File operations using U-Boot's OS abstraction layer
• Uses renamed U-Boot library functions (ub_printf)
• Clean shutdown with ulib_uninit()

Architecture Overview

u-boot-sys Crate Design

• Located in lib/rust/ for reuse across U-Boot Rust projects
• Follows Rust *-sys naming conventions for FFI binding crates
• Intended to provide a safe, well-documented interfaces to U-Boot functions
• Organized into logical modules with re-exports for convenience

Dependency Structure

examples/rust/demo → u-boot-sys → U-Boot C library
                                      ↓
                              libu-boot.so/.a

Build System Integration

• Uses standard Cargo dependency resolution
• Makefile provides U-Boot-specific environment setup
• Compatible with both U-Boot's build system and standalone Cargo builds

Features Demonstrated

• FFI Integration: Shows how to call U-Boot C functions from Rust
• Library Initialization: Proper ulib_init() and ulib_uninit() usage
• File Operations: Using U-Boot's os_open(), os_fgets(), os_close()
• Print Functions: Using U-Boot's ub_printf() vs Rust's println!()
• Mixed Languages: Combining Rust and C functionality seamlessly

Prerequisites

1. Rust toolchain: Install from https://rustup.rs/
2. U-Boot library: Build U-Boot sandbox with library support:

   make sandbox_defconfig
   make
   

Usage Examples

# Ensure U-Boot is built first
# Note this builds rust examples at /tmp/b/sandbox/example/rust
make O=/tmp/b/sandbox sandbox_defconfig all

# Build both versions using Makefile
cd examples/rust
make UBOOT_BUILD=/tmp/b/sandbox srctree=../..

# Or build directly with Cargo
env UBOOT_BUILD=/tmp/b/sandbox cargo build --release

# Test dynamic version
LD_LIBRARY_PATH=/tmp/b/sandbox ./demo

# Test static version
./demo-static

# Run tests
make test

License

GPL-2.0+ (same as U-Boot)

Note: Linking with U-Boot's GPL-2.0+ library makes your program subject to GPL licensing terms.

Documentation and Further Reading

• See doc/develop/ulib.rst
• C examples: Located in examples/ulib/ for comparison
• u-boot-sys crate: API documentation via cargo doc in lib/rust/