Toolchain Cheat Sheet

Everything here assumes the GNU Arm toolchain (arm-none-eabi-*), OpenOCD 0.12 or later, and the STM32F4 Discovery. Replace build/firmware.elf with your own output path.

Compiler flags

Target selection

Flag	Meaning
-mcpu=cortex-m4	Generate and schedule code for the Cortex-M4
-mthumb	Thumb instruction set (the only one Cortex-M runs)
-mfloat-abi=hard	Use FPU instructions and pass floats in FPU registers
-mfloat-abi=softfp	Use FPU instructions but pass floats in core registers (link-compatible with soft)
-mfloat-abi=soft	No FPU instructions at all (default if unspecified)
-mfpu=fpv4-sp-d16	The Cortex-M4F FPU: single precision, 16 double registers
-mcpu=cortex-m0plus, -mcpu=cortex-m7, -mcpu=cortex-m33	Other cores (M7 FPU: -mfpu=fpv5-d16 or fpv5-sp-d16)

All objects and libraries in one link must use the same float ABI.

Language and warnings

Flag	Meaning
-std=c11 / -std=gnu11	ISO C11 / C11 with GNU extensions
-Wall -Wextra -Wpedantic	Baseline warnings
-Werror	Warnings become errors
-Wshadow -Wconversion -Wdouble-promotion -Wformat=2 -Wundef	Strongly recommended extras (see C Quick Reference)
-ffreestanding	Do not assume a hosted environment; main is not special, builtins not assumed
-fno-builtin	Do not replace calls like memcpy with inline builtins (it does not stop GCC from turning loops into memcpy/memset calls)
-fno-common	Tentative definitions in multiple files become link errors (default since GCC 10)

Optimisation and debug

Flag	Meaning
-O0	No optimisation; debuggable, large, slow
-Og	Optimise without hurting debugging; good debug-build default
-O1, -O2, -O3	Increasing speed optimisation; -O2 is the usual release choice
-Os	Optimise for size
-Oz	Optimise harder for size (GCC 12+, Clang)
-flto	Link-time optimisation across files (pass at compile and link)
-g / -g3	Debug info / debug info including macro definitions
-ffunction-sections -fdata-sections	Each function and object in its own section, so --gc-sections can drop unused ones
-fstack-usage	Write a .su file with each function’s stack frame size
-fanalyzer	GCC static analyser (slow, finds leaks, null derefs, double frees)
-fstack-protector-strong	Stack canaries (needs a __stack_chk_fail and guard)
-fno-strict-aliasing	Disable type-based alias optimisation
-fwrapv	Define signed overflow as wrapping
-save-temps	Keep .i and .s intermediate files

Preprocessor and output control

Flag	Meaning
-E	Stop after preprocessing
-S	Stop after compiling, write assembly .s
-c	Stop after assembling, write object .o
-o file	Output file name
-Idir	Add include search directory
-DNAME=value / -UNAME	Define / undefine a macro
-MMD -MP	Write .d dependency files for make, with phony targets for headers
-dM -E	Dump all predefined macros

Linker flags (passed through gcc)

Flag	Meaning
-T link.ld	Use this linker script
--specs=nano.specs	Link newlib-nano (smaller printf, malloc)
--specs=nosys.specs	Link stub system calls that return errors
-nostartfiles	Do not link the toolchain’s crt0 startup files
-nostdlib	Link no standard libraries or startup files (add -lgcc back if needed)
-u _printf_float	Pull in float support for newlib-nano printf
-Wl,--gc-sections	Discard unreferenced sections
-Wl,-Map=build/firmware.map	Write a map file
-Wl,--print-memory-usage	Print region usage after linking
-Wl,--cref	Add a cross-reference table to the map file
-Wl,--wrap=malloc	Redirect malloc to __wrap_malloc; the original is __real_malloc
-Wl,--undefined=sym	Force sym to be linked
-Wl,--no-warn-rwx-segments	Silence the binutils 2.39+ RWX segment warning
-lm, -lc, -lgcc	Math library, C library, compiler support library

Inspecting the compiler

Command	Shows
arm-none-eabi-gcc -dM -E - < /dev/null	All predefined macros (add -mcpu flags to see target ones)
arm-none-eabi-gcc -print-multi-lib	Available library variants for different flags
arm-none-eabi-gcc -print-file-name=libc.a	Which libc.a will be linked for the given flags
arm-none-eabi-gcc -Q --help=optimizers -O2	Optimisations enabled at -O2
arm-none-eabi-gcc -v	Configuration, version, search paths

Binutils recipes

