Skip to content

source-layout.md

Latest commit

 

History

History
51 lines (42 loc) · 2.37 KB

source-layout.md

File metadata and controls

51 lines (42 loc) · 2.37 KB

Source Layout

The core source tree is organized by Jaguar hardware ownership. Keep mechanical file moves separate from behavior changes so emulator fixes stay easy to review and bisect.

Top-Level Files

  • libretro.c owns the libretro API entry points, core options, input polling, serialization glue, cheats, and per-frame execution handoff.
  • Makefile.common is the source list used by the main Makefile and Android NDK build. Update it whenever a C file is added, moved, or removed.

Subsystems

  • src/core/ contains system orchestration, the memory map, event scheduling, settings, file helpers, cheats, memory tracking, MMU helpers, and save-state support shared by multiple chips.
  • src/tom/ contains TOM-side hardware: video timing, Object Processor, GPU, Blitter, and Blitter SIMD implementations.
  • src/jerry/ contains JERRY-side hardware: DSP, DAC/audio pipeline, EEPROM, input/joystick handling, and wavetable data.
  • src/cd/ contains Jaguar CD/BUTCH register emulation and the disc-interface abstraction.
  • src/bios/ contains embedded BIOS and boot stub arrays. These are data-heavy generated/static inputs, not regular refactor targets.
  • src/m68000/ contains the UAE-derived 68K CPU core. Most files here are generated or upstream-derived and should remain isolated.

Refactor Guidelines

  • Preserve C89/GNU89 compatibility: declarations stay at the top of each block.
  • Keep public interfaces in subsystem headers and private cross-file state in small *_internal.h headers scoped to one subsystem.
  • Prefer one concern per commit: source moves, build updates, and logic changes should not be mixed unless the build cannot remain green otherwise.
  • When adding a new C file, update Makefile.common and the manual MSVC source list in .github/workflows/c-cpp.yml.
  • After source layout changes, run make lint, a clean native build, and the focused unit tests for the touched subsystem.

Blitter Files

  • src/tom/blitter.c contains the active Blitter implementation and Oberon-derived hardware logic.
  • src/tom/blitter_mmio.c contains Blitter lifecycle, register reads/writes, and command dispatch.
  • src/tom/blitter_compare.c contains comparison-mode diagnostics used when validating fast Blitter behavior against the accurate implementation.
  • src/tom/blitter_simd_*.c contains SIMD acceleration for selected data-path operations.