Baremetal Startup

---
name: baremetal-startup
description: 'Use when writing reset-to-main startup code, vector tables, VTOR, .data/.bss init, stack setup, startup.s, or crt0 for Cortex-M/RISC-V. Not for the bootloader jump: use bootloaders-embedded.'
---

# Bare-metal startup

## Contract

| Field | Bound contract |
|---|---|
| Trigger | Firmware never reaches `main()`, a new MCU is being brought up without a vendor HAL, or a custom `startup.s`, `Reset_Handler`, or crt0 is being written or debugged on Cortex-M or RISC-V. |
| Authority | Read-only: emits startup code, linker symbol requirements, and diagnostics to chat; the user places them in the project. Rollback is not needed because no file is written. No remote mutation. |
| Side effect | Chat output only. |
| Done | The startup path from the reset vector to `main()` is stated step by step, the vector table layout and the `.data` and `.bss` loops are given for the target core, and every linker symbol the code uses is listed with the linker script line that defines it. |

## Inputs

- Target core (Cortex-M0+, M3, M4F, M7, or RISC-V RV32 or RV64) and the vendor part.
- The linker script, or at least its `MEMORY` regions and the symbols it exports.
- Whether the firmware boots directly from flash or is launched by a bootloader at an offset.
- Which C runtime is linked (newlib, newlib-nano, none) and whether C++ static constructors exist.

## Procedure

1. State the boot sequence for the core before writing code. On Cortex-M the hardware loads `SP` from vector 0 and branches to vector 1, `Reset_Handler`. On RISC-V the core starts at the reset address with `sp` undefined, so the first instruction sets it. Done when: the sequence is written as an ordered list from power-on to `main()`.

   Cortex-M vector table head:

   | Index | Entry |
   |---|---|
   | 0 | Initial stack pointer (`_estack`) |
   | 1 | `Reset_Handler` |
   | 2 | `NMI_Handler` |
   | 3 | `HardFault_Handler` |
   | 4 and up | Fault handlers, then device IRQ handlers in NVIC order |

2. Write the vector table and `Reset_Handler` for Cortex-M. Copy `.data` from its load address in flash to its run address in RAM, zero `.bss`, then call `SystemInit` and `main`. Compare addresses with an unsigned branch (`bcc`), because addresses are unsigned. Done when: the assembly assembles for the target and the three symbol pairs come from the linker script.

   ```asm
   .syntax unified
   .thumb

   .section .isr_vector,"a",%progbits
   .global g_pfnVectors
   g_pfnVectors:
       .word _estack
       .word Reset_Handler
       .word NMI_Handler
       .word HardFault_Handler
       /* remaining fault and device IRQ vectors from the vendor CMSIS header order */

   .section .text.Reset_Handler
   .thumb_func
   .global Reset_Handler
   Reset_Handler:
       ldr r0, =_sidata        /* .data load address in flash */
       ldr r1, =_sdata         /* .data run address in RAM */
       ldr r2, =_edata
       b   copy_check
   copy_data:
       ldr r3, [r0], #4
       str r3, [r1], #4
   copy_check:
       cmp r1, r2
       bcc copy_data
       ldr r2, =_sbss
       ldr r4, =_ebss
       movs r3, #0
       b   zero_check
   zero_bss:
       str r3, [r2], #4
   zero_check:
       cmp r2, r4
       bcc zero_bss
       bl  SystemInit
       bl  main
       b   .
   ```

3. Define the linker symbols the startup code names. `_estack` is the top of RAM, `_sidata` is the load address of `.data`, and `_sdata`, `_edata`, `_sbss`, `_ebss` bracket the sections. Done when: each symbol appears in the linker script and `.data` carries `AT> FLASH` so its load and run addresses differ.

   ```ld
   _estack = ORIGIN(RAM) + LENGTH(RAM);
   _sidata = LOADADDR(.data);
   ```