Task	Command
Disassemble everything	arm-none-eabi-objdump -d build/firmware.elf
Disassemble with interleaved source	arm-none-eabi-objdump -d -S build/firmware.elf
Disassemble one function	arm-none-eabi-objdump -d --disassemble=main build/firmware.elf
Disassemble without raw bytes	arm-none-eabi-objdump -d --no-show-raw-insn build/firmware.elf
Section headers (VMA, LMA, size)	arm-none-eabi-objdump -h build/firmware.elf
Symbol table	arm-none-eabi-objdump -t build/firmware.elf
Dump a section’s raw bytes	arm-none-eabi-objdump -s -j .isr_vector build/firmware.elf
Symbols sorted by address	arm-none-eabi-nm -n build/firmware.elf
Largest symbols first	arm-none-eabi-nm -S --size-sort -r build/firmware.elf
Only undefined symbols in an object	arm-none-eabi-nm -u main.o
Section sizes, Berkeley format	arm-none-eabi-size build/firmware.elf
Section sizes, per section, hex	arm-none-eabi-size -A -x build/firmware.elf
ELF header	arm-none-eabi-readelf -h build/firmware.elf
Section table	arm-none-eabi-readelf -S build/firmware.elf
Program headers (what gets loaded where)	arm-none-eabi-readelf -l build/firmware.elf
Symbols	arm-none-eabi-readelf -s build/firmware.elf
Arm build attributes (float ABI, CPU)	arm-none-eabi-readelf -A main.o
ELF to raw binary	arm-none-eabi-objcopy -O binary build/firmware.elf build/firmware.bin
ELF to Intel HEX	arm-none-eabi-objcopy -O ihex build/firmware.elf build/firmware.hex
Extract one section	arm-none-eabi-objcopy -O binary -j .isr_vector build/firmware.elf vec.bin
Strip debug info	arm-none-eabi-objcopy --strip-debug build/firmware.elf stripped.elf
Embed a binary file as an object	arm-none-eabi-objcopy -I binary -O elf32-littlearm -B arm logo.raw logo.o
Address to function and line	arm-none-eabi-addr2line -e build/firmware.elf -f -i 0x080002A4
Printable strings	arm-none-eabi-strings build/firmware.elf
Archive members	arm-none-eabi-ar t libdrivers.a
Create a static library	arm-none-eabi-ar rcs libdrivers.a uart.o gpio.o

size output columns: text is code plus read-only data (all in flash); data is initialised RAM data, whose initial values are also stored in flash; bss is zeroed RAM. Flash used = text + data. RAM used (static) = data + bss.

The .bin file from objcopy -O binary spans from the lowest to the highest loadable address. A section placed in RAM with a flash load address is handled correctly; a section accidentally given a RAM load address produces a file hundreds of megabytes long.

Linker script snippets

Memory regions for the STM32F407

ENTRY(Reset_Handler)

MEMORY
{
    FLASH  (rx)  : ORIGIN = 0x08000000, LENGTH = 1024K
    RAM    (rwx) : ORIGIN = 0x20000000, LENGTH = 128K
    CCMRAM (rw)  : ORIGIN = 0x10000000, LENGTH = 64K
}

_estack     = ORIGIN(RAM) + LENGTH(RAM);
_stack_size = 4K;
_heap_size  = 0;

Vector table, code, and constants

SECTIONS
{
    .isr_vector : {
        . = ALIGN(4);
        KEEP(*(.isr_vector))
        . = ALIGN(4);
    } > FLASH

    .text : {
        *(.text*)
        *(.rodata*)
        KEEP(*(.init))
        KEEP(*(.fini))
        . = ALIGN(4);
        _etext = .;
    } > FLASH

    .ARM.exidx : {
        *(.ARM.exidx* .gnu.linkonce.armexidx.*)
    } > FLASH

Initialised and zeroed data

    _sidata = LOADADDR(.data);

    .data : {
        . = ALIGN(4);
        _sdata = .;
        *(.data*)
        *(.ramfunc*)
        . = ALIGN(4);
        _edata = .;
    } > RAM AT> FLASH

    .bss (NOLOAD) : {
        . = ALIGN(4);
        _sbss = .;
        *(.bss*)
        *(COMMON)
        . = ALIGN(4);
        _ebss = .;
    } > RAM

> RAM AT> FLASH gives .data a run address (VMA) in RAM and a load address (LMA) in flash. Startup code copies _edata - _sdata bytes from _sidata to _sdata and zeroes _sbss to _ebss.

Reset-persistent data, CCM, stack check

    .noinit (NOLOAD) : {
        . = ALIGN(4);
        *(.noinit*)
        . = ALIGN(4);
    } > RAM

    .ccmram (NOLOAD) : {
        . = ALIGN(4);
        *(.ccmram*)
        . = ALIGN(4);
    } > CCMRAM

    ._stack_check (NOLOAD) : {
        . = ALIGN(8);
        . = . + _heap_size;
        . = . + _stack_size;
        . = ALIGN(8);
    } > RAM

    /DISCARD/ : {
        *(.ARM.attributes)
    }
}

