GCC Toolchain in Depth

Introduction

You write main.c in English-like C. The microcontroller only flips transistors according to machine code — patterns of bits the CPU decodes as "add", "load", "jump". Somewhere between your editor and the chip, a toolchain must translate, combine, and place that code in flash and RAM.

Compilers and toolchains gave the big picture. Here you see each GCC step, what object files contain, why linking fails, and what names like arm-none-eabi-gcc mean. When you stare at undefined reference to 'sin' or a linker script error, this is the chapter that tells you which stage failed and why.

The translation pipeline — a factory line

Imagine a factory with four stations. Raw material enters; a finished executable leaves.

When you type gcc main.c -o main, GCC runs all four. Flags let you stop early and inspect intermediate output — essential for learning.

Stage 1: Preprocessor

Before the compiler sees your file, lines starting with # are processed.

1
2
3
4
5

#include <stdio.h>      /* paste entire header here */
#define LED_PIN 5       /* replace LED_PIN with 5 everywhere */
#ifdef DEBUG
    printf("debug\n");  /* only if DEBUG was defined */
#endif

Embedded boards use this heavily:

1
2
3
4
5

#ifdef BOARD_V2
    #define LED_PIN  GPIO_PIN_5
#else
    #define LED_PIN  GPIO_PIN_13
#endif

One source tree, multiple hardware targets — define BOARD_V2 at compile time (-DBOARD_V2).

See C types and macros for macro pitfalls.

Stage 2: Compiler — C to assembly

1

gcc -S main.c -o main.s

Open main.s — you see labels, mnemonics, and registers. A simple loop in C becomes compare-and-branch instructions. Optimization level matters:

Reading assembly connects to Assembly language.

Stage 3: Assembler — object files

1

gcc -c main.c -o main.o

An object file (.o) is not runnable yet. It contains:

• Machine code for functions in this file
• Data (global variables with initial values)
• BSS info (how much zeroed space to reserve)
• Symbol table — names like main, counter, HAL_Init
• Relocation table — "patch this jump when you know final address"

Symbols: defined vs undefined

main.o might define main and reference undefined printf. libc.a later provides printf.

Stage 4: Linker — the puzzle solver

1

gcc main.o utils.o -o firmware.elf

The linker:

1. Lays out all code and data in memory (flash at 0x08000000, RAM at 0x20000000 on typical STM32 — from linker script)
2. Resolves every undefined symbol to exactly one definition
3. Patches relocation entries — branch targets, load addresses
4. Discards debug tables or merges them into .elf

If two files define the same global name, or nothing defines a used name → error.

"Undefined reference" — what it really means

1

undefined reference to `HAL_GPIO_WritePin'

Translation: "Some .o called HAL_GPIO_WritePin, but no object or library in the link defined it." Fix: add the right .c file to the project, or link the HAL library.

This is not a syntax error — compile succeeded. Link failed.

Relocation in one sentence

Object files say "call function g" with a placeholder address 0. The linker knows g ended up at 0x08001234 and writes that number into the call instruction.

Stopping GCC at each stage

gcc -v prints every subprocess invoked — useful when the IDE hides commands.

Libraries — static and dynamic

A library is a collection of .o files archived together.

Bare-metal firmware almost always statically links libc_nano, libm, and vendor HAL — the chip has no OS to load .so files. Embedded Linux (Pi, gateway) often uses dynamic linking for libc.so to save disk space.

Static trade-off: bigger flash image, but self-contained — flash the one .bin and go.

Library order: sometimes gcc app.o -lm must come after objects that use sin() — linker scans left to right once.

Toolchain names decoded

arm-none-eabi-gcc breaks down as:

arm-linux-gnueabihf-gcc targets Linux on ARM with hardware float — wrong choice for bare-metal STM32.

Using the wrong toolchain can produce code that does not match your vector table or calling convention.

Build, host, and target

Cross-compilation means host ≠ target. You cannot run the .elf by double-clicking on Windows — you flash it.

Useful inspection commands

1
2
3
4

gcc -v main.c -o main          # verbose — see subprocesses
arm-none-eabi-nm firmware.o    # list symbols
arm-none-eabi-objdump -d firmware.elf   # disassemble
arm-none-eabi-size firmware.elf         # flash/RAM usage by section

Your IDE "Build" button runs the same tools with a long flag list and a linker script STM32F411RETx_FLASH.ld.

Relevant topics

• Compilers and toolchains
• Assembly language
• Memory systems
• GCC documentation

Starting points

1. Run gcc -S on a file with a for loop — count branch instructions.
2. Deliberately omit a source file from the link — read the undefined reference line carefully.
3. nm an object file — list defined (T, D) vs undefined (U) symbols.
4. Open your project's linker script — find FLASH and RAM length.

Focus points

• Compile error ≠ link error — different stage, different fix.
• Linker script is part of the build — wrong RAM size fails link or boot.
• -c builds objects; you still need a link step for an executable.
• Match toolchain to target (none-eabi vs linux-gnueabi).

Key points

• GCC runs preprocess → compile → assemble → link.
• Object files carry code plus symbol and relocation metadata.
• The linker assigns addresses and resolves cross-file references.
• Static linking bundles libraries into firmware; MCUs rarely use dynamic .so.