STM32 Porting Guide First Pass

haydenridd · May 23, 2024, 1:41am

Hey all,

Put together a first pass at a porting guide for STM32 projects to Zig’s compiler:

I have grander aspirations of potentially adding a general “porting” section to zig.guide if there’s interest!

wrapitup · May 23, 2024, 12:44pm

Thanks for putting this together. I just got a discovery board and wanted to start tinkering with it.

Sazerac · May 24, 2024, 11:55am

Nice tutorial @haydenridd !

Note with my GCC version (12.3.1)

syscall.c: It is not needed when nosys lib is included
and optional implementation is possible if not (weak functions)
sysmem.c : I need to implement _sbrk if nosys lib is not included

Float formatting support

I was able to enable float support by adding this line to my build.zig config

elf.forceUndefinedSymbol("_printf_float"); // Allow float formatting (printf, sprintf, ...)

Question

If you use libnosys.a, malloc will not work. Am I right ?
You don’t mention of libg_nano.a but I see that is included by GCC in my case at linking stage. What is the purpose of this library ?
Do you think that compile and provide this own libc (newlib, nano, …) can it be a part of this tutorial ? I have always wondered how difficult this task was.

haydenridd · May 24, 2024, 3:36pm

Good callout, I was originally using the compiler version that comes “bundled” with the STM32CubeMX stuff, but I think I’ll update the tutorial to use the latest official release from ARM. Yup, essentially the sys**.c files provided by ST provide similar functionality to the “nosys” library. I actually ran into some interesting duplicate symbol errors using the Zig compiler because of this that wasn’t present in GCC. I believe zig cc/clang handles “weak” symbols differently than GCC which is a whole other nightmare I haven’t started digging into yet

Whoa… I’ll hand it to newlib that is a proper cursed way of enabling an option via the linker You may want to read up on this it looks like you may want to tread lightly using floats with newlib’s printf() implementation.

Questions:

Sigh, this has been the source of so many headaches for me. TLDR, even with nosys newlib ships with a functional malloc implementation (and when you get down to the nitty gritty functional _sbrk implementation) that depends on having linker symbols that specify where the heap starts/ends (I think something like __heap_start__ and __heap_end__). So “malloc” may or may not work correctly depending on if you have the linker symbols it wants. And to find those you’ll have to go to the newlib source code and see what it wants. I believe since ST doesn’t define these symbols in their generated linker script, but use their own (_estack), you’ll want to stick with their implementation in sysmem.c. In general I would be wary of using malloc with this implementation as it is super simple and really is only suitable for allocating all your things at program start and never touching them after. Why dynamic allocation is tricky on MCU’s is a whole other topic, look up what a “Memory Management Unit” is and note that generally MCUs don’t have these.
Nice spot! Hadn’t seen this before but after some research it appears that’s just newlib-nano compiled with debug symbols included.
I think that would be super interesting. I think I would probably choose to offer a guide on compiling/using an alternative standard lib like this one someone on the Zig discord pointed me towards. Eventually we may even have a libc written in Zig we could compile/link against.

EDIT:
I went ahead and dug into the newlib source since I was curious. ST actually DOES provide the correct linker symbol, which in this case is end. Here’s the snippet from newlib source that uses it:

oid *
_sbrk (incr)
     int incr;
{
   extern char   end; /* Set by linker.  */
   static char * heap_end;
   char *        prev_heap_end;

   if (heap_end == 0)
     heap_end = & end;

   prev_heap_end = heap_end;
   heap_end += incr;

   return (void *) prev_heap_end;
}

