More

roms/disasm_with_labels.asm

@@ -191,6 +191,16 @@
 ; Memory Paging System Variables:
 ; • 0x1326: Breakpoint address backup (for memory paging operations)
 ;
+; HARDWARE I/O PORTS:
+; • Port 0xF0: Floppy Disk Controller (FDC) main status register
+; • Port 0xF1: Floppy Disk Controller (FDC) data register
+; • Port 0xF3: Z80 DMA controller command/status register
+; • Port 0xFC: Z80 DMA Controller - Command/Parameter Port
+;             Used for programming the Z80 DMA with initialization sequences
+;             The hardware config table at 0x0F55 shows 19 bytes (count + 18 data bytes)
+;             written to this port to configure DMA operations
+;             Values 0x83/0xC3 are DMA command codes for control operations
+;
 ; This monitor/debugger represents advanced 1980s software engineering with
 ; modular design, efficient algorithms, and professional user interface.
 ;
@@ -3091,13 +3101,14 @@ l0bb6h:
 	push bc			;0bb8
 	push de			;0bb9
 l0bbah:
-	in a,(0f0h)		;0bba
-	bit 7,a		;0bbc
-	jr z,l0bbah		;0bbe
-	bit 6,a		;0bc0
-	jr z,l0bd9h		;0bc2
-	ld a,083h		;0bc4
-	out (0fch),a		;0bc6
+	in a,(0f0h)		;0bba ; Read floppy controller main status register
+	bit 7,a		;0bbc ; Test READY bit (controller ready)
+	jr z,l0bbah		;0bbe ; Wait until controller is ready
+	bit 6,a		;0bc0 ; Test DATA_REQUEST bit (controller needs data)
+	jr z,l0bd9h		;0bc2 ; If no data request, handle differently
+	ld a,083h		;0bc4 ; Load DMA command 0x83
+	out (0fch),a		;0bc6 ; Send command to Z80 DMA controller port 0xFC
+				;     ; 0x83 = DMA control command for FDC coordination
 	ld (0124bh),a		;0bc8
 	call l0b88h		;0bcb
 	ld hl,0121ch		;0bce
@@ -3321,8 +3332,9 @@ l0d14h:
 	djnz l0d14h		;0d20
 	dec c			;0d22
 	jr nz,l0d14h		;0d23
-	ld a,083h		;0d25
-	out (0fch),a		;0d27
+	ld a,083h		;0d25 ; Load DMA command 0x83
+	out (0fch),a		;0d27 ; Send command to Z80 DMA controller port 0xFC
+				;     ; 0x83 = DMA control command for disk operations
 	call sub_0a8dh		;0d29
 	or a			;0d2c
 	ret			;0d2d
@@ -3640,39 +3652,70 @@ l0ec9h:
 	defb 0x03		;0ec9 Number of test patterns
 	defb 0x55		;0eca Test pattern 1: 01010101 (alternating bits)
 	defb 0xAA		;0ecb Test pattern 2: 10101010 (inverse alternating)
+
+;==============================================================================
+; INTERRUPT VECTOR TABLE INITIALIZATION (0x0ECC)
+;==============================================================================
+; Purpose: Set up interrupt vector table and perform peripheral testing
+; This routine initializes the interrupt mode 2 vector table with error
+; handlers and tests peripheral chips through port operations.
+;
+; Interrupt Vector Setup:
+; Sets addresses 0x1330, 0x1332, 0x1334, 0x1336 to point to l0f3fh
+; These are interrupt vector table entries for IM2 mode interrupts
+;
+; Peripheral Testing:
+; Tests ports 0xF4 through 0xF7 with specific control sequences
+; Uses port commands 0x30 (initialize) and 0x03 (test/verify)
+; Validates peripheral response through status flag at 0x1103
+;==============================================================================
 sub_0ecch:
-	ld hl,l0f3fh		;0ecc
-	ld (01330h),hl		;0ecf
-	ld (01332h),hl		;0ed2
-	ld (01334h),hl		;0ed5
-	ld (01336h),hl		;0ed8
-	ld c,0f4h		;0edb
-	ld a,030h		;0edd
-	out (c),a		;0edf
+	ld hl,l0f3fh		;0ecc ; Load address of interrupt error handler
+	ld (01330h),hl		;0ecf ; Set interrupt vector table entry 0
+	ld (01332h),hl		;0ed2 ; Set interrupt vector table entry 1  
+	ld (01334h),hl		;0ed5 ; Set interrupt vector table entry 2
+	ld (01336h),hl		;0ed8 ; Set interrupt vector table entry 3
+	ld c,0f4h		;0edb ; Start with port 0xF4 (first peripheral port)
+	ld a,030h		;0edd ; Load initialization command (0x30)
+	out (c),a		;0edf ; Send initialization command to peripheral
+
+;==============================================================================
+; PERIPHERAL PORT TESTING LOOP (0x0EE1)
+;==============================================================================
+; Purpose: Test peripheral chips at ports 0xF4-0xF7 for proper response
+; Tests each port with initialization and verification commands
+;==============================================================================
 l0ee1h:
