Status and known limitations#

This page is a snapshot of what EmbCC supports and what it does not: how complete each target is, which language features, attributes, builtins and options it refuses (with the exact diagnostic for each), where its calling conventions differ from the platform's, which defects are known, which optimizations GCC and Clang perform that EmbCC does not, and how to report a bug. It is for anyone deciding whether EmbCC can build their code, and for people changing EmbCC who need the list of open work. The per-target reference is Targets; the language levels are in C language and C++ support.

Summary#

• x86-64 and AArch64 ELF (bare metal, EmbLinkOS, Linux) are the complete targets: C and C++ with exceptions, the full optimizer, register allocation, DWARF debug information, and EmbCC's own C, C++ and compiler-runtime libraries. Linux programs are static images. embld links x86-64; AArch64 objects need another linker.
• The embedded targets -- Cortex-M (ARMv6-M to ARMv8-M), ARMv7-A, RISC-V (RV32 and RV64), MIPS32 and MIPS64, LoongArch64, Xtensa, TriCore, PowerPC, RX, SPARC, ColdFire and AVR -- are bare-metal targets with EmbCC's compiler runtime, C library (on AVR, lib/avr's smaller one), assembler and linker. C++ compiles on every one but AVR, without exceptions, and the 32-bit ones have a C++ runtime (make libcxx-embedded).
• Apple arm64 and macOS x86-64 compile C and C++ for the system linker, and the result runs natively. -g is accepted and writes no debug information yet.
• Windows x86-64 produces COFF objects that are not yet compatible with the Microsoft x64 ABI. EmbCC warns on every such compile.

What each target compiles, construct by construct, is in What each target compiles: a page generated from the compiler's own answers and checked against it by tests/golden/limits.sh, so it cannot drift as this page did.

How EmbCC refuses#

A construct EmbCC does not implement is an error that names it. EmbCC does not compile an unsupported construct into code that does something else. The exceptions to that rule, where something is accepted and silently has a different effect, are listed under Known defects.

A diagnostic has this form:

embcc: FILE:LINE:COL: error: MESSAGE

Some diagnostics carry no column, and those about the command line carry no file (embcc: error: MESSAGE). The tables on this page quote MESSAGE. Names such as f, x, g and 'd' in a quoted message stand for the function, variable or type in your program.

A backend that cannot lower an operation names itself, the operation and the IR instruction:

embcc: f.c:3: error: the ARMv7-M backend cannot lower __builtin_frame_address or __builtin_return_address (this backend keeps no frame-pointer chain) yet (function f) [frameaddr w=8 size=4]

The backend names are ARMv7-M (every Cortex-M target), RV32, RV64, MIPS32, LoongArch64 and AVR.

An attribute EmbCC does not know is a warning, not an error, and is ignored (see Attributes).

Targets#

The register allocator is described in Register allocation, the passes and their target dependencies in The optimizer, the libraries in Libraries, and how each target is tested (QEMU boards, a Linux kernel, native macOS runs) in Testing. What the Darwin and Windows targets refuse is listed under ABI limitations.

Linking#

The driver links x86-64 ELF programs and, for the embedded targets, images whose memory map the build gives: a linker script (-T, on ARM, RISC-V, AVR and MIPS32) or -Wl,-Ttext/-Tdata (on every one). A firmware link without one stops with embcc: error: linking a TRIPLE image needs its memory map. Every other target (AArch64 ELF, Mach-O, COFF) stops with embcc: error: cannot link for TRIPLE, because embld does not read those objects. AArch64 objects are refused by embld with:

embld: FILE: a 64-bit object for machine 183; only x86-64, RV64 (EM_RISCV), LoongArch64 (EM_LOONGARCH) and MIPS64 (EM_MIPS) are supported

The driver compiles several sources in one command by running itself once for each (-j N at a time), on a host that can run a program (macOS, Linux). A build with PROCESS=none -- EmbLinkOS, which has no fork/exec -- compiles one source per command and refuses a second:

embcc: error: more than one source file ('a.c' and 'b.c'), and this host cannot run a compiler for each (EmbCC was built with PROCESS=none): compile each with -c and link the objects (embcc a.o b.o -o OUT)

