ESP8266 boot process

I decided to write my own version of esptool for windows to create rom images. Although there is already a windows version available it can’t create new type firmware images for use with the latest versions of the boot loader from the espressif sdk (e.g v1.2). I could have just used the python version, but as with all this playing it was as much for my education and entertainment as for any practical purpose. In the process I ended up learning more about the boot process than I expected and writing my own boot loader.

As I haven’t seen a lot of info about it online I thought it might be useful to document the normal boot process here. The built in first stage bootloader reads the start of the SPI flash where it expects to find a simple 8 byte structure:

typedef struct {
	uint8 magic;
	uint8 sect_count;
	uint8 flags1;
	uint8 flags2;
	uint32 entry_addr;
} rom_header;

The magic value should be 0xe9. sect_count contains the number (may be zero) of elf sections to load to iram (this does not include the .irom.text section). flags1 & flags2 control the flash size, clock rate and IO mode. entry_addr contains the entry point to start executing user code from.

After the header come the actual elf sections. Each is headed by another 8 byte structure (followed immediately by the data itself):

typedef struct {
	uint32 address;
	uint32 length;
} sect_header;

The first stage boot loader verifies the magic and sets the flash mode according to the flags. Then it copies each section to the corresponding address from the header (which should be within the iram section starting at 0x40100000). As the sections are loaded a single checksum is created of all the data (headers are not included). If the final checksum matches the one stored at the end of the elf section on the flash it will call the function found at entry_addr.

The whole of the flash is also mapped to an area of memory from 0x40200000. The .irom.text elf section just sits somewhere on the flash after the other elf sections and does not have a header like those destined for iram. The default linker script eagle.v6.ld bases the section at 0x40240000 so it should be written to 0x40000. This mapping does not occur until later (presumably by sdk library code), so you can’t access the flash directly in memory in the boot loader – it must be accessed through spi read calls.

7 thoughts on “ESP8266 boot process”

  1. Hello, I’m sorry to bother you on this, but googling gives nothing except that you’re the only one to have some knowledge of the boot process of the 8266. I also know this is old stuff, but I was wondering if you could give me some hints because I’m stuck on a very bizarre issue. Would you mind if I send the details over email ? Thank you. Best regards.

  2. Hi there ! interesting blog, been reading a few posts you made and learning so much !.

    just wanted to say i tried to compile your code here (the structures) but they don’t. i think it’s not valid C code.

    anyway your doing a great job, and I am learning lots 🙂
    keep it up!


  3. Hi Richard and thank you for all the useful information you have in here. I am new to ESP8266 and have learned a lot about boot process here.

    I have been figuring out if the first stage boot loader is in the processors ROM or in the Flash. I guess it is in the ROM. If this is in ROM then there is no risk of messing flash and leave the device useless.

    Could you please confirm it.

Leave a Reply