From patchwork Thu Sep 11 21:44:15 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 296 Return-Path: X-Original-To: u-boot-concept@u-boot.org Delivered-To: u-boot-concept@u-boot.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1757627120; bh=z9w+K6Ve65vVxl9eAKusTue2hH+3vFjg0yBlcevBTVE=; h=From:To:Date:In-Reply-To:References:CC:Subject:List-Id: List-Archive:List-Help:List-Owner:List-Post:List-Subscribe: List-Unsubscribe:From; b=PLjPSVZgtUo0e3fDfk+uWXxe5DnIUi5Iby9arAsqeqbaBOF5Ffvhpg9ZxNk1wFc62 dQot/Xmj0hPH/t/GTrgZE7j6VkaQnRxTc1TKpLhBwsTuQxuFw3UDe0OXHDJeFrkHij lCqsico9uqfCb7x9KfeSi1EZtS1IbVJf10q7l5wUgxEttQVT1rxvqd4Yt4ULcp9YvL pXm7pjiqjpIBH/gunWRZEfxJBRHCkFmXpEXZwistIVcJE1Edguqlbln427JI+08rfb nnX48jclX5acNXTaq4OpBqKBxC3gMIkCrBvmrEC/eY8V4tzo/W1+nAvqYefFYQidN2 kBmURyphM8JAg== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 281B167B16 for ; Thu, 11 Sep 2025 15:45:20 -0600 (MDT) X-Virus-Scanned: Debian amavis at Received: from mail.u-boot.org ([127.0.0.1]) by localhost (mail.u-boot.org [127.0.0.1]) (amavis, port 10024) with ESMTP id QAYwQQPi_bST for ; Thu, 11 Sep 2025 15:45:20 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1757627118; bh=z9w+K6Ve65vVxl9eAKusTue2hH+3vFjg0yBlcevBTVE=; h=From:To:Date:In-Reply-To:References:CC:Subject:List-Id: List-Archive:List-Help:List-Owner:List-Post:List-Subscribe: List-Unsubscribe:From; b=Rdjh0wNIi+9AcFaHXx53Ctj6jlshLTvdCXfw/1O+h9FPdwGborfjJdvG5lIcFgC4j LzEqdUZBFmc8p53j7rxDeqPQlRLCcR4/K6BXVPbV0LOkX1p9cCee1TjrL3NTwItJQt i05pC4lwfauWh1Cu6cPa8X4n7B79XAIVTKVkvS/t/Wyl9S8iDQfY0fRVfFGKQNgo9Z Os79K2ZzEE7NpUVjpsD+s5uGw6+9/Q31PW7EEoHbY313bqLVRjqTQlXeDqQxhF5ohB 1KGrXtUL3hZ9a1Y4/zkJ+pWMpyejzzgm0q3t11+LNNRNcn3rcm0zhWeTqznnNv180l fu2TjugmXFYfA== Received: from mail.u-boot.org (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 23C9F67B0E for ; Thu, 11 Sep 2025 15:45:18 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1757627116; bh=GswesU997Z5Tlh9WMe9WSmbsmBmU1yldh3ZOmdjqEBg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Us0fgYQLKQNOSa30HmF9fL2exGT5Vx8ZkMGoR/3ibWlHExnOT52uCLeOcBi3R3S+O QDxubrGvOsiaKe0llQMaVi596qaFgu5eZeU9RHl884kmgISVl4B7K5BNGgf/uhlMeT MhW56hi8RmgY3xTh1Dw7hUNfGxaOAHqmKU4r160LcY2PZdOY44NZD1DnJ187gaY3UA 4TbQZSgUOpyC3xNhdRMWt16jc3EAk7ScHELbxjpEVDf0NzFYjiJL4KorNt/1kVBUEt bsr++Ov3AE2KtCaO/Ge6vgHar2Z+M09zQSgBbyo/9QpdEkOcipZknskACrvNAOmsR3 qJAGmCitoY8uQ== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id C6FFF67B0A; Thu, 11 Sep 2025 15:45:16 -0600 (MDT) X-Virus-Scanned: Debian amavis at Received: from mail.u-boot.org ([127.0.0.1]) by localhost (mail.u-boot.org [127.0.0.1]) (amavis, port 10026) with ESMTP id ifRuf4npbv_y; Thu, 11 Sep 2025 15:45:16 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1757627115; bh=BSljZabfWyMQQrvcKi7mdLZfeD5B+smSgej6vDixMZM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=g1bMvivxg5o/CgZo2U92Qz0FzT27gPs+GAP0JAD7QWOnJmTgxFmf3FI7HaKgpDqhb 2UP78wQmBg6tikeTjoQ1MnPP31PvRkhyjzd9hXr6akdKUyneIg92pVGoWW9RdDeMLi UfuKBM11MWG5b7y9UjRnmEclCQnyMb/I/ei3NndwZW9e0P0njk2nihPbfqC/G/uNMV ZMdOtpmlTyuoIcUdZXu9b1VsyRs+0BLawOadnYwlVo8Bd1zu9r9gjzgXapYJq3vGLd ZN6hTk8o6hRgAVeHSAA/I3Ad62P3op+84htMWL4/OuvPT+A2XjU0wdoVgJ5qyuw+PM MA2TRYCNfK+qQ== Received: from u-boot.org (unknown [73.34.74.121]) by mail.u-boot.org (Postfix) with ESMTPSA id 0C34567B06; Thu, 11 Sep 2025 15:45:14 -0600 (MDT) From: Simon Glass To: U-Boot Concept Date: Thu, 11 Sep 2025 15:44:15 -0600 Message-ID: <20250911214425.3687188-12-sjg@u-boot.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20250911214425.3687188-1-sjg@u-boot.org> References: <20250911214425.3687188-1-sjg@u-boot.org> MIME-Version: 1.0 Message-ID-Hash: TF47EDAYXUND25GI5PTPHP6YAKYSRU4V X-Message-ID-Hash: TF47EDAYXUND25GI5PTPHP6YAKYSRU4V X-MailFrom: sjg@u-boot.org X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: Heinrich Schuchardt , Simon Glass , Claude X-Mailman-Version: 3.3.10 Precedence: list Subject: [Concept] [PATCH 11/14] doc: ulib: Add Rust examples documentation List-Id: Discussion and patches related to U-Boot Concept Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: From: Simon Glass 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 Signed-off-by: Simon Glass --- doc/develop/ulib.rst | 61 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) 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