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
esp32c5	Y
esp32c6	Y
esp32c61	Y
esp32h2	Y
esp32p4	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, and where its data will be stored.

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

   It's important to note that the algorithm cannot be loaded at the start of RAM, because probe-rs loads a short header prior to the algo. IRAM origin and length can be obtained from esp-hal. Eg: ESP32-C3 memory map RWDATA should be accessible via the data bus, should be at least 96K in size, and must not overlap with IRAM. IRAM and RWDATA must not overlap with instruction/data caches or the memory reserved for ROM functions.
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 device specific data in chip/<chip_name>.rs, and add the file to the list of paths in main.rs. Take an existing chip as a reference. Obtain the ROM memory init addresses from the ROM code elf files.
9. (Optional) Implement code necessary to set maximum CPU speed.
10. 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);

11. Use target-gen without the update flag to generate a new yaml algorithm.
12. Update the resulting yaml file
13. Update name
14. 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
15. Add load_address under flash_algorithms and assign the IRAM ORIGIN value (step 4).
16. Add data_load_address under flash_algorithms and assign an appropriate value residing in DRAM.
17. Add transfer_encoding: Miniz under load_address
18. Upstream the new updates to probe-rs.