EmbCC documentation#

EmbCC is a C and C++ compiler for embedded systems, and the Emb toolchain is everything around it: the assembler, the linker, the debugger, the simulator, the flash programmer, the tracer, and the tools that size, pack and analyse firmware. It targets 12 families of embedded processors, from 8-bit AVR to 64-bit RISC-V, and also builds operating systems and hosted programs on x86-64 and AArch64. This documentation has two parts: the manual is for people who build software with the toolchain, and the internals reference is for people who change it.

Using EmbCC#

Start with the overview and getting started.

Page	Covers
Overview	What EmbCC is, its components, the targets at a glance
Getting started	Building and installing, first programs, cross builds
Invoking EmbCC	How the command line works, and each option in detail
Option reference	Every option, EmbCC's spelling and GCC's (generated)
Migrating from GCC	Switching a GCC build to EmbCC, and what differs
Targets	Triples, `-m` options, data models, ABIs, predefined macros, object formats
Target list	Every `--target`, what it runs on, and its data model (generated)
What each target compiles	27 constructs on 25 targets: compiled, warned or refused, and the message (generated, checked by a test)
C language support	`-std=`, and the status of each C89–C23 feature
Implementation-defined behavior	EmbCC's choices, in C17 Annex J.3 order
Language extensions	GNU and Clang extensions, attributes, builtins, pragmas
Inline assembly	Extended asm, and the constraints and modifiers of each target
C++ support	What the C++ front end accepts
Diagnostics	The diagnostic format, warnings, `--explain`, JSON output
Warning reference	Every warning, what it diagnoses, what turns it on (generated)
Optimization	`-O` levels and `-f` options
Debugging	`-g`, DWARF, and debugging programs
Bare-metal programming	Freestanding programs on the boards
Libraries	The C library, the C++ library, the compiler runtime

Tools#

Tool	Page
`embld`	The linker
`embas`	The NASM-syntax assembler
`embar`	The archiver
`embsvd`	A device's header, startup and linker script from its SVD file
`embmap`	Where an image's flash and RAM go: sections, regions, symbols, files, two builds
`embpack`	A linked image as bin, Intel HEX, S-records or UF2, with a CRC and a manifest
`embrt`	The worst-case stack of each entry point and interrupt, proved from the compiler's frames and call graph
`embsim`	A simulator (Cortex-M, RISC-V, AVR): run an image without a board
`embflash`	An image put into a target through the GDB remote protocol: QEMU, OpenOCD, pyOCD, J-Link, Black Magic Probe
`embtrace`	Function-level tracing on the target: calls, times, the call tree and a Perfetto trace, from -finstrument-functions
`embdbg`	The debugger
`embread`	The EMBX image reader
`embls`	The language server
`embidx`	The cross-unit interface index
`.ebm` manifests	EmbBuild manifests

EmbCC internals#

Start with the architecture and the contributing guide.

Page	Covers
Architecture	The pipeline from command line to object file, and the source tree
Front end	Preprocessor, lexer, parser and semantic analysis
EmbIR	The intermediate representation and its text form
Optimizer	The passes, their order, and what each may assume
Register allocation	The shared allocator and each target's use of it
Back ends	Code generation for each target
ARMv6-M plan	What a Cortex-M0 code generator needs from the Thumb backend, and the order to build it in
Object files	ELF, Mach-O, COFF and EMBX writers
Linker	How `embld` resolves, lays out and relocates
EmbSim	The simulator's modules and interfaces, its GDB server, and how to add a core, a peripheral or a board
Testing	The test suites, the boards, and how to add a test
Contributing	Conventions, the review checklist, commit style
Design decisions	The decision record (D-001 …)
Status	Per-target maturity and known limitations
Roadmap	What 1.0.0 will promise, and the releases on the way there
Porting to a new host	Running EmbCC on another OS: the platform layer, `PLATFORM=iso`, building it