Libraries#

EmbCC ships three libraries of its own, all compiled by EmbCC: a C library (lib/libc), a C++ runtime and standard library (lib/libcxx), and the compiler runtime (lib/rt), which holds the routines generated code calls for operations the machine has no instruction for. This chapter says what each contains and leaves out, which targets each is built for, how the driver links them, and how to build them. It is for anyone who links a program with EmbCC or wants to know which part of the C or C++ library a program can rely on. Firmware-specific use of the runtime is in Bare-metal programming.

Overview#

Every library is built per target by the embcc in the same tree, so it always matches the compiler's ABI. No library exists for the macOS or Windows triples: a Darwin object is linked by the system linker against the system's libraries, and the Windows triple has no C library.

How the driver links the libraries#

When the driver links at all#

embcc [FILE] [OBJECTS...] -o OUT (no -c, -S, -E or --syntax-only) compiles the source, if there is one, and links in the same process with EmbLD. The driver links the x86-64 ELF targets (x86_64-elf, x86_64-emblink, x86_64-linux-gnu) and, given a memory map (--link-script=board.ld, or -Wl,-Ttext/-Tdata), the ARM, RISC-V and AVR firmware targets; for AArch64 ELF, Mach-O and COFF targets it stops with embcc: error: cannot link for TRIPLE. The details are in Invoking.

The link line#

The driver builds a fixed link line, in this order:

1. crt1.o, if the target has one (only the Linux triples do);
2. the object it just compiled;
3. libcxx.a, when the source is C++;
4. libc.a, if the target has one;
5. librt.a, if the target has one.

libcxx.a comes before libc.a because the C++ runtime calls into the C library (operator new is malloc), and librt.a comes last because a C library routine can call the runtime (printing a 128-bit value divides it). Archives are searched left to right with a final pass that revisits them, so a member pulled in late can still resolve against an earlier archive. Only the archive members a program references are linked, and the embedded libc.a and librt.a have a section per function and per object, so an image linked with --gc-sections keeps only the functions it reaches inside those members (Embedded).

A missing library is reported by name rather than as a list of undefined symbols:

embcc: error: no crt1.o for x86_64-linux-gnu: its C library is not built; `make libc-linux-x86_64` in /path/to/EmbCC builds it
embcc: --print-search-dirs says where it looked

An installed compiler names make install instead of a make target. A C++ program on a target with no libcxx.a fails the same way, naming the C++ runtime's make target. On a hosted (Linux) target a missing crt1.o or libc.a is an error; on a freestanding target the driver links what it finds, and the program must define _start.

Where the libraries are found#

The driver looks for a target's files relative to its own executable:

In a build tree the directory is build/libc/x86_64 for x86_64-elf and x86_64-emblink, build/libc/aarch64 for aarch64-elf, build/libc/linux-x86_64 and build/libc/linux-aarch64 for the Linux triples, build/libc/darwin-aarch64 and build/libc/darwin-x86_64 for macOS (make rt-darwin-aarch64 rt-darwin-x86_64), and build/libc/TRIPLE for every other triple. libcxx.a is under build/libcxx/ in the same scheme. An installation has one directory per canonical triple and none for x86_64-emblink. The search for the installation itself, and EMBCC_PREFIX, are described in Invoking.

Opting out#

The driver has no --no-stdlib, --no-default-libs or --no-start-files, and no -l or -L; each is rejected as an unknown argument:

embcc: error: unknown argument '-nostdlib'

The driver's link takes EmbLD's own options through -Wl, and --linker-arg (--entry, -Ttext, -Tdata, -Tstack, --rom-limit, --lma-offset; see Invoking), but not other inputs. To link without EmbCC's libraries, or with others, compile with -c and run embld with exactly the inputs wanted:

embcc -c --opt=speed kernel.c -o kernel.o
embld -e _start -Ttext 0xFFFFFFFF80100000 -o kernel.elf entry.o kernel.o

--freestanding and --no-builtins are accepted and change neither the link line nor the header search. --no-std-include removes EmbCC's header directories from the search (see Invoking).

Header directories#

EmbCC's own headers are searched after every -I and --system-include directory, as system directories:

--print-search-dirs prints the directories found. The full search order, including the include directory beside the invoked executable, is in Invoking.

