Add better support for ESP32-C3 (#415)

* Add elf2image tool to create esp format binaries
* Add esp format target to esp port
* Add documentation on how to flash esp32-c3 target with both esp image and direct boot.

Author: tact1m4n3

.github/workflows/ci.yml

@@ -46,6 +46,24 @@ jobs:
         run: zig build test
         working-directory: tools/uf2
 
+  unit-test-esp-image:
+    name: Unit Test ESP Image
+    continue-on-error: true
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Zig
+        uses: mlugg/setup-zig@v1
+        with:
+          version: ${{ env.ZIG_VERSION }}
+      - name: Unit Test ESP Image
+        run: zig build test
+        working-directory: tools/esp_image
+
   stm32-gen-check:
     name: Check that stm32 generated code is up to date
     continue-on-error: true

build-internals/build.zig

@@ -6,7 +6,8 @@ const Module = Build.Module;
 const regz = @import("regz");
 pub const Patch = regz.patch.Patch;
 const uf2 = @import("uf2");
-const FamilyId = uf2.FamilyId;
+pub const FamilyId = uf2.FamilyId;
+const esp_image = @import("esp_image");
 
 pub fn build(b: *Build) void {
     _ = b.addModule("build-internals", .{
@@ -178,7 +179,7 @@ pub const BinaryFormat = union(enum) {
     uf2: uf2.FamilyId,
 
     /// The [firmware format](https://docs.espressif.com/projects/esptool/en/latest/esp32/advanced-topics/firmware-image-format.html) used by the [esptool](https://github.com/espressif/esptool) bootloader.
-    esp,
+    esp: esp_image.Options,
 
     /// Custom option for non-standard formats.
     custom: *Custom,

build-internals/build.zig.zon

@@ -5,6 +5,7 @@
     .dependencies = .{
         .regz = .{ .path = "../tools/regz" },
         .uf2 = .{ .path = "../tools/uf2" },
+        .esp_image = .{ .path = "../tools/esp_image" },
     },
     .paths = .{
         "LICENSE",

build.zig

@@ -70,6 +70,7 @@ pub fn build(b: *Build) void {
 fn generate_release_steps(b: *Build) void {
     const release_regz_step = b.step("release-regz", "Generate the release binaries for regz");
     const release_uf2_step = b.step("release-uf2", "Generate the release binaries for uf2");
+    const release_esp_image_step = b.step("release-esp-image", "Generate the release binaries for esp image");
 
     for (exe_targets) |t| {
         const release_target = b.resolveTargetQuery(t);
@@ -108,6 +109,25 @@ fn generate_release_steps(b: *Build) void {
         });
         release_uf2_step.dependOn(&uf2_target_output.step);
     }
+
+    for (exe_targets) |t| {
+        const release_target = b.resolveTargetQuery(t);
+
+        const esp_image_dep = b.dependency("tools/esp_image", .{
+            .optimize = .ReleaseSafe,
+            .target = release_target,
+        });
+
+        const elf2image_artifact = esp_image_dep.artifact("elf2image");
+        const elf2image_target_output = b.addInstallArtifact(elf2image_artifact, .{
+            .dest_dir = .{
+                .override = .{
+                    .custom = t.zigTriple(b.allocator) catch unreachable,
+                },
+            },
+        });
+        release_esp_image_step.dependOn(&elf2image_target_output.step);
+    }
 }
 
 pub const PortSelect = blk: {
@@ -632,7 +652,12 @@ pub fn MicroBuild(port_select: PortSelect) type {
                         },
 
                         .dfu => @panic("DFU is not implemented yet. See https://github.com/ZigEmbeddedGroup/microzig/issues/145 for more details!"),
-                        .esp => @panic("ESP firmware image is not implemented yet. See https://github.com/ZigEmbeddedGroup/microzig/issues/146 for more details!"),
+
+                        .esp => |options| @import("tools/esp_image").from_elf(
+                            fw.mb.dep.builder.dependency("tools/esp_image", .{}),
+                            elf_file,
+                            options,
+                        ),
 
                         .custom => |generator| generator.convert(fw.target.dep, elf_file),
                     };

build.zig.zon

@@ -12,6 +12,7 @@
         // tools
         .@"tools/regz" = .{ .path = "tools/regz" },
         .@"tools/uf2" = .{ .path = "tools/uf2" },
+        .@"tools/esp_image" = .{ .path = "tools/esp_image" },
 
         // modules
         .@"modules/foundation-libc" = .{ .path = "modules/foundation-libc" },

examples/espressif/esp/README.md

@@ -1,4 +1,21 @@
 # Examples for the Port `espressif-esp`
 
-- [Blinky](src/blinky.zig) on [ESP32-C3-32S-Kit](https://www.waveshare.com/wiki/ESP-C3-32S-Kit)  
+- [Blinky](src/blinky.zig) on [ESP32-C3-32S-Kit](https://www.waveshare.com/wiki/ESP-C3-32S-Kit)
   Showcases how to do a simple RGB cycling.
+
+## How to flash the image onto the device
+
+- esp image
+
+```sh
+esptool.py --chip esp32c3 --baud 460800 --before default_reset --after hard_reset write_flash \
+        0x0 bootloader.bin 0x8000 partition_table.bin 0x10000 zig-out/firmware/esp32_c3_blinky.bin
+```
+NOTE: you have to provide a [bootloader](https://docs.espressif.com/projects/esp-idf/en/stable/esp32c3/api-guides/bootloader.html) and a [partition table](https://docs.espressif.com/projects/esp-idf/en/stable/esp32c3/api-guides/partition-tables.html).
+
+- [direct boot image](https://github.com/espressif/esp32c3-direct-boot-example)
+
+```sh
+esptool.py --chip esp32c3 --baud 460800 --before default_reset --after hard_reset write_flash 0x0 \
+    zig-out/firmware/esp32_c3_direct_boot_blinky.bin
+```

examples/espressif/esp/build.zig

@@ -10,36 +10,48 @@ pub fn build(b: *std.Build) void {
 
     const mz_dep = b.dependency("microzig", .{});
     const mb = MicroBuild.init(b, mz_dep) orelse return;
+
+    const targets = [_]TargetDescription{
+        .{ .prefix = "esp32_c3", .target = mb.ports.esp.chips.esp32_c3 },
+        .{ .prefix = "esp32_c3_direct_boot", .target = mb.ports.esp.chips.esp32_c3_direct_boot },
+    };
+
     const available_examples = [_]Example{
-        .{ .target = mb.ports.esp.chips.esp32_c3, .name = "esp32-c3_blinky", .file = "src/blinky.zig" },
+        .{ .name = "blinky", .file = "src/blinky.zig" },
     };
 
     for (available_examples) |example| {
-        // `add_firmware` basically works like addExecutable, but takes a
-        // `microzig.Target` for target instead of a `std.zig.CrossTarget`.
-        //
-        // The target will convey all necessary information on the chip,
-        // cpu and potentially the board as well.
-        const firmware = mb.add_firmware(.{
-            .name = example.name,
-            .target = example.target,
-            .optimize = optimize,
-            .root_source_file = b.path(example.file),
-        });
-
-        // `installFirmware()` is the MicroZig pendant to `Build.installArtifact()`
-        // and allows installing the firmware as a typical firmware file.
-        //
-        // This will also install into `$prefix/firmware` instead of `$prefix/bin`.
-        mb.install_firmware(firmware, .{});
-
-        // For debugging, we also always install the firmware as an ELF file
-        mb.install_firmware(firmware, .{ .format = .elf });
+        for (targets) |target_desc| {
+            // `add_firmware` basically works like addExecutable, but takes a
+            // `microzig.Target` for target instead of a `std.zig.CrossTarget`.
+            //
+            // The target will convey all necessary information on the chip,
+            // cpu and potentially the board as well.
+            const firmware = mb.add_firmware(.{
+                .name = b.fmt("{s}_{s}", .{ target_desc.prefix, example.name }),
+                .target = target_desc.target,
+                .optimize = optimize,
+                .root_source_file = b.path(example.file),
+            });
+
+            // `installFirmware()` is the MicroZig pendant to `Build.installArtifact()`
+            // and allows installing the firmware as a typical firmware file.
+            //
+            // This will also install into `$prefix/firmware` instead of `$prefix/bin`.
+            mb.install_firmware(firmware, .{});
+
+            // For debugging, we also always install the firmware as an ELF file
+            mb.install_firmware(firmware, .{ .format = .elf });
+        }
     }
 }
 
-const Example = struct {
+const TargetDescription = struct {
+    prefix: []const u8,
     target: *const microzig.Target,
+};
+
+const Example = struct {
     name: []const u8,
     file: []const u8,
 };

port/espressif/esp/build.zig

@@ -5,6 +5,7 @@ const Self = @This();
 
 chips: struct {
     esp32_c3: *const microzig.Target,
+    esp32_c3_direct_boot: *const microzig.Target,
 },
 
 boards: struct {},
@@ -13,26 +14,60 @@ pub fn init(dep: *std.Build.Dependency) Self {
     const b = dep.builder;
 
     const hal: microzig.HardwareAbstractionLayer = .{
-        .root_source_file = b.path("src/hals/ESP32_C3.zig"),
+        .root_source_file = b.path("src/hal.zig"),
+    };
+
+    const chip_esp32_c3: microzig.Target = .{
+        .dep = dep,
+        .preferred_binary_format = .{ .esp = .{
+            .chip_id = .esp32_c3,
+            .flash_mode = .dio,
+            .flash_size = .@"4mb",
+            .flash_freq = .@"40m",
+        } },
+        .chip = .{
+            .name = "ESP32-C3",
+            .url = "https://www.espressif.com/en/products/socs/esp32-c3",
+            .cpu = .{
+                .cpu_arch = .riscv32,
+                .cpu_model = .{ .explicit = &std.Target.riscv.cpu.generic_rv32 },
+                .cpu_features_add = std.Target.riscv.featureSet(&.{
+                    .c,
+                    .m,
+                }),
+                .os_tag = .freestanding,
+                .abi = .eabi,
+            },
+            .cpu_module_file = b.path("src/cpus/esp-riscv-image.zig"),
+            .register_definition = .{ .svd = b.path("src/chips/ESP32-C3.svd") },
+            .memory_regions = &.{
+                // external memory, ibus
+                .{ .kind = .flash, .offset = 0x4200_0000, .length = 0x0080_0000 },
+                // sram 1, data bus
+                .{ .kind = .ram, .offset = 0x3FC8_0000, .length = 0x0006_0000 },
+            },
+        },
+        .hal = hal,
+        .linker_script = b.path("esp32_c3.ld"),
     };
-    const chip_esp32c3: microzig.Target = .{
+
+    const chip_esp32_c3_direct_boot: microzig.Target = .{
         .dep = dep,
-        // TODO: Exchange FLAT format with .esp format
         .preferred_binary_format = .bin,
         .chip = .{
             .name = "ESP32-C3",
             .url = "https://www.espressif.com/en/products/socs/esp32-c3",
-            .cpu = std.Target.Query{
+            .cpu = .{
                 .cpu_arch = .riscv32,
                 .cpu_model = .{ .explicit = &std.Target.riscv.cpu.generic_rv32 },
                 .cpu_features_add = std.Target.riscv.featureSet(&.{
-                    std.Target.riscv.Feature.c,
-                    std.Target.riscv.Feature.m,
+                    .c,
+                    .m,
                 }),
                 .os_tag = .freestanding,
                 .abi = .eabi,
             },
-            .cpu_module_file = b.path("src/cpus/espressif-riscv.zig"),
+            .cpu_module_file = b.path("src/cpus/esp-riscv-direct-boot.zig"),
             .register_definition = .{ .svd = b.path("src/chips/ESP32-C3.svd") },
             .memory_regions = &.{
                 // external memory, ibus
@@ -46,7 +81,8 @@ pub fn init(dep: *std.Build.Dependency) Self {
 
     return .{
         .chips = .{
-            .esp32_c3 = chip_esp32c3.derive(.{}),
+            .esp32_c3 = chip_esp32_c3.derive(.{}),
+            .esp32_c3_direct_boot = chip_esp32_c3_direct_boot.derive(.{}),
         },
         .boards = .{},
     };

port/espressif/esp/esp32_c3.ld

@@ -0,0 +1,66 @@
+/*
+ * This file was auto-generated by microzig
+ *
+ * Target CPU:  generic_rv32
+ * Target Chip: ESP32-C3
+ */
+
+ENTRY(_start);
+
+MEMORY
+{
+    irom (rx) : ORIGIN = 0x42000020, LENGTH = 0x800000 - 0x20
+    drom (r) : ORIGIN = 0x3C000020, LENGTH = 0x800000 - 0x20
+    iram (rwx) : ORIGIN = 0x40380000, LENGTH = 313K
+    dram (rw) : ORIGIN = 0x3FC80000, LENGTH = 313K
+}
+
+SECTIONS
+{
+    .irom.text :
+    {
+        KEEP(*(microzig_flash_start))
+        *(.text*)
+        . += 16;
+    } > irom
+
+    .drom.dummy (NOLOAD) :
+    {
+        . = ALIGN(ALIGNOF(.irom.text)) + SIZEOF(.irom.text);
+        . = ALIGN(0x10000) + 0x20;
+    } > drom
+
+    .drom.rodata : ALIGN(0x10)
+    {
+        KEEP(*(.app_desc))
+        *(.rodata*) /* should we leave this here? */
+        . = ALIGN(0x10);
+    } > drom
+
+    /* .iram.rwtext : */
+    /* { */
+    /*     *(.rwtext*) */
+    /* } > irom */
+    /**/
+    /* .dram.dummy (NOLOAD) : */
+    /* { */
+    /*     . = ALIGN(ALIGNOF(.iram.rwtext)) + SIZEOF(.iram.rwtext); */
+    /* } > drom */
+
+    .dram.data :
+    {
+        microzig_data_start = .;
+        *(.sdata*)
+        *(.data*)
+    } > dram
+
+    .dram.bss (NOLOAD) :
+    {
+        microzig_bss_start = .;
+        *(.bss*)
+        *(.sbss*)
+        microzig_bss_end = .;
+    } > dram
+
+    PROVIDE(__global_pointer$ = microzig_data_start + 0x800);
+}