And the section in the linker script that provides it:

  /* User_heap_stack section, used to check that there is enough RAM left */
  ._user_heap_stack (NOLOAD) :
  {
    . = ALIGN(8);
    PROVIDE ( end = . );
    PROVIDE ( _end = . );
    . = . + _Min_Heap_Size;`
    . = . + _Min_Stack_Size;
    . = ALIGN(8);
  } >RAM

So malloc will work out of the box even without ST’s sysmem.c.

Sazerac · May 26, 2024, 12:07pm

I believe zig cc/clang handles “weak” symbols differently than GCC which is a whole other nightmare I haven’t started digging into yet

me too

it looks like you may want to tread lightly using floats with newlib’s printf() implementation.

O, nice topic. Implementing my own printf/sprintf can be nice to save flash memory indeed.
With forceUndefinedSymbol("_printf_float"), I wanted to know how to do the equivalent of gcc option: -u _printf_float

I would probably choose to offer a guide on compiling/using an alternative standard lib like this one someone on the Zig discord pointed me towards. Eventually we may even have a libc written in Zig we could compile/link against.

Picolibc is super interesting. I already tried to integrate it on STM32 without success, a long time ago. I’m going to take advantage of my learning on Zig to try again !

Optimization

I was able to reduce the output bin to close/equivalent to the GCC build by adding optimization level flag when compile C source files (ex:-0g)
By compiling the guide example, the output binary size from 18Kb is reduced to 6.3Kb

EDIT: LTO

I got warning by setting elf.want_lto to true:

ld.lld: warning: Linking two modules of different target triples: '[...]/stm32l4_test.elf.o' is 'thumb-unknown-unknown-eabihf' whereas 'ld-temp.o' is 'thumbv7em-unknown-unknown-eabihf'

It is tracked on zig repo here

haydenridd · June 2, 2024, 4:33pm

@Sazerac + anyone else this might be relevant to:
Did some more digging, and fortunately I take back what I said about weak symbols, I believe zig/clang handles them more or less the same as GCC which is nice! My confusion came from the following behavior which I tracked down:

Compiling a program where a file syscalls.c defines neccessary system function symbols (_exit, _kill, etc.) AND a pre-compiled library (libnosys) is included that ALSO defines stubs for these symbols:
- Standard Makefile with arm-none-eabi-gcc compiler/linker: Compiles + links fine
- Modified Makefile with zig cc as the compiler/linker: Compiles + links fine
- Equivalent build.zig file, compiles, but fails linking due to duplicate symbols

Took a while to figure out, but basically when linking, if you pass in your objects that define a symbol before a library that has that same symbol, it will simply not include the duplicate symbol and use yours. However, if you pass in the library first and then your object files, you get a duplicate symbol error since it nabbed the symbol from the library, then found your symbol (which it won’t ignore). Confirmed that the low level call to ld.lld was including the library files before my object files in the arg list, and when I switched the order manually, it linked fine.

haydenridd · June 10, 2024, 8:15pm

Updated repo with a couple of learnings + support for 0.13.0!

Sazerac · June 18, 2024, 12:05pm

Hi,
I am wondering about several points to better understand the relationships and differences between gcc, clang and zig.

low-level runtime library

libgcc.a. An explanation of that one can be found here;

“-lgcc” is no longer included, as Zig provides its own equivalent functionality to this library

I found this part interesting.

How does the Zig language manage the implementation of these features? (Builtin Functions is a part of it ?)
When compiling C, clang is used. clang also has its own implementation of these routines ?
Zig and clang use the sames routines ? Or each has its own implementation ?

c_nano vs g_nano

Nice spot! Hadn’t seen this before but after some research it appears that’s just newlib-nano compiled with debug symbols included.

I didn’t have time to go further to find out what debug features this library provides.
I imagine it is interesting to include this library instead of “libc_nano.a” it if a macro is set or a selection optimization level selected (eg: -DDEBUG, -0g)

Zig and custom libc

From the official documentation:

Although Zig is independent of C, and, unlike most other languages, does not depend on libc, Zig acknowledges the importance of interacting with existing C code.

When linking against libc, Zig exposes this allocator with std.heap.c_allocator.

Does the standard Zig library have dependencies with the libc (even optional)?.
Does the custom libc integration (libc_nano.a) allow the zig standard library to use them ? ( zig expect libc activation with lib.linkLibC() ? )

haydenridd · June 19, 2024, 9:31pm

To answer some questions:

low-level runtime library

How does the Zig language manage the implementation of these features? (Builtin Functions is a part of it ?)

Nope no built-in’s from Zig! This doesn’t involve Zig code at all. It basically provides the equivalent to libgcc in a library called libcompiler_rt. I’m hazy on the exact implementation but it essentially resolves how math/integer types work on your particular platform you’re compiling for. Someone else please jump in if they’re more familiar

When compiling C, clang is used. clang also has its own implementation of these routines ?

Yep, basically same answer as above.

Zig and clang use the sames routines ? Or each has its own implementation ?

I’m not quite sure what you mean here, in terms of what’s provided by libgcc? Or something else?

c_nano vs g_nano

I didn’t have time to go further to find out what debug features this library provides.
I imagine it is interesting to include this library instead of “libc_nano.a” it if a macro is set or a selection optimization level selected (eg: -DDEBUG, -0g)

I believe it literally just gives you a version of the library that’s compiled with debug symbols. You’ll be able to see the difference if you try to step into an actual newlib function in your debugger. You’ll have a lot more information with the “debug” compiled version of the library.

Zig and custom libc

Does the standard Zig library have dependencies with the libc (even optional)?.

std.heap.c_allocator. could be seen as a “dependency” of libc, although if you’re purely writing Zig code and don’t care to use this allocator I don’t think there’s any “hard” dependencies on libc. Basically, there’s only dependencies if you really need to call libc functions or Zig wrappers around libc functions.

Does the custom libc integration (libc_nano.a) allow the zig standard library to use them ? ( zig expect libc activation with lib.linkLibC() ? )

I just recently did a little research into this, short answer: no. Using our custom libc integration Zig is not aware of being linked against libc, so for instance you couldn’t use std.heap.c_allocator. However, if you really really wanted to use newlib’s implementation of malloc as an allocator (you don’t), there’s nothing to stop you from creating an allocator-like struct in Zig that wraps these calls. See this issue here, eventually I think it will be easier to make Zig “aware” of custom libc implementations:

github.com/ziglang/zig

Improve LibC interface in build.zig

opened 04:16PM - 17 Jun 24 UTC

ikskuh

enhancement proposal zig build system

Right now, the `--libc [file]` command line argument isn't really well exposed i…n `std.Build.Step.Compile`: https://github.com/ziglang/zig/blob/455899668b620dfda40252501c748c0a983555bd/lib/std/Build/Step/Compile.zig#L87 This implementation doesn't really give us the options to pass down ad-hoc compiled libcs like [Foundation libc](https://github.com/ZigEmbeddedGroup/foundation-libc) or newlib inside build.zig. The fields available in a `libc.txt` file are these: ```ini # The directory that contains `stdlib.h`. # On POSIX-like systems, include directories be found with: `cc -E -Wp,-v -xc /dev/null` include_dir=/nix/store/i58yz1rxjxpha40l17hgg7cz62jck9q3-glibc-2.38-77-dev/include # The system-specific include directory. May be the same as `include_dir`. # On Windows it's the directory that includes `vcruntime.h`. # On POSIX it's the directory that includes `sys/errno.h`. sys_include_dir=/nix/store/i58yz1rxjxpha40l17hgg7cz62jck9q3-glibc-2.38-77-dev/include # The directory that contains `crt1.o` or `crt2.o`. # On POSIX, can be found with `cc -print-file-name=crt1.o`. # Not needed when targeting MacOS. crt_dir=/nix/store/j0by58xwyc66f884x0q8rpzvgpwvjmf2-glibc-2.38-77/lib # The directory that contains `vcruntime.lib`. # Only needed when targeting MSVC on Windows. msvc_lib_dir= # The directory that contains `kernel32.lib`. # Only needed when targeting MSVC on Windows. kernel32_lib_dir= # The directory that contains `crtbeginS.o` and `crtendS.o` # Only needed when targeting Haiku. gcc_dir= ``` These options could be exposed inside a struct `std.Build.LibC`: ```zig pub const LibC = struct { /// The directory that contains `stdlib.h`. /// On POSIX-like systems, include directories be found with: `cc -E -Wp,-v -xc /dev/null` include_dirs: []const LazyPath, /// A list of additional object files or static libraries that might be linked with the final executable. /// These objects are required when using custom libc files. link_objects: []const LazyPath = &.{}, /// The system-specific include directory. May be the same as `include_dir`. /// On Windows it's the directory that includes `vcruntime.h`. /// On POSIX it's the directory that includes `sys/errno.h`. sys_include_dirs: []const LazyPath = &.{}, /// The directory that contains `crt1.o` or `crt2.o`. /// On POSIX, can be found with `cc -print-file-name=crt1.o`. /// Not needed when targeting MacOS. crt_dir: ?LazyPath = null, /// The directory that contains `vcruntime.lib`. /// Only needed when targeting MSVC on Windows. msvc_lib_dir: ?LazyPath = null, /// The directory that contains `kernel32.lib`. /// Only needed when targeting MSVC on Windows. kernel32_lib_dir: ?LazyPath = null, /// The directory that contains `crtbeginS.o` and `crtendS.o` /// Only needed when targeting Haiku. gcc_dir: ?LazyPath = null, }; ``` which could be used like this then: ```diff - libc_file: ?LazyPath = null, + libc: ?std.Build.LibC = null, ``` **Pre-defined libc:** ```zig pub fn build(b: *std.Build) void { // Emulate "--libc custom.txt": const libc = b.parseLibCFile(p.path("custom.txt")); const exe = b.addExecutable(.{ .libc = libc, … }); } ``` **Custom libc:** ```zig pub fn build(b: *std.Build) void { const foundation_libc = foundation_mod.artifact("foundation"); const libc = std.Build.LibC { .include_dirs = &.{ foundation_libc.getEmittedIncludeTree(), }, .link_objects = &.{ foundation_libc.getEmittedBin(), }, }; const exe = b.addExecutable(.{ .libc = libc, … }); } ```

Sazerac · June 22, 2024, 6:37am

My bad, I understood. Zig compiler and C compiler (clang) use the same routines from libcompiler_rt . Symbols are defined by LLVM.
When you compile with gcc, the routines are defined in the libgcc library.

However, if you really really wanted to use newlib’s implementation of malloc as an allocator (you don’t), there’s nothing to stop you from creating an allocator-like struct in Zig that wraps these calls. See this issue here, eventually I think it will be easier to make Zig “aware” of custom libc implementations:

I was only wondering about the interactions between the Zig language and the libc. Maybe it’s the subject of another topic