ASSERT(_ebss + _heap_size + _stack_size <= _estack, "RAM overflow: stack and heap do not fit")

Discarding .ARM.attributes is optional and only removes metadata; omit that block if a tool complains.

Placing things from C

#include <stdint.h>

__attribute__((section(".noinit"))) uint32_t crash_count;      /* survives reset */
__attribute__((section(".ccmram"))) static uint8_t work[4096]; /* fast, no DMA */

__attribute__((section(".ramfunc"), noinline))
void flash_program_word(uint32_t addr, uint32_t value);         /* runs from RAM */

gdb commands

Host and target

Command	Short	Effect
break main / break file.c:42	b	Breakpoint at function or line
tbreak main		One-shot breakpoint
break f if x == 3		Conditional breakpoint
info breakpoints	i b	List breakpoints and watchpoints
delete 2 / disable 2	d	Remove or disable breakpoint 2
run	r	Start the program (host only)
continue	c	Resume
next / step	n / s	Next line, stepping over / into calls
nexti / stepi	ni / si	Next machine instruction
finish		Run until the current function returns, print return value
until 50 / advance 50		Run to line 50
backtrace	bt	Call stack
frame 2 / up / down	f	Select stack frame
info locals / info args		Local variables, arguments
print x / print/x x	p	Print a value, in hex
print arr / print *p@8		Whole array / 8 elements from pointer
print sizeof(struct s)		Evaluate any C expression
ptype var / whatis var		Show a type
display/x var		Print var after every step
display/i $pc		Show the next instruction after every step
set var x = 5		Modify a variable
x/16xb addr		Examine 16 bytes in hex
x/8xw addr		Examine 8 words in hex
x/4i $pc		Disassemble 4 instructions at pc
x/s str		Print a C string at an address
watch var		Stop when var is written
rwatch var / awatch var		Stop on read / on any access
info registers	i r	Core registers
info line *0x080002A4		Source line for an address
list *0x080002A4		Source around an address
disassemble /s main		Disassembly with source
tui enable / layout asm / layout split		Text UI with source and assembly panes
info frame		Detailed frame info, saved registers
quit	q	Exit

Embedded (with OpenOCD)

Command	Effect
arm-none-eabi-gdb build/firmware.elf	Start gdb with symbols (gdb-multiarch on Debian/Ubuntu)
target extended-remote :3333	Connect to OpenOCD’s gdb server
monitor reset halt	Reset the chip and halt at the reset vector
monitor reset init	Reset, halt, and run the target’s init script
load	Flash the ELF’s loadable sections
compare-sections	Verify flash contents match the ELF
hbreak func	Force a hardware breakpoint (6 on Cortex-M4)
p/x $pc, p/x $sp, p/x $lr, p/x $xpsr	Core registers
p/x $msp, p/x $psp, p/x $primask, p/x $basepri, p/x $control	Special registers (names depend on the target description)
p/x *(uint32_t *)0x40020C14	Read a peripheral register (GPIOD_ODR)
set *(uint32_t *)0x40020C18 = 0x1000	Write a peripheral register (GPIOD_BSRR: PD12 high)
x/8xw 0x08000000	Vector table: initial SP, Reset, NMI, HardFault …
p/x *(uint32_t *)0xE000ED28	CFSR after a fault
monitor mdw 0x40023830	Read a word through OpenOCD, bypassing gdb’s cache
monitor mww 0x40023830 0x8	Write a word through OpenOCD
monitor halt / monitor resume	Halt or resume via OpenOCD
set mem inaccessible-by-default off	Allow reads of addresses not described by the memory map
detach	Leave the target running and disconnect

A .gdbinit in the project directory (enable it with set auto-load safe-path / in ~/.gdbinit, or narrower):

target extended-remote :3333
monitor reset halt
load
break main
continue

OpenOCD commands

Command line

