From patchwork Tue Sep 9 15:18:14 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 277 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=1757431182; bh=pYyTyEfvg4AncmHyL/nlAJJ3vLQ8DlS1EIYocyyX40k=; 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=rMO2aR+IzzEn6S/1yarYW+ftUNPFlkASWKZx0/9mVWCStnMI+LEmAbOXEyf409IF+ jl3WCFBujjKUkmg6n/8xiHiakSRRvQ7bE5Aj2dGqVQvGh065kokNmFTrcNWknMJfu1 H9UIwBSdIcLckQQblQ6MQ5hr4gx3/ji9/i247slgPkiqt2sUtDY4dEkqJFjK7PWa+h XA8RCFRX3GszJXCQnQfuOol3e/DFEgHJuCRndaxQUA/twk/OEZkIAWGPxmFP5+ySCw M8EwYPf+n9X5ulJZI4fnFRGYhy32MwWMyIgjMGkRsniegACVPcJdQhOW04JfsshHqP gVFrjns2rvmWA== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 1474A67A85 for ; Tue, 9 Sep 2025 09:19:42 -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 oX8Cbtkf9ABS for ; Tue, 9 Sep 2025 09:19:42 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1757431180; bh=pYyTyEfvg4AncmHyL/nlAJJ3vLQ8DlS1EIYocyyX40k=; 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=G8nCTvfUiVpKp3oQLzpMxVTdwcstJGovKgp/T/Wr0VAxUbizEkijUC54ddukWhUVL QQVoOnvKJfr2KtsEKZ1E1jm1OkURncj7cvQLzAeVZIdb/oOu9Bfks41d94FqFmEt6X G2AKd7BuoHB1zlaxn/YzZoN4uboA54AJa2JSXuxDFnPFHhDDC3av/5oImG9NkFflYP 4+7/3IwKdofurGIqueJ9Y+Ro8qZZFkF3N/woy4SS4X4m948k1b+5Z3wz3ugGzNw+Rn +NrLJ1j5qeO2ng9/hezCc7VrqETFTKKSQRtc27qsdchhhXfsUupKIEei0AslPQqImy 754UPKSLbAjwA== Received: from mail.u-boot.org (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 0C2B7679E6 for ; Tue, 9 Sep 2025 09:19:40 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1757431178; bh=CM6EfWe8hinbf+JZz4rdDKCmXSi3s2+tBouOhv6BRGo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=bJ64RzP1W4fnJJBLbqmrusjQJZudMNrWqSz/qTlE80LJhKScAXDweOk1ckjUfsjaS Cpd0QoFkrpH02ytWkqNpiaNMrh6vOY6QgxehEkMpVDSB/1d6uNiUP0J0u1LtGtJBoS su1ADPE5huQUDKZ6ssBhzgf9siHgVMziZOBQFMXB72ys/zdJ6IdfPDwc821JDQESGX 22jjF4LD+iO9bT6K57gEMT7l4qFx5wXqqNGIZ3TAW9LVXK3tQjdtjcW7s9koAWtznk v1AaET+Rdk6cVEwF3HqQwenwsP6PrJLThC+reC66EOLHFfCRx2f16J8jrvhGXpoZJY KBepyQx1QUqpA== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 9691667A88; Tue, 9 Sep 2025 09:19:38 -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 yW3ZeAoZZQBt; Tue, 9 Sep 2025 09:19:38 -0600 (MDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1757431177; bh=AYooH0sTvWpkz27mi5YTM7j+0Y44WN45CdDMPGqvkgU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=MOgnDIFdGPN2gpeVS28l1um9yCzp/q5shVTHw+H1o/UYbfmcuiGlxtExqgvjHPoIf WN+XLidWtUR9ngXohJe3h/zk0WZaKQw3vuVnvJGfsekSSG2mzvabyzIgn5qiu6+9x8 x3JPp3E45JlsB9YrNDWa3+H3Dhm1ELfIpnCtBCsh1EQFFZpWr2z936OKHPSWwpDntl SbFCoKc4zb7k7AAg8n8YSgLksTXLHsMu5OubNi1aumOs6hZUopJqIc6FDewLk6T9oO AnWJeXPTzAqPshw2z5opP0m25a7X5SicRvfr6ZQBEECIZX/6q69zbe3aral2m8Qxad pud37tOeBtGtA== Received: from u-boot.org (unknown [73.34.74.121]) by mail.u-boot.org (Postfix) with ESMTPSA id 8F55960026; Tue, 9 Sep 2025 09:19:37 -0600 (MDT) From: Simon Glass To: U-Boot Concept Date: Tue, 9 Sep 2025 09:18:14 -0600 Message-ID: <20250909151824.2327219-18-sjg@u-boot.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20250909151824.2327219-1-sjg@u-boot.org> References: <20250909151824.2327219-1-sjg@u-boot.org> MIME-Version: 1.0 Message-ID-Hash: S3BVVHNCRZAEQ2WXYEIYBVKDCJQR4YD4 X-Message-ID-Hash: S3BVVHNCRZAEQ2WXYEIYBVKDCJQR4YD4 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 X-Mailman-Version: 3.3.10 Precedence: list Subject: [Concept] [PATCH 17/18] ulib: doc: Expand the documentation to cover new features 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 Most of the ulib functionality is in place now. Update the documentation to match. Include details of how to run the example. Signed-off-by: Simon Glass --- doc/develop/ulib.rst | 179 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 171 insertions(+), 8 deletions(-) diff --git a/doc/develop/ulib.rst b/doc/develop/ulib.rst index 8df3a6f99bc..d68ffcaa964 100644 --- a/doc/develop/ulib.rst +++ b/doc/develop/ulib.rst @@ -80,16 +80,25 @@ main entry point while still using U-Boot functionality. The libraries preserve U-Boot's linker lists, which are essential for driver registration and other U-Boot subsystems. +**Link Time Optimization (LTO) Compatibility** + +When building with ``CONFIG_ULIB=y``, Link Time Optimization (LTO) is +automatically disabled. This is because the symbol renaming process uses +``objcopy --redefine-sym``, which is incompatible with LTO-compiled object +files. The build system handles this automatically. + Building outside the U-Boot tree -------------------------------- -This is possible, but as soon as you want to call a function that is not in -u-boot-lib.h you will have problems, as described in the following sections. +This is possible using the provided examples as a template. The ``examples/ulib`` +directory contains a standalone Makefile that can build programs against a +pre-built U-Boot library. -This will be addressed with future work. +The examples works as expected, but note that as soon as you want to call +functions that are not in the main API headers, you may have problems with +missing dependencies and header files. See below. -With that caveat, see example/ulib/README for instructions on how to use the -provided example. +See the **Example Programs** section above for build instructions. Including U-Boot header files from outside ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -114,10 +123,13 @@ CONFIG settings would need to be exported from the build and packaged with the library. -Test Programs -------------- +Test Programs and Examples +-------------------------- + +U-Boot includes several test programs and examples that demonstrate library +usage: -U-Boot includes test programs that demonstrate library usage: +**Test Programs** * ``test/ulib/ulib_test`` - Uses the shared library * ``test/ulib/ulib_test_static`` - Uses the static library @@ -132,6 +144,42 @@ Run the static library version:: ./test/ulib/ulib_test_static +**Example Programs** + +The ``examples/ulib`` directory contains more complete examples: + +* ``demo`` - Dynamically linked demo program showing U-Boot functionality +* ``demo_static`` - Statically linked version of the demo program + +These examples demonstrate: + +* Proper library initialization with ``ulib_init()`` +* Using U-Boot OS functions like ``os_open()``, ``os_fgets()``, ``os_close()`` +* Using renamed U-Boot library functions via ``u-boot-api.h`` + (e.g., ``ub_printf()``) +* Multi-file program structure (``demo.c`` + ``demo_helper.c``) +* Proper cleanup with ``ulib_uninit()`` + +To build and run the examples:: + + # Make sure U-Boot itself is built + make O=/tmp/b/sandbox sandbox_defconfig all + + cd examples/ulib + make UBOOT_BUILD=/tmp/b/sandbox srctree=../.. + ./demo_static + +**Building Examples Outside U-Boot Tree** + +The examples can be built independently if you have a pre-built U-Boot library:: + + cd examples/ulib + make UBOOT_BUILD=/path/to/uboot/build srctree=/path/to/uboot/source + +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. + Linking and the Linker Script ----------------------------- @@ -246,6 +294,120 @@ Limitations program * EFI runtime-services and relocation are disabled +Symbol Renaming and API Generation +----------------------------------- + +U-Boot includes a build script (``scripts/build_api.py``) that supports symbol +renaming and API-header generation for library functions. This allows creating +namespaced versions of standard library functions to avoid conflicts. + +For example, when linking with the library, printf() refers to the stdio +printf() function, while ub_printf() refers to U-Boot's version. + +Build System Integration +~~~~~~~~~~~~~~~~~~~~~~~~ + +The symbol renaming system is automatically integrated into the U-Boot build +process: + +* The symbol definitions are stored in ``lib/ulib/rename.syms`` +* During the sandbox build, the build system automatically: + + - Renames symbols in object files using ``--redefine`` when building the + U-Boot libraries (``libu-boot.so`` and ``libu-boot.a``) + - Generates ``include/u-boot-api.h`` with renamed function declarations + using ``--api`` + +* The API header provides clean interfaces for external programs linking + against the U-Boot library +* Symbol renaming ensures no conflicts between U-Boot functions and system + library functions + +Symbol Definition File Format +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The script uses a symbol definition file (``rename.syms``) with this format:: + + # Comment lines start with # + file: stdio.h + printf + sprintf=ub_sprintf_custom + + file: string.h + strlen + strcpy + +The format rules are: + +* Lines starting with ``file:`` specify a header file +* Indented lines (space or tab) define symbols from that header +* Use ``symbol=new_name`` for custom renaming, otherwise ``ub_`` a prefix is + added by default. No space around ``=`` +* Use ``#`` at the beginning of a line for a comment +* Empty lines are allowed + +Script Usage +~~~~~~~~~~~~ + +The build script provides several functions: + +**Parse and display symbols**:: + + python scripts/build_api.py rename.syms --dump + +**Apply symbol renaming to object files**:: + + python scripts/build_api.py rename.syms \ + --redefine file1.o file2.o \ + --output-dir /tmp/renamed_objects + +**Generate API header with renamed functions**:: + + python scripts/build_api.py rename.syms \ + --api ulib_api.h \ + --include-dir /path/to/headers \ + --output-dir /tmp/objects + +Script Architecture +~~~~~~~~~~~~~~~~~~~ + +The build script consists mostly of these classes: + +* **RenameSymsParser**: Parse the symbol definition file format and validate + syntax +* **DeclExtractor**: Extract function declarations with comments from headers +* **SymbolRedefiner**: Apply symbol renaming to object files using ``objcopy`` +* **ApiGenerator**: Create unified API headers with renamed function + declarations + +Symbol renaming operations copy files to an output directory rather than +modifying them in-place, to avoid race conditions. + +Object File Processing +~~~~~~~~~~~~~~~~~~~~~~ + +When processing object files, the script: + +1. Uses ``nm`` to check which files contain target symbols +2. Copies unchanged files that don't contain target symbols +3. Applies ``objcopy --redefine-sym`` for files needing renaming +4. Creates unique output filenames by replacing path separators with + underscores + +API Header Generation +~~~~~~~~~~~~~~~~~~~~~ + +The API header generation process: + +1. Groups symbols by their source header files +2. Searches for original header files in the specified include directory +3. Extracts function declarations (including comments) from source headers +4. Applies symbol renaming to the extracted declarations +5. Combines everything into a single API header file + +If any required headers or function declarations are missing, the script fails +with detailed error messages listing exactly what couldn't be found. + Future Work ----------- @@ -254,3 +416,4 @@ Future Work * API versioning and stability guarantees * pkg-config support for easier integration * Support for calling functions in any U-Boot header +* Improved symbol renaming with namespace support