U-Boot Library (ulib)

The U-Boot Library (ulib) allows U-Boot to be built as a shared or static library that can be used by external programs. This enables reuse of U-Boot functionality in test programs and other applications without needing to build that functionality directly into a U-Boot image.

Please read License Implications below.

Motivation

U-Boot contains a vast arrange of functionality. It supports standard boot, native execution (sandbox) for development and testing, filesystems, networking, all sorts of boot protocols, drivers and support for about 1300 boards, a full command line interface, a configuration editor / graphical menu, good Linux compatibility for porting drivers, a powerful but efficient driver model which uses Linux devicetree and many other features. The code base is fairly modern, albeit with some dark spaces. Unusually for firmware, U-Boot provides a vast array of tests. It can boot EFI apps or as an EFI app. It supports most relevant architectures and modern SoCs.

But of course time marches on and innovation must continue. U-Boot will clearly be part of the picture in the future, but what is next?

Ulib is an attempt to make U-Boot’s functionality more easily available to other projects, so they can build on it improve it or even replace parts of it. Ulib aims to open up the capabilities of U-Boot to new use cases.

Ulib also provides the ability to write the main program in another language. For now C and Rust are supported, but Python should also be possible, albeit with a significant amount of work.

Few can predict where boot firmware will be in 10 years. The author of this file rashly believes that we may have moved on from U-Boot, EFI and many other things considered essential today. Perhaps firmware will be written in Rust or Zig or Carbon or some other new language. Our AI overlords may be capable of writing firmware based on a specification, if we can feed them enough electricity. Or it could be that the complexity of SoCs grows at such a rate that we just carry on as we are, content to just be able to make something boot.

Ulib aims to provide a bridge from the best (more or less) of what we have today to whatever it is that will replace it. Ulib is not an end itself, just a platform for further innovation in booting, to new languages, new boot protocols and new development methods.

Building the Libraries

For now the library is only available for Sandbox, i.e. for running natively on a host machine. Further work will extend that to other architectures supported by U-Boot.

To build U-Boot as a library (libu-boot.so):

make sandbox_defconfig
make [-s] -j$(nproc)

Use -s if you just want to see warnings / errors. This produces two files:

libu-boot.so

This is the shared library, sometimes called a dynamically linked library. Programs which need it can be dynamically linked with this library at runtime. This provides:

Smaller executable size for linked programs

Runtime dependency on the .so file

Must set LD_LIBRARY_PATH or use rpath for runtime linking

Suitable for development and testing

libu-boot.a

This is a static library, meaning that it is directly linked with your program and the resulting executable includes the U-Boot code. This provides:

Larger executable size (includes all code)

No runtime dependencies

Self-contained executables

Suitable for distribution and embedded systems

To disable creation of the library (e.g. to speed up the build), provide NO_LIBS=1 in the environment:

NO_LIBS=1 make -j$(nproc)

Simple test programs are provided for each library.

For dynamic linking:

$ LD_LIBRARY_PATH=. ./test/ulib/ulib_test
Hello, world

- U-Boot

PS: This program is dynamically linked (uses libu-boot.so)

For static linking:

$ ./test/ulib/ulib_test_static
Hello, world

- U-Boot

PS: This program is statically linked (uses libu-boot.a)

Architecture Notes

Both libraries exclude arch/sandbox/cpu/main.o which contains the main() function. This allows the linking program to provide its own 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 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.

The examples work 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.

See the Example Programs section above for build instructions.

Including U-Boot header files from outside

U-Boot has many header files, some of which are arch-specific. These are typically included via:

#include <asm/...>

and are located in the arch/<arch>/include/asm/... directory within the U-Boot source tree. You will need to ensure that this directory is present in the include path.

Kconfig options

There is currently no mechanism to make use of the Kconfig options used to build the U-Boot library. It is possible to add -include kconfig.h to your build, but for this to work more generally, the header file containing the CONFIG settings would need to be exported from the build and packaged with the library.

Test Programs and Examples

U-Boot includes several test programs and examples that demonstrate library usage:

Test Programs

test/ulib/ulib_test - Uses the shared library
test/ulib/ulib_test_static - Uses the static library

These are built by default with the sandbox build.

Run the shared library version:

./test/ulib/ulib_test

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.

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

For the static library, a custom linker script is needed to ensure proper section alignment, particularly for U-Boot linker lists. See arch/sandbox/cpu/ulib-test-static.lds for an example.

The linker script ensures:

Proper alignment of the __u_boot_list section (32-byte alignment)
Correct ordering of sandbox-specific sections
Preservation of linker list entries with KEEP() directives

For this to work, the library must be linked using a ‘whole archive’ approach, for example:

-Wl,--whole-archive $(obj)/libu-boot.a -Wl,--no-whole-archive

Failure to do either of these will result in strange errors, such as running out of memory or simple crashes during library init.

Dependencies

When linking with the U-Boot library for sandbox, you may need these system libraries:

pthread - POSIX threads
dl - Dynamic linking support
SDL2 - For sandbox display emulation (optional)
rt - Real-time extensions

Troubleshooting

Missing Symbols

If you encounter undefined symbol errors when linking:

For static library, ensure you’re using --whole-archive
Check that required system libraries are linked
Some symbols may need to be defined with --defsym:
- __stack_chk_guard - Stack protection guard
- sandbox_sdl_sync - SDL synchronization (can be set to 0 if unused)

Linker List Issues

If U-Boot subsystems don’t initialize properly:

Check linker list alignment with:

scripts/check_linker_lists.py /path/to/executable

For static linking, use --whole-archive to include all sections
Use a custom linker script for proper section organization

Runtime Errors

For shared library programs:

Ensure LD_LIBRARY_PATH includes the directory with libu-boot.so
Or use -Wl,-rpath when linking to embed the library path
Check library dependencies with ldd myapp

License Implications

U-Boot is licensed under GPL-2.0+ (GNU General Public License version 2 or later). This has important implications when linking against the U-Boot library:

Static Linking (libu-boot.a):
- Your program becomes a derivative work of U-Boot
- The entire combined work must be distributed under GPL-2.0+ terms
- You must provide source code for your entire application
- All code linked with the static library must be GPL-compatible
Dynamic Linking (libu-boot.so):
- The GPL interpretation for dynamic linking is legally complex
- Conservative interpretation: still creates a derivative work requiring GPL
- Some jurisdictions may treat dynamic linking differently
- Consult legal counsel for commercial applications
Compliance Requirements:
- Provide a GPL-2.0+ license notice
- Make source code available (including your modifications)
- Include copyright notices from U-Boot
- Provide build instructions to reproduce the binary
Alternative Approaches:
- Consider using U-Boot functionality via separate processes (IPC)
- Implement a clean-room alternative for needed functionality
- Request dual-licensing from all U-Boot contributors (impractical)

Note: This is not legal advice. Always consult with legal professionals when using GPL-licensed code in your products, especially for commercial use.

Limitations

Currently only supported for sandbox architecture
Network-subsystem init is disabled in library mode
Main-loop functionality is disabled to prevent interference with the host 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 a ub_ 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:

Uses nm to check which files contain target symbols
Copies unchanged files that don’t contain target symbols
Applies objcopy --redefine-sym for files needing renaming
Creates unique output filenames by replacing path separators with underscores

API Header Generation

The API header generation process:

Groups symbols by their source header files
Searches for original header files in the specified include directory
Extracts function declarations (including comments) from source headers
Applies symbol renaming to the extracted declarations
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

Support for other architectures beyond sandbox
Selective inclusion of U-Boot subsystems
API versioning and stability guarantees
pkg-config support for easier integration
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