From: Simon Glass <sjg@chromium.org> Provide a version of fgets() which works on file descriptors. This can be used to read lines from a file, as will be needed for the ulib test-program. Signed-off-by: Simon Glass <sjg@chromium.org> --- arch/sandbox/cpu/os.c | 32 ++++++++++++++++++++++++++++++++ include/os.h | 14 ++++++++++++++ 2 files changed, 46 insertions(+) diff --git a/arch/sandbox/cpu/os.c b/arch/sandbox/cpu/os.c index 1c4e23cb4eb..891dfd9c9b8 100644 --- a/arch/sandbox/cpu/os.c +++ b/arch/sandbox/cpu/os.c @@ -150,6 +150,38 @@ int os_unlink(const char *pathname) return unlink(pathname); } +char *os_fgets(char *str, int size, int fd) +{ + char *s = str; + int n = size - 1; + int i; + + if (n <= 0 || !str) + return NULL; + + for (i = 0; i < n; i++) { + ssize_t ret; + char c; + + ret = read(fd, &c, 1); + if (ret <= 0) { + /* EOF or error */ + if (!i) + return NULL; + break; + } + + *s++ = c; + + if (c == '\n') + break; + } + + *s = '\0'; + + return str; +} + void os_exit(int exit_code) { exit(exit_code); diff --git a/include/os.h b/include/os.h index 3393acb435a..e5c524c57a4 100644 --- a/include/os.h +++ b/include/os.h @@ -106,6 +106,20 @@ int os_isatty(int fd); */ int os_unlink(const char *pathname); +/** + * os_fgets() - read a string from a file stream + * + * Reads at most @size - 1 characters from the stream and stores them in str. + * Reading stops after an EOF or a newline. If a newline is read, it is + * stored in str. A terminating nul byte is appended. + * + * @str: Buffer to store the string + * @size: Maximum number of characters to read (including null terminator) + * @fd: File descriptor to read from + * Return: str on success, NULL on error, or EOF with no characters read + */ +char *os_fgets(char *str, int size, int fd); + /** os_persistent_fname() - Find the path to a test file * * @buf: Buffer to hold path -- 2.43.0

From: Simon Glass <sjg@chromium.org> By default U-Boot shows the console settings on startup, e.g.: In: serial,vidconsole Out: serial,vidconsole Err: serial,vidconsole These messages are useful for the user but not for an application using U-Boot as a library. Disable them. Signed-off-by: Simon Glass <sjg@chromium.org> --- common/console.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common/console.c b/common/console.c index 2073a9878a5..77f70588488 100644 --- a/common/console.c +++ b/common/console.c @@ -1301,7 +1301,7 @@ int console_init_r(void) done: - if (!IS_ENABLED(CONFIG_SYS_CONSOLE_INFO_QUIET)) + if (!IS_ENABLED(CONFIG_SYS_CONSOLE_INFO_QUIET) && !gd_ulib()) stdio_print_current_devices(); #ifdef CONFIG_VIDCONSOLE_AS_LCD -- 2.43.0

From: Simon Glass <sjg@chromium.org> The application wants control once the U-Boot library is ready, so skip the main loop and just return. Signed-off-by: Simon Glass <sjg@chromium.org> --- common/board_r.c | 8 ++++++++ include/init.h | 4 ++++ 2 files changed, 12 insertions(+) diff --git a/common/board_r.c b/common/board_r.c index a19c3138962..d38c2304e87 100644 --- a/common/board_r.c +++ b/common/board_r.c @@ -539,6 +539,9 @@ static int dm_announce(void) static int run_main_loop(void) { + if (gd_ulib()) + return 0; + #ifdef CONFIG_SANDBOX sandbox_main_loop_init(); #endif @@ -768,6 +771,11 @@ void board_init_r(gd_t *new_gd, ulong dest_addr) initcall_run_r(); +#ifdef CONFIG_ULIB + if (gd_ulib()) + return; +#endif + /* NOTREACHED - run_main_loop() does not return */ hang(); } diff --git a/include/init.h b/include/init.h index 2c37cef5fc0..e4b07ea48a0 100644 --- a/include/init.h +++ b/include/init.h @@ -277,8 +277,12 @@ struct global_data; void arch_setup_gd(struct global_data *gd_ptr); /* common/board_r.c */ +#ifdef CONFIG_ULIB +void board_init_r(struct global_data *id, ulong dest_addr); +#else void board_init_r(struct global_data *id, ulong dest_addr) __attribute__ ((noreturn)); +#endif int cpu_init_r(void); int mac_read_from_eeprom(void); -- 2.43.0

