MSX DIAGNOSTICS v1.2.0 - Technical Docs

1. Executive Summary

MSX Diagnostics is a hardware validation tool designed under the "Bare Metal" paradigm. Unlike standard MSX software, this program minimizes reliance on the system BIOS.

• BIOS Independence: Interacts directly with I/O ports (VDP, PSG, PPI) to ensure diagnostics work even if BIOS routines are corrupt or system memory configuration is anomalous.
• Pragmatic Robustness: Memory detection routines are non-destructive and capable of identifying complex configurations (Expanded Slots, Mappers) without hanging the system.
• Modular Architecture: The core is clearly split between the engine (N'gine) and application logic (Prog), facilitating maintainability.

2. Memory Map

The system enforces a specific memory layout to avoid conflicts with areas reserved by the host system or the stack.

2.1 RAM Memory Map

2.2 Video Memory Map (VRAM - SCREEN 2)

3. Software Architecture

3.1 Boot Flow & POST

1. Initialization (NGN_START): Waits for interrupt stabilization, applies patch to hook $FD9A (Watchdog), clears variables, and silences the PSG.
2. POST (Power On Self Test): Executes FUNCTION_SYSTEM_POST. Emits 3 beeps and blinks the CAPS LOCK LED. Goal: Life feedback (CPU OK) even if the video chip fails.
3. Hardware Detection: Scans Slots, RAM, and identifies the VDP.
4. Launch: Transfers control to FUNCTION_MAIN.

3.2 Menu State Machine

The program does not have a single loop. Each screen acts as an independent state:

• Setup: Clears VRAM, loads resources, and enables the screen.
• Local Loop: Reads HID, processes logic, synchronizes with HALT (V-Sync).
• Teardown: Upon exit, disables the screen and restores the video mode.

4. Engine Analysis (N'gine)

4.1 Hardware Abstraction (HAL)

The engine isolates logic via low-level drivers:

• VDP: Direct writing to ports $98/$99. Uses Shadow RAM for sprites, dumping data only during V-Blank.
• PSG: Ignores sound BIOS. Writes directly to AY-3-8910 registers (ports $A0-$A2).
• PPI: Reads the keyboard matrix by accessing the PPI ($A9-$AA), avoiding CHGET latency.

4.2 Synchronization Watchdog

In ngn_system.asm, the hook $FD9A intercepts the interrupt. If it's not from the VDP (Bit 7 of S0), it returns. This guarantees that the HALT in the main loop is a perfect vertical synchronizer (50/60Hz).

5. Diagnostic Modules

5.1 RAM and Mapper Detection (Core)

Location: memory_routines.asm. Non-destructive algorithm:

1. Topological Scan: Iterates through Slots and Sub-slots detecting expansion.
2. RAM Verification: Read byte -> Invert bits (CPL) -> Write -> Read -> Compare -> Restore original.
3. Mapper Detection: If 64KB is detected in a slot, performs a pagination test by writing markers to port $FC and verifying if memory segments change.

5.2 VDP Detection

Identifies the chip by hardware behavior, not BIOS:

• TMS vs V99xx: Writes to V99xx exclusive registers and checks for changes in S0/S2.
• V9938 vs V9958: Reads chip ID in register S1.
• Refresh: Counts CPU cycles between two V-Blanks to determine 50Hz/60Hz.

6. Compilation & Build

Different formats are generated via conditional directives in msxdiag.asm:

• ROM (f_rom.asm): Standard header, ORG $4000, padding to 32KB.
• BIN (f_binary.asm): BLOAD header, ORG $8000.
• COM (f_com.asm): ORG $0100 (MSX-DOS).