Linker Scripts

mohitmishra786/low-level-dev-skills/skills/embedded/linker-scripts

by mohitmishra786bdc58472fa9fNo license253 starsListed Oct 9, 2026Updated Oct 9, 2026Repository updated 3 months ago

Linker script skill for embedded bare-metal targets. Use when writing or modifying GNU ld linker scripts, placing code and data in specific flash or RAM regions, understanding VMA vs LMA, configuring startup .bss/.data initialization, using MEMORY and SECTIONS commands, or debugging linker errors about regions. Activates on queries about linker scripts, MEMORY command, SECTIONS command, .bss init, VMA vs LMA, weak symbols, or placing functions in specific memory regions.

Instructions onlySoftware Development
AI-generated overview

Guides writing and modifying GNU ld linker scripts for embedded bare-metal targets, covering memory regions, VMA/LMA and startup initialization.

What it does
This skill provides guidance and reference material for authoring and editing GNU ld linker scripts for embedded bare-metal firmware. It explains MEMORY and SECTIONS commands, VMA versus LMA placement, startup .bss/.data initialization, placing code and data in specific flash or RAM regions, and directives such as KEEP, ALIGN, PROVIDE and FILL. It also lists common linker errors with causes and fixes, and includes a reference document on linker script anatomy.
When to use it
Use it when writing or modifying a linker script for an MCU, placing functions or data in specific flash or RAM regions, reasoning about VMA versus LMA, or setting up .bss/.data initialization at startup. It is also relevant when diagnosing linker errors such as region overflow or missing linker script symbols.
Requirements
No scripts are shipped; the skill is instruction and reference content only. It assumes familiarity with GNU ld and embedded toolchains such as arm-none-eabi binutils for inspecting section sizes and addresses.

Linker Scripts

Purpose

Guide agents through writing and modifying GNU ld linker scripts for embedded targets: MEMORY and SECTIONS commands, VMA vs LMA for code relocation, startup .bss/.data initialization, placing sections in specific regions, and using PROVIDE/KEEP/ALIGN directives.

Triggers

  • "How do I write a linker script for my MCU?"
  • "How do I place a function in a specific flash/RAM region?"
  • "What's the difference between VMA and LMA in a linker script?"
  • "How does .bss and .data initialization work at startup?"
  • "Linker error: region 'FLASH' overflowed"
  • "How do I use weak symbols in a linker script?"

Workflow

1. Linker script anatomy

ld
/* Minimal Cortex-M linker script */
ENTRY(Reset_Handler)            /* entry point symbol */
MEMORY{    FLASH (rx)  : ORIGIN = 0x08000000, LENGTH = 512K    RAM   (rwx) : ORIGIN = 0x20000000, LENGTH = 128K}
SECTIONS{    .text :                     /* code section */    {        KEEP(*(.isr_vector))    /* interrupt vector must be first */        *(.text)        *(.text.*)        *(.rodata)        *(.rodata.*)        . = ALIGN(4);        _etext = .;             /* end of flash content */    } > FLASH
    .data : AT(_etext)          /* VMA = RAM, LMA = FLASH */    {        _sdata = .;        *(.data)        *(.data.*)        . = ALIGN(4);        _edata = .;    } > RAM
    .bss :    {        _sbss = .;        *(.bss)        *(.bss.*)        *(COMMON)        . = ALIGN(4);        _ebss = .;    } > RAM
    /* Stack at top of RAM */    _estack = ORIGIN(RAM) + LENGTH(RAM);}

2. VMA vs LMA

  • VMA (Virtual Memory Address): where the section runs at runtime
  • LMA (Load Memory Address): where the section is stored in the image (flash)

For .data: stored in flash (LMA), copied to RAM at startup (VMA).

ld
/* AT() sets LMA explicitly */.data : AT(ADDR(.text) + SIZEOF(.text)){    _sdata = .;    *(.data)    _edata = .;} > RAM          /* VMA goes in RAM */

LMA of .data is automatically placed after .text if you use AT(_etext).

3. Startup .bss / .data initialization

The C runtime must copy .data from flash to RAM and zero .bss before main():