From: Simon Glass <sjg@chromium.org> Each architecture will have its own version of the linker script, so use a Makefile variable for it. Signed-off-by: Simon Glass <sjg@chromium.org> --- Makefile | 5 +++-- arch/sandbox/config.mk | 3 +++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 7011535bb2f..1a378ebbee3 100644 --- a/Makefile +++ b/Makefile @@ -1856,7 +1856,7 @@ endif # Build U-Boot as a shared library quiet_cmd_libu-boot.so = LD $@ cmd_libu-boot.so = $(CC) -shared -o $@ -Wl,--build-id=none \ - -Wl,-T,$(srctree)/arch/sandbox/cpu/u-boot-lib.lds \ + -Wl,-T,$(LIB_LDS) \ $(u-boot-init) \ $(KBUILD_LDFLAGS:%=-Wl,%) $(SANITIZERS) $(LTO_FINAL_LDFLAGS) \ -Wl,--whole-archive \ @@ -1865,7 +1865,8 @@ quiet_cmd_libu-boot.so = LD $@ -Wl,--no-whole-archive \ $(PLATFORM_LIBS) -Wl,-Map -Wl,libu-boot.map -libu-boot.so: $(u-boot-init) $(u-boot-main) $(u-boot-keep-syms-lto) FORCE +libu-boot.so: $(u-boot-init) $(u-boot-main) $(u-boot-keep-syms-lto) \ + $(LIB_LDS) FORCE $(call if_changed,libu-boot.so) # Build ulib_test that links with shared library diff --git a/arch/sandbox/config.mk b/arch/sandbox/config.mk index 405843800e9..566f5b417ae 100644 --- a/arch/sandbox/config.mk +++ b/arch/sandbox/config.mk @@ -69,3 +69,6 @@ EFI_LDS := ${SRCDIR}/../../../arch/riscv/lib/elf_riscv64_efi.lds endif EFI_CRT0 := crt0_sandbox_efi.o EFI_RELOC := reloc_sandbox_efi.o + +# U-Boot Library +LIB_LDS := $(srctree)/arch/sandbox/cpu/u-boot-lib.lds -- 2.43.0

From: Simon Glass <sjg@chromium.org> Provide a simple function to set up the library, to avoid having to worry about the details. This requires the caller to know about global_data Signed-off-by: Simon Glass <sjg@chromium.org> --- arch/sandbox/cpu/start.c | 30 +++++++++++++++++++---- arch/sandbox/include/asm/u-boot-sandbox.h | 9 +++++++ test/ulib/ulib_test.c | 12 +++------ 3 files changed, 37 insertions(+), 14 deletions(-) diff --git a/arch/sandbox/cpu/start.c b/arch/sandbox/cpu/start.c index 59682b039e5..556d1985ccc 100644 --- a/arch/sandbox/cpu/start.c +++ b/arch/sandbox/cpu/start.c @@ -693,13 +693,14 @@ int sandbox_init(int argc, char *argv[], struct global_data *data) return 0; } -int sandbox_main(int argc, char *argv[]) +static int sandbox_flow(int argc, char *argv[], struct global_data *data, + uint flags) { - gd_t data; int ret; - memset(&data, '\0', sizeof(data)); - ret = sandbox_init(argc, argv, &data); + memset(data, '\0', sizeof(struct global_data)); + data->flags = flags; + ret = sandbox_init(argc, argv, data); if (ret) goto err; @@ -708,10 +709,29 @@ int sandbox_main(int argc, char *argv[]) board_init_r(gd->new_gd, 0); - /* NOTREACHED - board_init_r() does not return */ return 0; err: printf("Error %d\n", ret); return 1; } + +int sandbox_main(int argc, char *argv[]) +{ + gd_t data; + + sandbox_flow(argc, argv, &data, 0); + + /* NOTREACHED - board_init_r() does not return */ + return 1; +} + +int ulib_init_with_data(char *progname, struct global_data *data) +{ + char *argv[] = {progname, NULL}; + int ret; + + ret = sandbox_flow(1, argv, data, GD_FLG_ULIB); + + return ret; +} diff --git a/arch/sandbox/include/asm/u-boot-sandbox.h b/arch/sandbox/include/asm/u-boot-sandbox.h index 941f35f9e69..859c2f08b4c 100644 --- a/arch/sandbox/include/asm/u-boot-sandbox.h +++ b/arch/sandbox/include/asm/u-boot-sandbox.h @@ -75,4 +75,13 @@ int sandbox_init(int argc, char *argv[], struct global_data *data); */ int sandbox_main(int argc, char *argv[]); +/** + * ulib_init_with_data() - set up the U-Boot library + * + * @progname: Program name to use, typically argv[0] + * @data: Global data (must remain valid until the program exits) + * Return: 0 if OK, -ve error code on error + */ +int ulib_init_with_data(char *progname, struct global_data *data); + #endif /* _U_BOOT_SANDBOX_H_ */ diff --git a/test/ulib/ulib_test.c b/test/ulib/ulib_test.c index 621bcd49be9..e1e863712a8 100644 --- a/test/ulib/ulib_test.c +++ b/test/ulib/ulib_test.c @@ -23,15 +23,9 @@ int main(int argc, char *argv[]) printf("Calling U-Boot initialization via shared library...\n"); - /* init global data */ - memset(&data, '\0', sizeof(data)); - data.flags = GD_FLG_ULIB; - - ret = sandbox_init(argc, argv, &data); - - /* Do pre- and post-relocation init */ - board_init_f(gd->flags); - board_init_r(data.new_gd, 0); + ret = ulib_init_with_data(argv[0], &data); + if (ret) + return 1; return ret; } -- 2.43.0

