Build note

The first jump: ESP32-S3 startup and memory, simply

An ESP32-S3 does not jump from reset straight into C. Its built-in ROM loads a program into RAM, then jumps to the program’s startup code. That startup code sets up the stack, clears zero-initialized variables, and calls the C function.

This example uses two parts of the ESP32-S3 memory map: one address range for instructions and another for data. Think of one shelf with two doors. The instruction bus and data bus can sometimes use different addresses for the same physical RAM. Those addresses are two views of one shelf, not two shelves.

For a line-by-line explanation of the exact assembly and linker script, see ESP32-S3 start.S and linker.ld, line by line.

From reset to C

Reset
  ↓
ROM reads the image from flash
  ↓
ROM loads the image's RAM sections
  ↓
_start sets the stack and clears .bss
  ↓
baremetal_main() runs

This project uses an image marked --ram-only-header, which tells the ROM bootloader to load the image’s RAM sections. It then jumps to _start. The image is written at flash offset 0x0, which replaces the usual second-stage bootloader. The project README warns that you must restore the ESP-IDF bootloader before returning to that project.

The linker script chooses addresses for the program’s sections. It does not configure RAM, caches, or peripherals. The startup code uses the addresses that the linker assigned.

What gets built and what gets flashed

The computer builds the image. The chip runs it later.

On the computer:
start.S + main.c  →  start.o + main.o
objects + linker.ld  →  firmware.elf
firmware.elf + esptool  →  firmware.bin
                              ↓ flash this file
On the ESP32-S3:
ROM loads RAM sections  →  _start  →  baremetal_main()

The .o files are compiled pieces of the program. The linker reads those files and linker.ld to create firmware.elf. It chooses section addresses and fills symbols such as __bss_start and __stack_top.

Next, esptool elf2image --ram-only-header converts the ELF into firmware.bin, an ESP image with a header and RAM load addresses. The ROM needs that image format, so this project uses esptool instead of making a plain raw binary with objcopy. The image contains the compiled start.S instructions. It does not contain the linker.ld file itself; it carries the addresses and image information chosen during linking.

ENTRY(_start) tells the linker which ELF entry point to use. esptool puts that entry point in the image. The chip’s reset vector still enters the ROM. The ROM reads the image, loads its RAM sections, and then jumps to _start.

In this project, the ROM loads initialized sections such as .data at their linked RAM addresses. Therefore, start.S does not need a .data copy loop. It sets the stack, clears .bss, and calls baremetal_main(). A copy loop is needed in a different layout only when .data is stored at one address and must run from another.

The memory this program uses

The ESP32-S3 has 512 KB of internal SRAM. The Technical Reference Manual divides it into instruction-only, data-only, and shared blocks. This example uses only a small part of that memory.

Memory Address range How this project uses it
SRAM 0 Instruction: 0x40370000–0x40377FFF The linker uses 0x40374000–0x40377FFF for code. It reserves the first 0x410 bytes of that window for vectors.
SRAM 1 Data: 0x3FC88000–0x3FCEFFFF Holds constants, variables, .bss, and the stack. The linker uses 0x53700 bytes, ending just before 0x3FCDB700.
SRAM 1 again Instruction: 0x40378000–0x403DFFFF This is another address view of the same SRAM 1. The project does not place code here.
SRAM 2 Data: 0x3FCF0000–0x3FCFFFFF A 64 KB data-only block. This linker script does not use it as general RAM.

The addresses 0x40378000 and 0x3FC88000 are two views of the same 416 KB of SRAM 1. Their difference is 0x6F0000. Writing a byte through one address changes the same byte seen through the other. The alias does not add memory.

That matters when choosing addresses. If a linker script put code at 0x40378000 and data at 0x3FC88000, those sections could overlap in physical RAM. This example avoids that problem by placing code in SRAM 0 and data in SRAM 1.

The lower 16 KB of SRAM 0 may be assigned to the instruction cache. This linker layout assumes that setting, so it uses the upper 16 KB for code. ESP-IDF also lists 0x40374000 as usable IRAM only for its 16 KB instruction-cache configuration. The ESP32-S3 manual allows more than one cache size, so check the cache setting before using this address on a board.

Where the linker puts each part

The linker script at c-prog/c-28-esp32s3/01-esp32-baremetal/linker.ld gives each kind of program data a place:

Program part Where it goes Why it goes there
.text and instruction literals SRAM 0, after 0x40374410 The processor fetches instructions through the instruction bus.
.rodata and .data SRAM 1, starting at 0x3FC88000 The processor reads constants and variables through the data bus.
.bss After the other static data in SRAM 1 It holds zero-initialized variables. _start clears it before C runs.
Stack 0x3FCDA700–0x3FCDB6FF The final 4 KB of the chosen region. Function calls and local variables use it. It grows down from the top.

The ROM loader also loads initialized .data values from the image into RAM. start.S does not copy .data; it only sets the stack and clears .bss. If a future linker script stores .data at a different address from where it runs, startup code will need a copy step.

The project also writes to memory-mapped peripheral registers. These are control addresses, not extra RAM: UART0 starts at 0x60000000, GPIO at 0x60004000, and IO MUX at 0x60009000.

Checks before using the example

  • Check the cache setting. The linker uses 0x40374000 only if the lower 16 KB of SRAM 0 is assigned to instruction cache. A 32 KB cache leaves no code RAM at that address.
  • Check the UART output register. The current main.c defines GPIO_ENABLE1_W1TS_REG as 0x60004034. Espressif defines that address as the write-one-to-clear register. The write-one-to-set register is 0x60004030. As written, the code clears GPIO43’s output-enable bit instead of setting it, so UART output is not verified.
  • Remember the flash warning. Writing this image at 0x0 replaces the ESP-IDF second-stage bootloader.
  • The startup assembly may need a small adjustment. With Xtensa GCC 15.2, the current start.S puts its l32r literal words too far after the instructions. Moving those words above _start fixes that assembler error without changing the memory map.

Sources and authorship

The address ranges and bus rules come from Espressif’s ESP32-S3 Technical Reference Manual, Table 4.3-1. The ESP-IDF memory layout and linker memory definitions show how the chip’s address views are used. The application startup flow explains the ROM-to-application handoff. The GPIO register definitions identify the UART pin’s output-enable register.

The startup flow and linker sections are based on linux-utils/vimwiki/embedding/12-esp32-s3-bare-metal-startup.md and the files in c-prog/c-28-esp32s3/01-esp32-baremetal/. Written by Rupesh with AI assistance for drafting and editing.