AExp

Imported from sy2002/AExp (AGENTS.md). Install upstream with npx skills add sy2002/AExp. Copyright stays with the author.

AExp — Amiga 500 for MEGA65

Port of the MiSTer Minimig-AGA core to the MEGA65, scoped to an Amiga 500 OCS, built on the MiSTer2MEGA65 (M2M) framework V2.0.1.

Status: ADF floppy milestone achieved (2026-07-03). Read-only ADF support verified on real R3 hardware: Workbench 1.3.2 boots to the desktop, demoscene trackloaders run (State of the Art, Batman, TBL Eon). Mount via OSM " ADF:" → Shell streams to HyperRAM (QNICE device 0x0103, adf_mount_wrapper.vhd) → adf_track_engine.vhd serves Paula over the IO_FPGA host channel with bit-exact minimig_fdd.cpp MFM encoding. Design spec: .research/INTEGRATION-SPEC-floppy-adf.md (supersedes the vdrives advice). Milestone 1 (Kickstart hand, 2026-06-10/11) preceded it. Timing closed (run 3: all AExp-owned groups ≥ +0.24 ns; global WNS +0.017 ns sits on the framework HyperRAM PHY path). Interlace weave deinterlacing shipped 2026-07-04 (minimig field1 → video_fl chain → ascal i_fl, INTER => true; verified on R3 hardware — Batman Rises' laced intro is stable; commit 29c1aa2, WNS +0.108 ns). VGA analog modes + OSM restructure implemented 2026-07-04 (VGA: Standard / 15 kHz HS+VS / 15 kHz CSYNC radio, C64MEGA65-style decode + retro15kHz OSM-CE in main.vhd; filter submenu now directly under the HDMI resolution submenu; Audio-improvements item removed, qnice_audio_filter_o tied '0'; OPTM_SIZE 35→44) — synthesized (WNS +0.165 ns, BRAM unchanged) and verified on R3 hardware 2026-07-04. Firmware OSM constants are now autogenerated like in C64MEGA65 (make_rom.sh → osm_const.asm; refactor proven ROM-byte-identical); the settings file is generated by make_release.py at packaging — the tracked aexpcfg master was removed. Screen adjustment (issue #5): HDMI crop is hardware-verified (2026-07-09, both outputs of the old increment). The old "VGA centering" was an RCA-confirmed false positive — the soft blank only crops, it never pans. Replaced 2026-07-13 (A9) by a TRUE analog positioner — implemented + sim-proven (5-scenario nvc TB), NOT yet synthesized/hardware-tested. New generic M2M/vhdl/av_pipeline/analog_positioner.vhd (M2M-UPSTREAM screen-center, in all four .xpr): post-OSM, pre-CSYNC edge rescheduler that shifts HS/VS phase vs. final RGB (delay = predicted period − pan; two-back VS predictor keeps interlace half-line phase + parity; width-exact per-pulse delays; seamless engage/bypass; porch-measured H clamps from post-crop DE + structural line/8, V ±64 lines; pan=0 = combinational bypass → other cores bit-identical). Units mode-normalized via doubled_i ← scandoubler: pan_x = 1 hires px, pan_y = 1 line in ALL three VGA modes. Data path: v4 aexp_screen.cfg (84 B, per-mode rows [4 HDMI][4 overscan][2 pan]; firmware still accepts v3, pan=0) → LOAD_SCREEN_OFFSETS/DETECT_SCREEN_MODE → CFD gp_reg words 8-9 → i_qnice2video CDC (142→166). The soft blank stays as honest analog OVERSCAN (crop/reveal borders) and was hardened: reset + geometry-acquisition gate, clamped edge targets (no more permanent-blank/12-bit wrap). Tool v4 (grouped UI, --pan-x/-y, --reset, --copy-from, direction echo, v3 migration, test_aexp_screen_cfg.py = 25 tests); presets regenerated v4; doc/screen_adjust.md rewritten around position/overscan/no-true-scale. Interactive OSD adjust still pending. HDMI flicker-free (issue #12) — Increment 1 implemented 2026-07-09, statically verified (nvc analyze + elaborate against the real clk/cdc_stable; adversarial swarm) but NOT yet synthesized/hardware-tested. CORE-only (clk.vhd + mega65.vhd + config.vhd + CORE.xdc; zero M2M/.xpr/firmware edits). A second MMCM i_clk_fast = 28.437500 MHz (313-line = 50.030 Hz, above 50) + a glitch-free BUFGMUX_CTRL are dithered native↔fast by a 2-state FSM in the hr_clk domain driven by the already-plumbed ascal over/underflow loop (hr_high_i/hr_low_i, mega65.vhd:97-98) → the core's time-average frame rate is exactly 50.000 Hz; interlace already averages 50.000 and settles on native (zero dither). Direction inverted vs C64MEGA65: native 49.92 is BELOW 50 → the twin is FASTER. HDL-read OSM toggle "HDMI: Flicker-free" (top-level between the HDMI Filter and VGA submenus, single-select default ON; C_MENU_HDMI_FF=25, OPTM_SIZE 41→42, OPTM_DY 12→13, VGA C_MENU_*/lines +1; ships in the unreleased WIP-V1-A6, no version bump). CORE.xdc times the fast leg (set_case_analysis 1 on hr_core_speed_reg[0]/Q, create_generated_clock on i_clk_fast/CLKOUT0) — the leaf names i_clk_fast/hr_core_speed are load-bearing (a "no pins matched" warning silently no-ops STA). Recommend FF OFF for VGA/15 kHz (H-sync frequency step). Real synthesis risk = the R6 global HyperRAM-PHY WNS (+0.058 ns baseline), NOT core timing (~+7 ns). Increment 2 (3-clock, adds i_clk_slow=28.3125 for the rare >50 content) deferred. Spec: .research/INTEGRATION-SPEC-hdmi-flicker-free.md. Everything below is the distilled project knowledge — the deep material lives in doc/ (see "Key documents").

The emulated machine

• Amiga 500, OCS only (no ECS/AGA), PAL only, 68000 (fx68k, cycle-exact)
• 512 KB Chip RAM ($000000–$07FFFF) + 512 KB Slow RAM ($C00000–$C7FFFF, the "trapdoor" expansion) + 256 KB Kickstart 1.3 — all in FPGA BRAM, no SDRAM involved (R3 has none; R4+ SDRAM is unused). The Slow RAM is OSM-switchable: "Slow RAM (A501)" toggle, default on (issue #20, for programs like Rogue that break with expansion RAM; implemented 2026-07-16, NOT yet synthesized/HW-tested). The toggle drives slow_ram_i → amiga_config.vhd, which sets userio 0xF5 payload bit 2 (SS[0]); the firmware auto-soft-resets on toggle (RESET_CORE in OSM_SEL_POST) so the replayed config takes effect at once. With slow RAM off, minimig decodes $C00000+ as the custom-register mirror (authentic chip-only A500); the RTC at $DC0000 stays mapped (deliberate, matches MiSTer). The slow BRAM stays instantiated either way (no BRAM delta).
• Kickstart is loaded from SD card at boot: /amiga/kick.rom (raw 256 KB dump, big-endian, no byte swapping), mandatory — missing file = fatal error screen, core never starts (C_CRTROMTYPE_MANDATORY in CORE/vhdl/globals.vhd)
• One core clock: 28.375 MHz (PAL ideal 28.37516, −5.6 ppm), MMCM in CORE/vhdl/clk.vhd (100 MHz × 56.750 / 5 / 40). No 113.5 MHz clock — everything SDRAM/turbo/AGA that needed it is out of scope.
• Floppy: df0 with read/write ADF mount from the OSM (image staged in HyperRAM at word 0x200000 = C_HMAP_ADF_DF0). Write support implemented 2026-07-05, NOT yet synthesized/hardware-verified: hardware MFM write decoder (bit-exact minimig_fdd.cpp FindSync/GetHeader/GetData) commits verified sectors to HyperRAM; per-track dirty bitmap + vdrives-style anti-thrash (2 s, config.vhd word 13) in adf_mount_wrapper window 0xFFFE ("WBC"); firmware flushes dirty tracks to the SD file in the background via the new HANDLE_CORE_IO hook (512 B + fflush per slice, own FDH snapshot — the Shell re-opens HANDLE_RM_FILE1 before PREP_LOAD_IMAGE!); drive LED yellow while dirty. Design + review findings: .research/INTEGRATION-SPEC-floppy-adf-write.md (the arm-state invariant in §5a is load-bearing). Announced write-protected until the firmware arms WR_EN, on SD change, and while remounting. No df1..df3, no IDE. Keyboard + joysticks + mouse work.

Repository map

• M2M/ — the framework. NEVER modify, with SIX sanctioned exceptions (all testbeds for a later M2M upstream merge, tagged M2M-UPSTREAM <name> in-code, greppable): (1) interlace — new video_fl_i input through framework → av_pipeline → digital_pipeline → ascal i_fl, INTER => true; new inputs default to '0' (progressive cores unaffected). (2) core-io-hook — HANDLE_CORE_IO, an 8th mandatory core callback called from HANDLE_IO (shell.asm, at the _HANDLE_IO_0 label): a per-iteration time slice in the main loop AND all blocking wait loops (OSM/browser/help), for background tasks like non-vdrives write-back caches; contract: preserve all regs, return fast, may change RAMROM selection. (3) screen-center — the screen-adjustment plumbing (issue #5): (a) four signed per-edge offsets threaded framework → av_pipeline (i_qnice2video CDC) → digital_pipeline driving ascal's INPUT crop (iauto=0, himin/himax/vimin/vimax) for HDMI (hardware-verified 2026-07-09); (b) four signed analog OVERSCAN soft-blank edges (hardened p_vga_softblank, feeds only the analog pipeline); (c) two signed analog PAN inputs (gp_reg words 8-9) into the new analog_positioner.vhd, a post-OSM/pre-CSYNC sync-phase shifter (2026-07-13, awaiting synthesis). All new inputs default to 0 = bit-identical for other cores. (4) osm-hotkey — three core-driven inputs (osm_key_a_i/osm_key_b_i default 67=Help, osm_combo_i default '0') threaded core → framework.vhd → m2m_keyb.vhd so the core picks which key(s) drive the menu-open bit (qnice_keys bit 7, the ungated scan); the defaults reproduce the classic Help-only behaviour and leave the firmware ROM byte-identical, so every existing M2M core is unchanged. Issue #8, 2026-07-11 — implemented, awaiting synthesis; the 4th exception still needs sy2002's explicit sign-off (spec §8). (5) osm-scale — a RAM-inference override: tdp_ram.vhd gains a RAM_STYLE_SELECT generic (default "auto" = every existing caller unchanged) driving the block RAM's ram_style; ascal.vhd uses it to pin its shallow async ping-pong buffers (i_dpram) to "distributed" LUTRAM. Otherwise Vivado maps them to BRAM, burning 4 RAMB36s AND absorbing avl_dr into the BRAM output, invalidating the ascal-FIFO CDC max-delay endpoints (CORE/CORE.xdc) that MEGA65 cores depend on. (6) raw-joyports — M2M/vhdl/debouncer.vhd: the ten work.debounce instances (1 ms stable-time) replaced by plain 2-FF synchronizers, so the DB9 direction/fire (and mouse quadrature) lines reach the core raw — authentic (a real Amiga has no DB9 debouncing) and mandatory for quadrature mice, whose fast pulse trains the 1 ms filter swallowed (frozen-then-jumping pointer). Port-flip
  • joy on/off gating kept; CLK_FREQ/reset_n now unused. sy2002-approved 2026-07-22, to become a framework option when upstreamed. All other framework fixes go into CORE/CORE.xdc (constraints) or get documented for upstreaming. Git remote upstream = sy2002/MiSTer2MEGA65 (master = V2.0.1).
• CORE/vhdl/ — the port (all files ours):
  • mega65.vhd — BRAM lanes (2×256K×8 chip, 2×256K×8 slow, 2×128K×8 kick), banked-address decode, QNICE devices 0x0100 (kick) + 0x0103 (ADF), HyperRAM plumbing (avm_fifo CDC + 2-master arbiter → hr_core_*), OSM wiring
  • main.vhd — wraps minimig_m65 + cpu_wrapper + amiga_clk; fx68k phase enables, frame-locked video CE, sync inversion, interlace field export (video_fl_o ← minimig field1), reset mapping, host bus mux (amiga_config ↔ adf_track_engine) + avm_cache
  • amiga_config.vhd — FSM replaying MiSTer's HPS config via the userio protocol after every reset (0xF1=0x07 halt+reset, 0xF3=OCS, 0xF4=68000, 0xF5=0x04 = 512K+512K, 0xF6/0xF7/0xF8/0xF9/0xF2=0, 0xF1=0x00 release)
  • adf_mount_wrapper.vhd — QNICE device 0x0103: byte-window bridge into HyperRAM + M2M CSR (window 0xFFFF) + ADF size validator (160–166 tracks × 5632 bytes; "mounted"+track count → cdc_stable)
    • write-back CSR "WBC" (window 0xFFFE: WR_EN, 166-bit dirty bitmap W1C, anti-thrash ms countdown, dirty-event receiver)
  • adf_track_engine.vhd — Paula floppy host service (MiSTer HandleFDD in hardware): 1 ms poll + drive-status re-announce, per-sector MFM streaming with status-bit-8 flow control, MFM write decoder (drain-and-commit: verified sectors → HyperRAM via avm writes, dirty-track events → wrapper via two-phase cdc_stable toggle handshake); the protocol contract is documented in its header
  • keyboard.vhd — MEGA65 keys → raw Amiga scancodes (kms_level toggle)
  • clk.vhd, globals.vhd, config.vhd (OSM menu — bit = line number, must match C_MENU_* constants in mega65.vhd; exception: the HDMI Filter radio, lines 19–26, is read by the firmware (OSM_FLT_* in m2m-rom.asm must mirror them), not mega65.vhd; VGA radio lines 32/36/37)
• CORE/m2m-rom/ — core QNICE firmware (m2m-rom.asm): ADF size guard
  • ADF write-back (HANDLE_CORE_IO + FLUSH_ADF_STEP: FDH snapshot, SD-change + SD-slot guards, per-chunk fflush, force-flush + disarm in PREP_LOAD_IMAGE — the §5a arm-state invariant of the write spec)
  • HDMI Filter dispatcher LOAD_HDMI_FILTER (C64MEGA65-V6 port; ASCAL_USAGE=1, includes a backported M2M$LOAD_POLYPHASE — delete it when M2M is upgraded to V2.1+; coefficient blobs in video_filters/). OSM menu constants are autogenerated: make_rom.sh scrapes C_MENU_* (mega65.vhd) and the core OPTM_G_* (config.vhd) into osm_const.asm (AEXP_OSM_* / AEXP_OPTM_G_*, gitignored) — no hardcoded menu indexes in the firmware. The OSM settings file (72 bytes = OPTM_SIZE; SD name /amiga/aexp-<CORE_VERSION>.cfg) is generated by make_release.py at packaging — no tracked master. CORE_VERSION in config.vhd is the single version source (welcome/help screens, CORENAME, CFG_FILE all derive from it; make_release.py validates it and packages releases, alpha rows live in doc/inofficial.md).
• CORE/Minimig_MiSTerMEGA65/ — git submodule, upstream MiSTer-devel/Minimig-AGA_MiSTer. Branch develop carries all Xilinx/MEGA65 changes; master mirrors upstream. Every change to original files has a dated provenance comment with original code kept commented out. rtl/minimig_m65.v is our VHDL-friendly rename shim (minimig.v has leading-underscore ports = illegal VHDL identifiers).
• CORE/CORE-R{3,4,5,6}.xpr — one Vivado project per board.
• doc/ — the knowledge base. .research/ — untracked local research notes (integration specs, review reports); never committed.

Hard rules (each learned the expensive way)

1. Keep all four .xpr files in sync — every file-list or file-type change goes to R3+R4+R5+R6 in the same commit. Expected per-board deltas (do NOT "fix"): board top, board XDC, R3 max10.vhdl + pcm_to_pdm.vhdl vs R4+ audio.vhd.
2. .xpr SFType tokens: only VHDL2008, SVerilog, or no attribute (extension-inferred). Anything else (e.g. "Verilog", "SystemVerilog") makes Vivado segfault on project open (hs_err with HDDASrcFileType::getId).
3. BRAM is at 363.5/365 tiles — full. All future buffers (ADF images, sector buffers, monitor ROMs) MUST live in HyperRAM. Re-enabling IDE (+8 tiles) does not fit. The 320 Amiga tiles are an exact mapping, nothing left to squeeze.
4. No QNICE ports on die-spread BRAMs. QNICE reads/writes RAMs on the falling clock edge = half-period (10 ns) budget; the address bus cannot reach 256 spread tiles in time (cost us WNS −0.757). Only the kick ROM (64 tiles) has a QNICE port.
5. Timing margin is thin (+0.387 ns). Check the timing summary after every build. The ascal FIFO CDC constraints in CORE/CORE.xdc (set_max_delay -datapath_only) are load-bearing — they cut phantom ps-requirement inter-clock paths AND the hold-fix router detours.
6. Video into the framework: active-HIGH syncs (minimig outputs are active-low — inverted in main.vhd), blanks must cover syncs, video CE is frame-locked 7.09/14.19 MHz and never 28 MHz (M2M line buffers: video_mixer LINE_LENGTH=768, ascal IHRES=1024), qnice_scandoubler_o='1' (15.625 kHz core!).
7. OPTM_PAUSE stays false — pause_i is not implemented in the core.
8. Commit as sy2002 code@sy2002.de (repo-local git config is set). Do NOT add a Co-Authored-By: Claude trailer — Claude is credited in the AUTHORS file instead.
9. Do not delete /tmp/claude-501 task outputs (deny rules in .claude/settings.local.json); tell workflow subagents not to run cleanup commands.
10. CORE/m2m-rom/make_rom.sh scrapes globals.vhd (C_VDNUM/ C_CRTROMS_*_NUM), mega65.vhd (C_MENU_* → AEXP_OSM_*) and config.vhd (core OPTM_G_* → AEXP_OPTM_G_*) via awk into generated .asm files — keep all those constants single-line; the Vivado pre-synth hook rebuilds the firmware, so menu changes need a synthesis (or VM-side make_rom.sh) to reach the ROM. Changing OPTM_SIZE ⇒ make_release.py generates the matching settings file at packaging (no tracked master; manual for dev SD cards: M2M/tools/make_config.sh <name> auto from inside M2M/tools).
11. Every OSM growth needs a QNICE heap rebudget. OPTM_SIZE is not only the settings-file length: HELP_MENU copies the item string plus three OPTM_SIZE arrays into MENU_HEAP_SIZE, then uses the remainder as OPTM_HEAP for one SCR$OSM_O_DX-wide (OPTM_DX + 2 frame characters) buffer per vdrive, submenu and manual ROM, plus one scratch buffer. After changing OPTM_SIZE, OPTM_ITEMS, OPTM_DX, or any of those counts, verify both LOG_HEAP1/LOG_HEAP2 budgets (a fatal naming MENU_HEAP_SIZE or OPTM_HEAP_SIZE is the corresponding failed check). If MENU_HEAP_SIZE changes, normally subtract the identical delta from both debug and release HEAP_SIZE constants so the combined heap totals stay unchanged. Only raise a combined total after the assembled HEAP/stack addresses prove that STACK_SIZE still fits. Keep MENU_HEAP_SIZE tight: every extra word directly reduces file-browser capacity (a file entry costs three list words plus its name, terminator and directory flag). Round the calculated demand only to the next 128-word boundary, not to a large power of two. The exact demand formula (from HELP_MENU in M2M/rom/options.asm): 19 (menu struct) + OPTM_ITEMS string chars (\n = 2 chars) + 1 (terminator) + 3 × OPTM_SIZE + 1, plus (vdrives + submenus + manual ROMs + 1) × (OPTM_DX + 2) for OPTM_HEAP. WIP-V1-A11 with the 74-item menu (issue #20 added the Slow RAM toggle + one line, 72→74) needs exactly 1164 words and uses MENU_HEAP_SIZE 1280, headroom 116. For release, AExp follows the C64 total of 30208 words: with HEAP=0x8220 and stack start 0xFEE0, 1728 stack words remain versus 1536 required; the file-browser heap is 28928 words. Recheck both live heap budgets and the HEAP/VAR$STACK_START symbols in m2m-rom.lis manually whenever the menu or firmware variables grow.

Build & verification workflow

• No Vivado on this Mac. It runs in the user's Parallels Ubuntu VM on a shared folder. Prepare everything, then ask the user to synthesize and return: CORE/CORE-R3.runs/synth_1/runme.log, impl_1/*_utilization_placed.rpt, impl_1/*_timing_summary_routed.rpt, impl_1/*_route_status.rpt. Per-module BRAM: ask for report_utilization -hierarchical.
• QNICE firmware: the Vivado pre-synth hook rebuilds it inside the VM on every build — the VM works directly in this (mounted) folder, which is why M2M/QNICE/assembler/qasm/qasm2rom are Linux ELF binaries. Never overwrite them, and NEVER run CORE/m2m-rom/make_rom.sh on the Mac: the asm wrapper deletes m2m-rom.out/m2m-rom.rom BEFORE assembling, then dies on the Linux binaries. For Mac-side sanity checks compile temporary native tools into a temp dir (cc -O2 -o "$TMP"/qasm M2M/QNICE/assembler/qasm.c, same for qasm2rom), then from CORE/m2m-rom: cc -xc -E m2m-rom.asm | sed '/^#.*/d' > __t.asm && "$TMP"/qasm __t.asm m2m-rom.out && "$TMP"/qasm2rom m2m-rom.out m2m-rom.rom (verified to produce a .def-identical ROM vs the VM build).
• Headless QNICE menu regression: M2M/rom/menu_percent_test.asm runs the real OPTM_SHOW scanner and guards the C64 %-at-end-of-label fix. The QNICE snapshot pinned here predates multi-image -b mode, even when rebuilt; use a current batch-capable QNICE emulator externally (the C64 repository has one) without importing that emulator feature. Assemble the test with the native/VM assembler, then run $QNICE_HEADLESS -b 0x8000 M2M/QNICE/monitor/monitor.out M2M/rom/menu_percent_test.out. Expected: PASS: percentage labels preserve later %s indices. Run this after every change to M2M/rom/menu.asm or percentage-bearing OPTM_ITEMS labels.
• Local static checks before any Vivado round-trip (installed: nvc 1.21, ghdl 5.1, iverilog): analyze all CORE VHDL with nvc --std=2008 in dependency order (M2M packages first: tools.vhd, types_pkg, video_modes_pkg, tdp_ram, 2port2clk_ram); clk.vhd/mega65.vhd need stub unisim/xpm vcomponents packages (recipe in memory). iverilog -g2012 -t null over the kept Verilog set with stubs for dpram and fx68k. Known noise to ignore: forward references, fx68k unpacked structs, zero-width-concat follow-ons.
• Synthesis log checks: microrom.mem/nanorom.mem "read successfully" (silent failure = dead CPU with no error), Amiga RAMs as block RAM, Synth 8-5835 (BRAM over-utilized, "Will try to implement using LUT-RAM") now fires routinely — BRAM sits at 365/365, so Vivado spills the excess to LUT-RAM and the build still fits; it is a real failure only if implementation then cannot place/route. Vivado OOM in the VM: close the implemented design in the GUI before relaunching a run.

Architecture cheat sheet

• Memory bus: with 68000 + no fast RAM, ALL memory traffic (CPU + chipset DMA) flows through minimig's single SRAM-style port (ram_addr[22:1] word address + _bhe/_ble/_we/_oe). The address is BANKED by minimig_sram_bridge.v: chip at [22:19]="0000", slow at [22:19]="1000", kick at [22:19]="1111" (bit 18 ignored = F8/FC mirror). 1-cycle BRAM latency meets the 7.09 MHz bus easily; read-mux select is registered to match.
• QNICE device bus: qnice_dev_id_i ≥ 0x0100, 4k windows, byte addresses; kick = 0x0100 (lane U = even byte = bits 15:8, so raw ROM dumps load unmodified); 0x0101/0x0102 reserved (chip/slow, unwired).
• Host/userio channel: IO_UIO carries config commands (driven by amiga_config.vhd); IO_FPGA is Paula's floppy channel (tied 0 — the future floppy service and the RamDump upload engine plug in here / via cmd 0xF0 mem_write through the halted m68k_bridge).
• HyperRAM: 8 MB, Avalon-MM via hr_core_* ports (currently tied off), 100 MHz, ~9 cycles latency after CDC, arbiter shared with the ascal framebuffer. Core address space from C_HMAP_DEMO (0x0200, 4kW units). Pattern for core→HyperRAM: avm_cache + avm_fifo CDC (reference: C64MEGA65 REU chain).
• Reference port: /Users/mirko/.dev/MEGA65/C64MEGA65 — consult it for every M2M integration pattern (vdrives, CRT/PRG loaders, OSM, LEDs).

Roadmap

1. Floppy: read-only DONE 2026-07-03 (verified on hardware); write support IMPLEMENTED 2026-07-05 — awaiting synthesis + hardware test round (plan in .research/INTEGRATION-SPEC-floppy-adf-write.md §8: WB rename persists across power cycle, format, write+verify, swap-while-dirty, wprot regression). Before touching floppy code, read BOTH specs in .research/ — the read spec is authoritative on three verified points (DEVICE-type mount, bit-8 flow control not IO_WAIT, disk_present re-announce per poll); the write spec's §5a arm-state invariant closed three review-confirmed critical bugs (stale FDH across re-mounts, stale-READY re-arm, F1/F3 slot switch). Future increments: df1 (HyperRAM window C_HMAP_ADF_DF1 reserved), mount-status OSM feedback (<Saving> needs an M2M options.asm generalization, noted in the write spec §7).
2. DiagROM test round — zero code: 256 KB DiagROM as /amiga/kick.rom exercises slow RAM, keyboard, audio, CIAs (diagrom.com).
3. RamDump loader — run deft's demo without floppy (possibly obsolete now that ADFs boot — confirm with deft whether .A5R is still wanted): the .A5R format (192-byte header with full CPU context D0-D7/A0-A6/USP/SSP/SR/PC, segment table, RTE-based launcher entry) plus the German delivery contract for deft. Loader = OSM manual-load → QNICE→main CDC FIFO → upload engine drives userio 0xF0 → launcher ROM replaces kick. Hardware state deliberately NOT restored (V1); brief color flicker OK.
4. Pending decision: publish to GitHub as sy2002/AExp (plan exists: fork Minimig upstream → sy2002/Minimig_MiSTerMEGA65, fix .gitmodules URL, add origin, push master+develop).

Key documents (read before working)

User-facing docs (also the source for the a500.mega65.org website, built by doc/make_doc.py; see doc/make_doc.md):

• doc/keyboard.md — full keyboard mapping guide, both modes, per-key tables.
• doc/retrotubes.md — connecting real 15 kHz CRTs (BNC / SCART / DB9 RGB) to the analog output, including the wiring-safety cautions.
• doc/screen_adjust.md — HDMI crop + analog position/overscan, the aexp_screen.cfg format and the aexp_screen_cfg.py tool.
• doc/RTC.md — real-time clock setup and the Kickstart 1.3 quirks.
• doc/developers.md — build the core from source (clone → *.cor).

Internal engineering notes:

• doc/developers/floppy-adf.md — ADF floppy (read/write) design.
• doc/developers/audio.md — audio path.
• doc/developers/hdmi_latency.md — HDMI latency analysis.
• doc/developers/research_df1.md — second-drive (df1) research.
• doc/inofficial.md — alpha/beta build history (shipped only in WIP releases).
• .research/ (local only, untracked) — integration specs and agent review reports from the porting sessions.

People & communication

• The user IS sy2002 — author of the M2M framework and co-author of C64MEGA65. Expert level; framework questions can be asked directly.
• deft — MEGA65 project lead and Amiga demo author; provides test content (RamDump deliveries). Communication with deft is in German; documents intended for him: German, PDF via pandoc + xelatex (both installed; strip the English context header first).