From: Simon Glass <sjg@chromium.org> Create a static version of the library test. This requires a linker script, since the linker lists much be correctly placed within the final executable. Provide a linker script for the sandbox version. Signed-off-by: Simon Glass <sjg@chromium.org> --- Makefile | 18 +++++++++++++++++- arch/sandbox/config.mk | 1 + arch/sandbox/cpu/ulib-test-static.lds | 19 +++++++++++++++++++ 3 files changed, 37 insertions(+), 1 deletion(-) create mode 100644 arch/sandbox/cpu/ulib-test-static.lds diff --git a/Makefile b/Makefile index bf571de9f06..3ece9a02b6c 100644 --- a/Makefile +++ b/Makefile @@ -1046,7 +1046,7 @@ INPUTS-$(CONFIG_X86) += u-boot-x86-start16.bin u-boot-x86-reset16.bin \ ifdef CONFIG_CMDLINE ifneq ($(cc-name),clang) INPUTS-$(CONFIG_ULIB) += libu-boot.so test/ulib/ulib_test -INPUTS-$(CONFIG_ULIB) += libu-boot.a +INPUTS-$(CONFIG_ULIB) += libu-boot.a test/ulib/ulib_test_static endif endif @@ -1893,6 +1893,22 @@ quiet_cmd_ulib_test = HOSTCC $@ test/ulib/ulib_test: test/ulib/ulib_test.o libu-boot.so FORCE $(call if_changed,ulib_test) +# Build ulib_test_static to test linking with the static library +# main.o is excluded from the static library since the main program is provided +# by the user +# Use --whole-archive to include all linker lists +# Use a linker script to ensure proper alignment of linker-lists +quiet_cmd_ulib_test_static = HOSTCC $@ + cmd_ulib_test_static = $(HOSTCC) $(HOSTCFLAGS) \ + -I$(srctree)/arch/sandbox/include -o $@ $< \ + -Wl,-T,$(LIB_STATIC_LDS) \ + -Wl,--whole-archive $(obj)/libu-boot.a -Wl,--no-whole-archive \ + -lpthread -ldl -lSDL2 -lrt -Wl,-z,noexecstack + +test/ulib/ulib_test_static: test/ulib/ulib_test.o libu-boot.a \ + $(LIB_STATIC_LDS) FORCE + $(call if_changed,ulib_test_static) + quiet_cmd_sym ?= SYM $@ cmd_sym ?= $(OBJDUMP) -t $< > $@ u-boot.sym: u-boot FORCE diff --git a/arch/sandbox/config.mk b/arch/sandbox/config.mk index 566f5b417ae..f80e2ef369f 100644 --- a/arch/sandbox/config.mk +++ b/arch/sandbox/config.mk @@ -72,3 +72,4 @@ EFI_RELOC := reloc_sandbox_efi.o # U-Boot Library LIB_LDS := $(srctree)/arch/sandbox/cpu/u-boot-lib.lds +LIB_STATIC_LDS := $(srctree)/arch/sandbox/cpu/ulib-test-static.lds diff --git a/arch/sandbox/cpu/ulib-test-static.lds b/arch/sandbox/cpu/ulib-test-static.lds new file mode 100644 index 00000000000..c400fba4f2b --- /dev/null +++ b/arch/sandbox/cpu/ulib-test-static.lds @@ -0,0 +1,19 @@ +/* SPDX-License-Identifier: GPL-2.0+ */ +/* + * Linker script for ulib_test_static binary + * + * This ensures proper alignment for linker-lists when linking with libu-boot.a + */ + +SECTIONS +{ + /* Ensure proper alignment for linker lists */ + . = ALIGN(32); + __u_boot_list : { + __u_boot_list_start = .; + KEEP(*(SORT(__u_boot_list*))); + __u_boot_list_end = .; + } +} + +INSERT AFTER .rodata; -- 2.43.0

