universalisos/docs/esp32-master-plan.md

UniversalisOS ESP32 — Master Implementation Plan

Status: MCUboot + U-Boot chain working (2026-07-16) Target: ESP32-D0WDQ6-V3, Xtensa LX6, 4MB flash

1. Current State

1.1 Working

• ROM → MCUboot @ 0x1000 (image validation, OTA slots)
• MCUboot flash MMU: cache_flash_mmu_set → IROM @ 0x40800000 (rc=0)
• MCUboot → U-Boot handoff: jumps to _start, prints X\nW\nY\nE\n[UOS2\n
• U-Boot banner: "U-Boot 2025.04..." appears
• DRAM loading via D-bus (0x3FFAF000+)
• U-Boot IROM linker script at 0x40800000+
• Wrapper tool for ELF→MCUboot image format

1.2 Broken / Incomplete

• U-Boot console garbled after banner — can't interact
• IROM data loads (l32r) fail — D-bus has no path to I-bus addresses
• Exception vectors discarded in U-Boot linker — faults go to ROM
• U-Boot init functions reset cache/MMU — IROM mapping destroyed after board_early_init_f
• No DRAM loader for secondary images (UOS apps)
• No partition table parser in U-Boot

2. Architecture: Three-Layer Boot Chain

Flash Layout (4MB ESP32):
┌─────────────┬───────┬──────────────────────────────────┐
│ 0x0000      │ 4KB   │ (reserved)                       │
│ 0x1000      │ 30KB  │ MCUboot (1st stage bootloader)   │
│ 0x8000      │ 4KB   │ Partition Table (32B × 96)       │
│ 0x9000      │ 128KB │ OTA Data (boot state)            │
│ 0x20000     │ 1.3MB │ U-Boot (primary slot)            │
│ 0x170000    │ 1.5MB │ UOS App (secondary slot / app)   │
│ 0x300000    │ 1MB   │ UOS Data / NVS / scratch         │
└─────────────┴───────┴──────────────────────────────────┘

Boot Flow:
  ROM → MCUboot → U-Boot → UOS microkernel → FreeRTOS/Apps

2.1 Layer 1: MCUboot (Bootloader)

Responsibilities:

• Image validation (SHA256 via imgtool TLV)
• Flash MMU mapping for U-Boot IROM code
• DRAM loading for U-Boot data
• OTA slot management (primary/secondary swap)
• Flash encryption / secure boot (future)

Current status: ✅ Working. Needs:

• Fix IROM bus mask in DPORT register (done, but U-Boot resets it)
• Add DROM mapping alongside IROM (for l32r data loads)
• Partition table reading (currently uses hardcoded slot offsets)

2.2 Layer 2: U-Boot (Hardware Init + OS Loader)

U-Boot's job on ESP32 (mirrors STM32/ARM U-Boot):

Function	ARM U-Boot (STM32)	ESP32 U-Boot (target)
Console	UART via DM_SERIAL	✅ DM_SERIAL enabled, 🔴 garbled
DRAM init	UCLASS_RAM driver	🔴 Need SRAM sizing
Clock init	rcc_clock_setup()	🔴 Need PLL/APB config
Flash driver	SPI NOR via DM_SPI_FLASH	🔴 Need esp_flash driver
Partition table	GPT/DOS parser	🔴 Need ESP32 partition table parser
Environment	ENV_IS_IN_SPI_FLASH	🔴 Need ESP32 env backend
Network	ETH/PHY driver	N/A (ESP32 has WiFi)
Boot commands	bootm, bootelf, go	✅ go works (jumps)
Exception vectors	ARM vectors at 0x00	🔴 Discarded — need IROM vectors
Cache control	icache_enable/dcache	🔴 Need cache_hal wrappers
Timer	ARM systick	🔴 Need CCOUNT driver
Watchdog	IWDG driver	🔴 Need ESP32 WDT driver
GPIO	DM_GPIO driver	🔴 Need ESP32 GPIO driver
Device Tree	FDT blob	🔴 No DTS for ESP32

2.3 Layer 3: UOS Microkernel (RTOS)

UOS runs as a U-Boot application (loaded via bootelf/bootm):

UOS provides:

• Preemptive scheduler (tick via CCOMPARE0)
• IPC (message queues, semaphores)
• Memory protection (MPU-based, Tier 1)
• Health monitoring (heartbeat, watchdog)
• Device framework (UART, SPI, I2C, GPIO)
• Capability MDB (security model)

Current UOS ESP32 port has:

• UART0 init (polled TX)
• Timer init (CCOMPARE0, tick via CCOUNT)
• Interrupt controller (INTC_CPU_INT_ENA)
• Startup sequence (esp32_app_entry)
• Stack in DRAM, vectors in IRAM (old layout)
• Exception handlers (user/kernel/double/NMI)

3. Implementation Plan — 5 Phases

Phase 1: Stabilize U-Boot (Weeks 1-2)

Goal: U-Boot console working, can type commands.

Task	Effort	Depends on
1.1 Implement cache_ll_l1_enable_bus from esp-hal-3rdparty HAL	1d	—
1.2 Fix U-Boot init sequence: NO cache/MMU reset during boot	1d	1.1
1.3 Fix IROM data loads: add DROM mapping for U-Boot IROM region	1d	1.1
1.4 Fix U-Boot DM_SERIAL: proper UART0 config matching MCUboot	1d	—
1.5 Implement exception vectors in IROM linker (xtensa_vectors.S)	2d	1.1
1.6 Fix U-Boot env to RAM (ENV_IS_NOWHERE → ENV_IS_IN_SPI_FLASH)	1d	1.2
1.7 Implement CCOUNT timer for U-Boot delay/get_timer	1d	—

Deliverable: U-Boot prompt working, help shows commands.

Phase 2: U-Boot Hardware Drivers (Weeks 3-4)

Goal: U-Boot can access flash, load images, manage partitions.

Task	Effort	Depends on
2.1 Port ESP32 partition table parser from gen_esp32part.py to C	2d	—
2.2 Implement esp_flash_read via SPI1 ROM functions	1d	1.1
2.3 Implement DM_SPI_FLASH driver for ESP32	2d	2.2
2.4 Implement ENV in SPI flash backend (CONFIG_ENV_IS_IN_SPI_FLASH)	2d	2.2, 2.1
2.5 Implement ESP32 WDT driver (disable/feed/config)	1d	—
2.6 Implement basic GPIO driver	1d	—
2.7 SDRAM sizing: detect SRAM0/SRAM1/SRAM2 at runtime	1d	—
2.8 PLL/clock init: read from ROM defaults, expose APB freq	1d	—

Deliverable: U-Boot can fatload/ext4load from flash, setenv/saveenv, reset.

Phase 3: U-Boot OS Loader (Week 5)

Goal: U-Boot can load and boot UOS microkernel images.

Task	Effort	Depends on
3.1 Implement bootelf for Xtensa ELF loading	2d	2.2
3.2 Flash MMU mapping in U-Boot (add pages for UOS app)	1d	1.1
3.3 DRAM loading for UOS .data/.bss	1d	2.2
3.4 Auto-boot: CONFIG_BOOTCOMMAND → load UOS from partition	1d	3.1, 2.1
3.5 Boot script support (boot.scr or bootcmd)	1d	2.4

Deliverable: U-Boot boots UOS microkernel automatically.

Phase 4: UOS Microkernel ESP32 Port (Weeks 6-8)

Goal: UOS microkernel running on ESP32, loaded by U-Boot.

Task	Effort	Depends on
4.1 Update UOS linker to IROM (0x40800000+) + DRAM (0x3FFB0000+)	1d	—
4.2 Port ESP32 exception vectors from esp-hal-3rdparty xtensa_vectors.S	3d	—
4.3 Implement UOS port layer (uos_port.h API):
4.3.1 — tick_init (CCOMPARE0)	1d	—
4.3.2 — context_switch (save/restore a0-a15, PS, EPC)	2d	—
4.3.3 — task_stack_init	1d	—
4.3.4 — critical_enter/exit (rsil)	0.5d	—
4.3.5 — idle (waiti)	0.5d	—
4.4 ESP32 UART driver (polled + interrupt)	2d	4.3
4.5 ESP32 GPIO driver	1d	4.3
4.6 ESP32 timer/WDT driver	1d	4.3
4.7 Test: two tasks printing messages via UOS scheduler	1d	4.3
4.8 Test: IPC between two tasks (message queue)	1d	4.7

Deliverable: UOS scheduler running, tasks printing, IPC working.

Phase 5: FreeRTOS/App Compatibility (Weeks 9-10)

Goal: Run existing ESP-IDF/FreeRTOS apps on UOS.

Task	Effort	Depends on
5.1 FreeRTOS-to-UOS syscall shim (xTaskCreate→uos_task_create, etc.)	3d	4.3
5.2 ESP-IDF peripheral driver shim (spi_flash, gpio, uart, i2c)	3d	4.4-4.6
5.3 WiFi/BT stack integration (if desired)	10d+	Phase 4
5.4 OTA update via MCUboot from UOS	2d	2.1
5.5 Test: ESP-IDF blinky/hello_world on UOS	1d	5.1

4. Key Technical Decisions

4.1 IROM vs IRAM for Code

ESP32 D-bus cannot write to I-bus addresses (0x40000000+). All executable code MUST be flash-MMU-mapped to IROM (0x40800000+), never memcpy'd to IRAM. Data (.data/.bss) lives in DRAM (0x3FFxxxxx) and is loaded via memcpy.

4.2 Flash MMU Architecture

The ESP32 flash MMU maps 64KB-aligned flash pages to IROM/DROM virtual addresses:

• IROM0 entries (192-255): I-bus for instruction fetch
• DROM0 entries (0-63): D-bus for data loads

For l32r (PC-relative data load) to work from IROM code, a DROM entry must map the same flash page to a DROM virtual address. The compiler generates l32r even with -mtext-section-literals. Solution: map each IROM page ALSO as a DROM page at a corresponding 0x3F4xxxxx address. The linker must ensure literals are referenced via DROM, not IROM.

Alternative: Use only movi.n + slli sequences (no l32r) for early boot code. U-Boot startup does this. For general C code, use the DROM mapping approach.

4.3 Cache Bus Masks

DPORT_PRO_CACHE_CTRL1_REG (0x3FF00044) bits:

• Bit 0: DROM0 mask (1=masked)
• Bit 1: DROM1 mask
• Bit 2: IROM0 mask ← Must be CLEAR
• Bit 3: IROM1 mask ← Must be CLEAR

MCUboot clears these before jumping to U-Boot. U-Boot's init sequence must PRESERVE them.

4.4 Exception Vectors at VECBASE

VECBASE = 0x40800000 (IROM0 base). Vector offsets:

• 0x040: UserException
• 0x100: KernelException
• 0x180: Level2 interrupt
• 0x1C0: Level3 interrupt
• 0x200: Level4 interrupt
• 0x240: Level5 interrupt
• 0x280: Level6 interrupt
• 0x2C0: NMI
• 0x3C0: DoubleException

Must use Espressif's xtensa_vectors.S (from esp-hal-3rdparty) or equivalent. Currently U-Boot discards these in the linker script.

4.5 ESP32 Partition Table Format

[esp_partition_info_t] × N  (N ≤ 96)
Each 32 bytes:
  uint16 magic    = 0x50AA
  uint8  type     (APP=0, DATA=1, BOOT=2)
  uint8  subtype  (FACTORY=0, OTA_0=0x10, ...)
  uint32 offset   (flash byte offset)
  uint32 size     (flash byte size)
  char   label[16]
  uint32 flags
Terminator: magic = 0xFFFF

U-Boot needs a parser for this. The structure is simple enough to implement in ~200 lines of C.

5. Files to Create / Modify

U-Boot (universalis-uboot/)

New files:
  arch/xtensa/cpu/cache.c           — cache_hal wrapper
  arch/xtensa/cpu/ccompare_timer.c  — CCOUNT-based timer
  arch/xtensa/lib/board.c           — board_init_f/r
  board/espressif/esp32/partition.c — partition table parser
  drivers/mtd/spi/esp32_flash.c     — SPI flash driver
  drivers/serial/esp32_uart.c       — UART driver
  drivers/gpio/esp32_gpio.c         — GPIO driver
  drivers/watchdog/esp32_wdt.c      — WDT driver
  include/configs/esp32.h           — update CFG_* macros
  arch/xtensa/dts/esp32.dts         — Device Tree

Modified:
  board/espressif/esp32/u-boot.lds  — add vector sections (DROM mapped)
  arch/xtensa/include/asm/arch-esp32/core.h — add XCHAL_* from official core-isa.h
  configs/esp32_defconfig           — enable DM_SPI_FLASH, ENV_IN_SPI_FLASH, etc.
  board/espressif/esp32/esp32.c     — full board_init

UOS Microkernel (universalisos/microkernel/)

New files:
  ports/esp32/uos_port_asm.S       — context switch in asm
  ports/esp32/uos_port_tick.c      — CCOMPARE0 tick init
  ports/esp32/uos_port_uart.c      — UART driver
  ports/esp32/uos_port_gpio.c      — GPIO driver
  ports/esp32/uos_port_wdt.c       — WDT driver
  ports/esp32/uos_vectors.S        — exception handlers (from xtensa_vectors.S)

Modified:
  ports/esp32/linker_flash.ld      — IROM 0x40800000 + DRAM layout
  ports/esp32/startup.S            — VECBASE, vectors from IROM
  ports/esp32/esp32_integration.c  — full HW init

6. Immediate Next Actions

1. Fix U-Boot console (Phase 1.4): Verify DM_SERIAL UART0 config. The garbled output after banner suggests baud rate mismatch or FIFO corruption between U-Boot init and console driver.

2. Implement ESP32 cache_ll wrapper (Phase 1.1-1.2): Copy cache_ll_l1_enable_bus from esp-hal-3rdparty/components/hal/esp32/include/hal/cache_ll.h into U-Boot.

3. Preserve MMU state (Phase 1.2): Audit U-Boot init sequence for any Cache_Read_Disable/Cache_Flush calls that would reset the MMU. Disable them for ESP32.

4. Fix IROM data loads (Phase 1.3): Map DROM entry alongside IROM entry in MCUboot.