Add ESP32-C2 support (#4)

* feat: Initial support for ESP32-C2

* docs: Update readme

* docs: Update readme

* feat: Add esp32c2 yaml

* feat: Add load address

* fix: Fix names

* docs: Update instructions

* docs: Update supported chips

* Update output/esp32c2.yaml

Co-authored-by: Jesse Braham <jessebraham@users.noreply.github.com>

* docs: Add docstrings

* docs: Update instructions

---------

Co-authored-by: Jesse Braham <jessebraham@users.noreply.github.com>

Author: SergioGasquez

Cargo.toml

@@ -13,6 +13,7 @@ ufmt = { version = "0.1.0", optional = true }
 log = ["ufmt"]
 
 # targets
+esp32c2 = []
 esp32c3 = []
 esp32c6 = []
 esp32h2 = []
@@ -24,4 +25,4 @@ debug-assertions = false
 incremental = false
 lto = "fat"
 opt-level = 'z'
-overflow-checks = false
+overflow-checks = false

README.md

@@ -6,27 +6,29 @@ To build the flash loader:
 
 ```bash
 $ cargo build --release --feature $(CHIP_NAME) --target $(RUST_TARGET) # builds the flashing stub
-$ target-gen elf target/$(RUST_TARGET)/release/esp-flashloader output/esp32.yaml --update --name $(CHIP_NAME)-flashloader
+$ 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.
 
 ```bash
 $ cargo build --release --features esp32c3 --target riscv32imc-unknown-none-elf
-$ target-gen elf target/riscv32imc-unknown-none-elf/release/esp-flashloader output/esp32.yaml --update --name esp32c3-flashloader
+$ target-gen elf target/riscv32imc-unknown-none-elf/release/esp-flashloader output/esp32c3.yaml --update --name esp32c3-flashloader
 ```
 
 ## Chip support
 
-|name   |supported|
-|-------|---------|
-|esp32c3|   Y     |
-|esp32c6|   Y     |
+| name    | supported |
+| ------- | --------- |
+| esp32c2 | Y         |
+| esp32c3 | Y         |
+| esp32c6 | Y         |
+| esp32h2 | Y         |
 
 ## Adding new chips
 
 1. Add a feature for the chip inside `Cargo.toml`
-2. Add the ROM API linker script inside the `ld` directory.
+2. Add the [ROM API linker script](https://github.com/search?q=repo%3Aespressif%2Fesp-idf++path%3A*rom.api.ld&type=code) inside the `ld` directory.
 3. Inside the ROM API linker script, add a memory section detailing where the program will be loaded.
     ```c
     MEMORY {
@@ -35,16 +37,28 @@ $ target-gen elf target/riscv32imc-unknown-none-elf/release/esp-flashloader outp
     }
     ```
     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.
-4. Add the following snippet to the bottom of the `main()` function inside `build.rs`, adapting it for the new chip name.
+    IRAM origin and length can be obtained from esp-hal. Eg: [ESP32-C3 memory map](https://github.com/esp-rs/esp-hal/blob/ff80b69183739d04d1cb154b8232be01c0b26fd9/esp32c3-hal/ld/db-esp32c3-memory.x#L5-L22)
+4. Add the following snippet to the `main()` function inside `build.rs`, adapting it for the new chip name.
     ```rust
     #[cfg(feature = "esp32c3")]
-    {
-        fs::copy("ld/esp32c3.x", out_dir.join("esp32c3.x")).unwrap();
-        println!("cargo:rerun-if-changed=ld/esp32c3.x");
-        println!("cargo:rustc-link-arg=-Tld/esp32c3.x");
-    }
+    let chip = "esp32c3";
     ```
-5. Follow the instructions above for building
-6. Use `target-gen` _without_ the `update` flag to generate a new yaml algorithm.
-7. merge the new flash algorithm into the the main `esp32.yaml`
-8. Upstream the new updates to probe-rs.
+5. [Define `spiconfig` for your the target in `main.rs`](https://github.com/search?q=repo%3Aespressif%2Fesp-idf+ets_efuse_get_spiconfig+path%3A*c3*&type=code)
+6. 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](https://github.com/search?q=repo%3Aespressif%2Fesp-idf+esp_rom_spiflash_attach+path%3A*c2*&type=code)
+        2. Add it to the ROM API linker script: `PROVIDE(esp_rom_spiflash_attach = spi_flash_attach);`
+7. Use `target-gen` _without_ the `update` flag to generate a new yaml algorithm.
+8. Update the resulting yaml file
+   1. Update `name`
+   2. 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
+   3. Add `load_address` under `flash_algorithms` and assing the IRAM `ORIGIN` value (step 3).
+9.  Merge the new flash algorithm into the the main `esp32c3.yaml`
+10.  Upstream the new updates to probe-rs.

build.rs

@@ -8,16 +8,21 @@ fn main() {
     fs::copy("ld/loader.x", out_dir.join("loader.x")).unwrap();
     println!("cargo:rerun-if-changed=ld/loader.x");
 
+    #[cfg(feature = "esp32c2")]
+    let chip = "esp32c2";
     #[cfg(feature = "esp32c3")]
     let chip = "esp32c3";
     #[cfg(feature = "esp32c6")]
     let chip = "esp32c6";
     #[cfg(feature = "esp32h2")]
     let chip = "esp32h2";
 
-    
     {
-        fs::copy(format!("ld/{}.x", chip), out_dir.join(format!("{}.x", chip))).unwrap();
+        fs::copy(
+            format!("ld/{}.x", chip),
+            out_dir.join(format!("{}.x", chip)),
+        )
+        .unwrap();
         println!("cargo:rerun-if-changed=ld/{}.x", chip);
         println!("cargo:rustc-link-arg=-Tld/{}.x", chip);
     }