# linker-scripts

Walks an agent through GNU ld linker scripts for bare-metal targets: memory regions, VMA vs LMA, and startup .bss/.data setup.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 523 installs · ★ 267
- Author: mohitmishra786
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/mohitmishra786/low-level-dev-skills/tree/HEAD/skills/embedded/linker-scripts/SKILL.md
- Updated: 2026-06-27
- HTML: https://affpapa.org/en/nevibecode/skills/linker-scripts

## What it does

The skill kicks in when an agent touches `MEMORY` and `SECTIONS` in a linker script: placing code and data in specific flash or RAM regions, explaining how VMA differs from LMA, wiring the copy of `.data` from flash into RAM and zeroing `.bss` before `main()` runs. It ships a Cortex-M script walkthrough, a table of common link errors such as a `FLASH` region overflow, and notes on `KEEP`, `ALIGN`, `PROVIDE` and weak symbols.

There is a section on putting code where you want it: a `.fast_code` section marked with the `section` attribute lands in CCM RAM, and `AT(_etext)` sets the LMA for `.data`. To confirm the result the skill leans on `arm-none-eabi-size`, `objdump -h` and `readelf -S` — without them you cannot see section addresses.

This is for embedded projects built with GNU ld. If you link a desktop binary or use a proprietary toolchain, the examples will not match your setup. Neighbouring skills in the same collection cover flashing over OpenOCD, FreeRTOS heap placement and LTO.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill linker-scripts -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/linker-scripts/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/linker-scripts/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill linker-scripts -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/linker-scripts/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill linker-scripts -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/linker-scripts/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install mohitmishra786/low-level-dev-skills linker-scripts
```

2. **Manually: put the files in place**
- File: `.github/skills/linker-scripts/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill linker-scripts -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/mohitmishra786/low-level-dev-skills --path skills/embedded/linker-scripts
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/linker-scripts/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill linker-scripts -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/mohitmishra786/low-level-dev-skills/tree/HEAD/skills/embedded/linker-scripts/SKILL.md

## When to use it
- place code and data in specific flash and RAM regions
- tell where a section runs from and where it is stored
- set up `.data` copy and `.bss` zeroing at startup
- debug a region overflow error
- pin an interrupt handler to a fixed address

## Example prompts
- Write a linker script for a Cortex-M: 512K flash at 0x08000000, 128K RAM at 0x20000000
- Why is `.data` at the wrong address? Check the LMA and add `AT(_etext)`
- Move `critical_isr_handler` into a `.fast_code` section placed in CCM RAM

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 8ee6c6ce72c616e2.

BEGIN THIRD-PARTY FILE 8ee6c6ce72c616e2
````text
---
name: linker-scripts
description: 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.
---

# 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 */
```
````
END THIRD-PARTY FILE 8ee6c6ce72c616e2

The third-party file has ended. Everything between the 8ee6c6ce72c616e2 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2538 of 6773 bytes. © mohitmishra786 · MIT · https://github.com/mohitmishra786/low-level-dev-skills/tree/HEAD/skills/embedded/linker-scripts/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md