embar is EmbCC's archiver (ar and ranlib); the library builds use it.

There is no position-independent code, no shared library and no dynamic linking. -fPIC, -shared and the related options are refused (see Options). EmbLD reads GNU ld linker scripts (embld -T) for ARM, RISC-V, AVR and MIPS32 images, not yet for the other targets:

embld: -T: a linker script is supported for ARM, RISC-V, AVR and MIPS32 images only (this one is machine 62)

Where it reads one, the driver links firmware with them (embcc -T board.ld a.o b.o -o fw.elf). --gc-sections drops the sections nothing reaches, on every machine, for objects built with -ffunction-sections -fdata-sections; -Map and --print-memory-usage report the layout as ld does.

Assembly#

Any other instruction in a file-scope asm block is refused. On x86-64:

file-scope asm instruction not supported: "movq %rdi, %rax" (EmbCC assembles .global/labels/.byte/.long/.quad and and/call/jmp/ret)

On Apple arm64, every instruction in a block is refused, including the four that x86-64 accepts, because the Mach-O writer takes no relocation type from an assembler:

file-scope asm instruction "ret": EmbCC assembles a block's instructions on x86-64 (a few) and on every ELF target, not yet into Mach-O objects. On this target write the block as .byte/.long data (see lib/libc/src/setjmp).

Inline asm inside a function is assembled on every target; its vocabulary is in Inline assembly.

On MIPS32 a .S file, a file-scope block, a naked function and an inline-asm template start in .set reorder mode, as with GNU as, GCC and clang: the assembler puts a nop in each delay slot unless the code says .set noreorder.

Thread-local storage#

__thread and _Thread_local use the local-exec model on x86-64 and AArch64 ELF (R_X86_64_TPOFF32, R_AARCH64_TLSLE_*). On the embedded targets a thread-local object is placed in .tbss or .tdata but addressed with ordinary absolute or PC-relative relocations, so there is one instance, not one per thread. On Darwin and Windows it is refused (see ABI limitations).

Target-specific refusals#

Which constructs each target refuses -- __int128, long double, _Float16, the atomics of each width, the frame builtins, C++ and its exceptions, -S, -g, unwind tables and the rest -- is the generated page What each target compiles, with the message for each. Beyond those:

Each target's other refused options are listed in its section of Targets.

Runtime libraries#

• EmbCC ships a C library for x86_64-elf, aarch64-elf, both Linux triples and EmbLinkOS, and a C++ library for the x86-64 and AArch64 ELF triples (make libc, make libcxx, make libc-linux).
• For the embedded targets, make rt-embedded builds the compiler runtime (librt.a) for every triple, and make libc-embedded the C library for every one but AVR, whose library is lib/avr's (<avr/pgmspace.h>, <avr/eeprom.h>, a small printf and the string functions). make libcxx-embedded builds the C++ runtime (operator new, the guards, RTTI) for the 32-bit ones; RV64, little-endian MIPS64 and LoongArch64 have none.
• The runtime routines have libgcc's names (__divdi3, __addsf3, __multi3, ...), and on ARM the run-time ABI's __aeabi_* routines as well.
• On Linux, time functions enter the kernel on every call (the vDSO is not used), and the file-status functions use statx, so they need Linux 4.11 or later.

C language features#

EmbCC compiles one C dialect, with the GNU extensions and many C23 features; C language describes what is supported. This section lists what is not.

Types#

_Float128 is accepted where long double is binary128 (AArch64 ELF, RISC-V).

Declarations, statements and expressions#

Implicit int and implicit function declarations are errors, as C99 requires. Trigraphs are not replaced.

Preprocessor#

#pragma pack is the only pragma EmbCC acts on, in either the directive or the _Pragma form. Every other pragma is ignored without a diagnostic, including #pragma once; see Known defects. The C23 unreachable() macro is not defined by <stddef.h>. __STDC_VERSION__ is 201710L whatever -std= says.

Attributes#

These attributes would change the generated code in a way EmbCC does not implement, so they are errors:

error and warning are accepted with a warning that the check they request will not happen:

warning: __attribute__((error)) is accepted but does nothing here: it makes a CALL to this function a compile error unless the optimizer removes the call, so the diagnostic has to wait until after optimisation and EmbCC issues its own before then; a build-time assertion written with it will not fire [--warn=attributes]