Task	Command
Start the gdb server for the Discovery	openocd -f board/stm32f4discovery.cfg
Equivalent explicit config	openocd -f interface/stlink.cfg -f target/stm32f4x.cfg
Flash an ELF, verify, reset, exit	openocd -f board/stm32f4discovery.cfg -c "program build/firmware.elf verify reset exit"
Flash a raw binary (needs an address)	openocd -f board/stm32f4discovery.cfg -c "program build/firmware.bin 0x08000000 verify reset exit"
Mass erase	openocd -f board/stm32f4discovery.cfg -c "init; reset halt; stm32f4x mass_erase 0; exit"
Connect under reset (firmware disabled SWD or sleeps)	openocd -f board/stm32f4discovery.cfg -c "reset_config srst_only srst_nogate connect_assert_srst"
Lower the SWD clock	add -c "adapter speed 1000" before other commands

Ports: 3333 gdb, 4444 telnet, 6666 Tcl.

Telnet console (telnet localhost 4444) or monitor in gdb

Command	Effect
reset halt / reset run / reset init	Reset and halt / run / run init script
halt / resume / step	Core control
reg / reg pc	Show all registers / one register
mdw 0x20000000 8	Display 8 words
mdb addr 16 / mdh addr 4	Display bytes / halfwords
mww addr value	Write a word
bp 0x08000200 2 hw / rbp 0x08000200	Set / remove hardware breakpoint
wp 0x20000010 4 w / rwp 0x20000010	Set / remove write watchpoint
flash banks / flash info 0	Flash bank list, sector layout
flash erase_sector 0 5 7	Erase sectors 5 to 7 of bank 0
flash write_image erase build/firmware.elf	Erase as needed and write
verify_image build/firmware.elf	Compare flash with the file
dump_image ram.bin 0x20000000 0x20000	Save 128 KB of SRAM to a file
stm32f4x unlock 0	Remove read protection (triggers a mass erase)
stm32f4x lock 0	Set read protection level 1
targets	List targets and their state
shutdown	Exit OpenOCD

Renode commands

Run renode, then type at the monitor prompt (or put the lines in a .resc script and run renode script.resc).

Command	Effect
mach create "disco"	Create a machine
machine LoadPlatformDescription @platforms/boards/stm32f4_discovery-kit.repl	Load the STM32F4 Discovery model
sysbus LoadELF @build/firmware.elf	Load firmware (path relative to where Renode started, or absolute)
showAnalyzer sysbus.usart2	Open a terminal window on USART2
start / pause	Run / pause emulation
emulation RunFor "00:00:02"	Run for 2 seconds of virtual time
machine Reset	Reset the machine
machine StartGdbServer 3333	Accept gdb on port 3333 (target remote :3333)
sysbus.cpu PC	Show the program counter
sysbus.cpu Step	Execute one instruction
sysbus ReadDoubleWord 0x40020C14	Read a 32-bit word from the bus
sysbus WriteDoubleWord 0x40020C18 0x1000	Write a 32-bit word
sysbus LogPeripheralAccess sysbus.gpioPortD true	Log every access to a peripheral
logLevel 0	Most verbose logging (3 = errors only)
peripherals	List peripherals in the loaded platform
include @other.resc	Run another script
quit	Exit

A minimal .resc script:

mach create "disco"
machine LoadPlatformDescription @platforms/boards/stm32f4_discovery-kit.repl
sysbus LoadELF @build/firmware.elf
showAnalyzer sysbus.usart2
machine StartGdbServer 3333
start

Peripheral names (sysbus.usart2, sysbus.gpioPortD) come from the platform file; list them with peripherals if a name does not resolve.

QEMU

Task	Command
List machines	qemu-system-arm -M help
Run an ELF on the STM32F405 model, UART on the terminal	qemu-system-arm -M netduinoplus2 -nographic -kernel build/firmware.elf
Wait for gdb on port 1234	add -s -S, then target remote :1234 in gdb
Exit -nographic	Ctrl+A then X

Makefile skeleton

Makefile

TARGET   := firmware
BUILD    := build
SRCS     := src/main.c src/startup.c
LDSCRIPT := link.ld

CROSS    := arm-none-eabi-
CC       := $(CROSS)gcc
OBJCOPY  := $(CROSS)objcopy
SIZE     := $(CROSS)size

CPU      := -mcpu=cortex-m4 -mthumb -mfloat-abi=hard -mfpu=fpv4-sp-d16
CFLAGS   := $(CPU) -std=c11 -Og -g3 -ffunction-sections -fdata-sections \
            -Wall -Wextra -Wpedantic -Iinclude -MMD -MP
LDFLAGS  := $(CPU) -T $(LDSCRIPT) --specs=nano.specs --specs=nosys.specs \
            -Wl,--gc-sections -Wl,-Map=$(BUILD)/$(TARGET).map \
            -Wl,--print-memory-usage

