How the GNU Linker Works: Symbols, Relocation, and ELF Binaries Explained

How the GNU Linker Works: Symbols, Relocation, and ELF Binaries Explained

1. Introduction

Every embedded developer working with STM32, NXP, or any other Cortex-M device eventually runs a command like:

The compiler's job is well understood: it turns C into Thumb-2 machine code. But there is a second tool in that pipeline whose work is almost entirely invisible until something goes wrong: the linker, invoked here through the GCC driver.

Undefined reference errors, a HardFault on boot because the vector table landed at the wrong flash address, a BSS region that never gets zeroed because _sbss and _ebss are missing from the map all of these are linker problems. Yet most embedded developers treat the linker as a black box and only interact with it through a handful of -T and -Wl flags.

This article opens that black box. We follow a small C program from the moment arm-none-eabi-gcc -c finishes to the moment a flashable ELF exists on disk, examining every decision the linker makes: how it reads ARM ELF object files, how it matches undefined BL targets to definitions, how it assigns real Cortex-M flash and RAM addresses to code and data, and how a linker script controls the final memory map.

2. From Source to Object File

2.1 What the compiler produces

Given a C source file, the compiler runs four phases: preprocessing, parsing and semantic analysis, Thumb-2 code generation, and assembly. The final phase hands off to arm-none-eabi-as, which encodes the instructions and writes an ELF relocatable object the .o file.

The object file is not a complete firmware image. It is a fragment: Thumb-2 machine code with holes where branch targets and data addresses will eventually go, plus tables describing those holes so the linker knows how to fill them.

Compile only, stop before linking (-c flag)

The key words are ELF 32-bit LSB relocatable. This is a fragment, not an executable. No flash addresses have been assigned yet.

2.2 The anatomy of an object file: sections and symbols

An ARM ELF object file is organized into sections. Each section holds a distinct category of content:

Use arm-none-eabi-nm and arm-none-eabi-readelf to inspect these structures directly:

List symbols in main.o

Show relocation entries (ARM uses REL not RELA)

The U symbols are undefined: the compiler saw a call to add_values, emitted a BL instruction with a zero branch offset, and recorded an R_ARM_THM_CALL relocation saying "patch this slot when you know the address."

Fig 1. Internal structure of an ARM ELF relocatable object file.

Struggling to implement this for a professional project? If you need to master full-scale firmware architecture, security, and build automation, join our 1-D or 4-Day Live Implemnetation Workshops. I'll show you the exact direct path to production-ready firmware without the trial and error.

3. Symbol Resolution

3.1 Defined and undefined symbols

When the linker opens all object files it builds a global symbol table by merging every individual symbol table. Each symbol is either:

- Defined the object contains the actual Thumb-2 code or data for this name.

- Undefined the object references the name but does not define it.

If any undefined symbol cannot be satisfied by the time all inputs are scanned, the linker halts:

3.2 How the linker resolves references across object files

Consider a minimal two-file Cortex-M program:

The compiler turns the add_values(3, 4) call into a Thumb-2 BL with a zero placeholder offset:

The linker scans main.o, records add_values as unresolved, then scans utils.o, finds the strong definition, and marks the reference satisfied. The symbol now has a section and an offset within that section.

Fig 2. The linker matches the undefined add_values reference in main.o to the strong definition in utils.o and records the binding in its global symbol table.

3.3 Strong and weak symbols

Not all definitions carry equal weight. GNU ld distinguishes strong (STB_GLOBAL) and weak (STB_WEAK) symbols. The rules are:

- Two strong definitions of the same name is a hard error.

- A strong definition always wins over a weak one.

- If only weak definitions exist, the linker uses one of them.

This is exactly how Cortex-M interrupt handlers work. Every ARM CMSIS-compliant startup file ships weak default handlers in assembly:

Any handler you define in your application is a strong symbol and silently overrides the weak alias:

Common pitfall: If you define a handler but its source file is not compiled into the build (wrong Makefile rule, missing source), the weak default is silently used. The CPU enters the interrupt and loops forever in Default_Handler. Always verify with:

> arm-none-eabi-nm -n firmware.elf | grep IRQHandler

4. Relocation

4.1 Why addresses are not known at compile time

When the compiler emits a BL add_values Thumb-2 instruction, the encoding requires a signed PC-relative offset. But the compiler does not know that offset it depends on:

- Where the linker places utils.o's .text in flash.

- Where within that section add_values starts.

- How many alignment-padding bytes the linker inserts between sections.

All unknowable at compile time. The compiler writes a zero-offset BL (f7ff fffe) and records a relocation entry for the linker to fix up later.

4.2 Relocation entries

ARM ELF uses the REL format: the addend is implicit in the instruction encoding, not stored separately. Each entry in .rel.text contains:

