Build note
ESP32-S3 start.S and linker.ld, line by line
This is the code-level companion to the short ESP32-S3 memory-map guide. It explains the project’s start.S and linker.ld without changing either source file.
The two files have different jobs. linker.ld assigns addresses to code, data, and the stack. start.S reads the addresses the linker provides, prepares C, and calls baremetal_main().
start.S: prepare C to run
The ROM bootloader loads the image’s RAM sections before it jumps to _start. The code below then sets the stack and clears .bss.
.section .entry.text, "ax", @progbits
.align 4
.global _start
.type _start, @function
_start:
l32r a1, .Lstack_top
l32r a2, .Lbss_start
l32r a3, .Lbss_end
movi a4, 0
.Lbss_loop:
bgeu a2, a3, .Lbss_done
nop
s32i a4, a2, 0
addi a2, a2, 4
j .Lbss_loop
nop
.Lbss_done:
call0 baremetal_main
.Lhalt:
j .Lhalt
nop
.align 4
.Lstack_top:
.word __stack_top
.Lbss_start:
.word __bss_start
.Lbss_end:
.word __bss_end
.size _start, . - _start
The first four lines describe and export the startup code:
| Line | Code | Meaning |
|---|---|---|
| 1 | .section .entry.text, "ax", @progbits |
Put startup instructions in .entry.text. a keeps the section in the program, x marks it executable, and @progbits says it contains bytes. |
| 2 | .align 4 |
Align the address of the next item for the Xtensa assembler. |
| 3 | .global _start |
Make _start visible to the linker and image builder. |
| 4 | .type _start, @function |
Mark _start as a function in the ELF file. |
| 6 | _start: |
Name the first startup instruction. The image’s entry address points here. |
Next, _start loads three addresses and prepares a zero value:
| Line | Code | Meaning |
|---|---|---|
| 7 | l32r a1, .Lstack_top |
Load the word at .Lstack_top into a1, the stack pointer. The word contains the linker’s __stack_top address. |
| 8 | l32r a2, .Lbss_start |
Load the first address of .bss into a2. |
| 9 | l32r a3, .Lbss_end |
Load the address just after .bss into a3. |
| 10 | movi a4, 0 |
Put zero in a4. The loop stores this value into .bss. |
| 12 | .Lbss_loop: |
Mark the start of the loop that clears .bss. |
| 13 | bgeu a2, a3, .Lbss_done |
Compare the addresses as unsigned values. Exit once the current address reaches the end. |
| 14 | nop |
Fill the Xtensa branch delay slot. |
| 15 | s32i a4, a2, 0 |
Store one 32-bit zero at the address in a2. |
| 16 | addi a2, a2, 4 |
Move to the next four-byte word in .bss. |
| 17 | j .Lbss_loop |
Return to the start of the clearing loop. |
| 18 | nop |
Fill the jump delay slot. |
| 20 | .Lbss_done: |
Mark the point reached after every .bss word is zero. |
| 21 | call0 baremetal_main |
Call the C function using the Xtensa call0 convention. |
| 23 | .Lhalt: |
Name the fallback loop used if baremetal_main() returns. |
| 24 | j .Lhalt |
Stay here forever. Bare metal has no operating system to return to. |
| 25 | nop |
Fill the jump delay slot. |
The last lines provide literal words for the l32r instructions:
| Line | Code | Meaning |
|---|---|---|
| 27 | .align 4 |
Align the literal words for the assembler. |
| 28 | .Lstack_top: |
Name the word that follows. The .L prefix makes this a local label. |
| 29 | .word __stack_top |
Ask the linker to put the final stack-top address in this word. |
| 30 | .Lbss_start: |
Name the next word. |
| 31 | .word __bss_start |
Store the linker’s first .bss address here. |
| 32 | .Lbss_end: |
Name the last word. |
| 33 | .word __bss_end |
Store the linker’s end-of-.bss address here. |
| 35 | .size _start, . - _start |
Record the size of _start in the ELF metadata. |
The linker creates __stack_top, __bss_start, and __bss_end. The assembly loads those values from nearby words because l32r reads a nearby literal rather than embedding an arbitrary 32-bit address in the instruction.
Build caveat: the source puts these literal words after the instructions that use them. With Xtensa GCC 15.2, the assembler reports l32r out of range. Moving the three .word lines above _start fixes that error; it does not change the memory layout. This note describes the source as written and does not modify it.
linker.ld: assign addresses to sections
The linker script tells the linker which RAM ranges the program may use and where each section belongs.
ENTRY(_start)
STACK_SIZE = 0x1000;
MEMORY
{
/* The higher IRAM addresses alias physical D/IRAM used through DRAM. */
iram (rx) : ORIGIN = 0x40374000, LENGTH = 0x4000
dram (rw) : ORIGIN = 0x3FC88000, LENGTH = 0x53700
}
SECTIONS
{
/* Keep the vector area free; this first example does not install vectors. */
.vectors ORIGIN(iram) (NOLOAD) :
{
. += 0x410;
} > iram
.text : ALIGN(4)
{
KEEP(*(.entry.text))
*(.literal .literal.*)
*(.text .text.*)
} > iram
.rodata : ALIGN(4)
{
*(.rodata .rodata.*)
} > dram
.data : ALIGN(4)
{
__data_start = .;
*(.data .data.*)
. = ALIGN(4);
__data_end = .;
} > dram
.bss (NOLOAD) : ALIGN(4)
{
__bss_start = .;
*(.bss .bss.*)
*(COMMON)
. = ALIGN(4);
__bss_end = .;
} > dram
.stack ORIGIN(dram) + LENGTH(dram) - STACK_SIZE (NOLOAD) :
{
__stack_bottom = .;
. += STACK_SIZE;
__stack_top = .;
} > dram
/DISCARD/ :
{
*(.comment)
*(.note .note.*)
}
}
ASSERT(__bss_end <= __stack_bottom, "static data overlaps the stack")
ASSERT((__stack_top & 0xF) == 0, "stack top must be 16-byte aligned")
ASSERT(SIZEOF(.text) <= LENGTH(iram) - 0x410,
"code and literals exceed the dedicated instruction RAM window")
The first lines select the entry point, define the stack size, and name the allowed RAM ranges:
| Line | Code | Meaning |
|---|---|---|
| 1 | ENTRY(_start) |
Set _start as the ELF entry point. |
| 3 | STACK_SIZE = 0x1000 |
Reserve 4 KB for the stack. |
| 5–6 | MEMORY { ... } |
Begin the list of memory regions. |
| 7 | Comment | Warn that higher instruction addresses can alias the data-side SRAM. |
| 8 | iram (rx) ... |
Allow code in a 16 KB instruction-RAM window beginning at 0x40374000. |
| 9 | dram (rw) ... |
Allow read/write data in a selected part of SRAM beginning at 0x3FC88000. Its length is 0x53700 bytes. |
| 10 | } |
Finish the memory-region list. |
| 12–13 | SECTIONS { |
Begin assigning compiled input sections to the named regions. |
The vector reservation and .text section use the instruction-RAM window:
| Line | Code | Meaning |
|---|---|---|
| 14 | Comment | Explain why this example leaves space for vectors. |
| 15 | .vectors ORIGIN(iram) (NOLOAD) : |
Start a reserved section at the beginning of iram. NOLOAD keeps it out of the image file. |
| 16–18 | { ... } > iram |
Advance the location by 0x410 bytes and assign the reservation to iram. |
| 20 | .text : ALIGN(4) |
Start the instruction section with four-byte alignment. |
| 22 | KEEP(*(.entry.text)) |
Keep the startup section even if linker garbage collection is enabled. |
| 23 | *(.literal .literal.*) |
Place Xtensa literal pools beside the code that uses them. |
| 24 | *(.text .text.*) |
Add normal program instructions. |
| 25 | } > iram |
Place .text in the instruction-RAM region. |
The next sections place constants and variables in data RAM:
| Line | Code | Meaning |
|---|---|---|
| 27–30 | .rodata ... > dram |
Place read-only constants in data RAM. Read-only describes how the program uses them; it does not mean they live in flash. |
| 32 | .data : ALIGN(4) |
Start the initialized-variable section. |
| 34 | __data_start = .; |
Save the current address as the start of .data. |
| 35 | *(.data .data.*) |
Collect initialized global and static variables. |
| 36 | . = ALIGN(4); |
Round the end of .data up to a four-byte boundary. |
| 37 | __data_end = .; |
Save the address just after .data. |
| 38 | } > dram |
Place .data in data RAM. These symbols do not perform a copy by themselves. |
| 40 | .bss (NOLOAD) : ALIGN(4) |
Start zero-initialized storage. NOLOAD means the image does not contain initial bytes for it. |
| 42 | __bss_start = .; |
Give startup code the first address to clear. |
| 43 | *(.bss .bss.*) |
Collect zero-initialized global and static variables. |
| 44 | *(COMMON) |
Collect common symbols, another form of uninitialized global storage. |
| 45 | . = ALIGN(4); |
Align the end so the startup loop can clear complete words. |
| 46 | __bss_end = .; |
Give startup code the end address. The end itself is not part of .bss. |
| 47 | } > dram |
Place .bss in data RAM. |
The stack and final checks protect the layout:
| Line | Code | Meaning |
|---|---|---|
| 49 | .stack ... (NOLOAD) : |
Place a reserved stack section at the top of the selected dram region. |
| 51 | __stack_bottom = .; |
Record the low address of the stack. |
| 52 | . += STACK_SIZE; |
Reserve the 4 KB stack space. |
| 53 | __stack_top = .; |
Record the high address. Startup loads this into a1; the stack grows down. |
| 54 | } > dram |
Assign the stack reservation to data RAM. |
| 56 | /DISCARD/ : |
Start a rule for sections that should not enter the output image. |
| 57 | { |
Start the list of sections to discard. |
| 58 | *(.comment) |
Discard compiler comment metadata. |
| 59 | *(.note .note.*) |
Discard ELF note metadata. |
| 60 | } |
Finish the discard list. |
| 61 | } |
Finish the SECTIONS block. |
| 63 | ASSERT(__bss_end <= __stack_bottom, ...) |
Fail the link if .bss grows into the stack. |
| 64 | ASSERT((__stack_top & 0xF) == 0, ...) |
Fail the link if the stack top is not aligned to 16 bytes. |
| 65–66 | ASSERT(SIZEOF(.text) ... ) |
Fail the link if code and literals do not fit after the 0x410-byte reservation. |
How the two files fit the memory map
The linker script assigns _start and the other code to instruction RAM. It assigns .rodata, .data, .bss, and the stack to the data-side SRAM range. It also creates the symbols that startup needs.
The ROM loader fills the image sections before jumping to _start. Then the assembly loads __stack_top, __bss_start, and __bss_end. It sets the stack pointer and writes zero across .bss. This is why the linker and startup code must agree on section addresses and symbol names.
The data region is a project choice, not the full SRAM 1 range. The 16 KB instruction window is also conditional: this layout assumes the lower 16 KB of SRAM 0 is used as instruction cache. See the short memory-map guide for the alias, cache, UART-register, and flash-safety notes.
Source and authorship
The listings match c-prog/c-28-esp32s3/01-esp32-baremetal/start.S and linker.ld. The address choices are explained in the ESP32-S3 Technical Reference Manual and ESP-IDF’s memory layout. Written by Rupesh with AI assistance for drafting and editing.