OBJS     := $(SRCS:%.c=$(BUILD)/%.o)
DEPS     := $(OBJS:.o=.d)

.PHONY: all clean flash debug size

all: $(BUILD)/$(TARGET).elf $(BUILD)/$(TARGET).bin $(BUILD)/$(TARGET).hex

$(BUILD)/%.o: %.c
  @mkdir -p $(dir $@)
  $(CC) $(CFLAGS) -c $< -o $@

$(BUILD)/$(TARGET).elf: $(OBJS) $(LDSCRIPT)
  $(CC) $(LDFLAGS) $(OBJS) -o $@
  $(SIZE) $@

$(BUILD)/$(TARGET).bin: $(BUILD)/$(TARGET).elf
  $(OBJCOPY) -O binary $< $@

$(BUILD)/$(TARGET).hex: $(BUILD)/$(TARGET).elf
  $(OBJCOPY) -O ihex $< $@

flash: $(BUILD)/$(TARGET).elf
  openocd -f board/stm32f4discovery.cfg -c "program $< verify reset exit"

debug: $(BUILD)/$(TARGET).elf
  arm-none-eabi-gdb -ex "target extended-remote :3333" \
      -ex "monitor reset halt" -ex "load" $<

size: $(BUILD)/$(TARGET).elf
  $(SIZE) -A -x $<

clean:
  rm -rf $(BUILD)

-include $(DEPS)

Recipe lines must start with a tab character. -MMD -MP makes the compiler write .d files so editing a header rebuilds the files that include it; -include $(DEPS) reads them and ignores missing ones on the first build. For make debug, start OpenOCD in another terminal first.

Make automatic variables

Variable	Meaning
$@	The target being built
$<	The first prerequisite
$^	All prerequisites, deduplicated
$(dir $@)	Directory part of the target
$*	The stem matched by % in a pattern rule
:= / = / ?= / +=	Immediate / deferred / set if unset / append

CMake skeleton

cmake/arm-none-eabi.cmake

set(CMAKE_SYSTEM_NAME Generic)
set(CMAKE_SYSTEM_PROCESSOR arm)

set(CMAKE_C_COMPILER   arm-none-eabi-gcc)
set(CMAKE_ASM_COMPILER arm-none-eabi-gcc)
set(CMAKE_OBJCOPY      arm-none-eabi-objcopy)
set(CMAKE_SIZE         arm-none-eabi-size)

# A bare-metal test executable cannot link without a linker script
set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)

set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

CMakeLists.txt

cmake_minimum_required(VERSION 3.20)
project(firmware C ASM)

set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)
set(CMAKE_C_EXTENSIONS OFF)

set(CPU_FLAGS -mcpu=cortex-m4 -mthumb -mfloat-abi=hard -mfpu=fpv4-sp-d16)
set(LINKER_SCRIPT ${CMAKE_SOURCE_DIR}/link.ld)

add_executable(firmware src/main.c src/startup.c)
set_target_properties(firmware PROPERTIES SUFFIX ".elf")
target_include_directories(firmware PRIVATE include)

target_compile_options(firmware PRIVATE
    ${CPU_FLAGS}
    -ffunction-sections -fdata-sections
    -Wall -Wextra -Wpedantic
)

target_link_options(firmware PRIVATE
    ${CPU_FLAGS}
    -T ${LINKER_SCRIPT}
    --specs=nano.specs --specs=nosys.specs
    -Wl,--gc-sections
    -Wl,-Map=$<TARGET_FILE_DIR:firmware>/firmware.map
    -Wl,--print-memory-usage
)
set_property(TARGET firmware APPEND PROPERTY LINK_DEPENDS ${LINKER_SCRIPT})

add_custom_command(TARGET firmware POST_BUILD
    COMMAND ${CMAKE_OBJCOPY} -O binary $<TARGET_FILE:firmware>
            $<TARGET_FILE_DIR:firmware>/firmware.bin
    COMMAND ${CMAKE_SIZE} $<TARGET_FILE:firmware>
)

Task	Command
Configure (Debug, Ninja)	cmake -B build -G Ninja -DCMAKE_TOOLCHAIN_FILE=cmake/arm-none-eabi.cmake -DCMAKE_BUILD_TYPE=Debug
Configure (Release)	same with -DCMAKE_BUILD_TYPE=Release (adds -O3 -DNDEBUG; use MinSizeRel for -Os)
Build	cmake --build build
Verbose build (see every command)	cmake --build build --verbose
Export compile database for editors	add -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
Clean	cmake --build build --target clean

LINK_DEPENDS makes CMake relink when the linker script changes; without it, edits to link.ld are silently ignored until something else changes.