The C library: lib/libc#

Scope#

lib/libc is a C11 library written for EmbCC, with C23's additions: the portable part is the same source on every target, and each operating system is reached through one small backend file (see Backends). Its headers are the C11 hosted set:

<assert.h> <complex.h> <ctype.h> <errno.h> <fenv.h> <inttypes.h> <iso646.h> <limits.h> <locale.h> <math.h> <setjmp.h> <signal.h> <stdalign.h> <stdatomic.h> <stdio.h> <stdlib.h> <stdnoreturn.h> <string.h> <tgmath.h> <threads.h> <time.h> <uchar.h> <wchar.h> <wctype.h>

and, of POSIX's and the common Unix ones, <aio.h> <arpa/inet.h> <dirent.h> <dlfcn.h> <elf.h> <endian.h> <err.h> <error.h> <fcntl.h> <fmtmsg.h> <fnmatch.h> <fts.h> <ftw.h> <getopt.h> <glob.h> <grp.h> <iconv.h> <ifaddrs.h> <langinfo.h> <libgen.h> <libintl.h> <link.h> <malloc.h> <mntent.h> <monetary.h> <mqueue.h> <net/if.h> <netdb.h> <netinet/ether.h> <netinet/in.h> <netinet/tcp.h> <netpacket/packet.h> <nl_types.h> <paths.h> <poll.h> <pthread.h> <pty.h> <pwd.h> <regex.h> <sched.h> <search.h> <semaphore.h> <shadow.h> <spawn.h> <strings.h> <syslog.h> <termios.h> <ucontext.h> <ulimit.h> <unistd.h> <utime.h> <utmp.h> <utmpx.h> <wordexp.h> and <sys/auxv.h> <sys/epoll.h> <sys/eventfd.h> <sys/file.h> <sys/inotify.h> <sys/ioctl.h> <sys/ipc.h> <sys/klog.h> <sys/mman.h> <sys/mount.h> <sys/msg.h> <sys/param.h> <sys/personality.h> <sys/prctl.h> <sys/random.h> <sys/reboot.h> <sys/resource.h> <sys/select.h> <sys/sem.h> <sys/sendfile.h> <sys/shm.h> <sys/signalfd.h> <sys/socket.h> <sys/stat.h> <sys/statfs.h> <sys/statvfs.h> <sys/swap.h> <sys/syscall.h> <sys/sysinfo.h> <sys/sysmacros.h> <sys/time.h> <sys/timeb.h> <sys/timerfd.h> <sys/times.h> <sys/types.h> <sys/ucontext.h> <sys/uio.h> <sys/un.h> <sys/utsname.h> <sys/vfs.h> <sys/wait.h> <sys/xattr.h>. Where a C header also declares POSIX names (getline in <stdio.h>, strtok_r in <string.h>), <features.h> decides: they are declared unless the program asked for ISO C alone (-std=c11 with no _POSIX_C_SOURCE, _XOPEN_SOURCE, _DEFAULT_SOURCE, _BSD_SOURCE or _GNU_SOURCE), and the GNU and BSD ones (strchrnul, memrchr, clearenv, fopencookie) are hidden too when the program names a POSIX version and nothing more, as with glibc. In the default mode <string.h> also brings <strings.h>, and <stdlib.h> <alloca.h>, as glibc's do. The large-file names (open64, stat64, fopen64 ...) are the same calls, off_t being 64 bits already: macros under _GNU_SOURCE or _LARGEFILE64_SOURCE, and symbols for a program that declares its own.

Linux's own interfaces -- <sys/epoll.h> and the other descriptor kinds, <sys/syscall.h> and syscall, statfs, sysinfo, prctl, mounting, extended attributes, processor affinity, POSIX message queues and System V IPC -- are its system calls where the kernel is Linux. Elsewhere each fails with ENOSYS, unless it has a meaning the library can give without that kernel: sendfile and copy_file_range copy through a buffer, statfs comes from statvfs, close_range closes, locking memory where nothing pages already holds.

Every POSIX function is defined weak, so a program -- or an operating system's own support library linked beside this one -- may define any of them itself and its definition is the one used. C's names are strong.