From: Simon Glass <sjg@chromium.org> When the test is run, indicate which library the test was linked against, static or dynamic. Drop the printf() at the start of main(). Since all printf() calls go to U-Boot, this message is not shown anyway, since the global-data pointer gd is NULL at this point and console_puts() just returns immediately. Signed-off-by: Simon Glass <sjg@chromium.org> --- test/ulib/ulib_test.c | 39 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/test/ulib/ulib_test.c b/test/ulib/ulib_test.c index a68290ff484..51b1c62e6b2 100644 --- a/test/ulib/ulib_test.c +++ b/test/ulib/ulib_test.c @@ -2,7 +2,7 @@ /* * Test application for U-Boot shared library * - * This demonstrates linking against libu-boot.so + * This demonstrates linking against libu-boot.so and libu-boot.a * * Copyright 2025 Canonical * Written by Simon Glass <simon.glass@canonical.com> @@ -11,17 +11,50 @@ /* Use system headers, not U-Boot headers */ #include <stdio.h> #include <string.h> + +#include <os.h> #include <u-boot-lib.h> +/* Runtime detection of link type using /proc/self/maps */ +static const char *detect_link_type(void) +{ + char line[512]; + int fd; + int found_libuboot = 0; + + /* Open /proc/self/maps to check loaded libraries */ + fd = os_open("/proc/self/maps", 0); + if (fd < 0) + return "unable to detect linkage"; + + /* Read line by line to avoid boundary issues */ + while (os_fgets(line, sizeof(line), fd)) { + if (strstr(line, "libu-boot.so")) { + found_libuboot = 1; + break; + } + } + + os_close(fd); + + /* Return appropriate message based on what we found */ + if (found_libuboot) + return "dynamically linked (uses libu-boot.so)"; + else + return "statically linked (uses libu-boot.a)"; +} + int main(int argc, char *argv[]) { int ret; - printf("Calling U-Boot initialization via shared library...\n"); - ret = ulib_init(argv[0]); if (ret) return 1; + printf("Hello, world\n"); + printf("\n- U-Boot\n"); + printf("\nPS: This program is %s\n", detect_link_type()); + return ret; } -- 2.43.0

From: Simon Glass <sjg@chromium.org> Add documentation for the U-Boot Library (ulib) feature, explaining how to build and use both shared (.so) and static (.a) libraries. Co-developed-by: Claude <noreply@anthropic.com> Signed-off-by: Simon Glass <sjg@chromium.org> --- doc/develop/index.rst | 1 + doc/develop/ulib.rst | 253 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 254 insertions(+) create mode 100644 doc/develop/ulib.rst diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 592736331f2..12a71b5b23a 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -56,6 +56,7 @@ Implementation falcon std_passage uefi/index + ulib vbe version diff --git a/doc/develop/ulib.rst b/doc/develop/ulib.rst new file mode 100644 index 00000000000..559f170ce42 --- /dev/null +++ b/doc/develop/ulib.rst @@ -0,0 +1,253 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +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 U-Boot image. + +Please read `License Implications`_ below. + +Building the Libraries +---------------------- + +For now the library is only available for :doc:`/arch/sandbox/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. + +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 will be addressed with future work. + +Including U-Boot header files from outside +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +U-Boot has many header files, some of which are arch-specific. These are +typically including 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 +------------- + +U-Boot includes test programs that demonstrate library usage: + +* ``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 + +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 sanbod, 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: + +1. For static library, ensure you're using ``--whole-archive`` +2. Check that required system libraries are linked +3. 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: + +1. Check linker list alignment with:: + + scripts/check_linker_lists.py /path/to/executable + +2. For static linking, use ``--whole-archive`` to include all sections +3. Use a custom linker script for proper section organization + +Runtime Errors +~~~~~~~~~~~~~~ + +For shared library programs: + +1. Ensure ``LD_LIBRARY_PATH`` includes the directory with ``libu-boot.so`` +2. Or use ``-Wl,-rpath`` when linking to embed the library path +3. 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 + +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 -- 2.43.0