# dwedit/pocketnes architecture

> Architecture diagram of the GitHub repository dwedit/pocketnes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dwedit/pocketnes
- Repository: https://github.com/dwedit/pocketnes

## Overview

##### Project Type and Purpose
- PocketNES is an embedded emulator: it implements the NES’s 6502-based CPU, PPU (graphics), APU (sound), memory mappers, and UI layers to run NES ROMs on Game Boy Advance hardware.

##### File Structure
- Top level:
- nespack/ – Windows executables for packing ROMs (tooling, not on‐GBA runtime)
- Makefile / Makefile_mb – build scripts targeting GBA toolchain
- README.md – brief project description
- src/ – emulator source:
- CPU core (6502.s, 6502mac.h)
- Memory subsystem (memory.s, mem.s, cache.c/.h)
- Cartridge loader (loadcart.c/.h) & mappers/ – one .s file per mapper
- PPU (ppu.s), APU (sound.s), interrupt dispatcher (interruptdispatcher.s)
- UI & menus (ui.c/.h, rommenu.c/.h, cheat.c/.h)
- Save/load state (savestate*.c/.h), SRAM (sram.c/.h)
- Speed hacks & deferred calls (new_speed_hack.c/.h, deferred_calls.s)
- Compression lib (minilzo.107/ & minilzo.c/.h)
- GBA startup (gba_crt0_my.s, gba_my.specs, gba_cart_my.ld, etc.)

##### README
- Confirms: “NES emulator for GBA.” No further architecture notes; all detail resides in the file tree.

