emulator: GAM4980
type: libretro
core_classification: pure_libretro
source: "https://github.com/ThisBoringWorld/gam4980"
upstream: "https://codeberg.org/iyzsong/gam4980"
profiled_date: "2026-03-23"
core_version: "0.2"
display_name: "GAM4980"
cores:
  - gam4980
systems:
  - bbk-longman-4980

# GAM4980 emulates the BBK Longman 4980 (A4980/A4988) electronic dictionary.
# Original code from https://codeberg.org/iyzsong/gam4980, based on the
# BA4988 BBK simulator by Wuyun. Uses a 6502-based CPU with banked ROM access.
#
# ROM loading (src/libretro.c:692-760, sys_init):
#   Opens romdir/8.BIN and reads 0x200000 bytes (2 MB) into sys.rom_8 (font ROM).
#   Opens romdir/E.BIN and reads 0x200000 bytes (2 MB) into sys.rom_e (OS ROM).
#   The upstream has error handling (error_msg + RETRO_ENVIRONMENT_SHUTDOWN on
#   missing files). The fork (ThisBoringWorld) removed these checks -- crashes
#   on missing files.
#
# Memory map (src/libretro.c:109-110, 300-305):
#   0x800000-0x9FFFFF  rom_8 (font ROM, 8.BIN)
#   0xE00000-0xFFFFFF  rom_e (OS ROM, E.BIN)
#
# No hash validation. No size validation. The .info declares firmware_count=0.

notes: |
  Place 8.BIN and E.BIN in the RetroArch system/gam4980/ subdirectory.
  Both files must be 2 MB dumps from a BBK Longman 4980 dictionary:
    8.BIN - font ROM, dumped from address range 0x800000-0x9FFFFF
    E.BIN - OS ROM, dumped from address range 0xE00000-0xFFFFFF
  Game files use the .gam extension.

files:
  - name: "gam4980/8.BIN"
    size: 2097152
    required: true
    system: bbk-longman-4980
    note: "Font ROM (2 MB). Loaded at 0x800000."
    source_ref: "src/libretro.c:716-718"

  - name: "gam4980/E.BIN"
    size: 2097152
    required: true
    system: bbk-longman-4980
    note: "OS ROM (2 MB). Loaded at 0xE00000."
    source_ref: "src/libretro.c:720-722"

platform_details:
  bios_mapping:
    target: "0x800000-0x9FFFFF (font), 0xE00000-0xFFFFFF (OS) in banked address space"
    source_ref: "src/libretro.c:109-110, 300-305"
    notes: |
      sys.rom_8 and sys.rom_e are flat 2 MB arrays. The CPU accesses them
      through bank-switched memory (PA() macro resolves virtual to physical
      address). rom_8_vread and rom_e_vread handle indirect reads via
      the banking system.

  load_path:
    source_ref: "src/libretro.c:1173-1175"
    notes: |
      retro_init() builds the path as {system_directory}/gam4980/ and
      passes it to sys_init(). Files must be named exactly 8.BIN and
      E.BIN (case sensitive on Linux). No .info firmware declarations
      exist, so RetroArch won't warn about missing files at scan time.