emulator: VeMUlator
type: libretro
source: "https://github.com/libretro/vemulator-libretro"
profiled_date: "2026-03-18"
core_version: "0.1"
display_name: "VeMUlator"
cores:
  - vemulator
systems:
  - sega-vmu

notes: |
  VeMUlator is a Sega Dreamcast Visual Memory Unit (VMU/VMS) emulator ported
  from Android (Java) to C++ for libretro. It emulates the Sanyo LC8670
  "Potato" CPU, 128 KB flash memory, 48x32 monochrome LCD, piezo buzzer,
  and basic timer subsystems.

  No BIOS files are required. The core uses High Level Emulation (HLE) to
  bypass the VMU firmware entirely:

  - At startup, startCPU() checks the BIOSExists flag (vmu.cpp:195). When
    false (always, in the libretro port), it calls initializeHLE() which
    sets up SFR registers (SP=0x7F, PSW=0x02, IE=0x80, MCR=0x08, P7=0x02,
    OCR=0xA3, BTCR=0x41) and system RAM variables directly (vmu.cpp:206-222).

  - A loadBIOS() function exists in the VMU class (vmu.cpp:82-137) and can
    handle both encrypted (XOR 0x37, 4-byte header stripped) and unencrypted
    BIOS images (first byte must be 0x2A = JMPF opcode). Maximum accepted
    size is 0xF004 (61444) bytes, loaded into 0xF000 (61440) bytes of ROM.
    However, this function is never called by the libretro frontend code.
    retro_load_game() in main.cpp only loads game flash data, with no BIOS
    path resolution or RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY call.

  - The README lists "BIOS support" as a planned future feature.

  The .info file declares no firmware entries (firmware_count absent).
  Supported ROM formats: VMS (.vms), DCI (.dci), raw flash dump (.bin).
  The core option "enable_flash_write" allows persistent saves for .bin files.

files: []

platform_details:
  hle_implementation:
    source_ref: "vmu.cpp:195-222"
    sfr_init:
      SP: "0x7F"
      PSW: "0x02"
      IE: "0x80"
      MCR: "0x08"
      P7: "0x02"
      OCR: "0xA3"
      BTCR: "0x41"
    ram_init:
      - "0x31 = 0xFF (battery level)"
      - "0x6E = 0xFF"
      - "P3 = 0xFF (no buttons pressed)"
      - "BCD date/time at 0x10-0x16, raw at 0x17-0x1D"
    notes: |
      HLE skips the BIOS boot sequence and jumps directly into the loaded
      game. System clock, date, and button state are initialized in RAM.
      The EXT register is set to 1 to signal HLE mode to the CPU
      (vmu.cpp:198-199). Games that depend on BIOS-initialized state
      beyond what HLE provides may not work correctly.

  unused_bios_loader:
    source_ref: "vmu.cpp:82-137"
    max_file_size: 61444
    rom_load_size: 61440
    encryption: "XOR 0x37 after stripping 4-byte header"
    detection: "first byte 0x2A (JMPF) = unencrypted, otherwise encrypted"
    notes: |
      The loadBIOS() method is fully implemented but unreachable from the
      libretro interface. No system directory query, no BIOS path construction,
      and no call site exists in main.cpp. A future update could wire this up
      to support real VMU firmware boot (file manager, clock, mini-games menu).