Lukas Höppner
56 lines
4.8 KiB
Markdown
56 lines
4.8 KiB
Markdown
# Nova64 Cyberdeck Platform - High-Level System Specification
|
|
|
|
## 1. System Overview & Core Concept
|
|
* **Project Name:** Nova64
|
|
* **Architecture Model:** Dual-target modular system featuring a native execution core (`nova64_core`) running on top of **FreeRTOS**.
|
|
* **Target Microcontroller:** **ESP32-P4** (RISC-V architecture) driving local display output, audio generation, custom expansion bus, and network interfaces.
|
|
* **Desktop Simulator / Tooling:** Native C core compiled as a shared library (`.dll` / `.so`) and driven by a **C# Host Application** via P/Invoke. Hardware dependencies are injected at runtime via function pointer callbacks (Dependency Injection pattern).
|
|
* **Central Unit Input Constraint:** The base display unit **contains no (or only limited) built-in physical input controls** (no onboard buttons or D-pad). Control inputs are provided externally via connected cartridges, expansion modules, network interfaces, or desktop simulator inputs.
|
|
|
|
---
|
|
|
|
## 2. Physical Cartridge & Expansion Slot Architecture
|
|
* **Mechanical Interface:** Uses a 32-pin edge-connector format (Game Boy style form factor, required PCB thickness: 1.2 mm).
|
|
* **Poka-Yoke Protection:** Custom mechanical keying (notches/grooves) to physically prevent legacy/original Game Boy cartridges from being inserted and damaging the 3.3V logic lines.
|
|
* **Bus Protocols & Interfaces:**
|
|
* **SD Card Interface (SDMMC):** Dedicated high-speed lines. *Rule: SD pins must remain allocated and accessible across all slot modes. This allows loading custom cartridge software for specialized cartridges.*
|
|
* **USB:** Native USB Host / Device capability for smart cartridges or peripherals.
|
|
* **I2C, SPI & CAN-Bus:** Serial buses for sensors, co-processors, and expanders.
|
|
* **Cartridge pinout reference:** Detailed connector numbering, signal roles, and idle states are defined in [CARTRIDGE_PINOUT.md](./CARTRIDGE_PINOUT.md) to keep this document as the single high-level system spec.
|
|
* **Power Bus:** Supports dual-directional power delivery (supplying power to cartridges or receiving alternative system power/charging from external battery cartridges).
|
|
|
|
---
|
|
|
|
## 3. Networking Interface (10BASE-T1L)
|
|
* **Protocol:** **10BASE-T1L** (Single-Pair Ethernet) for long-distance, industrial-grade point-to-point and networked communication between decks/modules.
|
|
* **Physical Cabling:** routed through **audio-style connectors/cables** (e.g., 3.5mm/6.3mm jacks) to fit the cyberpunk aesthetic while maintaining robust single-pair data transmission.
|
|
* **Audio Use:** the same 10BASE-T1L connector is also intended to carry analog audio signals in some modes, requiring dedicated isolation and protection circuitry to separate audio from data and to protect the network interface.
|
|
|
|
---
|
|
|
|
## 4. WASM Application Runtime (WAMR)
|
|
* **Runtime Engine:** **WAMR (WebAssembly Micro Runtime)** embedded directly into `nova64_core`.
|
|
* **Execution Model:** Sandboxed application layer for dynamic software, games, and cartridge binaries.
|
|
* **Cross-Platform Parity:** Uncompiled WASM bytecode runs identically on both the physical ESP32-P4 hardware and the C# Desktop Simulator.
|
|
* **Host Bindings:** WAMR exports host functions bound to the internal `nova64_core` APIs, allowing sandboxed WASM applications to draw to the framebuffer, play audio, and read cartridge storage safely.
|
|
|
|
---
|
|
|
|
## 5. Software HAL & FreeRTOS Architecture
|
|
* **Hardware Abstraction (I/O Callbacks):**
|
|
* Core engine defines function pointer contracts: `display_flush`, `audio_output`, `sd_read_sector`, and `cartridge_status` (with `slot_idx` support for multi-slot setups).
|
|
* System initialized via `nova64_init_io()`.
|
|
|
|
---
|
|
|
|
## 6. Display, Framebuffer & Core Allocation Strategy
|
|
* **Dual-Core Processor Allocation (ESP32-P4):**
|
|
* **Core 0 (System & I/O Core):** Handles background FreeRTOS tasks, hardware drivers, 10BASE-T1L networking stack, audio generation, and system status bar overlays.
|
|
* **Core 1 (Execution Core):** Exclusively dedicated to running the WAMR WebAssembly engine and application code, guaranteeing deterministic performance and preventing OS tasks from causing frame drops.
|
|
* **Framebuffer Architecture:**
|
|
* Uses double-buffering (RGB565 format) to prevent screen tearing during active rendering.
|
|
* Framebuffers are explicitly allocated in **External PSRAM via the AXI bus**, enabling direct DMA (Direct Memory Access) streaming to the MIPI-DSI controller without CPU overhead.
|
|
* Application output and system UI are composited into the target buffer before triggering the host-injected `display_flush` callback (or VSYNC pointer swap).
|
|
* **Persistent System Status Bar:**
|
|
* A reserved hardware/system UI region at the top of the display rendered independently by Core 0.
|
|
* Displays active cartridge ID, 10BASE-T1L link status, battery levels, and system health metrics without interfering with running WASM applications. |