4. Relocate the vector table when the image does not sit at the default boot address. Write `SCB->VTOR`, then `__DSB()` and `__ISB()`. The table base must be aligned to its own size rounded up to a power of two, with a minimum of 128 bytes on ARMv7-M; the mask below is the ARMv7-M `TBLOFF` field and a table with many vectors needs coarser alignment. Done when: `VTOR` holds the address of this image's `g_pfnVectors` and an interrupt reaches this image's handler.

   ```c
   void relocate_vector_table(uint32_t base)
   {
       SCB->VTOR = base & 0xFFFFFF80U;   /* ARMv7-M TBLOFF field; align to table size */
       __DSB();
       __ISB();
   }
   ```

5. Write the RISC-V entry when the target is RISC-V. Set `sp`, zero `.bss` with `sw` on RV32 or `sd` on RV64, set `mtvec` to the trap handler, and call `main`. Done when: the entry assembles for the target XLEN and `mtvec` points at a valid handler before interrupts are enabled.

   ```asm
   .section .text.entry
   .global _start
   _start:
       la sp, _stack_top
       la t0, _bss_start
       la t1, _bss_end
   clear_bss:
       beq t0, t1, bss_done
       sw zero, 0(t0)      /* sd on RV64 */
       addi t0, t0, 4      /* 8 on RV64 */
       j clear_bss
   bss_done:
       la t0, trap_handler
       csrw mtvec, t0
       call main
       j .
   ```

6. Assign the remaining crt0 duties and confirm who owns each. Done when: every row below has an owner in the project.

   | Task | Owner |
   |---|---|
   | Copy `.data` from flash to RAM | `Reset_Handler` |
   | Zero `.bss` | `Reset_Handler` |
   | Initial stack | Vector 0 on Cortex-M; explicit `sp` load on RISC-V |
   | Heap (`_sbrk`) | Optional; newlib syscall or a custom allocator |
   | C++ static constructors | `__libc_init_array()` from newlib, called before `main` |
   | FPU enable on Cortex-M4F and M7 | `SystemInit`, by writing `SCB->CPACR` to grant CP10 and CP11 full access before any float instruction |

7. Keep `main` from returning. The `b .` after `bl main` catches a return; the body of `main` normally ends in a loop or `__WFI()`. Done when: a return from `main` lands in a known loop and not in the next bytes of flash.
8. Verify on the target: halt at `Reset_Handler` with the debugger, step the copy and zero loops, and inspect a known initialized global and a known zero global at the first line of `main`. Done when: both globals hold their expected values.

## Failure and recovery

| Symptom | Cause | Fix |
|---|---|---|
| HardFault on the first instruction | Vector 0 does not point into RAM | Set `_estack` to `ORIGIN(RAM) + LENGTH(RAM)`. |
| Initialized globals read as garbage | `.data` never copied | Add the copy loop and define `_sidata` with `LOADADDR(.data)`. |
| Zero-initialized globals are non-zero | `.bss` never zeroed | Add the zero loop over `_sbss` to `_ebss`. |
| Interrupts run the wrong handler or fault | `VTOR` points at another image's table | Write `SCB->VTOR` to this image's table and issue `__DSB(); __ISB();`. |
| Crash on the first float instruction | FPU not enabled on M4F or M7 | Set CP10 and CP11 in `SCB->CPACR` in `SystemInit`. |
| C++ constructor crashes before `main` | Constructors ran before clocks or peripherals were ready | Call `SystemInit` before `__libc_init_array`. |
| Execution falls off the end of `main` | No loop after `main` | Loop or `__WFI()` in `main`; keep `b .` after the call. |

## Output

Startup code for the target core (vector table, `Reset_Handler` or `_start`, `.data` and `.bss` loops), the list of linker symbols it requires with their defining lines, the `VTOR` relocation routine when the image is offset, and a debugger checklist for confirming globals at the first line of `main`.