ESP32-H2 support

Author: roma-jam

.github/workflows/build.yml

@@ -11,14 +11,24 @@ jobs:
     runs-on: ubuntu-22.04
     strategy:
       matrix:
+        target: [esp32c3, esp32h2]
+        example: ["blink", "hello_world"]
         include:
-          - example: "blink"
+          - target: esp32c3
+            example: "blink"
             expected_size: 7436
-          - example: "hello_world"
+          - target: esp32c3
+            example: "hello_world"
             expected_size: 10216
+          - target: esp32h2
+            example: "blink"
+            expected_size: 4561
+          - target: esp32h2
+            example: "hello_world"
+            expected_size: 8484
     steps:
       - uses: actions/checkout@v2
-      - name: Build for ESP32-C3
+      - name: Build ${{ matrix.example }} for ${{ matrix.target }}
         shell: bash
         run: |
           export TOOLCHAIN_VERSION="12.2.0-3"
@@ -30,7 +40,7 @@ jobs:
           export PATH=$PWD/${TOOLCHAIN_DIR}/bin:$PATH
           cd examples/${{ matrix.example }}
           mkdir -p build
-          cmake -S . -B build
+          cmake -S . -B build -D target=${{ matrix.target }}
           cmake --build build
           bin_size=$(stat --format="%s" build/${{ matrix.example }}.bin)
           expected_size=${{ matrix.expected_size }}

README.md

@@ -1,24 +1,29 @@
-# ESP32-C3 Direct Boot example
+# Direct Boot example
 
-This is an example of ESP32-C3 "direct boot" feature. It allows an application to be executed directly from flash, without using the 2nd stage bootloader.
+Supported chips: ESP32-C3, ESP32-H2
+
+This is an example of "direct boot" feature.
+It allows an application to be executed directly from flash, without using the 2nd stage bootloader.
 
 ## Background
 
