Merge pull request 'add ESP-IDF project with Spider Runtime for ESP32' (#2) from lopez/esp32 into main

Reviewed-on: #2

.gitignore

@@ -0,0 +1,4 @@
+esp32/idf_project/build/
+esp32/idf_project/managed_components/
+esp32/bin/
+esp32/out/

esp32/Makefile

@@ -0,0 +1,62 @@
+# ========================================================== #
+# Spider Runtime - ESP32 Build System                        #
+# Toolchain: Espressif ESP-IDF (xtensa-esp-elf-g++)          #
+# ========================================================== #
+
+CC          := xtensa-esp-elf-g++
+TARGET      := spider_esp32.elf
+SRCDIR      := ../../spider-runtime/src
+BUILDDIR    := bin
+TARGETDIR   := out
+SRCEXT      := cpp
+OBJEXT      := o
+
+ESP_FLAGS   := -DESP32 -DSPIDER_DISTRO_MICRO -DSPIDER_OS_NONE -mlongcalls -ffunction-sections -fdata-sections -fno-exceptions -fno-rtti
+
+# -O0: no optimizations, faster compilation during development
+CFLAGS      := -Wall -std=c++20 -O0 -DSPIDER_COMPILING $(ESP_FLAGS)
+LFLAGS      := -Wl,--gc-sections -mlongcalls
+INC         := -I../../spider-runtime/src/
+
+# Exclude desktop-only modules
+EXCLUDE     := $(SRCDIR)/spider/runtime/util/Terminal.cpp \
+               $(SRCDIR)/spider/runtime/debug/LiveDebug.cpp \
+               $(SRCDIR)/spider/SpiderRuntime.cpp
+
+# ESP32 specific entry point (local to this build folder)
+EXTRA       := ./main_esp32.cpp
+
+SOURCES     := $(filter-out $(EXCLUDE), $(shell find $(SRCDIR) -type f -name "*.$(SRCEXT)" 2>/dev/null)) $(EXTRA)
+OBJECTS     := $(patsubst ./%,$(BUILDDIR)/%,$(patsubst $(SRCDIR)/%,$(BUILDDIR)/%,$(SOURCES:.$(SRCEXT)=.$(OBJEXT))))
+
+all: directories $(TARGET)
+	@echo "Build complete: $(TARGETDIR)/$(TARGET)"
+
+remake: cleaner all
+
+directories:
+	@mkdir -p $(TARGETDIR)
+	@mkdir -p $(BUILDDIR)
+
+clean:
+	@$(RM) -rf $(BUILDDIR)
+
+cleaner: clean
+	@$(RM) -rf $(TARGETDIR)
+
+$(TARGET): $(OBJECTS)
+	@echo "Linking $(TARGET)..."
+	$(CC) $(LFLAGS) -o $(TARGETDIR)/$(TARGET) $^
+	@echo "Done!"
+
+$(BUILDDIR)/%.$(OBJEXT): $(SRCDIR)/%.$(SRCEXT)
+	@mkdir -p $(dir $@)
+	@echo "Compiling $<..."
+	$(CC) $(CFLAGS) $(INC) -c -o $@ $<
+
+$(BUILDDIR)/%.$(OBJEXT): ./%.$(SRCEXT)
+	@mkdir -p $(dir $@)
+	@echo "Compiling $<..."
+	$(CC) $(CFLAGS) $(INC) -c -o $@ $<
+
+.PHONY: all remake clean cleaner

esp32/README.md

@@ -0,0 +1,83 @@
+# ESP32 Build Tools for Spider Runtime
+
+Build system for compiling the Spider Runtime for the ESP32
+microcontroller using the Espressif Xtensa toolchain.
+
+---
+
+## Requirements
+
+- [ESP-IDF v5.x](https://dl.espressif.com/dl/esp-idf/) installed
+- MSYS2 or any Unix-like shell
+- `spider-runtime` repository cloned at the same level as this repo
+
+Expected folder structure:
+```
+Internship/
+    spider-runtime/
+    spider-micro-buildtools/
+        esp32/   ← you are here
+```
+
+Add the Xtensa toolchain to your PATH before building:
+```bash
+export PATH=$PATH:/c/Espressif/tools/xtensa-esp-elf/<version>/xtensa-esp-elf/bin
+```
+
+---
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `Makefile` | Build recipe for ESP32 using `xtensa-esp-elf-g++` |
+| `gen_makefile.py` | Regenerates the Makefile (run if Makefile gets corrupted) |
+| `main_esp32.cpp` | ESP32 entry point, replaces the desktop `main()` |
+
+---
+
+## Build
+```bash
+make
+```
+
+Output: `out/spider_esp32.elf`
+
+To clean and rebuild from scratch:
+```bash
+make cleaner
+make
+```
+
+---
+
+## Flash to ESP32
+
+**Step 1 — Convert to flashable binary:**
+```bash
+xtensa-esp-elf-objcopy -O binary out/spider_esp32.elf out/spider_esp32.bin
+```
+
+**Step 2 — Connect your ESP32 via USB and find the COM port**
+
+On Windows, check Device Manager under "Ports (COM & LPT)".
+
+**Step 3 — Flash:**
+```bash
+esptool.py --chip esp32 --port COM3 --baud 115200 write_flash 0x1000 out/spider_esp32.bin
+```
+
+Replace `COM3` with your actual port.
+
+---
+
+## Compiler Flags
+
+| Flag | Purpose |
+|------|---------|
+| `-DESP32` | Activates ESP32 detection in `distro_mcu.hpp` |
+| `-DSPIDER_DISTRO_MICRO` | Enables microcontroller mode |
+| `-DSPIDER_OS_NONE` | Declares bare-metal, no OS |
+| `-mlongcalls` | Required for Xtensa memory layout |
+| `-fno-exceptions -fno-rtti` | Disable unavailable C++ features |
+| `-O0` | No optimizations, faster development builds |

esp32/gen_makefile.py

@@ -0,0 +1,70 @@
+tab = '\t'
+dollar = '$'
+
+content = f"""# ========================================================== #
+# Spider Runtime - ESP32 Build System                        #
+# Toolchain: Espressif ESP-IDF (xtensa-esp-elf-g++)          #
+# ========================================================== #
+
+CC          := xtensa-esp-elf-g++
+TARGET      := spider_esp32.elf
+SRCDIR      := ../../spider-runtime/src
+BUILDDIR    := bin
+TARGETDIR   := out
+SRCEXT      := cpp
+OBJEXT      := o
+
+ESP_FLAGS   := -DESP32 -DSPIDER_DISTRO_MICRO -DSPIDER_OS_NONE -mlongcalls -ffunction-sections -fdata-sections -fno-exceptions -fno-rtti
+
+# -O0: no optimizations, faster compilation during development
+CFLAGS      := -Wall -std=c++20 -O0 -DSPIDER_COMPILING {dollar}(ESP_FLAGS)
+LFLAGS      := -Wl,--gc-sections -mlongcalls
+INC         := -I../../spider-runtime/src/
+
+# Exclude desktop-only modules
+EXCLUDE     := {dollar}(SRCDIR)/spider/runtime/util/Terminal.cpp \\
+               {dollar}(SRCDIR)/spider/runtime/debug/LiveDebug.cpp \\
+               {dollar}(SRCDIR)/spider/SpiderRuntime.cpp
+
+# ESP32 specific entry point (local to this build folder)
+EXTRA       := ./main_esp32.cpp
+
+SOURCES     := {dollar}(filter-out {dollar}(EXCLUDE), {dollar}(shell find {dollar}(SRCDIR) -type f -name "*.{dollar}(SRCEXT)" 2>/dev/null)) {dollar}(EXTRA)
+OBJECTS     := {dollar}(patsubst ./%,{dollar}(BUILDDIR)/%,{dollar}(patsubst {dollar}(SRCDIR)/%,{dollar}(BUILDDIR)/%,{dollar}(SOURCES:.{dollar}(SRCEXT)=.{dollar}(OBJEXT))))
+
+all: directories {dollar}(TARGET)
+{tab}@echo "Build complete: {dollar}(TARGETDIR)/{dollar}(TARGET)"
+
+remake: cleaner all
+
+directories:
+{tab}@mkdir -p {dollar}(TARGETDIR)
+{tab}@mkdir -p {dollar}(BUILDDIR)
+
+clean:
+{tab}@{dollar}(RM) -rf {dollar}(BUILDDIR)
+
+cleaner: clean
+{tab}@{dollar}(RM) -rf {dollar}(TARGETDIR)
+
+{dollar}(TARGET): {dollar}(OBJECTS)
+{tab}@echo "Linking {dollar}(TARGET)..."
+{tab}{dollar}(CC) {dollar}(LFLAGS) -o {dollar}(TARGETDIR)/{dollar}(TARGET) {dollar}^
+{tab}@echo "Done!"
+
+{dollar}(BUILDDIR)/%.{dollar}(OBJEXT): {dollar}(SRCDIR)/%.{dollar}(SRCEXT)
+{tab}@mkdir -p {dollar}(dir {dollar}@)
+{tab}@echo "Compiling {dollar}<..."
+{tab}{dollar}(CC) {dollar}(CFLAGS) {dollar}(INC) -c -o {dollar}@ {dollar}<
+
+{dollar}(BUILDDIR)/%.{dollar}(OBJEXT): ./%.{dollar}(SRCEXT)
+{tab}@mkdir -p {dollar}(dir {dollar}@)
+{tab}@echo "Compiling {dollar}<..."
+{tab}{dollar}(CC) {dollar}(CFLAGS) {dollar}(INC) -c -o {dollar}@ {dollar}<
+
+.PHONY: all remake clean cleaner
+"""
+
+with open('Makefile', 'w', newline='\n') as f:
+    f.write(content)
+print("Makefile generated successfully!")

esp32/idf_project/CMakeLists.txt

@@ -0,0 +1,3 @@
+cmake_minimum_required(VERSION 3.16)
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(spider_esp32)

esp32/idf_project/README.md

@@ -0,0 +1,53 @@
+| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S2 | ESP32-S3 | Linux |
+| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- | ----- |
+
+# Hello World Example
+
+Starts a FreeRTOS task to print "Hello World".
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+## How to use example
+
+Follow detailed instructions provided specifically for this example.
+
+Select the instructions depending on Espressif chip installed on your development board:
+
+- [ESP32 Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/stable/get-started/index.html)
+- [ESP32-S2 Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/get-started/index.html)
+
+
+## Example folder contents
+
+The project **hello_world** contains one source file in C language [hello_world_main.c](main/hello_world_main.c). The file is located in folder [main](main).
+
+ESP-IDF projects are built using CMake. The project build configuration is contained in `CMakeLists.txt` files that provide set of directives and instructions describing the project's source files and targets (executable, library, or both).
+
+Below is short explanation of remaining files in the project folder.
+
+```
+├── CMakeLists.txt
+├── pytest_hello_world.py      Python script used for automated testing
+├── main
+│   ├── CMakeLists.txt
+│   └── hello_world_main.c
+└── README.md                  This is the file you are currently reading
+```
+
+For more information on structure and contents of ESP-IDF projects, please refer to Section [Build System](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html) of the ESP-IDF Programming Guide.
+
+## Troubleshooting
+
+* Program upload failure
+
+    * Hardware connection is not correct: run `idf.py -p PORT monitor`, and reboot your board to see if there are any output logs.
+    * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again.
+
+## Technical support and feedback
+
+Please use the following feedback channels:
+
+* For technical queries, go to the [esp32.com](https://esp32.com/) forum
+* For a feature request or bug report, create a [GitHub issue](https://github.com/espressif/esp-idf/issues)
+
+We will get back to you as soon as possible.

esp32/idf_project/main/CMakeLists.txt

@@ -0,0 +1,20 @@
+set(SPIDER_RUNTIME_SRC 
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../../../spider-runtime/src"
+)
+idf_component_register(
+    SRCS 
+        "main.cpp"
+        "${SPIDER_RUNTIME_SRC}/spider/runtime/Runtime.cpp"
+        "${SPIDER_RUNTIME_SRC}/spider/runtime/cpu/CPU.cpp"
+        "${SPIDER_RUNTIME_SRC}/spider/runtime/memory/RAM.cpp"
+        "${SPIDER_RUNTIME_SRC}/spider/runtime/memory/ByteArray.cpp"
+        "${SPIDER_RUNTIME_SRC}/spider/runtime/reel/InstrReel.cpp"
+        "${SPIDER_RUNTIME_SRC}/spider/runtime/reel/InstrReelDyn.cpp"
+        "${SPIDER_RUNTIME_SRC}/spider/runtime/reel/InstrReelFixed.cpp"
+        "${SPIDER_RUNTIME_SRC}/spider/runtime/instr/Instr_00-1F.cpp"
+        "${SPIDER_RUNTIME_SRC}/spider/runtime/instr/InstrMap.cpp"
+        "${SPIDER_RUNTIME_SRC}/spider/runtime/math/Quat.cpp"
+    INCLUDE_DIRS "."
+    PRIV_INCLUDE_DIRS 
+        "${SPIDER_RUNTIME_SRC}"
+)

esp32/idf_project/main/main.cpp

@@ -0,0 +1,21 @@
+#include <stdio.h>
+#include "esp_log.h"
+#include <spider/SpiderRuntime.hpp>
+#include <spider/runtime/Runtime.hpp>
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+
+static const char* TAG = "Spider";
+
+extern "C" void app_main(void) {
+    ESP_LOGI(TAG, "Spider Runtime starting...");
+    
+    spider::Runtime runtime(32 * 1024);
+    
+    ESP_LOGI(TAG, "Spider Runtime initialized!");
+    ESP_LOGI(TAG, "RAM size: 32KB");
+    
+   while(1) {
+    vTaskDelay(pdMS_TO_TICKS(1000));
+}
+}

esp32/idf_project/pytest_hello_world.py

@@ -0,0 +1,55 @@
+# SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: CC0-1.0
+import hashlib
+import logging
+from typing import Callable
+
+import pytest
+from pytest_embedded_idf.dut import IdfDut
+from pytest_embedded_idf.utils import idf_parametrize
+from pytest_embedded_qemu.app import QemuApp
+from pytest_embedded_qemu.dut import QemuDut
+
+
+@pytest.mark.generic
+@idf_parametrize('target', ['supported_targets', 'preview_targets'], indirect=['target'])
+def test_hello_world(dut: IdfDut, log_minimum_free_heap_size: Callable[..., None]) -> None:
+    dut.expect('Hello world!')
+    log_minimum_free_heap_size()
+
+
+@pytest.mark.host_test
+@idf_parametrize('target', ['linux'], indirect=['target'])
+def test_hello_world_linux(dut: IdfDut) -> None:
+    dut.expect('Hello world!')
+
+
+@pytest.mark.host_test
+@pytest.mark.macos_shell
+@idf_parametrize('target', ['linux'], indirect=['target'])
+def test_hello_world_macos(dut: IdfDut) -> None:
+    dut.expect('Hello world!')
+
+
+def verify_elf_sha256_embedding(app: QemuApp, sha256_reported: str) -> None:
+    sha256 = hashlib.sha256()
+    with open(app.elf_file, 'rb') as f:
+        sha256.update(f.read())
+    sha256_expected = sha256.hexdigest()
+
+    logging.info(f'ELF file SHA256: {sha256_expected}')
+    logging.info(f'ELF file SHA256 (reported by the app): {sha256_reported}')
+
+    # the app reports only the first several hex characters of the SHA256, check that they match
+    if not sha256_expected.startswith(sha256_reported):
+        raise ValueError('ELF file SHA256 mismatch')
+
+
+@pytest.mark.host_test
+@pytest.mark.qemu
+@idf_parametrize('target', ['esp32', 'esp32c3'], indirect=['target'])
+def test_hello_world_host(app: QemuApp, dut: QemuDut) -> None:
+    sha256_reported = dut.expect(r'ELF file SHA256:\s+([a-f0-9]+)').group(1).decode('utf-8')
+    verify_elf_sha256_embedding(app, sha256_reported)
+
+    dut.expect('Hello world!')

esp32/main_esp32.cpp

@@ -0,0 +1,8 @@
+// ESP32 entry point for Spider Runtime
+// This replaces SpiderRuntime.cpp for microcontroller builds
+#include <spider/SpiderRuntime.hpp>
+
+int main() {
+    // TODO: initialize Spider runtime for ESP32
+    return 0;
+}