Merge pull request #1 from MabezDev/cleanup-and-multichip

Multi-chip framework & docs

Author: MabezDev

.cargo/config.toml

@@ -1,18 +1,8 @@
 
 
-[target.riscv32imc-unknown-none-elf]
-## For flash loader
+[target.'cfg(any(target_arch = "xtensa", target_arch = "riscv32"))']
 rustflags = [
-    "-C", "link-arg=-Tld/esp32c3.x",
     "-C", "link-arg=-Tld/loader.x",
     "-C", "link-args=-Map=target/esp-loader.map",
     "-C", "link-args=--nmagic",
-
-    # We don't know where the flash loader will be
-    # placed in memory, so we need to create
-    # position independent code (pic).
-    # "-C", "relocation-model=pic", # no longer required after https://github.com/probe-rs/probe-rs/pull/822
-]
-
-[build]
-target = "riscv32imc-unknown-none-elf"
+]

Cargo.toml

@@ -12,6 +12,9 @@ ufmt = { version = "0.1.0", optional = true }
 [features]
 log = ["ufmt"]
 
+# targets
+esp32c3 = []
+
 [profile.release]
 codegen-units = 1
 debug = false

README.md

@@ -1,10 +1,49 @@
 ### esp flash loader
 
-A WIP probe-rs flash loader.
+A probe-rs flash loader for Espressif chips.
 
 To build the flash loader:
 
 ```bash
-cargo build --release # builds the on chip flasher code
-target-gen elf target/riscv32imc-unknown-none-elf/release/esp-flashloader > output/esp32c3.yaml # dumps the elf to yaml format for probe-rs
+$ 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
 ```
+
+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
+```
+
+## Chip support
+
+|name   |supported|
+|-------|---------|
+|esp32c3|   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.
+3. Inside the ROM API linker script, add a memory section detailing where the program will be loaded.
+    ```c
+    MEMORY {
+        /* Start 64k into the RAM region */
+        IRAM : ORIGIN = 0x40390000, LENGTH = 0x40000
+    }
+    ```
+    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.
+    ```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");
+    }
+    ```
+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.

build.rs

@@ -8,7 +8,10 @@ fn main() {
     fs::copy("ld/loader.x", out_dir.join("loader.x")).unwrap();
     println!("cargo:rerun-if-changed=ld/loader.x");
 
-    // TODO feature gate per chip?
-    fs::copy("ld/esp32c3.x", out_dir.join("esp32c3.x")).unwrap();
-    println!("cargo:rerun-if-changed=ld/rom.x");
-}
+    #[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");
+    }
+}

build.sh

@@ -29,6 +29,17 @@ SECTIONS {
 
         . = ALIGN(4);
     } > IRAM
+
+    /* Description of the flash algorithm */
+    DeviceData : 
+    {
+        /* The device data content is only for external tools,
+         * and usually not referenced by the code.
+         *
+         * The KEEP statement ensures it's not removed by accident.
+         */
+        KEEP(*(DeviceData))
+    } > IRAM
 }
 
 

ld/loader.x

@@ -0,0 +1,60 @@
+---
+name: esp32
+manufacturer: ~
+variants:
+  - name: esp32c3
+    part: ~
+    cores:
+      - name: main
+        type: riscv
+        core_access_options:
+          Riscv: {}
+    memory_map:
+      - Nvm:
+          range:
+            start: 0
+            end: 8388608
+          is_boot_memory: true
+          cores:
+            - main
+      - Ram:
+          range:
+            start: 1077411840
+            end: 1077805056
+          is_boot_memory: false
+          cores:
+            - main
+      - Ram:
+          range:
+            start: 1070071808
+            end: 1070137344
+          is_boot_memory: false
+          cores:
+            - main
+    flash_algorithms:
+      - esp32c3-flashloader
+flash_algorithms:
+  - name: esp32c3-flashloader
+    description: A flash loader for the esp32c3.
+    default: true
+    instructions: QREGxjcFOUADRQUHGcEBRS2glwDH/+eAoHCBRZcAx//ngIAUlwDH/+eAwBEZ5QFFtwU5QAVGI4jFBrJAQQGCgDGBFwPH/2cAYw4XA8f/ZwBjDRN3NgABxxMFoAqCgK6GsoU2hhcDx/9nAIMMAUWCgAAAAAA=
+    load_address: 1077477376
+    pc_init: 0
+    pc_uninit: 108
+    pc_program_page: 82
+    pc_erase_sector: 64
+    pc_erase_all: 74
+    data_section_offset: 116
+    flash_properties:
+      address_range:
+        start: 0
+        end: 67108864
+      page_size: 2048
+      erased_byte_value: 255
+      program_page_timeout: 1000
+      erase_sector_timeout: 2000
+      sectors:
+        - size: 4096
+          address: 0
+    cores:
+      - main