<stddef.h>, <stdarg.h>, <stdbool.h>, <stdint.h> and <float.h> come from the freestanding directory, and so do C23's <stdbit.h> and <stdckdint.h>, which a program with no C library has too. <limits.h> defines the library's own limits (PATH_MAX 4096, NAME_MAX 255, ...) and includes the freestanding <limits.h> for the type widths.

Behavior worth knowing#

Formatted output. printf converts floating-point values exactly, by integer arithmetic on the binary value, so every precision is correctly rounded with ties to even (%.0f of 2.5 is 2). long double is converted at its own width. %a is exact and rounds a precision to nearest, ties to even; a subnormal is printed normalized with a leading 1. %b prints binary. A null %s prints (null) and a null %p prints (nil). %n stores into the type its length modifier names (%hhn a signed char, %jn an intmax_t). An unknown conversion prints itself. %lc and %ls take wide characters and write their UTF-8, a precision on %ls counting bytes and never cutting a character; one with no UTF-8, a lone surrogate, makes the call return -1 with errno EILSEQ.

Formatted input. scanf supports %[, %n, %a and hexadecimal floating-point input. It distinguishes an input failure (returns EOF) from a matching failure (returns the number of items assigned, possibly 0): sscanf("x", "%d", &n) returns 0. The character it reads ahead and does not use goes back to the stream: fscanf(f, "%d", &n) on 12x leaves the x for the next read. %lc, %ls and %l[ store the wide characters the input's UTF-8 decodes to.

Wide streams. fwprintf, fgetwc and the rest read and write a stream's bytes as UTF-8, a character at a time, so a FILE costs nothing more for being able to be wide. The first byte or wide operation on a stream fixes its orientation, as C11 7.21.2 says, and fwide reports it. ungetwc holds one wide character. A byte sequence that is not UTF-8, or a wide character with no UTF-8, is an encoding error: WEOF or -1, errno EILSEQ, and the stream's error indicator. The wide printfs count width, precision and %n in wide characters; swprintf returns -1 when the result does not fit, where snprintf returns the length it would have had. A byte printf with no %ls or %lc links none of this.

C23's 0b. strtol and its family with base 0 or 2, and scanf's %i and %b, read a 0b or 0B prefix in every language mode, as C23 does; a C17 program that parses "0b1" with base 0 gets 1, not 0. A prefix with no digit after it is not one: strtol("0xz", &end, 16) is 0 and leaves end at the x.

strtod. strtod, strtof and strtold are correctly rounded: the nearest value of the type, ties to even, for every input, each at its own precision -- a long double keeps the x87's 64 bits or binary128's 113. Hexadecimal input is rounded the same way, and its binary exponent is optional (strtod("0x1") is 1). scanf's floating conversions and wcstod give the same answers; scanf keeps a numeral's first 900 digits and reads the rest as one, which can matter only to a long double.

Buffering. BUFSIZ is 4096 and FOPEN_MAX is 32. stdout is fully buffered, or line-buffered when the backend reports it is a terminal; stderr is unbuffered. exit flushes every stream after running the atexit handlers.

atexit. atexit and __cxa_atexit share one list, so C handlers and C++ static destructors run in reverse order of registration, interleaved. The list holds 256 entries; registering more is reported on stderr.

malloc. First fit over an explicit free list, with coalescing, on a heap grown with the backend's sbrk. Every block is 16-byte aligned. aligned_alloc returns a block that free releases like any other. When the backend cannot grow the heap, malloc returns a null pointer with errno set to ENOMEM.

Math. The double-precision functions are Sun's fdlibm (kept verbatim in src/math/fdlibm/, about 1 ulp), plus log2, exp2, log1p, the inverse hyperbolics, lgamma, tgamma and erf. sqrt is the hardware instruction. The float forms compute in float, by newlib's conversions of the same functions (fdlibm/ef_*.c, kf_*.c, sf_*.c): within 1 ulp, and 2 for tanhf, log10f, cbrtf, log2f and exp2f, where computing in double was correctly rounded but cost a software double on a single-precision FPU -- sinf takes about 225 cycles on a Cortex-M4F where it took 25,000. sqrtf is the FPU's instruction where the target has a single-precision one. Where double is binary32 (RX), the double functions are these float ones. The long double forms of the functions that compute a new value (sinl, expl, powl, ...) compute in double, so on x86-64 they deliver 53 of the 64 significand bits; the functions that only move or inspect a value (fabsl, truncl, floorl, frexpl, ldexpl, fmodl, copysignl, ...) are exact at full width. The classification macros (fpclassify, isnan, isinf, isfinite, isnormal, signbit) read a long double in its own format, so isinf(LDBL_MAX) is 0 and a long double subnormal is FP_SUBNORMAL. nearbyint and rint follow the current rounding mode; remainder rounds the quotient to nearest, ties to even.

Complex. The exponential, logarithm, square root, power, and the trigonometric and hyperbolic functions with their inverses are FreeBSD's (src/math/msun/, by their authors' notices): every special value Annex G lists, and accuracy across the plane -- the inverse functions are Hull, Fairgrieve and Tang's algorithm, which keeps its digits beside the branch points. clog's real part is exact near |z| = 1, where log(cabs(z)) keeps none. The float forms compute in float; the long double forms compute in double (as above), except creall, cimagl, conjl and cprojl, which only take a value apart or put it back. CMPLX, CMPLXF and CMPLXL are the header's own and call nothing in the library.

Locale. There is one locale, "C". setlocale accepts "C", "POSIX" and "" and returns a null pointer for any other name. The multibyte encoding is UTF-8: overlong forms, surrogates and values above U+10FFFF are rejected. wchar_t is 32 bits on every target but Xtensa, where it is 16, as GCC has it; there a character past U+FFFF has no wide form, and its UTF-8 is rejected too rather than cut down to fit.

Temporary files. tmpfile creates its file under /tmp, named with twelve letters from the backend's entropy (or the clock, where there is none), opens it exclusively and for the owner only, and removes the name at once: the file lasts as long as the stream. tmpnam's names are under /tmp too, each one no file had when it was made. A target with no filesystem has no temporary files: tmpfile returns a null pointer.

Time. localtime follows TZ as POSIX writes it (CET-1CEST,M3.5.0,M10.5.0/3, with quoted names like <+0530>-5:30, Jn and n rules, and rule times past 24 hours or negative), or names a compiled zone file (Europe/Paris, :Europe/Paris) under TZDIR or /usr/share/zoneinfo, read whole: TZif versions 1 to 3, with the footer's rule for times after the last transition. With no TZ, /etc/localtime where there is one, UTC where there is not; a TZ that is neither is UTC named "UTC", as no error is possible. mktime reads tm_isdst as glibc does at the hours the clocks change: 0 or 1 chooses between the two meanings of an ambiguous time and moves a missing one by the hour that is missing. strptime is glibc's in the "C" locale, down to its readings of fields it leaves unsaid (tm_wday and tm_yday once a date is read, and the date from %U or %W with a weekday). Two choices differ from glibc 2.36: a rule applies before 1970 too, and where glibc reads past its month table (day 366 of a common year, week 0) the calendar is followed. time and clock return what the backend provides, which on the freestanding targets is -1.

Signals. Two models, one interface. Where the kernel delivers signals (Linux), sigaction installs the handler with the kernel, and signals arrive from outside: alarm, kill from another process, a child's SIGCHLD. Elsewhere the library keeps the table itself -- the handlers, a mask, a pending set -- and is the only sender: raise, and kill of the program's own id, call the handler; a blocked signal waits in the pending set and is delivered when it is unblocked; a signal at its default action ends the program as the default says. abort raises SIGABRT, and if a handler returns, resets it and raises again. The same test program passes under both (tests/exec/posix-signals.c).

What the operating system cannot do. A POSIX function whose primitive the backend has not got fails with ENOSYS, never with a made-up answer: on a board, fork is ENOSYS, and so is socket. sysconf answers -1 for what it cannot know rather than guess. The *at functions use the backend's own where it has them, and otherwise turn the directory descriptor back into a path. posix_spawn runs a program through the backend's spawn -- fork and exec on Linux, the kernel's spawn on EmbLinkOS -- and posix_spawnattr_setflags refuses with ENOTSUP a flag that spawn cannot honour, rather than a spawn that would ignore it.

Threads. pthread_create and thrd_create start a thread where the backend can (Linux and EmbLinkOS); elsewhere they fail (EAGAIN, thrd_error) and everything else still works with the one thread there is -- locks, once, keys. One implementation serves both spellings, so a C11 thread's tss_t is a POSIX key. Each thread's keys live in a record the library keeps for it, so no thread-local storage is needed beneath them. pthread_exit returns to the start of its thread and runs the keys' destructors there; frames it leaves are not unwound, so a C++ destructor between it and the thread's function does not run (as under musl). A thread's stack is the backend's: 8 MiB on Linux, mapped as it is used; pthread_attr_setstacksize is kept and reported, and pthread_attr_setstack is refused at pthread_create. Timed waits take an absolute time, POSIX's and C11's alike. thread_local is defined as _Thread_local.

Environment. getenv reads the vector the startup code publishes in environ. The first change copies that vector into the heap; the strings setenv makes are freed when they are replaced or removed, the startup vector's and putenv's never are (a putenv string IS the entry, and a later change to it changes the environment).

POSIX's choices. Where POSIX lets an implementation choose, this one chose glibc's answer, except: fmemopen refuses a size of 0 (POSIX lets it); open_memstream's length moves only when a write passes it, as POSIX says, so a seek to SEEK_END after rewriting the middle goes to the end and not to where the write stopped (glibc 2.36 differs); and dirname("//") is "//", as glibc's is.

Thread safety#

The library's shared state is locked. The heap has one lock; each FILE has its own, held for the whole of a call, so the output of one printf or puts is never interleaved with another thread's; the table of open streams has a third. A stream's lock nests: a thread that holds it with flockfile may still printf to the stream. The locks are futex-based: uncontended, locking and unlocking are one atomic instruction each. On a target whose backend has no futex the wait degrades to a yield, which is only reached when a lock is contended, and such a target has one thread.

errno is per thread on the Linux triples, where the C library sets up thread-local storage, and on EmbLinkOS, whose crt0 sets up the first thread's and hands the template over (lib/libc/os/tls-template.h) for the library to copy into every thread it starts. Elsewhere it is one variable. Functions that keep state between calls by definition (strtok, rand, gmtime, localtime, asctime, ctime) share it between threads; use the _r forms of the time functions.

Not provided#

glibc instead: --libc=system#

For a Linux target, --libc=system replaces this library with the system's own, glibc -- the way to POSIX threads, and to whatever else of glibc's this library has not got. EmbCC does what GCC does:

glibc's types are laid out as GCC lays them out: tests/golden/libc-system.sh compares 40 of them, pthread_mutex_t and struct stat among them, byte for byte with GCC's, and runs a threaded program on a Linux kernel. One difference does not cross a call: EmbCC's va_list is a pointer to the ABI's argument tag, 8 bytes where GCC's is the tag, and passing one to vprintf passes that pointer either way.

-static links glibc's libc.a, which needs GCC's libgcc.a and libgcc_eh.a; EmbCC takes them from the root's usr/lib/gcc/TRIPLE/N/ and says so when there are none. A C++ program is refused: EmbCC's C++ runtime is built on its own C library.

Backends#

Everything above is portable C. An operating system is reached through the 140 functions declared in lib/libc/os/backend.h, and one file per OS implements them. The C part is small:

C++'s <thread>, <mutex> and the other synchronization headers are built on the thread group, and <filesystem> on the filesystem group.

The rest, the second half of backend.h, is POSIX's: descriptors, the rest of the filesystem and its *at forms, directories, processes and spawn, signals, clocks and timers, mapped memory, the system's identity and limits, polling, sockets and the resolver, terminals. Each is shaped like the POSIX call it serves, and where a meaning needs a number (a flag, an fcntl command, a signal, an ioctl request, a socket address's layout) it is Linux's, which a backend whose kernel numbers it differently translates. All of it is optional: os/absent.inc defines each one as an ENOSYS failure, and a backend includes it after defining OS_HAS_name for each it implements itself. tests/golden/libc-backends.sh compiles every backend and fails if any of the 140 is missing from one, which would otherwise be a link error in the first program that called it.

Four backends exist:

A new operating system needs one new backend file and nothing else.

The C++ library: lib/libcxx#

The runtime#

lib/libcxx/src implements the Itanium C++ ABI runtime, what GCC calls libsupc++:

__cxa_atexit and __cxa_finalize are in the C library, beside exit. __cxa_vec_* are not provided; EmbCC lowers array new and delete itself. Function-local static initialization is thread-safe: a second thread waits for the first to finish, and recursive initialization of the same object traps.

Exceptions and the unwinder#

A throw reaches the unwinder through _Unwind_RaiseException, and every landing pad ends with _Unwind_Resume. Which unwinder that is depends on the target:

<unwind.h> in the freestanding directory declares the level-I unwinder interface (_Unwind_RaiseException, _Unwind_GetIP, ...) with the GCC extensions libsupc++ uses.

The standard library#

lib/libcxx/include is EmbCC's own standard library: 95 standard headers.

Not provided: <locale>, <codecvt>, <strstream>, <ciso646>, <cstdbool>, <cstdalign>, <ctgmath>, <ccomplex>, and the C++23 headers (<expected>, <print>, <stacktrace>, <spanstream>, <flat_map>, <flat_set>, <mdspan>, <generator>, <stdfloat>). <thread> and the other concurrency headers create threads only where the C library's backend can; elsewhere std::thread's constructor throws std::system_error. The language level EmbCC accepts is described in C++.

lib/libcxx/include/__tree and __hash are internal: the red-black tree shared by <map> and <set>, and the hash table shared by <unordered_map> and <unordered_set>.

The compiler runtime: lib/rt#

Contents#

lib/rt holds the routines generated code calls instead of an instruction. No program names them; the backend does. They use libgcc's names and calling conventions, so EmbCC objects link against libgcc and GCC- or Clang-compiled objects link against librt.a. Every file is compiled for every target and compiles to an empty object where it does not apply.

On the ARM hard-float triples the helpers keep the base (core-register) calling convention, as the ARM run-time ABI requires. Conversions from a floating-point value too large for the integer type saturate. The routines are written so that none uses the operation it implements: a 128-bit value is only ever taken apart into 64-bit halves, and the software floating point works on the bit patterns.

unwind.c finds the unwind tables through the symbols __eh_frame_start and __eh_frame_end, which EmbLD defines for the .eh_frame section and lib/libc/os/linux/link.ld defines for a GNU link. It scans the FDEs linearly; there is no .eh_frame_hdr search table. CFA rules given as DWARF expressions are refused rather than guessed.

When a routine is missing at link time, EmbLD says what it is:

embld: undefined symbol '__divdi3' (referenced by main.o)
  note: this is a compiler-runtime helper (libgcc's __muldi3 family) — the routine a backend calls for an operation the machine has no instruction for, such as 128-bit multiply or divide. EmbCC ships these in librt.a (lib/rt); the driver puts it on the link line by itself, and a hand-written link has to name it after libc.a

The same kind of note is given for the conversion routines (__fix*, __float*, __trunc*, __extend*) and for the unwinder's symbols.

Per-target archives#

Each librt.a holds complex.c, half.c, powi.c, clear_cache.c and embtrace.c, and all but Darwin's builtin-setjmp.c; beyond those:

Building the libraries#

All libraries are compiled by ./embcc from the same tree, so build the compiler first (make embcc). Each rule rebuilds its archive from scratch.

The archiver is a cross ar: x86_64-elf-ar and aarch64-elf-ar by default, overridden with EMBCC_X86_AR and EMBCC_AARCH64_AR. tools/build-rt.sh uses llvm-ar, or EMBCC_AR, or ar when neither is found, and EMBCC names the compiler it runs.

make install PREFIX=DIR builds all of the above except libc-emblinkos and installs them; make install-files only copies. Each triple's files go to PREFIX/lib/embcc/VERSION/TRIPLE/, the Linux triples also get link.ld there, and the headers go to PREFIX/lib/embcc/VERSION/include, include/c++ and freestanding. The EmbLinkOS C library is not installed. See Getting started.

Linking a Linux program by hand#

The driver links x86_64-linux-gnu programs itself. For aarch64-linux-gnu, or to add objects, link with a GNU-compatible linker and the installed script, which keeps the program headers inside the first loadable segment (the C library finds thread-local storage through them):

embcc --target=aarch64-linux-gnu --opt=speed -c prog.c -o prog.o
aarch64-elf-ld -static -T link.ld -o prog crt1.o prog.o libc.a librt.a

All four files are in the triple's library directory.