TinyCC for ARMv8-M — Tiny C Compiler fork for ARMv8-M (Cortex-M33, Cortex-M23)
=================================================================================
This is a fork of the Tiny C Compiler (TCC) by Fabrice Bellard, modified for
**ARMv8-M architecture** with a custom IR, register allocator, and Thumb-2
code generator.
Differences from Original TinyCC
--------------------------------
**1. Target Architecture**
Original TCC targets x86/x86_64/aarch64/riscv64 on desktop/server OSes.
This fork targets **ARMv8-M** microcontrollers (Cortex-M33, Cortex-M23, etc.)
with the Thumb-2 instruction set.
**2. Custom IR (Intermediate Representation)**
The original TCC uses a simple, direct translation to machine code. This fork
introduces a **three-address code IR** with explicit register operands, enabling
a separate front-end and back-end, and an SSA form built on top of it.
Public interface: `source/ir/tccir.h`; construction in `source/ir/gen/`.
**3. Optimizer**
Upstream TCC does not optimize. This fork carries a full optimizer under
`source/opt/`, driven by a pass pipeline table (`source/opt/engine/`) with two
phases — flat-IR peepholes/fusion (`opt/flat/`) and SSA passes (`opt/ssa/`) —
plus alias and def-use analysis, pre/post-RA passes, and a declarative pass DSL
(`opt/framework/`). `-O1` does scalar cleanup, ARM addressing-mode fusion,
constant/range propagation, loop rotation and light inlining; `-O2` adds the
heavy tier (loop unrolling, IV strength reduction, LICM, re-rolling, MUL+ADD→MLA
fusion, interprocedural constant propagation, full small-function inlining).
**4. Register Allocation**
An **SSA register allocator** (`source/ir/regalloc.c`, parameterized by
`RegAllocTarget`) with a linear-scan core (`source/machine/tccls.c`) performs
liveness analysis and assigns physical registers, including the VFP bank. The
original TCC uses a simpler approach without liveness analysis.
**5. Code Generation**
Instead of x86 code generation, this fork generates **Thumb-2 machine code**
via `source/backend/arch/arm/thumb/`: `arm-thumb-gen.c` drives the per-opcode
`thop_*.c` encoders (ALU, memory, branch, DSP, coprocessor, VFP, exclusive
access, …), which walk instruction variants narrow→wide and pick the first
whose constraints hold. Covers the ARMv8-M instruction set including DSP
extensions.
**6. Floating Point**
Hardware floating point is supported: VFP single-precision codegen, the full
AAPCS-VFP hard-float ABI, and inline RP2350 DCP sequences for `double`.
See the *Floating Point* section below for flags, coverage and limits.
**7. Library Mode**
Can be used as `libtcc.a` for **JIT compilation** in host applications.
**8. ARM-Specific Features**
- ARM Procedure Call Standard (AAPCS/AAPCS-VFP) support
- ARMv8-M EABI helper functions
- ARM assembler parser for inline assembly
- ARM-specific ELF linking (`source/backend/arch/arm/arm-link.c`)
**9. YAFF Output for YasOS**
Besides ELF, the linker emits **YAFF** (`source/obj/tccyaff.c`), a flat
position-independent module format for the YasOS loader, selected with
`-Wl,-oformat=yaff` (executables and shared libraries alike). The YasOS target
also defaults to PIC with text/data separation, shared read-only `.rodata`, and
SB-relative GOT addressing — `-no-share-rodata` and `-mno-sb-relative-got` opt
back out.
**10. Self-Hosting on Target**
The compiler builds for ARMv8-M itself and runs on-device under YasOS, so the
same sources produce both the host cross compiler and an on-target compiler
(`tests/selfhost/`).
**11. Runtime Library**
Includes a custom runtime library (`libtcc1`) with ARM EABI helpers in
`lib/armeabi.c` and `lib/armv8m_eabi.c`.
Project Structure
-----------------
All compiler code lives under `source/`, one directory per module. Each module
owns its headers, carries its own `Makefile` and builds to its own static
library; the top-level `Makefile` links them into `armv8m-tcc`. The repo root
holds only build inputs, generated headers and project metadata.
```
.
├── source/ # Compiler sources (one module per directory)
│ ├── include/ # tcc.h (umbrella header), tcctypes.h
│ ├── driver/ # tcc.c (CLI), libtcc.c (TCCState/options/driver), tcctools.c
│ ├── frontend/ # tccpp.c (preprocessor), tccasm.c (GAS asm), svalue.c
│ │ └── gen/ # Parser, type checker, IR emission (the former tccgen.c)
│ ├── ir/ # Target-independent IR
│ │ ├── tccir.h # Public IR interface (opcodes, builder)
│ │ ├── gen/ # IR construction (arith, control, float, params, vla, ...)
│ │ ├── cfg.c ssa.c # CFG and SSA form
│ │ ├── codegen.c # Two-pass dispatch (dry-run + real-run) to backend _mop handlers
│ │ ├── regalloc.c # SSA register allocator (parameterized by RegAllocTarget)
│ │ └── vreg.c stack.c # Virtual registers, stack frame layout
│ ├── opt/ # Optimizer
│ │ ├── engine/ # Pass registry, pipeline table, pass timing
│ │ ├── flat/ # Flat-IR passes (cfg, dce, fusion, loop, memory, scalar, ipa)
│ │ ├── ssa/ # SSA passes (cfg, dce, loop, memory, scalar, string)
│ │ ├── analysis/ # Alias analysis, def-use chains, memory SSA
│ │ ├── ra/ # Pre/post register-allocation passes
│ │ └── framework/ # Declarative pass DSL
│ ├── machine/ # Backend boundary: tccls.c (linear scan), tccmachine.c, tccabi.h
│ ├── backend/
│ │ ├── arch/arm/ # arm.c, arm_aapcs.c, arm-link.c, arm_regalloc.c, ssa_opt_arm.c
│ │ │ └── thumb/ # arm-thumb-gen.c, arm-thumb-asm.c, thop_*.c encoders
│ │ ├── arch/fpu/ # FPU capability descriptions
│ │ └── generators/ # Target-independent generator helpers
│ ├── obj/ # tccelf.c, tccld.c, tccyaff.c (YAFF), tccdbg.c (DWARF/STABS)
│ ├── support/ # tccdebug.c (gdb printers), logging, debug-env knobs
│ ├── memory/ # vector.c, unique_ptr.c, container headers
│ └── utils/ # Header-only helpers
│
├── lib/ # Runtime library sources (libtcc1)
│ ├── libtcc1.c # Core runtime functions
│ ├── armeabi.c # ARM EABI helpers
│ ├── armv8m_eabi.c # ARMv8-M EABI specific
│ ├── builtin.c # Freestanding builtin fallbacks
│ └── fp/ # Floating point libraries (see Floating Point)
├── include/ # Headers shipped with the compiler
│
├── tests/
│ ├── ir_tests/ # Primary suite: compile + run under QEMU (pytest)
│ ├── unit/ # Host unit tests for individual passes (make ut)
│ ├── thumb/armv8m/ # Thumb-2 encoder tests
│ ├── frontend/ linker/ # Per-subsystem pytest suites
│ ├── debug/ runtime/ # "
│ ├── selfhost/ # The compiler compiling itself
│ ├── gcctestsuite/ # GCC torture tests (fetched on demand)
│ ├── benchmarks/ # Performance, code size, FP conformance
│ ├── fuzz/ # Fuzzing and divergence triage
│ └── tests2/ pp/ # Upstream legacy suites
│
├── scripts/ # Bisect, reduce, disassembly diff, container runner
├── metrics/ # Code size / performance tracking, Grafana dashboards
├── docs/ # Design documents and plans
│
├── configure # Configuration script
├── Makefile # Top-level build rules (module Makefiles under source/*)
├── config.h / config.mak # Generated configuration
└── tcc-doc.texi # Texinfo documentation source
```
Build
-----
```bash
# Configure
./configure [options]
```
Frequently used `./configure` options:
| Flag | Description |
|------|-------------|
| `--enable-cross` | Build the ARMv8-M cross compiler (`armv8m-tcc`) |
| `--enable-O0` … `--enable-O3`, `--enable-Os`, `--enable-Og` | Optimization level TCC itself is built with (`-O2` default) |
| `--disable-asan` | **AddressSanitizer is ON by default**; disable it for fast or production builds |
| `--enable-ubsan`, `--enable-lsan` | Additional sanitizers |
| `--debug` | Include debug info in the resulting binaries |
Example:
```bash
./configure --enable-cross --disable-asan
make cross
```
Run `./configure --help` for the full list.
```bash
# Build ARMv8-M cross compiler
make cross
# Build everything including FP libraries
make cross fp-libs
# Run the full test suite
make test -j16
```
Two build-time knobs affect what ends up in the binary:
| Variable | Effect |
|----------|--------|
| `make cross CONFIG_minimal=yes` | Drops the `-dump-ir` / `-dump-ir-passes` machinery (`CONFIG_TCC_DEBUG`), which is on by default so IR tooling and the golden-IR tests work with a plain `make cross`. Generated code is unaffected either way. |
| `make cross CONFIG_debugenv=no` | Compiles out the getenv-driven debug/bisect knobs (`TCC_DISABLE_PASS`, `TCC_NO_COALESCE`, …); each folds to a compile-time constant. Worth ~17 KB on the device compiler, but disables the host bisect tooling. |
Floating Point
--------------
Both software and **hardware** floating point are supported. Two flags select
the behaviour:
| Flag | Values | Meaning |
|------|--------|---------|
| `-mfloat-abi=` | `soft`, `softfp` (default), `hard` | how FP values cross a call boundary |
| `-mfpu=` | `none`, `fpv4-sp-d16`, `fpv5-sp-d16`, `fpv5-d16`, `rp2350` (= `rp2350-dcp`) | which FP unit may be used inside a function |
The compile-time default can be changed for a whole toolchain with
`-DCONFIG_TCC_DEFAULT_FPU=ARM_FPU_...` (e.g. `ARM_FPU_RP2350`); an explicit
`-mfpu=` on the command line still wins, and the float ABI is untouched, so
objects stay link-compatible across the switch. Code that must stay soft-float
has to say `-mfpu=none` rather than rely on the default.
**What is emitted inline** (with `-mfloat-abi=softfp` or `hard`;
`-mfloat-abi=soft` disables all inline FP codegen regardless of `-mfpu`)
| Operation | `-mfpu=none` | `fpv4/fpv5-sp-d16` | `-mfpu=rp2350` |
|---|---|---|---|
| `float` add/sub/mul/div | `__aeabi_f*` | `vadd/vsub/vmul/vdiv.f32` | `vadd/vsub/vmul/vdiv.f32` |
| `float` compare/convert/negate | `__aeabi_*` | `__aeabi_*` | `__aeabi_*` |
| `double` add/sub/compare | `__aeabi_d*` | `__aeabi_d*` | inline DCP (CP4) sequences |
| `double` mul/div/convert | `__aeabi_d*` | `__aeabi_d*` | `__aeabi_d*` (DCP-backed library) |
**Hard-float ABI** (`-mfloat-abi=hard`) is complete: `float` arguments in
`s0-s15`, `double` arguments in `d0-d7` with AAPCS back-filling, returns in
`s0`/`d0`, VFP spills/reloads via `vldr`/`vstr`, and `.ARM.attributes`
(`Tag_FP_arch`, `Tag_ABI_HardFP_use`, `Tag_ABI_VFP_args`) matching
`arm-none-eabi-gcc` byte-for-byte. `softfp` keeps the base PCS at call
boundaries while still using the FPU internally, so it links against
soft-float libraries unchanged.
Note that AAPCS-VFP passes doubles in `d0-d7` even on a single-precision-only
FPU — the ABI says where arguments live, not which arithmetic exists, so a
callee unpacks `d0` into a GPR pair to call `__aeabi_dadd`.
**Runtime libraries** (`make fp-libs`, sources in `lib/fp/`):
| Library | `-mfpu` | Contents |
|---------|---------|----------|
| `libsoftfp` | `none` | pure software IEEE-754 |
| `libvfpv4sp` | `fpv4-sp-d16`, `fpv5-sp-d16` | float in HW, double in SW (self-contained) |
| `libvfpv5dp` | `fpv5-d16` | float and double in HW |
| `librp2350fp` | `rp2350` | double via the RP2350 DCP coprocessor |
**Testing**
```bash
# Float tests under one ABI (soft | softfp | hard)
make test-fp FLOAT_ABI=hard
# IEEE-754 conformance on real RP2350 silicon (inline DCP/VFP codegen,
# which QEMU cannot model); the same vectors run under QEMU as
# tests/ir_tests/421_fp_conformance.c
python3 tests/benchmarks/run_fp_conformance.py <host> --opt-level 1 \
--fp-lib rp2350fp --mfpu rp2350 --allow-ftz
```
`--allow-ftz` applies only to the DCP configuration: the coprocessor flushes
subnormals to zero and has no path that doesn't. The soft-float baseline (the
same script without those flags) stays held to full IEEE-754.
**Current limits**
- `float` compares, conversions and negate still go through `__aeabi_*`
helpers even with an FPU selected.
- No native `vadd.f64` on a double-precision unit (`-mfpu=fpv5-d16`); doubles
always call, or use DCP on RP2350.
- DCP `dmul`, `dneg` and the double conversions are not inlined yet.
- `.ARM.attributes` is written at link time only — object files carry none, so
GNU `ld` cannot ABI-check them.
- `-mfloat-abi=hard` on RP2350 silicon is untested (needs pico-sdk rebuilt for
the hard ABI); RP2350 uses `softfp` today.
- The DCP save/restore hooks exist in `dcp_aeabi.S` but the library entry
points do not use them, so an interrupt handler doing `double` math can
corrupt an interrupted user-space DCP sequence. The OS context switch half
is handled on YasOS.
Details: `docs/plan_vfp_hard_float.md` (VFP / hard-float ABI),
`docs/plan_rp2350_dcp.md` (DCP), `lib/fp/README.md` (runtime libraries).
Container
---------
A Dockerfile provides a reproducible build environment, published as
`ghcr.io/matgla/tinycc-armv8m`. The `run` target pulls it and mounts the repo
(`scripts/run_container.py` does the plumbing; podman by default, or
`CONTAINER_RUNTIME=docker`):
```bash
# Interactive shell in the container
make run
# Run one command inside it
make run CMD='make test -j16'
# Build the multi-arch image locally / push it
make build_container
make push_container
```
`container-build` / `container-pull` / `container-push` / `docker-build` /
`docker-start` remain as aliases.
Testing
-------
```bash
# Fetch the GCC torture tests (one-time). Only gcc.c-torture (~16 MB) is
# pulled, sparsely, not the whole gcc repo (~1.3 GB):
make download-gcc-tests # or: bash tests/gcctestsuite/download_gcc_tests.sh
# Full suite: IR tests + asm + unit tests + frontend/linker/debug/runtime/selfhost
make test -j16
# Same, but sequential — clean logs
make test-sequential
# Everything above plus the GCC torture tests
make test-all
```
Individual suites:
| Target | Scope |
|--------|-------|
| `make test-ir` | The primary QEMU corpus in `tests/ir_tests/` |
| `make ut` | Host unit tests for individual optimizer passes |
| `make test-asm` | Thumb-2 encoder tests (`tests/thumb/armv8m/`) |
| `make test-fp FLOAT_ABI=…` | Float tests under one ABI (see *Floating Point*) |
| `make test-selfhost` | The compiler compiling its own sources |
| `make test-frontend`, `test-linker`, `test-debug`, `test-runtime` | Per-subsystem suites |
| `make test-gcc-torture-compile`, `test-gcc-torture-execute` | GCC torture, split by phase |
| `make test-golden-ir` | Golden IR dumps (needs a `CONFIG_TCC_DEBUG` build) |
`make help` lists the rest.
Quick Test Runner
-----------------
```bash
cd tests/ir_tests
# Compile and run a single file
python run.py -c mytest.c
# With optimization
python run.py -c mytest.c --cflags="-O1"
# Dump IR
python run.py -c mytest.c --cflags="-O1" --dump-ir
# Compare against GCC, pass program arguments, or attach a debugger
python run.py -c mytest.c --gcc arm-none-eabi-gcc
python run.py -c mytest.c -a arg1 arg2
python run.py -c mytest.c --gdb
```
Debugging
---------
```bash
# Show IR output
./armv8m-tcc -dump-ir -c test.c
# Dump IR after each named optimizer pass (comma-separated, or 'all')
./armv8m-tcc -dump-ir-passes=all -O2 -c test.c
# Verbose: version banner plus every file read and written
./armv8m-tcc -vv -c test.c
```
Both dump options need a compiler built with `CONFIG_TCC_DEBUG`, which is the
default (see *Build*).
The getenv knobs described in `source/support/tccdbgenv.h` — `TCC_DISABLE_PASS`
and friends — bisect a miscompile to a single pass without rebuilding;
`scripts/bisect_pass.sh` and `scripts/opt_profile.py` drive them.
For extra compile-time logging (e.g. `-DTCC_LS_DEBUG` for the register
allocator), add the define to `CFLAGS` in `config.mak` or pass it to
`./configure --extra-cflags=`. Do **not** use `make CFLAGS+=-DFOO`: that
overrides the flags the sub-makes compute, so the affected TUs silently lose
`-fsanitize=address` and the resulting mixed binary crashes in unrelated code.
License
-------
TCC is distributed under the GNU Lesser General Public License (LGPL).
See the COPYING file for details.
This fork is maintained for ARMv8-M embedded development.