R_ARM_THM_CALL applies to Thumb-2 BL and BLX instructions. It instructs the linker to compute S + A - P, encode the result as a Thumb-2 branch offset across two 16-bit halfwords, and set bit 0 of the target address to 1 (the Thumb interworking bit). Here S is the symbol's final flash address, A is the addend extracted from the instruction encoding, and P is the address of the instruction being patched.

4.3 How the linker patches addresses

Once all symbols have final flash addresses assigned, the linker iterates over every relocation entry and applies the formula. Here is a concrete walk-through with real Thumb-2 encoding:

The Thumb bit: arm-none-eabi-nm shows add_values at 0x08000130, but the BL target encoded in the instruction is 0x08000131 (bit 0 = 1). The CPU strips bit 0 before fetching the instruction it is a Thumb interworking flag, not part of the address. Branching to an even address on Cortex-M triggers a UsageFault. This is why function pointers for Thumb code must always have bit 0 set.

Fig 3. The R_ARM_THM_CALL relocation entry drives the linker to replace the zero-offset BL encoding with the correct Thumb-2 branch offset .

5. The Final Binary

5.1 Merging sections

After symbol resolution, the linker lays out the output ELF. Sections with the same name and compatible flags from all input objects are concatenated into a single output section. The .text from startup_stm32f407xx.o is followed by main.o's .text, then utils.o's .text, and so on. The same happens for .data, .rodata, and .bss.

Each output section gets two addresses:

- VMA (Virtual Memory Address) the address code uses at runtime. For .text and .rodata this is a flash address. For .data and .bss this is a RAM address.

- LMA (Load Memory Address) where the section's initial bytes actually live in the ELF file or in ROM. For .data, initial values are stored in flash (LMA) and copied to RAM (VMA) by the startup code before main() runs.

Fig 4. The linker concatenates input sections into output sections, assigns flash VMAs to code and RAM VMAs to data, and groups everything into two PT_LOAD segments.

NB: On Cortex-M, VMA is simply the runtime address used by the CPU—there is no virtual memory or MMU

5.2 The linker script: MEMORY and SECTIONS

The default GNU ld script is designed for hosted Linux programs and is completely wrong for Cortex-M. An embedded linker script takes control of the entire memory map. Here is a realistic script for an STM32F407 (1 MB flash, 128 KB SRAM1):

The symbols _sdata, _edata, _sbss, _ebss, and _etext are consumed by the startup assembly:

Why .isr_vector must come first: On Cortex-M, the processor reads the initial stack pointer from address 0x08000000 and the Reset_Handler address from 0x08000004 on power-up. If anything lands before .isr_vector, the CPU reads garbage and locks up before a single instruction executes. KEEP also prevents gc-sections from eliminating the vector table, which would otherwise appear unreferenced from the linker's perspective.

6. Why Linking Order Matters

Object files passed directly on the command line are always included. Static libraries (.a archives such as libm.a or the HAL library) are handled differently: the linker pulls a member out of an archive only if that member defines a currently-unresolved symbol. Archives are scanned left to right, once.

Wrong: -lm scanned before main.o has recorded its undefined sqrtf

Correct: object files first, libraries after

When libraries depend on each other circularly -- which is common with

-lc, -lm, and -lgcc on bare-metal ARM -- a single left-to-right

pass cannot satisfy all references. --start-group tells the linker to

scan the grouped libraries repeatedly until no new symbols are resolved.

Dead-code elimination matters a lot on microcontrollers with limited flash. Place each function in its own section at compile time and let the linker garbage-collect the unreferenced ones:

Each function gets its own .text.funcname section

Linker removes unreferenced sections from the final binary

Check what was removed

KEEP and gc-sections: gc-sections starts from a root set (the entry point and any section wrapped in KEEP() in the linker script) and discards everything unreachable. The vector table and startup code must be protected with KEEP or the linker eliminates them, producing a binary that does nothing on power-up.

7. Conclusion

The linker performs three conceptually distinct operations on every firmware build:

- Symbol resolution matching every undefined BL target (and every external data reference) to exactly one strong definition, using the weak/strong binding rules that power the CMSIS interrupt-handler override mechanism.

- Layout assigning flash and RAM addresses to every output section according to the MEMORY and SECTIONS directives in the linker script, and exporting the boundary symbols (_sdata, _edata, _sbss, _ebss, _estack) that the startup assembly depends on.

- Relocation iterating over every R_ARM_THM_CALL entry (and others) and rewriting the placeholder BL encoding with the correct Thumb-2 PC-relative branch offset, including setting the Thumb interworking bit so the CPU never faults on a mode transition.

With this model in place, any linker error becomes diagnosable. Undefined reference means a symbol was never defined or the defining archive came before the object that needed it. HardFault on boot usually means the vector table missed flash origin, or _estack points into an invalid RAM region, or the .data copy loop read from _etext under a different name than the startup code expected. Data that is always zero at runtime means the initial-value copy loop never ran or ran with wrong boundary symbols.