##### Main Components & Interactions
A. GBA Hardware Layer (external)
- Video I/O, Sound hardware, Input buttons, Cartridge interface, SRAM
B. GBA Runtime/Startup
- crt0, linker script, specs → initializes hardware, sets up stack, calls main()
C. Cartridge Loader & NES ROM Storage
- loadcart module reads ROM from flash into emulator memory
D. Memory System & Mapper Layer
- memory.s + mem.c + cache.c + mappers/*
- Handles CPU memory reads/writes, bank switching, mirroring
E. CPU Core (6502)
- 6502.s – fetch/decode/execute, uses asmcalls.h for C integration
F. PPU (Picture Processing Unit)
- ppu.s – renders scanlines, accesses VRAM, writes to GBA frame buffer
G. APU (Audio Processing Unit)
- sound.s – generates audio channels, outputs via GBA sound registers
H. Interrupt & Timing Dispatcher
- interruptdispatcher.s, interrupt.c – synchronizes PPU, APU, DMA, timers
I. UI & Menus
- ui.c, rommenu.c, cheat.c – on-screen menus, cheat toggles, text rendering (font.lz77)
J. Persistence & State
- savestate2.c, sram.c – save/load snapshots, battery-backed SRAM
K. Utilities & Libraries
- Compression (minilzo) for assets, font decompression
- Speed hacks to accelerate hot loops

##### Architectural Patterns & Principles
- Layered design: low-level CPU/PPU/APU in assembly for performance, high-level UI in C
- Modular mappers allow adding support for new cartridge hardware by dropping in .s files
- Clear separation: hardware abstraction (GBA) vs. emulator core (NES)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% GBA Hardware & Startup Layer
    subgraph "GBA Hardware & Startup"
        direction TB
        HW_IO["GBA Hardware\n(Video, Sound, Input,\nCartridge, SRAM)"]:::startup
        CRT0["crt0 & Specs\n(gba_crt0_my.s,\ngba_cart_my.ld,\ngba_my.specs,\ngba_mb_my.ld,\ngba_mb_my.specs)"]:::startup
        IO_S["I/O Setup\n(src/io.s)"]:::startup
    end

    %% Cartridge Loader & ROM Storage
    subgraph "Cartridge Loader & NES ROM Storage"
        direction TB
        Loader["Loadcart Module\n(loadcart.c/.h,\ncart.s, apack.s)"]:::memory
        Tools["nespack Tools\n(nespack/)"]:::startup
    end

    %% Memory System & Mappers
    subgraph "Memory System & Mapper Layer"
        direction TB
        MemoryCore["Memory Core\n(memory.s, mem.s,\nmemcopy.s)"]:::memory
        Cache["Cache\n(cache.c/.h)"]:::memory
        Mappers["Mappers\n(src/mappers/*.s)"]:::memory
    end

    %% Emulator Core
    subgraph "Emulator Core"
        direction TB
        CPU["CPU Core (6502)\n(6502.s, asmcalls.h,\n6502mac.h)"]:::core
        PPU["PPU\n(ppu.s)"]:::core
        APU["APU\n(sound.s)"]:::core
    end

    %% Interrupt & Timing
    subgraph "Interrupt & Timing Dispatcher"
        direction TB
        IRQ["Interrupt Dispatcher\n(interruptdispatcher.s,\ninterrupt.c)"]:::core
    end

    %% UI & Menus
    subgraph "UI & Menus"
        direction TB
        UI_mod["UI Modules\n(ui.c/.h,\nrommenu.c/.h,\ncheat.c/.h)"]:::ui
        Text["Text & Fonts\n(pocketnes_text.c/.h,\nfont.lz77, font2.lz77,\nfontpal.bin)"]:::ui
    end

    %% Persistence & State
    subgraph "Persistence & State"
        direction TB
        State["Save/Load State\n(savestate2.c/.h,\nsavestate.h)"]:::ui
        SRAM["SRAM Interface\n(sram.c/.h)"]:::ui
    end

    %% Utilities & Hacks
    subgraph "Utilities & Performance Hacks"
        direction TB
        LZO["Compression Lib\n(minilzo.107, minilzo.c/.h)"]:::util
        Speed["Speed Hacks\n(new_speed_hack.c/.h,\ndeferred_calls.s,\nspeedhack_asm.s)"]:::util
    end

    %% Build & Toolchain
    subgraph "Build Scripts & Toolchain"
        direction TB
        Build["Makefiles & Link\n(Makefile, Makefile_mb,\nlink.s, README.md)"]:::startup
    end

    %% Connections
    Tools -->|packs ROM| Loader
    Loader -->|loads ROM| MemoryCore
    MemoryCore <-->|reads/writes| CPU
    CPU -->|executes| IRQ
    IRQ -->|sync| PPU
    IRQ -->|sync| APU
    PPU -->|video scanlines| HW_IO
    APU -->|audio samples| HW_IO
    CPU -->|instructions| MemoryCore
    MemoryCore -->|bank switching| Mappers
    UI_mod <-->|input events| IRQ
    UI_mod -->|renders text| Text
    State <-->|save/load| SRAM
    State -->|state data| MemoryCore
    Build -->|builds| CRT0
    CRT0 -->|initializes| CPU

    %% Click Events
    click CRT0 "https://github.com/dwedit/pocketnes/blob/main/src/gba_crt0_my.s"
    click CRT0 "https://github.com/dwedit/pocketnes/blob/main/src/gba_cart_my.ld"
    click CRT0 "https://github.com/dwedit/pocketnes/blob/main/src/gba_my.specs"
    click IO_S "https://github.com/dwedit/pocketnes/blob/main/src/io.s"
    click Loader "https://github.com/dwedit/pocketnes/blob/main/src/loadcart.c"
    click Loader "https://github.com/dwedit/pocketnes/blob/main/src/loadcart.h"
    click Loader "https://github.com/dwedit/pocketnes/blob/main/src/cart.s"
    click Loader "https://github.com/dwedit/pocketnes/blob/main/src/apack.s"
    click Tools "https://github.com/dwedit/pocketnes/tree/main/nespack/"
    click MemoryCore "https://github.com/dwedit/pocketnes/blob/main/src/memory.s"
    click MemoryCore "https://github.com/dwedit/pocketnes/blob/main/src/mem.s"
    click MemoryCore "https://github.com/dwedit/pocketnes/blob/main/src/memcopy.s"
    click Cache "https://github.com/dwedit/pocketnes/blob/main/src/cache.c"
    click Cache "https://github.com/dwedit/pocketnes/blob/main/src/cache.h"
    click Mappers "https://github.com/dwedit/pocketnes/tree/main/src/mappers/"
    click CPU "https://github.com/dwedit/pocketnes/blob/main/src/6502.s"
    click CPU "https://github.com/dwedit/pocketnes/blob/main/src/asmcalls.h"
    click CPU "https://github.com/dwedit/pocketnes/blob/main/src/6502mac.h"
    click PPU "https://github.com/dwedit/pocketnes/blob/main/src/ppu.s"
    click APU "https://github.com/dwedit/pocketnes/blob/main/src/sound.s"
    click IRQ "https://github.com/dwedit/pocketnes/blob/main/src/interruptdispatcher.s"
    click IRQ "https://github.com/dwedit/pocketnes/blob/main/src/interrupt.c"
    click UI_mod "https://github.com/dwedit/pocketnes/blob/main/src/ui.c"
    click UI_mod "https://github.com/dwedit/pocketnes/blob/main/src/ui.h"
    click UI_mod "https://github.com/dwedit/pocketnes/blob/main/src/rommenu.c"
    click UI_mod "https://github.com/dwedit/pocketnes/blob/main/src/rommenu.h"
    click UI_mod "https://github.com/dwedit/pocketnes/blob/main/src/cheat.c"
    click UI_mod "https://github.com/dwedit/pocketnes/blob/main/src/cheat.h"
    click Text "https://github.com/dwedit/pocketnes/blob/main/src/pocketnes_text.c"
    click Text "https://github.com/dwedit/pocketnes/blob/main/src/pocketnes_text.h"
    click State "https://github.com/dwedit/pocketnes/blob/main/src/savestate2.c"
    click State "https://github.com/dwedit/pocketnes/blob/main/src/savestate2.h"
    click State "https://github.com/dwedit/pocketnes/blob/main/src/savestate.h"
    click SRAM "https://github.com/dwedit/pocketnes/blob/main/src/sram.c"
    click SRAM "https://github.com/dwedit/pocketnes/blob/main/src/sram.h"
    click LZO "https://github.com/dwedit/pocketnes/tree/main/src/minilzo.107/"
    click LZO "https://github.com/dwedit/pocketnes/blob/main/src/minilzo.c"
    click LZO "https://github.com/dwedit/pocketnes/blob/main/src/minilzo.h"
    click Speed "https://github.com/dwedit/pocketnes/blob/main/src/new_speed_hack.c"
    click Speed "https://github.com/dwedit/pocketnes/blob/main/src/new_speed_hack.h"
    click Speed "https://github.com/dwedit/pocketnes/blob/main/src/deferred_calls.s"
    click Speed "https://github.com/dwedit/pocketnes/blob/main/src/speedhack_asm.s"
    click Build "https://github.com/dwedit/pocketnes/tree/main/Makefile"
    click Build "https://github.com/dwedit/pocketnes/tree/main/Makefile_mb"
    click Build "https://github.com/dwedit/pocketnes/blob/main/src/link.s"
    click Build "https://github.com/dwedit/pocketnes/blob/main/README.md"

    %% Styles
    classDef core fill:#add8e6,stroke:#000,stroke-width:1px
    classDef memory fill:#90ee90,stroke:#000,stroke-width:1px
    classDef startup fill:#ffdead,stroke:#000,stroke-width:1px
    classDef ui fill:#ffffe0,stroke:#000,stroke-width:1px
    classDef util fill:#d3d3d3,stroke:#000,stroke-width:1px
```
