Architecture description

HarvOS is a small observable SoC for boot and runtime experiments. Its central design choice is a hard separation between instruction and data paths, so ELF code can be loaded into IMEM and locked by hardware.

CPU-internal view

HarvOS CPU architecture with boot ROM, MMU, MPU, Harvard boundary and immutable IMEM

SoC blocks

Block	Function	Implementation state
`harvos_cpu`	RV32I-like 32-bit CPU with local CSRs, HarvOS MMU/MPU, traps, fetch path and data path.	Implemented in RTL and used in Verilator tests.
`harvos_soc`	Top-level integration with two CPU harts, IMEM, DMEM, MMIO, DMA IOMMU, secure boot, USB, HNET and HPS block bridge.	Implemented in RTL; the test path uses images and Npcap/TAP-style bridging.
`harvos_smp_bus2`	Arbitrated shared data bus for both CPU harts.	Active for DMEM and MMIO accesses.
`harvos_mmu`	Virtual-to-physical access check with PTE-style flags and W^X enforcement.	Separate instances for fetch and data.
`harvos_mpu`	Fixed physical access policy for instruction ROM/IMEM, data RAM, MMIO and lock state; not RISC-V PMP.	Enforces Harvard rules and access faults.
`harvos_imem_loader_mmio`	The only legitimate write path into instruction memory during boot.	After `LOCK`, IMEM writes are rejected until reset.
`harvos_net_mmio`	Packet-DMA network device for HarvTTP, HarvSQL and the test suite.	RX/TX, IRQ, link status and DMA window.
`harvos_usb_host_mmio`	USB host MMIO with DMA, UTMI/DPDM signals, port power and retry/NAK/STALL status.	Integrated on the RTL side; mass-storage logic is software-side.
`harvos_mister_hps_block`	MiSTer/HPS-compatible block access to two disk images.	Current boot-ROM test path for program and data images.

CPU microarchitecture

The CPU is not superscalar or out-of-order. It is a deterministic multi-cycle machine. Each instruction passes through fetch, decode, execute and, when needed, memory/writeback. This keeps boot-ROM and low-level hardware debugging easy to observe.

State	Task
`ST_FETCH`	Check PC, handle interrupts/traps, apply fetch MMU/MPU and read the instruction word.
`ST_DECODE`	Decode source and destination registers.
`ST_EXEC`	ALU, branch, jump, CSR, system, Custom-0 and address calculation.
`ST_MEM`	Data MMU/MPU, byte lanes, load/store and MMIO access.
`ST_WB`	Write back to `rd` and advance the PC.
`ST_CLRMEM`	Privileged block clearing through Custom-0.

Harvard separation

The normal data path cannot write IMEM directly. Executable ELF code is loaded only by the boot ROM through the IMEM loader. Once the loader is locked, a running service can use data, BSS, stack and MMIO, but it cannot patch or load instructions.

Web content, SQL catalogs, start parameters and HTTP bundles live in DMEM or data images. Executable segments live in IMEM.

Current boot/runtime boundary

The SoC initializes IMEM through $readmemh or a default ROM.
Secure boot releases boot_ok; on failure the CPU stays in the reset path.
The boot ROM detects two images, mounts them and searches for valid ELF/YAML/data pairs.
ELF text segments are written through the IMEM loader; data segments go to DMEM.
The boot ROM builds start parameters and optional service bundles.
IMEM is locked and the CPU jumps to the ELF entry.
Services such as HarvTTP and HarvSQL use HNET MMIO and data-image assets.