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.