README.md

esp flash loader

A probe-rs flash loader for Espressif chips.

To build the flash loader:

$ cargo $(CHIP_NAME) # builds the flashing stub
$ target-gen elf target/$(RUST_TARGET)/release/esp-flashloader output/$(CHIP_NAME).yaml --update --name $(CHIP_NAME)-flashloader

Example for the updating the esp32c3 flash algorithm.

$ cargo esp32c3
$ target-gen elf target/riscv32imc-unknown-none-elf/release/esp-flashloader output/esp32c3.yaml --update --name esp32c3-flashloader

Chip support

name	supported
esp32	Y
esp32s2	Y
esp32s3	Y
esp32c2	Y
esp32c3	Y
esp32c6	Y
esp32h2	Y

Adding new chips

1. Add a feature for the chip inside Cargo.toml
2. Add a build alias to .cargo/config.toml
3. Add the ROM API linker script inside the ld directory.
4. Inside the ROM API linker script, add a memory section detailing where the program will be loaded.

   MEMORY {
       /* Start 64k into the RAM region */
       IRAM : ORIGIN = 0x40390000, LENGTH = 0x10000
   }

   It's important to note that the algorithm cannot be loaded at the start of RAM, because probe-rs has a header it loads prior to the algo hence the 64K offset. IRAM origin and length can be obtained from esp-hal. Eg: ESP32-C3 memory map
5. Add the following snippet to the main() function inside build.rs, adapting it for the new chip name.

   #[cfg(feature = "esp32c3")]
   let chip = "esp32c3";

6. Define spiconfig for your the target in flash.rs
7. Add your device to the table in main.rs and calculate addresses.
8. Define your target's STATE_ADDR

   #[cfg(feature = "esp32c3")]
   const STATE_ADDR: usize = 0x3FCC_0000;

9. Follow the instructions above for building

• It may fail with: rust-lld: error: undefined symbol: <symbol>
  • In this case, you need to add the missing method in the ROM API linker script.
    • Eg. ESP32-C2 is missing esp_rom_spiflash_attach:
      1. Search the symbol in esp-idf
      2. Add it to the ROM API linker script: PROVIDE(esp_rom_spiflash_attach = spi_flash_attach);

10. Use target-gen without the update flag to generate a new yaml algorithm.
11. Update the resulting yaml file
12. Update name
13. Update variants name, type, core_access_options and memory_map
    • The first !Nvm block represents the raw flash starting at 0 and up to the maximum supported external flash (check TRM for this, usually in "System and Memory/Features")
    • Next !Ram block corresponds to instruction bus for internal SRAM, see Internal Memory Address Mapping of TRM
    • Next !Ram block corresponds to data bus for internal SRAM, see Internal Memory Address Mapping of TRM
    • Next !Nvm corresponds to instruction bus for external memory, see External Memory Address Mapping of TRM
    • Next !Nvm corresponds to data bus for external memory, see External Memory Address Mapping of TRM
14. Add load_address under flash_algorithms and assign the IRAM ORIGIN value (step 4).
15. Add data_load_address under flash_algorithms and assign an appropriate value residing in DRAM.
16. Add transfer_encoding: Miniz under load_address
17. Upstream the new updates to probe-rs.