An attribute EmbCC does not know is ignored with a warning:

warning: attribute 'no_such_attribute' is not one EmbCC knows, and is ignored [--warn=attributes]

A further set of attributes (hot, cold, pure, const, nonnull, flatten, optimize, returns_twice and others) is accepted and has no effect, because what it asks for is either already true or used only by an analysis EmbCC does not have. The source table in src/parse/parse.c gives the reason for each. For returns_twice the reason is compatibility with newlib's <setjmp.h>; the source notes that ignoring it can be wrong above -O0, where a value kept in a register across the call may not survive the second return.

Builtins#

A builtin EmbCC does not provide is an undeclared function:

error: '__builtin_cpu_supports' is not declared in 'f' — for a call, add a prototype or define it first [E0001]

__has_builtin answers 0 for these. Among the GCC and Clang builtins that are missing:

• __builtin_va_arg_pack.
• Vector builtins: __builtin_elementwise_*, __builtin_reduce_*, __builtin_nontemporal_load (__builtin_shufflevector is provided).
• Target builtins: __builtin_cpu_supports, __builtin_cpu_init, __builtin_ia32_*; on AVR __builtin_avr_flash_segment and the fixed-point ones.

Code generation#

C++#

C++ is compiled by lowering it to C (D-013). Its status feature by feature is in C++ support. By target:

Language refusals:

Two-phase name lookup is not implemented: a template is parsed again at each instantiation, so a non-dependent name is looked up at the point of instantiation. Several ill-formed constructs are accepted without a diagnostic. Both are described in C++ support.

ABI limitations#

Windows#

Every compile for x86_64-windows-gnu (or its alias x86_64-w64-mingw32) prints this warning. It is on by default and -Wno-windows-abi silences it:

embcc: f.c: warning: x86_64-windows-gnu is not yet the Microsoft x64 ABI: `long` is 8 bytes and wchar_t 4 (Windows has 4 and 2), and rsi, rdi, xmm6 and xmm7 are not preserved across a call: objects EmbCC compiles agree with each other and with nothing else [--warn=windows-abi]

Argument registers, shadow space, by-reference passing of aggregates and the Microsoft va_list are implemented; see Windows. No program built for this target has run on Windows, and EmbCC provides no C library for it. These are refused:

Darwin#

Both Darwin triples produce Mach-O objects for the system linker. aarch64-apple-darwin follows Apple's arm64 convention and data model, and x86_64-apple-darwin follows System V; see Apple arm64. These are refused:

EmbCC compiles against its own C headers on Darwin too. They declare stdin, stdout and stderr as objects of those names and make errno a call to __errno_location; the macOS C library defines none of these, so a program that uses them does not link with the system library. The macOS SDK headers do not compile with EmbCC: sys/cdefs.h stops with #error Unsupported architecture, because EmbCC does not predefine __arm64__. Calls to C library functions declared in EmbCC's headers, such as printf, link and run.

Embedded targets#

• Cortex-M objects carry .ARM.attributes, and embld refuses to link objects whose float ABI (Tag_ABI_VFP_args) or enumeration size (Tag_ABI_enum_size) disagree. An enumeration is int-sized unless one of its values does not fit in int, as with Clang, or the smallest type that holds its values under -fshort-enums or __attribute__((packed)). EmbCC's libc and librt say nothing about enum size (-fenum-size-neutral) and link with both.
• On AVR, structures are passed and returned by avr-gcc's documented rules. Clang's AVR target passes structure arguments differently.
• MIPS32 objects carry .MIPS.abiflags (soft float), and embld refuses to link objects whose floating-point ABI disagrees. EmbCC's objects and clang's (--target=mipsel-unknown-elf -msoft-float) call each other correctly in both directions (tests/golden/mips-abi.sh), including clang's _Complex results in v0..a1; clang's PIC and small-data objects (-fPIC, -mno-abicalls -G8) are refused by embld by relocation name.
• C++ on the 32-bit embedded targets follows the Itanium C++ ABI's 32-bit form, with the ARM C++ ABI's changes on ARM; C++ is refused on AVR, whose int and pointers are 16 bits (see C++).