c
// startup.c or startup.s equivalent in Cextern uint32_t _sdata, _edata, _sidata; // _sidata = LMA of .dataextern uint32_t _sbss, _ebss;
void Reset_Handler(void) {    // Copy .data from flash to RAM    uint32_t *src = &_sidata;    uint32_t *dst = &_sdata;    while (dst < &_edata) *dst++ = *src++;
    // Zero-initialize .bss    dst = &_sbss;    while (dst < &_ebss) *dst++ = 0;
    // Call C++ constructors    // (call __libc_init_array() if using newlib)
    main();    for (;;);  // should never return}

Linker script provides _sidata (LMA of .data):

ld
.data : AT(_etext){    _sdata = .;    *(.data)    _edata = .;} > RAM
_sidata = LOADADDR(.data);    /* LMA of .data for startup code */

4. Placing code in specific regions

ld
/* Place time-critical code in RAM for faster execution */MEMORY{    FLASH (rx) : ORIGIN = 0x08000000, LENGTH = 512K    RAM   (rwx): ORIGIN = 0x20000000, LENGTH = 128K    CCM   (rwx): ORIGIN = 0x10000000, LENGTH = 64K   /* Cortex-M4 CCM */}
.fast_code : AT(_etext){    _sfast = .;    *(.fast_code)   /* sections marked __attribute__((section(".fast_code"))) */    _efast = .;} > CCM              /* runs from CCM RAM */
c
// Mark a function to go in fast_code section__attribute__((section(".fast_code")))void critical_isr_handler(void) {    // runs from CCM RAM}

5. KEEP, ALIGN, PROVIDE

ld
/* KEEP — prevent garbage collection of section */KEEP(*(.isr_vector))        /* linker gc won't remove interrupt table */KEEP(*(.init))KEEP(*(.fini))
/* ALIGN — advance location counter to alignment boundary */. = ALIGN(8);               /* align to 8 bytes */
/* PROVIDE — define symbol only if not already defined (weak default) */PROVIDE(_stack_size = 0x400);  /* default 1KB stack; override in code */
/* Symbols for stack */.stack :{    . = ALIGN(8);    . += _stack_size;    _stack_top = .;} > RAM
/* FILL — fill unused bytes */.text :{    *(.text)    . = ALIGN(4);    FILL(0xFF)             /* fill flash gaps with 0xFF (erased state) */} > FLASH

6. Weak symbols

ld
/* In linker script — provide weak default ISR */PROVIDE(NMI_Handler        = Default_Handler);PROVIDE(HardFault_Handler  = Default_Handler);PROVIDE(SysTick_Handler    = Default_Handler);
c
// In C — weak default handler__attribute__((weak)) void Default_Handler(void) {    for (;;);  // spin — override this in application}
// Override by defining a non-weak symbol with the same namevoid SysTick_Handler(void) {    tick_count++;}

7. Common linker errors

ErrorCauseFix
region 'FLASH' overflowedBinary too large for flashEnable LTO, -Os, remove unused code; --gc-sections
region 'RAM' overflowedToo much RAM usedReduce stack size, use static buffers, check .bss size
undefined reference to '_estack'Missing linker script symbolDefine _estack in linker script
no rule to process file.ld extension not recognizedPass with -T script.ld
cannot find linker scriptWrong pathUse -L dir -T name.ld
Data section .data at wrong addressLMA not setAdd AT(_etext) after .data section definition
bash
# Analyze section sizesarm-none-eabi-size firmware.elfarm-none-eabi-size -A firmware.elf    # verbose per-section
# Show all sections and their addressesarm-none-eabi-objdump -h firmware.elf
# Check if .data LMA is in flash rangearm-none-eabi-readelf -S firmware.elf | grep -A2 "\.data"

For linker script anatomy details, see references/linker-script-anatomy.md [blocked].

Related skills

  • Use skills/embedded/openocd-jtag for flashing to addresses defined in linker script
  • Use skills/embedded/freertos for FreeRTOS heap placement in specific RAM regions
  • Use skills/binaries/linkers-lto for linker LTO and symbol flags
  • Use skills/binaries/elf-inspection to inspect section sizes and addresses

Source and attribution

Source:mohitmishra786/low-level-dev-skillsinskills/embedded/linker-scriptsat commitbdc5847

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from mohitmishra786/low-level-dev-skills

Zig Debugging

mohitmishra786

Guides debugging of Zig programs with GDB, LLDB, panic interpretation, error return traces, logging, and IDE setup.

Software Development253updated 3 months ago

Simd Intrinsics

mohitmishra786

Guides writing and diagnosing SIMD vectorization with x86 SSE/AVX and ARM NEON intrinsics.

Software Development253updated 3 months ago

Zig Cross

mohitmishra786

Guides Zig cross-compilation: target triples, CPU features, zig cc for C, embedded and WASM targets.

Software Development253updated 3 months ago

Rustc Basics

mohitmishra786

Guides Rust compiler configuration: RUSTFLAGS, Cargo profiles, build tuning, and inspecting MIR or assembly output.

Software Development253updated 3 months ago

Zig Cinterop

mohitmishra786

Guides Zig C interoperability: @cImport, translate-c, extern and packed structs, and mixed C/Zig builds.

Software Development253updated 3 months ago

Zig Build System

mohitmishra786

Guides writing and debugging Zig build.zig files, including targets, C sources, options, tests and package manifests.

Software Development253updated 3 months ago

More in Software Development

Playground

anthropics

Featured

Builds self-contained interactive HTML playgrounds with controls, live preview, and copyable prompt output.

Software Development37Kupdated today

M5 Onboard

anthropics

Featured

Provisions M5Stack ESP32 boards by detecting them on USB, flashing UIFlow 2.0 firmware, and installing a MicroPython app bundle.

Software Development37Kupdated today

Cardputer Buddy

anthropics

Featured

Guides iterating on a Cardputer-Adv MicroPython app bundle: adding apps, pushing files over USB-serial, tailing logs, and running REPL commands.

Software Development37Kupdated today

Web Design Guidelines

vercel-labs

Featured

Reviews UI code against Web Interface Guidelines fetched from a remote source and reports findings as file:line entries.

Software Development32Kupdated 5 weeks ago

Vercel React Native Skills

vercel-labs

Featured

React Native and Expo best-practice rules covering list performance, animation, navigation, UI patterns, state, and monorepo setup.

Software Development32Kupdated 5 weeks ago

Vercel React Best Practices

vercel-labs

Featured

Vercel's React and Next.js performance guidelines, organized as 70 rules for writing, reviewing, and refactoring code.

Software Development32Kupdated 5 weeks ago
Linker Scripts · skills/embedded/linker-scripts Agent Skill | SourceWeft