-	ld a,0ffh		;0ee1
-	ld (01103h),a		;0ee3
-	call sub_0f01h		;0ee6
-	push bc			;0ee9
-	ld bc,01900h		;0eea
-	call sub_0f0ah		;0eed
-	pop bc			;0ef0
-	ld a,003h		;0ef1
-	out (c),a		;0ef3
-	ld a,(01103h)		;0ef5
-	or a			;0ef8
-	ret nz			;0ef9
-	inc c			;0efa
-	ld a,c			;0efb
-	cp 0f8h		;0efc
-	jr nz,l0ee1h		;0efe
-	ret			;0f00
+	ld a,0ffh		;0ee1 ; Set error flag (assume failure initially)
+	ld (01103h),a		;0ee3 ; Store error flag in status location
+	call sub_0f01h		;0ee6 ; Send command sequence to current peripheral
+	push bc			;0ee9 ; Save current port number
+	ld bc,01900h		;0eea ; Load delay count (6400 cycles for peripheral response)
+	call sub_0f0ah		;0eed ; Wait for peripheral to process command
+	pop bc			;0ef0 ; Restore current port number
+	ld a,003h		;0ef1 ; Load verification command (0x03)
+	out (c),a		;0ef3 ; Send verification command to peripheral
+	ld a,(01103h)		;0ef5 ; Read status flag after peripheral operation
+	or a			;0ef8 ; Test if peripheral responded correctly (0=success)
+	ret nz			;0ef9 ; Return if peripheral failed to respond
+	inc c			;0efa ; Move to next peripheral port (0xF4→0xF5→0xF6→0xF7)
+	ld a,c			;0efb ; Check current port number
+	cp 0f8h		;0efc ; Compare with end limit (0xF8 = beyond 0xF7)
+	jr nz,l0ee1h		;0efe ; Continue testing if more ports remain
+	ret			;0f00 ; Return with success (all peripherals tested)
+
+;==============================================================================
+; PERIPHERAL COMMAND SEQUENCE (0x0F01)
+;==============================================================================
+; Purpose: Send specific command sequence to peripheral chip
+; Sends initialization commands to configure peripheral for testing
+;==============================================================================
 sub_0f01h:
-	ld a,028h		;0f01
-	ld b,087h		;0f03
-	out (c),b		;0f05
-	out (c),a		;0f07
-	ret			;0f09
+	ld a,028h		;0f01 ; Load parameter value (0x28 = timing/mode setting)
+	ld b,087h		;0f03 ; Load command value (0x87 = control command)
+	out (c),b		;0f05 ; Send control command to peripheral
+	out (c),a		;0f07 ; Send parameter value to peripheral
+	ret			;0f09 ; Return after command sequence complete
 ; --------------------------------------------------
 ; sub_0f0ah: Wait/Delay Loop
 ; Burns CPU cycles by decrementing BC until it reaches zero.
@@ -3699,83 +3742,213 @@ sub_0f0ah:
 ; - If zero, compares 256 bytes at HL and DE (memory test), returns if mismatch
 ; Called at 0e9b as part of system initialization/test sequence
 ; --------------------------------------------------
+;==============================================================================
+; MEMORY TEST AND HARDWARE INITIALIZATION (0x0F10)
+;==============================================================================
+; Purpose: Comprehensive RAM test comparing ROM shadow with actual RAM
+; This routine performs a critical memory integrity test by comparing the
+; first 256 bytes of ROM (0x0000-0x00FF) with corresponding RAM locations
+; (0x1000-0x10FF) to verify RAM is functioning correctly.
+;
+; Test Strategy:
+; 1. Initialize hardware peripherals and interrupt handlers
+; 2. Set up error detection mechanisms
+; 3. Allow hardware to stabilize with timing delay
+; 4. Perform byte-by-byte comparison between ROM and RAM
+; 5. Return status indicating memory integrity
+;
+; Memory Locations Used:
+; • 0x1204: Test control flags (0=test mode, 1=normal operation)
+; • 0x133C: Interrupt vector pointer (set to 0x0F48)
+; • 0x1103: Error status flag (0xFF=error, 0x00=success)
+;
+; Hardware Integration:
+; • Configures peripheral hardware via setup_peripherals_01a1h
+; • Sets up interrupt handling for test environment
+; • Uses timing delays to ensure hardware stability
+;
+; Returns:
+; • Zero flag set: Memory test passed, RAM integrity verified
+; • Zero flag clear: Memory test failed, RAM fault detected
+;==============================================================================
 sub_0f10h:
-	xor a			;0f10
-	ld (01204h),a		;0f11
-	ld hl,l0f48h		;0f14
-	ld (0133ch),hl		;0f17
-	dec a			;0f1a
-	ld (01103h),a		;0f1b
-	ld hl,l0f55h		;0f1e
-	call setup_peripherals_01a1h		;0f21
-	ld bc,01000h		;0f24
-	call sub_0f0ah		;0f27
-	ld a,(01103h)		;0f2a
-	or a			;0f2d
-	ret nz			;0f2e
-	ld hl,01000h		;0f2f
-	ld de,l0000h		;0f32
-	ld b,0ffh		;0f35
+	xor a			;0f10 ; Clear accumulator (A = 0)
+	ld (01204h),a		;0f11 ; Set test control flag to 0 (enable test mode)
+	ld hl,l0f48h		;0f14 ; Load address of interrupt service routine
+	ld (0133ch),hl		;0f17 ; Set interrupt vector pointer for test environment
+	dec a			;0f1a ; Set A = 0xFF (error flag value)
+	ld (01103h),a		;0f1b ; Initialize error status to 0xFF (assume error initially)
+	ld hl,l0f55h		;0f1e ; Load address of hardware configuration data
+	call setup_peripherals_01a1h		;0f21 ; Initialize peripheral hardware and interrupts
+	ld bc,01000h		;0f24 ; Load delay count (4096 iterations for hardware stabilization)
+	call sub_0f0ah		;0f27 ; Execute timing delay loop (allow hardware to settle)
+	ld a,(01103h)		;0f2a ; Read error status flag after hardware initialization
+	or a			;0f2d ; Test if error flag is non-zero
+	ret nz			;0f2e ; Return immediately if hardware initialization failed
+;==============================================================================
+; RAM INTEGRITY TEST - ROM vs RAM COMPARISON (0x0F2F)
+;==============================================================================
+; Performs byte-by-byte comparison between ROM (0x0000-0x00FF) and 
+; RAM (0x1000-0x10FF) to verify RAM is correctly mirroring ROM data.
+; This test validates that the memory system is functioning properly.
+;==============================================================================
+	ld hl,01000h		;0f2f ; Point to start of RAM test area (0x1000)
+	ld de,l0000h		;0f32 ; Point to start of ROM reference area (0x0000)
+	ld b,0ffh		;0f35 ; Set counter for 255 bytes (256 total with DJNZ behavior)
 l0f37h:
-	ld a,(de)			;0f37
-	cp (hl)			;0f38
-	ret nz			;0f39
-	inc hl			;0f3a
-	inc de			;0f3b
-	djnz l0f37h		;0f3c
-	ret			;0f3e
+	ld a,(de)			;0f37 ; Load byte from ROM (reference data)
+	cp (hl)			;0f38 ; Compare with corresponding byte in RAM
+	ret nz			;0f39 ; Return immediately if mismatch found (memory fault)
+	inc hl			;0f3a ; Move to next RAM address
+	inc de			;0f3b ; Move to next ROM address  
+	djnz l0f37h		;0f3c ; Continue until all 256 bytes tested
+	ret			;0f3e ; Return with zero flag set (test passed)
+;==============================================================================
+; INTERRUPT SERVICE ROUTINE - ERROR HANDLER (0x0F3F)
+;==============================================================================
+; Purpose: Generic interrupt service routine for error handling during hardware tests
+; This routine is installed in multiple interrupt vector table entries to catch
+; any unexpected interrupts that occur during hardware initialization and testing.
+;
+; Called from: Interrupt vector table entries at 0x1330, 0x1332, 0x1334, 0x1336
+; Used during: Hardware initialization, FDC operations, and system testing
+;
+; Operation:
+; 1. Save processor state (AF register)
+; 2. Clear error status flag (mark as successful)
+; 3. Restore processor state
+; 4. Return from interrupt with interrupts enabled
+;
+; Function: Provides safe interrupt handling during critical hardware operations
+; This prevents system crashes if unexpected interrupts occur during testing.
+;==============================================================================
 l0f3fh:
-	push af			;0f3f
+	push af			;0f3f ; Save accumulator and flags on stack
+;==============================================================================
+; INTERRUPT COMPLETION HANDLER (0x0F40)
+;==============================================================================
+; Purpose: Common completion path for interrupt service routines
+; Clears error status and returns from interrupt with proper state restoration.
+;==============================================================================
 l0f40h:
-	xor a			;0f40
-	ld (01103h),a		;0f41
-	pop af			;0f44
-	ei			;0f45
-	reti		;0f46
+	xor a			;0f40 ; Clear accumulator (A = 0)
+	ld (01103h),a		;0f41 ; Clear error status flag (0 = success, no error)
+	pop af			;0f44 ; Restore accumulator and flags from stack
+	ei			;0f45 ; Enable interrupts (standard RETI behavior)
+	reti		;0f46 ; Return from interrupt (pops PC and restores state)
+;==============================================================================
+; SPECIALIZED INTERRUPT HANDLER WITH PORT OPERATIONS (0x0F48)
+;==============================================================================
+; Purpose: Interrupt service routine that performs port I/O operations
+; This appears to be a hardware-specific interrupt handler that sends data
+; to port 0xFC during interrupt processing, possibly for peripheral control.
+;
+; Port Operations:
+; • Sends 0xC3 to port 0xFC six times in sequence
+; • Port 0xFC likely controls DMA, FDC, or other peripheral hardware
+; • Multiple writes may be required for hardware sequencing
+;
+; Used by: Hardware initialization routine (pointed to by interrupt vector)
+; Context: Called during peripheral setup and hardware testing phases
+;==============================================================================
 l0f48h:
-	push af			;0f48
-	push bc			;0f49
-	ld a,0c3h		;0f4a
-	ld b,006h		;0f4c
+	push af			;0f48 ; Save accumulator and flags
+	push bc			;0f49 ; Save BC register pair
+	ld a,0c3h		;0f4a ; Load control value 0xC3 for port operation
+	ld b,006h		;0f4c ; Set counter for 6 iterations
 l0f4eh:
-	out (0fch),a		;0f4e
-	djnz l0f4eh		;0f50
-	pop bc			;0f52
-	jr l0f40h		;0f53
+	out (0fch),a		;0f4e ; Send DMA command 0xC3 to Z80 DMA controller
+				;     ; 0xC3 = DMA reset/initialization command
+				;     ; Repeated 6 times for proper DMA controller reset
+	djnz l0f4eh		;0f50 ; Repeat 6 times (decrement B, loop if not zero)
+	pop bc			;0f52 ; Restore BC register pair
+	jr l0f40h		;0f53 ; Jump to common interrupt completion routine
+;==============================================================================
+; HARDWARE CONFIGURATION DATA TABLE (0x0F55)
+;==============================================================================
+; Purpose: Configuration data for peripheral hardware initialization
+; Used by: setup_peripherals_01a1h routine during system initialization
+; Format: Binary configuration data for DMA setup
+;
+; This table contains the initialization parameters and control sequences
+; required to properly configure the Z80 peripheral hardware during boot.
+; The data is processed by the hardware setup routine to configure:
+; • Z80 DMA controller transfer parameters
+;
+; TABLE FORMAT: [byte_count] [port_address] [data_bytes...]
+; • 0x13 (19 decimal) = total byte count for this configuration block
+; • 0xFC = Z80 DMA controller port address
+; • Following 19 bytes = DMA initialization sequence written to port 0xFC
+
+;==============================================================================
 l0f55h:
-	inc de			;0f55
-	call m,sub_0079h		;0f56
-	nop			;0f59
-	cp 000h		;0f5a
-	djnz $+22		;0f5c
-	cp l			;0f5e
-	nop			;0f5f
-	djnz $+20		;0f60
-	inc a			;0f62
-	add a,d			;0f63
-	rst 8			;0f64
-	dec b			;0f65
-	rst 8			;0f66
-	or e			;0f67
-	xor e			;0f68
-	add a,a			;0f69
-	nop			;0f6a
+	defb 0x13		;0f55  Byte count: 19 bytes total (1 count + 18 DMA init bytes)
+	defb 0xfc		;0f56  Target port: 0xFC (Z80 DMA controller)
+	defb 0x79		;0f57  DMA WR0: Base register, transfer mode (Block transfer, A→B)
+	defb 0x00		;0f58  DMA WR1: Port A starting address LOW byte
+	defb 0x00		;0f59  DMA WR2: Port A starting address HIGH byte  
+	defb 0xfe		;0f5a  DMA WR0: Port A address LOW (0xFE = FDC data port region)
+	defb 0x00		;0f5b  DMA WR1: Port A address HIGH byte
+	defb 0x10		;0f5c  DMA WR2: Block length LOW byte (16 bytes)
+	defb 0x14		;0f5d  DMA WR3: Block length HIGH + control
+	defb 0xdb		;0f5e  DMA WR4: Port B starting address LOW byte 
+	defb 0x00		;0f5f  DMA WR5: Port B starting address HIGH byte
+	defb 0x10		;0f60  DMA WR0: Port B address configuration
+	defb 0x12		;0f61  DMA WR1: Port B control (memory increment mode)
+	defb 0x3c		;0f62  DMA WR2: Interrupt control and timing
+	defb 0x82		;0f63  DMA WR3: Interrupt vector base
+	defb 0xcf		;0f64  DMA WR4: Pulse control (Ready/Wait signal timing)
+	defb 0x05		;0f65  DMA WR5: Command register (Enable DMA, continuous mode)
+	defb 0xcf		;0f66  DMA WR6: Additional control flags
+	defb 0xb3		;0f67  DMA command: Load and enable DMA operation
+	defb 0xab		;0f68  DMA command: Configure interrupt and ready modes
+	defb 0x87		;0f69  DMA command: Enable DMA transfer operation  
+	defb 0x00		;0f6a  Configuration terminator: 0x00
+
+;==============================================================================
+; ERROR MESSAGE DISPLAY ROUTINES (0x0F6B-0x0F7F)
+;==============================================================================
+; Purpose: Display specific error messages for hardware failures
+; These routines set HL to point to error message strings and call the
+; standard print routine at l00fdh to display them to the console.
+;
+; Error Messages:
+; • sub_0f6bh: "MEM ERR" - Memory error detected
+; • sub_0f70h: "FLOPPY CTC ERR" - Floppy controller CTC timing error  
+; • sub_0f75h: "FLOPPY NEC ERR" - NEC µPD765A FDC hardware error
+; • sub_0f7ah: "DMA ERR" - Z80 DMA controller error (also sets drive flag)
+;==============================================================================
+
 sub_0f6bh:
-	ld hl,l0f85h		;0f6b
-	jr l0f82h		;0f6e
+	ld hl,l0f85h		;0f6b ; Point to "MEM ERR" message
+	jr l0f82h		;0f6e ; Jump to common print routine
 sub_0f70h:
-	ld hl,l0f8fh		;0f70
-	jr l0f82h		;0f73
+	ld hl,l0f8fh		;0f70 ; Point to "FLOPPY CTC ERR" message  
+	jr l0f82h		;0f73 ; Jump to common print routine
 sub_0f75h:
-	ld hl,l0fa0h		;0f75
-	jr l0f82h		;0f78
+	ld hl,l0fa0h		;0f75 ; Point to "FLOPPY NEC ERR" message
+	jr l0f82h		;0f78 ; Jump to common print routine
 sub_0f7ah:
-	ld a,001h		;0f7a
-	ld (01204h),a		;0f7c
-	ld hl,l0fb1h		;0f7f
+	ld a,001h		;0f7a ; Set error flag value
+	ld (01204h),a		;0f7c ; Store in drive status location (mark DMA error)
+	ld hl,l0fb1h		;0f7f ; Point to "DMA ERR" message
 l0f82h:
-	jp l00fdh		;0f82
-l0f85h:
+	jp l00fdh		;0f82 ; Call standard string print routine
+
+;==============================================================================
+; ERROR MESSAGE STRINGS (0x0F85-0x0FBA)
+;==============================================================================
+; Null-terminated error message strings displayed by the error routines above.
+; Each message includes CR/LF for proper console formatting.
+;
+; Messages:
+; • l0f85h: "MEM ERR" - Memory subsystem error
+; • l0f8fh: "FLOPPY CTC ERR" - CTC timing error for floppy operations
+; • l0fa0h: "FLOPPY NEC ERR" - NEC µPD765A FDC hardware error  
+; • l0fb1h: "DMA ERR" - Z80 DMA controller error
+;==============================================================================
+
+l0f85h:					; "MEM ERR" message
 	defb 0x4d 	;0f85 'M'
 	defb 0x45 	;0f86 'E'
 	defb 0x4d 	;0f87 'M'