Options#

The options below are refused, each with the message shown. The full list, with the options that are accepted and have no effect, is in Invoking EmbCC.

These are unknown arguments (embcc: error: unknown argument '-march=native', followed by the usage summary): -march=, -mtune=, -m32, -m64, -mabi= on x86-64, AArch64 and AVR, -mavx2 and the other x86 feature flags; -imacros, -iquote, -idirafter, -undef; -ansi; -ffp-contract=, -funroll-loops, -ftrapv, -fvisibility=, -fopenmp; -v. The flags GCC builds for Cortex-M pass (-ffast-math, -fcommon, -fno-jump-tables, -save-temps, -specs=, -mabi=aapcs and the rest) are accepted, implemented or refused as Invoking EmbCC lists.

-Wl,OPTION and -Xlinker OPTION reach the driver's link. EmbLD's own options (-T, -L, -u, -e, -Ttext, -Tdata, -Tstack, --rom-limit, --lma-offset, --orphan-handling, --gc-sections, --print-gc-sections, -Map, --print-memory-usage) are applied, a set that changes nothing about the image (-s, -z now and others) is accepted, and any other is refused before anything is linked:

embcc: error: linker option '-T' is not one EmbLD has (it takes -e, -Ttext, -Tdata, -Tstack, --rom-limit and --lma-offset); dropping it could build a different image from the one asked for

-Wa,OPTION accepts --noexecstack, -g, --gdwarf* and -mrelax and refuses any other (embcc: error: assembler option '-al' is not one the integrated assembler has). The full rules are in Invoking EmbCC.

-pedantic and -pedantic-errors report what the -std= standard does not have, for C and C++ (Invoking EmbCC).

Any -W name that is not one of EmbCC's warnings (--help-warnings lists them) is accepted with:

embcc: warning: -Wcast-align is not a warning EmbCC has, so it turns nothing on (--help-warnings lists them)

-std= selects the language, C89 to C2y and C++98 to C++26, as GCC does (Invoking EmbCC).

Known defects#

These are cases where EmbCC accepts something and does not do what was asked, without an error. Each is a defect, not intended behavior.

• Pragmas. pack, once, push_macro, pop_macro and weak have an effect. Every other pragma is dropped without a diagnostic, and there is no -Wunknown-pragmas. In particular, #pragma GCC diagnostic does not change any warning, #pragma GCC poison poisons nothing, and #pragma redefine_extname does not rename the symbol.
• Debug information. On AVR, -g produces a compile unit with no functions, variables or line-table rows. Enumerations, typedef names and lexical blocks are not described on any target. The full list is in Debugging.

Optimizer gaps#

The optimizer is described in The optimizer and the user-visible levels in Optimization. These are the transformations GCC and Clang make that EmbCC does not, as the source states them:

• No machine-level IR. Instruction selection writes machine code directly from EmbIR (embcc inspect mir says so). There is no instruction scheduling and no machine-level optimization pass.
• SSA only inside one pass. EmbIR is linear three-address code. mem2reg builds SSA form and immediately leaves it again, turning each phi into copies; every other pass works on the non-SSA form and recomputes the control-flow and data-flow facts it needs.
• Alias analysis by base object only. Two references based on different objects do not alias, and an unknown pointer cannot reach a stack slot whose address is never taken. There is no type-based aliasing (so -fstrict-aliasing changes nothing), no use of restrict, and no field sensitivity.
• Interprocedural optimization is limited to one translation unit: inlining, inference of which functions read or write memory a caller can see, and replacing loads from a static global that nothing in the unit writes with its value. There is no link-time optimization, and no call is ever eliminated: two calls to a const or pure function stay two calls.
• The inliner declines a callee that is not defined in the unit, is variadic, recursive, noinline or too large for the budget, has exception regions, returns a structure or a value wider than a register, takes a parameter that is not a simple scalar, contains inline asm, va_start, a variable-length array or a computed goto, computes in __int128, or calls a function that returns a structure. -fremarks names the reason at each call (remark: not-inlined 'g' [inline/callee-is-varargs]).
• Vectorization is done on x86-64 only, and not at -Os. A floating-point sum reduction is not vectorized, because that would change the order of the additions; there is no option that permits it.
• Division by a constant becomes a multiply only on 64-bit targets. On Cortex-M the hardware divide is used; on AVR it is a library call.
• No profile-guided optimization: -fprofile-* is refused, and hot and cold do not affect code placement.
• No fast-math mode. Floating-point arithmetic is not reassociated or contracted into fused multiply-adds.
• Functions with exception regions or computed goto. The passes that need a complete control-flow graph are skipped in a function with live exception regions, and the passes that place code on an edge are skipped in a function with goto *. On x86-64 and AArch64 such a function keeps every value in memory; the other backends allocate registers in it, the allocator giving goto *p an edge to every label whose address is taken.
• -O3 is -O2. -Og is -O1 with every source variable kept in its stack slot.

