From Source Code to Machine Code

A microcontroller cannot compile its own firmware; it has no room for a compiler and nowhere to run one. You build on a PC and run on the target, so the compiler must be a cross-compiler: it runs on one architecture and generates code for another. GNU cross toolchains are named by a target triple. In arm-none-eabi-gcc, arm is the architecture, none says there is no operating system underneath (the program owns the machine, unit 3), and eabi is the Arm Embedded ABI, the calling and object-file conventions from unit 3. Flags then narrow the target further: -mcpu=cortex-m0plus -mthumb selects the exact core and its Thumb instruction set, so the compiler never emits an instruction that core lacks.

Follow one function through the stages in the figure below. The preprocessed text has lost the macro: the compiler proper never sees LED_PIN, only 25, which is why a debugger cannot show you a macro’s name. The assembly has registers and instructions but still uses names for things outside this file. The object file has real machine code, with offsets counted from zero, because the assembler has no idea where in memory this code will end up or where gpio_put lives: gpio_put might be in another file, in a library, or not exist at all.

↑ This step uses the figure at the top of the page.

So the object file contains placeholders plus instructions for filling them in, called relocations (lesson 2). Only the linker sees every object file at once, so only the linker can choose addresses and fill the placeholders. That is why linking happens once, after everything else, and why “undefined reference” is a link error, not a compile error: each file compiled perfectly well on its own.

A Thumb BL (branch with link) does not store the target address. It stores the distance from the branch to the target, measured from the branch’s own address plus 4 (the value the program counter reads as while the instruction executes):

where $S$ is the target’s address and $P$ the address of the BL itself. In the figure’s linked layout, led_on starts at 0x1000_0234, so the BL six bytes in is at $P$ = 0x1000_023A, and the linker has placed gpio_put at $S$ = 0x1000_0410:

The BL encoding splits that offset (halved, since instructions are 2-byte aligned) across two 16-bit halfwords: 466 / 2 = 233 = 0xE9 goes into the low 11 bits of the second halfword, the rest of the fields are zero or their “positive” values, and the instruction becomes f000 f8e9. In the object file the same instruction was the placeholder f7ff fffe, which the ELF for the Arm Architecture specification gives as the encoding of BL ., a branch to itself, representing an initial addend of −4. Move either function at all in the link and the four bytes change; that is why they cannot be known until the end.

The linker’s output is an ELF file: the machine code and data, plus section headers, symbol tables, debug information and each section’s load address. A debugger wants all of that. A chip’s flash wants only the bytes, at the right addresses. objcopy converts between the two: arm-none-eabi-objcopy -O binary app.elf app.bin writes a raw memory image, starting at the load address of the lowest section and discarding symbols and relocations; -O ihex writes Intel HEX, a text format in which every line carries its own address and a checksum. Programming tools and boot loaders accept one or more of these; some chips define their own container, such as the RP2040’s UF2 files, which carry the target address in every block.

The raw binary has one trap. It is a single contiguous dump from the lowest to the highest load address, so if any section is ever given a load address far away (say, in RAM at 0x2000_0000 while code sits at 0x1000_0000), the “binary” becomes hundreds of megabytes of padding. Lesson 4 shows how the linker script keeps every load address in flash.