-ESP8266 and ESP32 series of chips share the common [binary image format](https://github.com/espressif/esptool/wiki/Firmware-Image-Format). This format describes how the binary image stored in flash should be loaded into IRAM/DRAM by the ROM bootloader. In typical applications, the ROM bootloader doesn't load the application binary directly. Instead, it loads the 2nd stage bootloader into RAM. The 2nd stage bootloader then loads the application: sections which should reside in RAM are copied from flash into RAM, and cache MMU is configured to map the remaining sections, which are accessed from flash.
+ESP8266 and ESP32 series of chips share the common [binary image format](https://docs.espressif.com/projects/esptool/en/latest/esp32/advanced-topics/firmware-image-format.html). This format describes how the binary image stored in flash should be loaded into IRAM/DRAM by the ROM bootloader. In typical applications, the ROM bootloader doesn't load the application binary directly. Instead, it loads the 2nd stage bootloader into RAM. The 2nd stage bootloader then loads the application: sections which should reside in RAM are copied from flash into RAM, and cache MMU is configured to map the remaining sections, which are accessed from flash.
 
 Compared to other microcontrollers, where the program in flash is executed directly without the need for additional stages of bootloaders, this arrangement does add complexity. However, it should be noted that in most production applications the 2nd stage bootloader is required to support firmware update, rollback, and security features. Because of this, the 2nd stage bootloader is used in ESP-IDF, despite the extra complexity.
 
-## Direct boot in ESP32-C3
+## Direct boot feature
 
-ESP32-C3 (starting from silicon revision 3) allows an application stored in flash to be executed directly, without being copied into RAM. This makes it possible to link an application with a relatively simple linker script, and produce the binary using `objcopy` command, then flash the resulting binary to the ESP32-C3.
+Chips, supported in this example (for example, ESP32-C3, starting from silicon revision 3) allow an application stored in flash to be executed directly, without being copied into RAM. This makes it possible to link an application with a relatively simple linker script, and produce the binary using `objcopy` command, then flash the resulting binary to the target chip.
 
 Direct boot feature is activated under the following conditions:
 * Secure boot is disabled.
 * Direct boot feature is not disabled via `EFUSE_DIS_LEGACY_SPI_BOOT` eFuse bit.
 * The ROM bootloader doesn't detect a valid binary image [in the usual format](https://github.com/espressif/esptool/wiki/Firmware-Image-Format)
 * The first 8 bytes in flash are `1d 04 db ae 1d 04 db ae` — that is a "magic number" 0xaedb041d repeated twice.
 
-In this case, the ROM bootloader sets up Flash MMU to map 4 MB of Flash to addresses 0x42000000 (for code execution) and 0x3C000000 (for read-only data access). The bootloader then jumps to address 0x42000008, i.e. to the instruction at offset 8 in flash, immediately after the magic numbers.
+In this case, the ROM bootloader sets up Flash MMU to map all amount of Flash then jumps to address `Flash address + 8`, i.e. to the instruction at offset 8 in flash, immediately after the magic numbers.
+
+For example, the ROM bootloader of ESP32-C3 sets up Flash MMU to map 4 MB of Flash to addresses 0x42000000 (for code execution) and 0x3C000000 (for read-only data access).
 
 The application entry function needs to:
 1. set up global pointer register
@@ -41,7 +46,7 @@ Use it if all of the below are true:
 * The code doesn't fit into RAM, therefore execution from flash is required.
 * Dependency on the ESP-specific binary image format or the ESP-IDF 2nd stage bootloader is undesirable.
 
-This feature can also be useful in an educational context to "hide" the added complexity of ESP32-C3 Flash MMU and cache configuration.
+This feature can also be useful in an educational context to "hide" the added complexity of chip Flash MMU and cache configuration.
 
 ## Alternatives to direct boot
 
@@ -56,16 +61,17 @@ If the entire application code is small enough to fit into RAM, then the direct
 This example contains the following parts:
 
 * [common/](common/) directory with the application entrypoint, placeholder for the vector table, and a simple implementation of `_write` syscall.
-* [ld/](ld/) directory with the linker scripts.
-* [examples/hello_world/](examples/hello_world/) directory with the minimal example project which prints "Hello, world!" to the UART.
 * [examples/blink/](examples/blink/) directory with an example project which blinks an LED.
+* [examples/hello_world/](examples/hello_world/) directory with the minimal example project which prints "Hello, world!" to the UART.
+* [img/](img/) directory with *.svg format diagrams which illustrate the run-time memory layout and binary image layout when direct boot is used.
+* [ld/](ld/) directory with the linker scripts.
 
 
 ## Prerequisites
 
 ### Cross-compiler
 
-Download and install `riscv-none-elf-gcc` toolchain, for example from the [xPack project](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases). 
+Download and install `riscv-none-elf-gcc` toolchain, for example from the [xPack project](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases).
 
 This example has been built and tested with toolchain release `12.2.0-3`.
 
@@ -79,7 +85,7 @@ This example uses CMake. Make sure that CMake and your build system of choice (e
 
 ### esptool.py
 
-To flash binaries into the ESP32-C3, [esptool.py](https://github.com/espressif/esptool) is used.
+To flash binaries into the chip, [esptool.py](https://github.com/espressif/esptool) is used.
 
 If you have Python and pip installed, you can install esptool using:
 ```bash
@@ -105,7 +111,7 @@ To debug the examples using JTAG and GDB, follow these steps:
    riscv-none-elf-gdb -x gdbinit build/blink
    ```
    This will use the provided gdbinit file to:
-   - Launch OpenOCD in pipe mode. Adjust the `gdbinit` file if you need to change OpenOCD launch configuration. You can also launch OpenOCD manually, in that case use `target extended-remote :3333` in `gdbinit`.
+   - Launch OpenOCD in pipe mode. Adjust the `gdbinit` file if you need to change OpenOCD launch configuration or select another target chip. You can also launch OpenOCD manually, in that case use `target extended-remote :3333` in `gdbinit`.
    - Flash the program over JTAG
    - Reset the target
    - Set a temporary breakpoint at `main`
@@ -114,16 +120,26 @@ To debug the examples using JTAG and GDB, follow these steps:
 
 ## Memory layout
 
-The following diagram illustrates the run-time memory layout and binary image layout when direct boot is used.
-
-![img/esp32c3-directboot.svg](img/esp32c3-directboot.svg)
+### ESP32-C3
 
 The sections shown in blue on the left are parts of the flash image.
 
+![img/esp32c3-directboot.svg](img/esp32c3-directboot.svg)
+
 ROM bootloader maps the 0 – 4 MB region of flash to the CPU address space twice: to the "DROM" region using the data cache, and to the "IROM" region using the instruction cache.
 
 As it is obvious from the diagram, some parts of this mapping are unnecessary. These parts are shown in gray on the right. For example, `.text` section gets mapped not only to the IROM, but also to DROM, even though code execution only happens through IROM.
 
 Such uniform mapping was chosen simply because it is universal, and can be set up by the ROM code without any prior knowledge about the application being loaded. This mapping isn't in any way a limitation of ESP32-C3 cache hardware; for example, ESP-IDF 2nd stage bootloader maps only those regions which are necessary in the given part of the address space.
 
-The run-time memory layout and flash binary image layout shown above are achieved in the linker script ([ld/common.ld](ld/common.ld)) by specifying the LMAs (load addresses). LMAs start at 0, and match the addresses in flash. VMAs for IROM (`entry` and `.text`) and DROM (`.rodata`) sections are set in such a way that LMA == VMA - BASE, where *BASE* is the starting address of IROM or DROM. Non-cached `.data` section is then added at the next available LMA.
+The run-time memory layout and flash binary image layout shown above are achieved in the linker script ([ld/esp32c3/common.ld](ld/esp32c3/common.ld)) by specifying the LMAs (load addresses). LMAs start at 0, and match the addresses in flash. VMAs for IROM (`entry` and `.text`) and DROM (`.rodata`) sections are set in such a way that LMA == VMA - BASE, where *BASE* is the starting address of IROM or DROM. Non-cached `.data` section is then added at the next available LMA.
+
+### ESP32-H2
+
+![img/esp32h2-directboot.svg](img/esp32h2-directboot.svg)
+
+ROM bootloader maps the 0 – 4 MB region of flash to the CPU address space using the cache and the Flash MMU.
+
+The memory layout can be found in liker script ([ld/esp32h2/memory.ld](ld/esp32h2/memory.ld)).
+
+The run-time memory layout and flash binary image layout shown above are achieved in the linker script ([ld/esp32h2/common.ld](ld/esp32h2/common.ld)) by specifying the LMAs (load addresses). LMAs start at 0, and match the addresses in flash. VMAs for ROM (`entry`, `.text` and `.rodata`) section is set in such a way that LMA == VMA - BASE, where *BASE* is the starting address of ROM. Non-cached `.data` section is then added at the next available LMA.

common/CMakeLists.txt

@@ -1,14 +1,15 @@
-enable_language(ASM)
+enable_language(C ASM)
 
-list(APPEND srcs 
+list(APPEND srcs
     "start.S"
     "vectors.S"
     "syscalls.c"
     )
 
 add_library(common STATIC ${srcs})
-target_include_directories(common PUBLIC include)
+target_include_directories(common PUBLIC)
 set_target_properties(common PROPERTIES C_STANDARD 11)
+target_compile_options(common PRIVATE -g -Og)
 target_link_libraries(common INTERFACE -nostartfiles)
 
 

examples/blink/CMakeLists.txt

@@ -14,7 +14,6 @@ target_link_libraries(blink PRIVATE common hal)
 
 target_compile_options(blink PRIVATE -g -Og)
 target_link_options(blink PRIVATE -g)
-
 target_compile_options(blink PRIVATE -Wall -Werror -Wextra)
 
 include(${ROOT_DIR}/utils.cmake)

examples/blink/README.md

@@ -2,7 +2,7 @@
 
 ## Hardware
 
-Attach an LED and a current limiting resistor between GPIO 2 and 3V3 pins of an ESP32-C3 development board.
+Attach an LED and a current limiting resistor between GPIO 2 and 3V3 pins of a development board.
 
 ## Building and running the example
 
@@ -11,9 +11,10 @@ Attach an LED and a current limiting resistor between GPIO 2 and 3V3 pins of an
    ```bash
    cd examples/blink
    mkdir build
-   cmake -B build -G Ninja .
+   cmake -B build -D target=esp32c3 -G Ninja .
    cmake --build build
    ```
+   For other chip, please use the `target=chip_name`, where `chip_name` can be any from the supported ones.
    You should get the following output at the end:
    ```
    [3/4] Running utility command for blink-size
@@ -31,4 +32,4 @@ Attach an LED and a current limiting resistor between GPIO 2 and 3V3 pins of an
    esptool.py --port /dev/ttyUSB0 --baud 921600 write_flash 0x0000 build/blink.bin
    ```
    (Adjust the serial port name as needed.)
-4. The LED attached to GPIO 2 should be blinking at around 3 Hz rate.
+4. The LED attached to GPIO 2 should be blinking at around 3 Hz rate for ESP32-C3 (frequency can be vary depending on the maximum frequency of the selected chip).

examples/hello_world/README.md

@@ -7,9 +7,10 @@
    ```bash
    cd examples/hello_world
    mkdir build
-   cmake -B build -G Ninja .
+   cmake -B build -D target=esp32c3 -G Ninja .
    cmake --build build
    ```
+   For other chip, please use the `target=chip_name`, where `chip_name` can be any from the supported ones.
    You should get the following output at the end:
    ```
    [2/3] Generating hello_world.bin

hal/CMakeLists.txt

@@ -15,8 +15,14 @@ FetchContent_GetProperties(
 )
 message(STATUS "Downloaded esp-hal-components into ${esp_hal_components_srcdir}")
 
+set(supported_mcu esp32c3 esp32h2)
+if(DEFINED target AND target IN_LIST supported_mcu)
+    message(STATUS "Configure project for ${target} ... ")
+else()
+    message(FATAL_ERROR "Invalid target. \nUse argument '-D target=chip_name', where chip_name=[${supported_mcu}]")
+endif()
+
 # FIXME: soc component depends on sdkconfig.h
-set(target esp32c3)
 string(TOUPPER ${target} target_uppercase)
 set(config_dir ${CMAKE_CURRENT_BINARY_DIR}/config)
 file(MAKE_DIRECTORY ${config_dir})

img/esp32h2-directboot.svg

@@ -0,0 +1,162 @@
+ENTRY(_start)
+
+SECTIONS
+{
+  .header : AT(0)
+  {
+    _rom_start = .;
+    LONG(0xaedb041d)
+    LONG(0xaedb041d)
+  } > rom
+
+  .text.entry ORIGIN(rom) + 8 :
+  {
+    KEEP(*(.text.entry))
+  } > rom
+
+  .text :
+  {
+    *(.text .stub .text.* .gnu.linkonce.t.*)
+    *(.rela.text .rela.text.* .rela.gnu.linkonce.t.*)
+    *(.gnu.warning)
+  }
+  . = ALIGN(4);
+
+  .rodata :
+  {
+    *(.rodata .rodata1 .rodata.* .srodata .srodata.* .sdata2 .sdata2.* .gnu.linkonce.r.*)
+    *(.rela.data .rela.data.* .rela.gnu.linkonce.r.*)
+  } > rom
+
+  .init_array :
+  {
+    PROVIDE_HIDDEN (__init_array_start = .);
+    KEEP (*(SORT_BY_INIT_PRIORITY(.init_array.*) SORT_BY_INIT_PRIORITY(.ctors.*)))
+    KEEP (*(.init_array EXCLUDE_FILE (*crtbegin.o *crtbegin?.o *crtend.o *crtend?.o ) .ctors))
+    PROVIDE_HIDDEN (__init_array_end = .);
+  } > rom
+
+  .fini_array :
+  {
+    PROVIDE_HIDDEN (__fini_array_start = .);
+    KEEP (*(SORT_BY_INIT_PRIORITY(.fini_array.*) SORT_BY_INIT_PRIORITY(.dtors.*)))
+    KEEP (*(.fini_array EXCLUDE_FILE (*crtbegin.o *crtbegin?.o *crtend.o *crtend?.o ) .dtors))
+    PROVIDE_HIDDEN (__fini_array_end = .);
+  } > rom
+
+  .ctors :
+  {
+    KEEP (*crtbegin.o(.ctors))
+    KEEP (*crtbegin?.o(.ctors))
+    KEEP (*(EXCLUDE_FILE (*crtend.o *crtend?.o ) .ctors))
+    KEEP (*(SORT(.ctors.*)))
+    KEEP (*(.ctors))
+  } > rom
+
+  .dtors :
+  {
+    KEEP (*crtbegin.o(.dtors))
+    KEEP (*crtbegin?.o(.dtors))
+    KEEP (*(EXCLUDE_FILE (*crtend.o *crtend?.o ) .dtors))
+    KEEP (*(SORT(.dtors.*)))
+    KEEP (*(.dtors))
+  } > rom
+
+  PROVIDE (__etext = .);
+  PROVIDE (_etext = .);
+  PROVIDE (etext = .);
+  _rom_size = . - _rom_start;
+
+  .data ORIGIN(ram) : AT(_rom_size)
+  {
+    _data_start = .;
+    __DATA_BEGIN__ = .;
+    *(.data .data.* .gnu.linkonce.d.*)
+    *(.data.rel.ro.local* .gnu.linkonce.d.rel.ro.local.*) *(.data.rel.ro .data.rel.ro.* .gnu.linkonce.d.rel.ro.*)
+    SORT(CONSTRUCTORS)
+  } > ram
+  .data1 :
+  {
+    *(.data1)
+  }
+  .sdata :
+  {
+    __SDATA_BEGIN__ = .;
+    *(.sdata .sdata.* .gnu.linkonce.s.*)
+  }
+  . = ALIGN(4);
+  _edata = .; PROVIDE (edata = .);
+  _data_lma = ORIGIN(rom) + LOADADDR(.data);
+  _data_size = _edata - _data_start;
+
+  __bss_start = .;
+  .sbss           :
+  {
+    *(.dynsbss)
+    *(.sbss .sbss.* .gnu.linkonce.sb.*)
+    *(.scommon)
+  }
+  .bss            :
+  {
+   *(.dynbss)
+   *(.bss .bss.* .gnu.linkonce.b.*)
+   *(COMMON)
+  }
+  . = ALIGN(4);
+  __BSS_END__ = .;
+  __global_pointer$ = MIN(__SDATA_BEGIN__ + 0x800,
+                          MAX(__DATA_BEGIN__ + 0x800, __BSS_END__ - 0x800));
+  _end = .; PROVIDE (end = .);
+
+  /* Stack */
+  .stack :
+  {
+    __stack_bottom = .;
+    __stack_top = ORIGIN(ram) + LENGTH(ram);
+    __stack_size_min = 0x4000;
+    ASSERT(__stack_bottom + __stack_size_min < __stack_top, "Error: no space for stack");
+  }
+
+  /* Stabs debugging sections.  */
+  .stab          0 : { *(.stab) }
+  .stabstr       0 : { *(.stabstr) }
+  .stab.excl     0 : { *(.stab.excl) }
+  .stab.exclstr  0 : { *(.stab.exclstr) }
+  .stab.index    0 : { *(.stab.index) }
+  .stab.indexstr 0 : { *(.stab.indexstr) }
+  .comment       0 : { *(.comment) }
+  .gnu.build.attributes : { *(.gnu.build.attributes .gnu.build.attributes.*) }
+  /* DWARF debug sections.
+     Symbols in the DWARF debugging sections are relative to the beginning
+     of the section so we begin them at 0.  */
+  /* DWARF 1 */
+  .debug          0 : { *(.debug) }
+  .line           0 : { *(.line) }
+  /* GNU DWARF 1 extensions */
+  .debug_srcinfo  0 : { *(.debug_srcinfo) }
+  .debug_sfnames  0 : { *(.debug_sfnames) }
+  /* DWARF 1.1 and DWARF 2 */
+  .debug_aranges  0 : { *(.debug_aranges) }
+  .debug_pubnames 0 : { *(.debug_pubnames) }
+  /* DWARF 2 */
+  .debug_info     0 : { *(.debug_info .gnu.linkonce.wi.*) }
+  .debug_abbrev   0 : { *(.debug_abbrev) }
+  .debug_line     0 : { *(.debug_line .debug_line.* .debug_line_end) }
+  .debug_frame    0 : { *(.debug_frame) }
+  .debug_str      0 : { *(.debug_str) }
+  .debug_loc      0 : { *(.debug_loc) }
+  .debug_macinfo  0 : { *(.debug_macinfo) }
+  /* SGI/MIPS DWARF 2 extensions */
+  .debug_weaknames 0 : { *(.debug_weaknames) }
+  .debug_funcnames 0 : { *(.debug_funcnames) }
+  .debug_typenames 0 : { *(.debug_typenames) }
+  .debug_varnames  0 : { *(.debug_varnames) }
+  /* DWARF 3 */
+  .debug_pubtypes 0 : { *(.debug_pubtypes) }
+  .debug_ranges   0 : { *(.debug_ranges) }
+  /* DWARF Extension.  */
+  .debug_macro    0 : { *(.debug_macro) }
+  .debug_addr     0 : { *(.debug_addr) }
+  .gnu.attributes 0 : { KEEP (*(.gnu.attributes)) }
+  /DISCARD/ : { *(.note.GNU-stack) *(.gnu_debuglink) *(.gnu.lto_*) }
+}