Milestones#

The project's original milestones, and their state:

Roadmap#

The releases up to 1.0.0, and what each must achieve, are in the roadmap. These are the open items in the code that it schedules, each checked against the compiler when this page was last audited:

• Position-independent code, shared libraries and dynamic linking.
• embld: linking AArch64 objects, and GNU linker scripts on the targets other than ARM, RISC-V, AVR and MIPS32.
• Debug information, thread-local storage and constructors in Mach-O and COFF objects; the Microsoft x64 data model and callee-saved registers; .pdata/.xdata unwind tables for Windows.
• GNU-syntax assembly files for x86-64; on AArch64, an assembler for the whole instruction set (its vocabulary is the kernel's), and blocks in Mach-O objects.
• Unwind tables, and so C++ exceptions, on every target but x86-64 and AArch64.
• __attribute__((interrupt)) on ARMv7-A, MIPS64, LoongArch64, Xtensa, TriCore, PowerPC, RX, SPARC and ColdFire; GCC's MIPS use_shadow_register_set and use_debug_exception_return.
• A _Float16 through ..., and a struct of them by value with the ARM or RISC-V hard-float convention; asm goto, nested functions, and sixteen-byte atomics off x86-64 and AArch64 (see What each target compiles).
• On MIPS32, a delay slot filled from anywhere but the instruction just before the transfer (the branch target's first instruction, or one from before the slt a compare-and-branch needs).
• Linker relaxation: on RISC-V a call between sections stays an eight-byte auipc/jalr.
• A machine-level IR below EmbIR; SSA as the form of EmbIR between passes; alias information on memory references (types, restrict, fields).
• Vectorization on targets other than x86-64.
• Reading the vDSO on Linux.
• The C++ items marked "not supported yet" above and in C++ support.
• M4 on EmbLinkOS.

Reporting a bug#

Is it a bug?#

• An error that says something "is not supported" is a limitation listed on this page, not a bug.
• These are bugs: an internal error (EmbCC adds note: this is a bug in EmbCC, not in the program being compiled), a crash, a program that compiles and computes a wrong result, an object that another toolchain's assembler, linker or debugger rejects, a construct that is accepted and silently ignored or changed, and a disagreement with GCC or Clang about a calling convention or a data layout that the target's ABI defines.

Narrowing it down#

• Compile at -O0, -O1 and -O2. A failure only at -O2 points at the optimizer or the register allocator.
• Turn off one pass at a time with -fno-NAME (for example -fno-gcse); the names are in Optimization.
• Set EMBCC_VERIFY=1. The optimizer then checks the IR before and after it runs and stops at the first inconsistency.
• embcc inspect ir -O2 FILE prints the IR the backend receives, and -fremarks reports what the optimizer did and declined to do.
• Reduce the program to the smallest file that still fails.

What to include#

• The first line of embcc --version, and the host system.
• The complete command line, including --target=, or the output of -dumpmachine with the same options.
• The source, preprocessed with the same options (embcc -E OPTIONS FILE.c > FILE.i), or the reduced file.
• The complete output of the compiler.
• What you expected and what happened. For a calling-convention or layout problem, the other compiler, its version and its command line.

Report it as an issue in the EmbCC repository, https://github.com/EmbLinkOs/EmbCC/issues.

A fix comes with a test that fails without it; see Testing. A construct that EmbCC should refuse is added to tests/compile/reject-unimplemented.sh (A refusal test).