1# Architecture
2
3## Overview
4
5The crates can be broken up roughly into 6 categories:
6* Common libraries: `jgenesis-common`, `jgenesis-proc-macros`, `cdrom`, `dsp`
7* CPU emulators: `z80-emu`, `m68000-emu`, `mos6502-emu`, `wdc65816-emu`, `spc700-emu`, `sh2-emu`
8* Config libraries: `smsgg-config`, `genesis-config`, `nes-config`, `snes-config`, `gb-config`
9* Emulation backend: `smsgg-core`, `genesis-core`, `segacd-core`, `s32x-core`, `nes-core`, `snes-core`, `snes-coprocessors`, `gb-core`, `ym-opll`
10* Emulation frontend: `jgenesis-renderer`, `jgenesis-native-driver`, `jgenesis-native-config`, `jgenesis-cli`, `jgenesis-gui`, `jgenesis-web`
11* CPU emulator test harnesses: `z80-test-runner`, `m68000-test-runner`, `mos6502-test-runner`, `wdc65816-test-runner`, `spc700-test-runner`
12
13Repo structure:
14* `common/` contains common library crates
15* `cpu/` contains the CPU emulator and test harness crates
16* `config/` contains the config library crates
17* `backend/` contains the emulation backend crates
18* `frontend/` contains the emulation frontend crates
19
20The CPU emulators are designed to be usable with any implementation of their respective bus traits. The test harnesses provide a bus implementation that maps every address to RAM (which is what the tests expect), while the various consoles provide implementations that emulate the console's memory map.
21
22The "config" crates contain common structs and enums that are both used in the corresponding backend crate and serialized into the frontend's config file. These are in separate crates from the backend cores to improve incremental compilation times, specifically by only re-executing `serde` and `clap` derive macros when needed.
23
24For the most part, the backends interact with the frontends through trait implementations. The backends implement traits that enable frontend features including save states and rewind. The frontends provide trait implementations to the backends that enable the backends to display video frames, output audio samples, and persist any save files (e.g. for a cartridge with battery-backed SRAM). The frontends are also responsible for passing current emulated controller state to the backends (i.e. which buttons are currently pressed).
25
26## Common Crates
27
28### `jgenesis-common`
29
30Contains traits that define the interface between the emulation backends and the emulation frontends, as well as some dependency-light common code that is used across many of the other crates (e.g. helper extension traits).
31
32### `jgenesis-proc-macros`
33
34Custom derive macros and other proc macros used across many of the other crates.
35
36### `cdrom`
37
38Contains code for reading CD-ROM images in CUE/BIN or CHD format.
39
40### `dsp`
41
42DSP (digital signal processing) code, used primarily for audio-related functionality (e.g. resampling).
43
44## CPU Crates
45
46### `z80-emu`
47
48Instruction-based emulation core for the Zilog Z80 CPU, which is used in the Master System, the Game Gear, and the Genesis.
49
50### `m68000-emu`
51
52Instruction-based emulation core for the Motorola 68000 CPU, which is used in the Genesis and the Sega CD.
53
54### `mos6502-emu`
55
56Cycle-based emulation core for the MOS 6502 CPU. Supports both the stock 6502 and the NES 6502.
57
58### `wdc65816-emu`
59
60Cycle-based emulation core for the WDC 65C816 CPU (aka 65816), which is used in the SNES.
61
62### `spc700-emu`
63
64Cycle-based emulation core for the Sony SPC700 CPU, which is used in the SNES as a dedicated audio processor embedded inside the APU.
65
66### `sh2-emu`
67
68Instruction-based emulation core for the Hitachi SH-2 CPU, used in the Sega 32X and the Sega Saturn. This implementation includes the SH7604 hardware features.
69
70## Config Crates
71
72### `smsgg-config`
73
74Common structs and enums for the Sega Master System and Game Gear.
75
76### `genesis-config`
77
78Common structs and enums for the Sega Genesis, including Sega CD and 32X.
79
80### `nes-config`
81
82Common structs and enums for NES.
83
84### `snes-config`
85
86Common structs and enums for SNES.
87
88### `gb-config`
89
90Common structs and enums for Game Boy and Game Boy Color.
91
92## Backend Crates
93
94### `ym-opll`
95
96Emulation core for the Yamaha OPLL sound chip, used in the Sega Master System FM sound unit expansion and the NES VRC7 mapper.
97
98### `smsgg-core`
99
100Emulation core for the Sega Master System, Game Gear, and SG-1000. The core is shared because there are very few hardware differences between the three.
101
102### `genesis-core`
103
104Emulation core for the Sega Genesis / Mega Drive. Uses the PSG component from `smsgg-core`, since the Genesis reused the Master System PSG as a secondary sound chip.
105
106### `segacd-core`
107
108Emulation core for the Sega CD / Mega CD. Uses many components from `genesis-core`, as the Genesis side of the system is virtually unchanged except for the parts of the memory map that the standalone Genesis maps to the cartridge.
109
110### `s32x-core`
111
112Emulation core for the Sega 32X / Mega 32X. Also uses many components from `genesis-core`.
113
114### `nes-core`
115
116Emulation core for the Nintendo Entertainment System (NES) / Famicom.
117
118### `snes-core`
119
120Emulation core for the Super Nintendo Entertainment System (SNES) / Super Famicom. Depends on `snes-coprocessors` to emulate cartridges that contain coprocessors.
121
122### `snes-coprocessors`
123
124Emulation for coprocessors used in SNES cartridges. Coprocessor cartridge implementations expose methods such as reading a memory address, writing a memory address, and ticking the internal processor (for cartridges that contain a CPU or DSP).
125
126### `gb-core`
127
128Emulation core for the Game Boy and Game Boy Color.
129
130## Frontend Crates
131
132### `jgenesis-renderer`
133
134GPU-based implementation of the `Renderer` trait in `jgenesis-traits`, built on top of `wgpu`. Can be used with any window that implements the `raw-window-handle` traits. Exists in its own crate so that it can be used in both the native and web frontends.
135
136### `jgenesis-native-driver`
137
138Native emulation frontend that uses SDL3 for windowing, audio, and input.
139
140### `jgenesis-native-config`
141
142Contains the code representation of the configuration file used by the CLI and GUI.
143
144### `jgenesis-cli` / `jgenesis-gui`
145
146CLI and GUI that both invoke `jgenesis-native-driver` to run the emulator. `jgenesis-gui` is built using `egui` and `eframe`.
147
148### `jgenesis-web`
149
150Web emulation frontend that compiles to WASM and runs in a web browser.
151
152## CPU Test Harness Crates
153
154### `z80-test-runner`
155
156Test harness to test `z80-emu` against Z80 test suites that were assembled for old PCs, such as ZEXDOC and ZEXALL.
157
158### `m68000-test-runner`
159
160Test harness to test `m68000-emu` against [TomHarte's 68000 test suite](https://github.com/TomHarte/ProcessorTests/tree/main/680x0/68000/v1).
161
162### `mos6502-test-runner`
163
164Test harness to test `mos6502-emu` against [TomHarte's NES 6502 test suite](https://github.com/TomHarte/ProcessorTests/tree/main/nes6502).
165
166### `wdc65816-test-runner`
167
168Test harness to test `wdc65816-emu` against [TomHarte's 65816 test suite](https://github.com/TomHarte/ProcessorTests/tree/main/65816).
169
170### `spc700-test-runner`
171
172Test harness to test `spc700-emu` against [JSON SPC700 test suites](https://github.com/TomHarte/ProcessorTests/tree/main/spc700).