Keil MDK Build

Patterns for building embedded firmware with Keil MDK. Covers both ARM Compiler 5 (armcc) and ARM Compiler 6 (armclang).

UV4 CLI Build (Authoritative)

UV4.exe batch mode is the canonical build path. A CI reimplementation is possible but may miss include paths.

<Keil>\UV4\UV4.exe -b project.uvprojx -t TargetName -j0 -o <log_path>

Replace <Keil> with the Keil install root. Auto-discover by checking common locations or ask the user when unknown.

Flags:

Exit codes:

Critical: Log path resolution — The -o path is resolved relative to the .uvprojx file's directory, not the current working directory. Always use an absolute path or a path under a known-existing subdirectory (e.g., objects\) of the project directory.

Recommended invocation — UV4 produces no stdout; use Start-Process with -Wait -PassThru and check ExitCode:

$keil = "<Keil_install_root>"  # Ask user or auto-discover
$log = Join-Path (Get-Location) "build.log"
$p = Start-Process -FilePath "$keil\UV4\UV4.exe" `
    -ArgumentList "-b project.uvprojx -t Target -j0 -o $log" `
    -Wait -PassThru -NoNewWindow
if ($p.ExitCode -ne 0) { throw "Build failed (exit $($p.ExitCode))" }

Compiler Selection

Keil MDK supports two compiler generations. Identify which one the project uses before generating commands.

How to identify: Check the .uvprojx XML for <ARMCC> (AC5) or <ARMCLANG> (AC6) sections. A project can mix both — check per-file or per-group settings.

ARM Compiler 5 (armcc)

Legacy compiler, still common in long-lived projects. Uses its own flag syntax, incompatible with AC6.

Detection: Installed at <Keil>\ARM\ARMCC. Run armcc --vsn to verify.

Optimization levels — AC5 has two orthogonal axes: optimization level (-On) and optimization goal (-Ospace vs -Otime). Keil's UI combines them into a single dropdown:

-Ospace is the default goal at levels 0-3 (favor smaller code). -Otime swaps to favor speed. These are separate from the -On level.

Sources: ARM Compiler v5.06 User Guide (DUI0472M), §3.154-3.159.

Key flags:

• --cpu Cortex-M4 (adjust to target MCU; use --cpu=list to see supported targets)
• --c99 or --c11 (language standard; C90 is the AC5 default)
• --gnu (enable GNU extensions if project relies on them)
• --apcs=/interwork (ARM/Thumb interworking)
• -c (compile only, no link)
• --split_sections (equivalent to -ffunction-sections -fdata-sections)

Warning control: --diag_suppress=<id> to suppress specific warnings; --diag_error=<id> to promote to error.

ARM Compiler 6 (armclang)

LLVM-based, current generation. Installed at <Keil>\ARM\ARMCLANG*.

Detection: Search common install roots for directories matching ARMCLANG*. Validate with armclang --version. If detection fails, ask the user.

Optimization levels:

Key flags for Cortex-M:

• --target=arm-arm-none-eabi -mcpu=cortex-m4 -mfpu=fpv4-sp-d16 -mfloat-abi=hard (adjust MCU/FPU to target)
• -c (compile only, no link)
• -ffunction-sections -fdata-sections (enable linker garbage collection)
• -fshort-enums -fshort-wchar (common embedded defaults)

AC5 to AC6 Migration Traps

Projects migrating from AC5 to AC6 commonly hit these issues. Sources: ARM Compiler Migration Guide (DUI0742), Arm Compiler for Embedded FuSa Migration Guide.

Migration verification: After switching compiler, compare .map file sizes and symbol lists. Unexpected size changes often indicate a packing or inlining difference.

Build Lifecycle

A full Keil build has 5 stages:

1. Pre-build — Version header generation, manifest updates
2. Compile — .c/.cpp/.s → .o via armcc (AC5) or armclang (AC6)
3. Link — armlink --via=<response>.lnp → .axf
4. Post-build (fromelf) — fromelf --bin objects/app.axf → application.bin
5. Post-build (merge) — Merge application BIN + filesystem + bootloader into flash image

If bypassing UV4 (CI build), all 5 stages must be replicated explicitly.

Merge / Packaging

Embedded firmware packages typically merge multiple components into a single flash image.

Bootloader Selection (Parity Rule)

A common pattern: use version.build parity to select development vs. production bootloader.

• Parse version.build as hexadecimal (not decimal)
• Odd → production bootloader
• Even → development bootloader

This is the most common source of confusion — 0x10 (hex) is even, even though "16" as a decimal number looks like it could be interpreted differently.

Manifest Structure

Merged firmware images include a manifest at a fixed address with:

• Version fields (major, minor, patch, build)
• Component sizes (firmware, filesystem)
• CRC32 checksums for each component
• Magic number for validation

Components are typically padded to alignment boundaries before CRC calculation.

Non-Standard CRC32

Embedded firmware CRC32 often differs from the standard zlib/crc32 implementation:

• Byte-swapped within each word (MCU word order)
• No reflection (forward bit order)
• No final XOR
• Polynomial: 0x104C11DB7

Verify the CRC implementation against a known-good reference before trusting any reimplementation.

Common Build Failures

MAP File Analysis

The .map file (at <listings>/<target>.map) is the linker's memory blueprint. Make it a habit to review after each build.

Key Sections

Size Optimization Workflow

1. Sort Image component sizes by Code + RO Data. Focus on the top 5 files.
2. In Global Symbols, find functions with large Size values. Consider splitting or rewriting.
3. Check .constdata / .rodata for debug strings — guard with #if or move to runtime generation.
4. In Memory Map, look for PAD entries — these are alignment waste. Reorder struct members to minimize.
5. Verify MicroLIB is enabled; check that no accidental printf/sprintf/malloc drags in heavy library code.
6. Keep an optimization log: ROM/RAM before and after each change.

Memory Budget Verification

From the Memory Map section:

• Load Region LR_IROM1 size = total Flash used (Code + RO + RW initial values)
• Execution Region RW_IRAM1 = total RAM used (RW data + ZI data + Stack + Heap)
• RW Data consumes BOTH Flash and RAM — initial values stored in Flash, copied to RAM at startup
• ZI Data consumes RAM only — zero-initialized at startup

Check that Stack + Heap sizes match the worst-case call chains (from .htm call graph) plus margin.

HardFault / Exception Triage

For crash analysis — fault registers, stack-frame capture, PC-to-source resolution, root-cause classification — load Skill("hardfault-triage"). The .map file sections described above (Global Symbols, Memory Map) are the bridge between the two skills: build the .map here, debug the crash there.