More

roms/disasm_with_labels.asm

@@ -248,6 +248,8 @@
 ;   - 0x120A: I/O port configuration (0xF0 = FDC port base settings)
 ;   - 0x120B: Drive count/mode (0x03 = 3 drives or mode 3)
 ;   - 0x120C: Additional FDC configuration and status data
+;   - 0x120D: FDC status register (used by disk operation status validation)
+;   - 0x120E: FDC extended status register (used by error condition checking)
 ;   - 0x1213: FDC command byte (0x03 = READ, 0x04 = write, 0x0F = seek)
 ;   - 0x1214: Drive/head selection (computed from 0x1226 + 0x1202)
 ;   - 0x1215-0x1218: Track/sector parameter table (4 bytes, copied from l0c98h):
@@ -1735,26 +1737,26 @@ l04a5h:					; Single-Step Execution Loop Controller
 	jr z,l0475h			;04b8 If at breakpoint, jump to memory restoration routine
 	jr l0479h			;04ba Otherwise, jump to breakpoint installation routine
 l04bch:
-	ld (011d4h),hl		;04bc
-	pop hl			;04bf
-	ld (011ech),sp		;04c0
-	ld sp,01400h		;04c4
-	call sub_0770h		;04c7
-	call sub_04ebh		;04ca
-	ld hl,l04d3h		;04cd
-	push hl			;04d0
-	reti		;04d1
+	ld (011d4h),hl		;04bc Store execution return address in debug control block
+	pop hl			;04bf Restore HL register from stack (return to caller state)
+	ld (011ech),sp		;04c0 Save current stack pointer for later restoration
+	ld sp,01400h		;04c4 Set up temporary debug stack at 0x1400
+	call sub_0770h		;04c7 Call system state preservation routine
+	call sub_04ebh		;04ca Call memory paging restore routine
+	ld hl,l04d3h		;04cd Load address of execution continuation point
+	push hl			;04d0 Push continuation address onto stack
+	reti		;04d1 Return from interrupt (execute user instruction)
 l04d3h:
-	ld hl,(011eeh)		;04d3
-	ld (011d6h),hl		;04d6
-	call sub_0582h		;04d9
-	ld hl,011d0h		;04dc
-	dec (hl)			;04df
-	jr nz,l04a5h		;04e0
-	inc (hl)			;04e2
-	call sub_080dh		;04e3
-	jp nz,l02c9h		;04e6
-	jr l04a5h		;04e9
+	ld hl,(011eeh)		;04d3 Restore debug control parameters from backup
+	ld (011d6h),hl		;04d6 Store restored parameters back to system settings
+	call sub_0582h		;04d9 Call post-execution cleanup routine
+	ld hl,011d0h		;04dc Point to single-step counter location
+	dec (hl)			;04df Decrement step counter (one instruction executed)
+	jr nz,l04a5h		;04e0 If more steps remaining, continue execution loop
+	inc (hl)			;04e2 Reset step counter to 1 (prepare for next command)
+	call sub_080dh		;04e3 Call debugger command processing routine
+	jp nz,l02c9h		;04e6 If command processed, jump to main command loop
+	jr l04a5h		;04e9 Otherwise, continue single-step execution
 ;==============================================================================
 ; MEMORY PAGING RESTORE ROUTINE (0x04EB)
 ;==============================================================================
@@ -3474,21 +3476,21 @@ l0b54h:
 ; Returns: Carry set on success, clear on error
 ;==============================================================================
 l0b64h:
-	ld c,0f1h		;0b64
+	ld c,0f1h		;0b64 Set port C = 0xF1 (FDC data register)
 l0b66h:
-	in a,(0f0h)		;0b66
-	and 01fh		;0b68
-	jr nz,l0b66h		;0b6a
+	in a,(0f0h)		;0b66 Read FDC status register (port 0xF0)
+	and 01fh		;0b68 Mask lower 5 bits (status/error flags)
+	jr nz,l0b66h		;0b6a Loop until all status flags are clear
 l0b6ch:
-	in a,(0f0h)		;0b6c
-	bit 7,a		;0b6e
-	jr z,l0b6ch		;0b70
-	and 040h		;0b72
-	ret nz			;0b74
-	outi		;0b75
-	jr nz,l0b6ch		;0b77
-	scf			;0b79
-	ret			;0b7a
+	in a,(0f0h)		;0b6c Read FDC status register again
+	bit 7,a		;0b6e Test bit 7 (command ready flag)
+	jr z,l0b6ch		;0b70 Loop until FDC is ready for command
+	and 040h		;0b72 Test bit 6 (direction/error flag)
+	ret nz			;0b74 Return with error if direction flag set
+	outi		;0b75 Output byte from (HL) to port C, increment HL, decrement B
+	jr nz,l0b6ch		;0b77 Loop until all B bytes transmitted (B≠0)
+	scf			;0b79 Set carry flag = success (all bytes transmitted)
+	ret			;0b7a Return to caller with success status
 
 ;==============================================================================
 ; FLOPPY COMMAND PARAMETER BUILDER (0x0B7B)
@@ -3704,37 +3706,56 @@ l0c22h:
 	ret			;0c2e Return to caller with success status
 ; End sub_0c05h: SEEK command completed, head positioned on target track
 ;==============================================================================
+; DISK I/O OPERATION DISPATCH ROUTINE (l0c2fh/l0c33h) - 0x0C2F-0x0C69
+;==============================================================================
+; Purpose: High-level disk I/O operation coordinator with dual entry points
+; Entry Points:
+;   l0c2fh: Entry for write operations (sets operation type = 6)
+;   l0c33h: Entry for read operations (sets operation type = 5)
+; Called by: Disk I/O functions requiring complete read/write operation sequence
+;
+; Operation Sequence:
+; 1. Set operation type (read=5, write=6) in memory location 0x1223
+; 2. Check drive configuration status and exit if not configured
+; 3. Configure drive parameters, FDC commands, and DMA setup
+; 4. Execute FDC operation with up to 9 retry attempts
+; 5. Perform final status validation and error checking
+; 6. Return with success/failure status
+;
+; Returns: Carry flag set = success, clear = failure
+; Memory: Uses 0x1223 for operation type, 0x124B for error status
+;==============================================================================
 l0c2fh:
-	ld a,006h		;0c2f
-	jr l0c35h		;0c31
+	ld a,006h		;0c2f Set operation type = 6 (WRITE operation)
+	jr l0c35h		;0c31 Jump to common I/O processing
 l0c33h:
-	ld a,005h		;0c33
+	ld a,005h		;0c33 Set operation type = 5 (READ operation)
 l0c35h:
-	ld hl,01223h		;0c35
-	ld (hl),a			;0c38
-	ld a,(01204h)		;0c39
-	or a			;0c3c
-	ret nz			;0c3d
-	call sub_0c6ah		;0c3e
-	call sub_0b7bh		;0c41
-	call sub_0c73h		;0c44
-	call sub_0d2eh		;0c47
-	ret nc			;0c4a
-	call sub_0ca0h		;0c4b
-	call sub_0cc5h		;0c4e
-	xor a			;0c51
-	ld (0124bh),a		;0c52
-	ld hl,01223h		;0c55
-	ld b,009h		;0c58
-	call l0b64h		;0c5a
-	ret nc			;0c5d
-	call sub_0d11h		;0c5e
-	ret nc			;0c61
-	ld a,(0120ch)		;0c62
-	and 0c0h		;0c65
-	ret nz			;0c67
-	scf			;0c68
-	ret			;0c69
+	ld hl,01223h		;0c35 Point to operation type storage location
+	ld (hl),a			;0c38 Store operation type (5 or 6) in memory
+	ld a,(01204h)		;0c39 Load drive configuration byte from memory
+	or a			;0c3c Test if drive is configured (non-zero = configured)
+	ret nz			;0c3d Return immediately if drive not configured
+	call sub_0c6ah		;0c3e Call drive configuration setup routine
+	call sub_0b7bh		;0c41 Call FDC command preparation routine
+	call sub_0c73h		;0c44 Call DMA parameter configuration routine
+	call sub_0d2eh		;0c47 Call FDC status validation routine
+	ret nc			;0c4a Return with error if FDC validation failed
+	call sub_0ca0h		;0c4b Call FDC operation setup routine
+	call sub_0cc5h		;0c4e Call DMA transfer configuration routine
+	xor a			;0c51 Clear accumulator (A = 0)
+	ld (0124bh),a		;0c52 Clear error status flag in memory
+	ld hl,01223h		;0c55 Point to operation type location
+	ld b,009h		;0c58 Set retry count = 9 attempts
+	call l0b64h		;0c5a Call FDC command execution routine
+	ret nc			;0c5d Return with error if command execution failed
+	call sub_0d11h		;0c5e Call final status check routine
+	ret nc			;0c61 Return with error if final status check failed
+	ld a,(0120ch)		;0c62 Load final operation status byte
+	and 0c0h		;0c65 Mask upper 2 bits (critical error flags)
+	ret nz			;0c67 Return with error if critical errors detected
+	scf			;0c68 Set carry flag = success (operation completed)
+	ret			;0c69 Return to caller with success status
 sub_0c6ah:
 	ld a,(01203h)		;0c6a
 	rrca			;0c6d
@@ -3854,39 +3875,53 @@ l0cadh:
 	ret			;0cbc Return to caller with DMA controller configured
 ; End DMA configuration: Z80 DMA ready for high-speed disk data transfers
 ;==============================================================================
+; DMA TRANSFER LENGTH SETUP ROUTINE (sub_0cbdh) - 0x0CBD-0x0CFA
+;==============================================================================
+; Purpose: Configure DMA transfer parameters and initiate disk data transfer
+; Called by: Format and disk I/O operations requiring DMA data movement
+;
+; Operation:
+; 1. Calculate transfer length based on operation type and FDC command
+; 2. Set up DMA configuration block from ROM template
+; 3. Configure memory addresses and transfer parameters
+; 4. Send complete DMA configuration to Z80 DMA controller
+;
+; Transfer Types: Different lengths for read/write vs format operations
+; Memory: Uses 0x122C as DMA configuration workspace, ports 0xFC for DMA
+;==============================================================================
 sub_0cbdh:
-	ld hl,00068h		;0cbd
-	ld a,(01213h)		;0cc0
-	jr l0cd2h		;0cc3
+	ld hl,00068h		;0cbd Set default transfer length to 0x68 (104 bytes)
+	ld a,(01213h)		;0cc0 Load FDC command byte from command buffer
+	jr l0cd2h		;0cc3 Jump to common DMA setup processing
 sub_0cc5h:
-	ld hl,l0080h		;0cc5
-	ld a,(01203h)		;0cc8
-	or a			;0ccb
-	jr z,l0ccfh		;0ccc
-	add hl,hl			;0cce
+	ld hl,l0080h		;0cc5 Set base transfer length to 0x80 (128 bytes)
+	ld a,(01203h)		;0cc8 Load drive status/configuration byte
+	or a			;0ccb Test if drive supports extended operations
+	jr z,l0ccfh		;0ccc Skip length doubling if standard operation
+	add hl,hl			;0cce Double transfer length (0x80 → 0x100 = 256 bytes)
 l0ccfh:
-	ld a,(01223h)		;0ccf
+	ld a,(01223h)		;0ccf Load disk operation parameter for processing
 l0cd2h:
-	dec hl			;0cd2
-	push hl			;0cd3
-	ld hl,l0cfbh		;0cd4
-	ld de,0122ch		;0cd7
-	ld bc,00016h		;0cda
-	ldir		;0cdd
-	pop hl			;0cdf
-	ld (01235h),hl		;0ce0
-	ld hl,(01200h)		;0ce3
-	ld (01233h),hl		;0ce6
-	and 001h		;0ce9
-	rlca			;0ceb
-	rlca			;0cec
-	ld hl,0123eh		;0ced
-	or (hl)			;0cf0
-	ld (hl),a			;0cf1
-	ld hl,0122ch		;0cf2
-	ld bc,016fch		;0cf5
-	otir		;0cf8
-	ret			;0cfa
+	dec hl			;0cd2 Decrement transfer length (adjust for DMA requirements)
+	push hl			;0cd3 Save adjusted transfer length on stack
+	ld hl,l0cfbh		;0cd4 Point to DMA configuration template in ROM
+	ld de,0122ch		;0cd7 Point to DMA configuration workspace in RAM
+	ld bc,00016h		;0cda Set copy length to 22 bytes (0x16)
+	ldir		;0cdd Copy DMA template from ROM to RAM workspace
+	pop hl			;0cdf Restore transfer length from stack
+	ld (01235h),hl		;0ce0 Store transfer length in DMA block (bytes 8-9)
+	ld hl,(01200h)		;0ce3 Load DMA buffer address from memory
+	ld (01233h),hl		;0ce6 Store buffer address in DMA block (bytes 6-7)
+	and 001h		;0ce9 Test bit 0 of operation parameter (direction flag)
+	rlca			;0ceb Rotate left (bit 0 → bit 1)
+	rlca			;0cec Rotate left (bit 1 → bit 2, final position)
+	ld hl,0123eh		;0ced Point to DMA control byte in configuration block
+	or (hl)			;0cf0 OR with existing control settings
+	ld (hl),a			;0cf1 Store updated control byte with direction flag
+	ld hl,0122ch		;0cf2 Point to start of DMA configuration block
+	ld bc,016fch		;0cf5 Set B=22 (bytes to send), C=0xFC (DMA port)
+	otir		;0cf8 Send 22-byte DMA configuration to Z80 DMA controller
+	ret			;0cfa Return with DMA controller configured and ready
 ;==============================================================================
 ; DMA CONFIGURATION DATA BLOCK (l0cfbh) - 0x0CFB-0x0D10 (22 bytes)
 ;==============================================================================
@@ -3916,135 +3951,231 @@ l0cfbh:
 	defb 083h		;0d0e DMA control: Final command byte (0x83)
 	defb 0cfh		;0d0f DMA vector: Interrupt vector high byte
 	defb 007h		;0d10 DMA mask: End-of-block mask/control (final config byte)
+;==============================================================================
+; DISK OPERATION STATUS POLLING ROUTINE (sub_0d11h) - 0x0D11-0x0D2D
+;==============================================================================
+; Purpose: Wait for disk operation completion by polling status register
+; Called by: Disk I/O routines that need to wait for operation completion
+;
+; Operation:
+; 1. Initialize BC=0x0000 (timeout counter: B=0, C=0 = 65536 iterations max)
+; 2. Poll status location 0x124B repeatedly until non-zero (operation done)
+; 3. If status becomes non-zero, set carry flag and return (success)
+; 4. If timeout expires, send DMA command 0x83 and call FDC init
+; 5. Clear carry flag and return (timeout/error)
+;
+; Memory: 0x124B = FDC operation status (0=busy, non-zero=complete)
+; Ports: 0xFC = Z80 DMA controller command port
+;==============================================================================
 sub_0d11h:
-	ld bc,l0000h		;0d11
-l0d14h:
-	ld a,(0124bh)		;0d14
-	or a			;0d17
-	scf			;0d18
-	ret nz			;0d19
-	ld a,(0124bh)		;0d1a
-	or a			;0d1d
-	scf			;0d1e
-	ret nz			;0d1f
-	djnz l0d14h		;0d20
-	dec c			;0d22
-	jr nz,l0d14h		;0d23
-	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
+	ld bc,l0000h		;0d11 Initialize timeout counter (BC=0x0000 = 65536 max loops)
+l0d14h:					; Status polling loop entry point
+	ld a,(0124bh)		;0d14 Load FDC operation status from memory
+	or a			;0d17 Test if status is non-zero (operation complete)
+	scf			;0d18 Set carry flag (success indicator)
+	ret nz			;0d19 Return with carry set if operation completed
+	ld a,(0124bh)		;0d1a Load status again (double-check for reliability)
+	or a			;0d1d Test status again
+	scf			;0d1e Set carry flag again
+	ret nz			;0d1f Return with carry if now complete
+	djnz l0d14h		;0d20 Decrement B counter, loop if not zero
+	dec c			;0d22 Decrement C counter (outer loop)
+	jr nz,l0d14h		;0d23 Continue polling if C not zero (timeout not reached)
+	ld a,083h		;0d25 Load DMA command 0x83 (timeout cleanup)
+	out (0fch),a		;0d27 Send command to Z80 DMA controller port 0xFC
+				;     0x83 = DMA control command for disk operations
+	call sub_0a8dh		;0d29 Call FDC initialization routine (recovery attempt)
+	or a			;0d2c Clear carry flag (indicate timeout/error)
+	ret			;0d2d Return with carry clear (failure)
+;==============================================================================
+; FDC WRITE STATUS CHECK ROUTINE (sub_0d2eh) - 0x0D2E-0x0D36
+;==============================================================================
+; Purpose: Check if FDC is ready for write operations by testing status bit 5
+; Called by: Write command routines and disk operation validators
+;
+; Operation:
+; 1. Call sub_0bf2h (FDC write command setup) to get current FDC status
+; 2. Return with carry clear if FDC setup failed (not ready)
+; 3. Test bit 5 of status register (write ready indicator)
+; 4. Return with carry clear if bit 5 is zero (write not ready)
+; 5. Return with carry set if bit 5 is set (write ready)
+;
+; Returns: Carry flag = FDC write ready status (1=ready, 0=not ready)
+;==============================================================================
 sub_0d2eh:
-	call sub_0bf2h		;0d2e
-	ret nc			;0d31
-	and 020h		;0d32
-	ret z			;0d34
-	scf			;0d35
+	call sub_0bf2h		;0d2e Call FDC write command setup, get status in A
+	ret nc			;0d31 Return with carry clear if FDC setup failed
+	and 020h		;0d32 Test bit 5 of status (write ready indicator)
+	ret z			;0d34 Return with carry clear if bit 5 = 0 (not ready)
+	scf			;0d35 Set carry flag (write ready confirmed)
 	ret			;0d36
+;==============================================================================
+; DISK SEEK AND RETRY OPERATION (sub_0d37h) - 0x0D37-0x0D59
+;==============================================================================
+; Purpose: Perform disk seek operation with retry logic and status tracking
+; Called by: Disk operation routines that need head positioning and validation
+;
+; Operation:
+; 1. Check if FDC is ready for write operations (via sub_0d2eh)
+; 2. If not ready, return with carry clear (failure)
+; 3. Set retry counter to 2 attempts (B=0x02)
+; 4. For each attempt:
+;    - Call sub_0c05h (disk seek and status check)
+;    - Store current track number from 0x1225 to IY+0 (drive status table)
+;    - If seek successful (carry set), return immediately
+;    - Call sub_0b1ch (disk read operation)
+;    - If read fails, return with carry clear
+;    - Increment error counter at 0x1244
+;    - Retry if attempts remaining
+; 5. Clear carry and return if all retries exhausted
+;
+; Memory: 0x1225=track number, 0x1244=error counter, IY=drive status pointer
+;==============================================================================
 sub_0d37h:
-	call sub_0d2eh		;0d37
-	ret nc			;0d3a
-	ld b,002h		;0d3b
-l0d3dh:
-	push bc			;0d3d
-	call sub_0c05h		;0d3e
-	pop bc			;0d41
-	ld a,(01225h)		;0d42
-	ld (iy+000h),a		;0d45
-	ret c			;0d48
-	push bc			;0d49
-	call sub_0b1ch		;0d4a
-	pop bc			;0d4d
-	ret nc			;0d4e
-	ld hl,(01244h)		;0d4f
-	inc hl			;0d52
-	ld (01244h),hl		;0d53
-	djnz l0d3dh		;0d56
-	or a			;0d58
-	ret			;0d59
+	call sub_0d2eh		;0d37 Check if FDC is ready for write operations
+	ret nc			;0d3a Return with carry clear if FDC not ready
+	ld b,002h		;0d3b Set retry counter to 2 attempts
+l0d3dh:					; Retry loop entry point
+	push bc			;0d3d Save retry counter on stack
+	call sub_0c05h		;0d3e Call disk seek and status check routine
+	pop bc			;0d41 Restore retry counter from stack
+	ld a,(01225h)		;0d42 Load current track number from memory
+	ld (iy+000h),a		;0d45 Store track number in drive status table (IY+0)
+	ret c			;0d48 Return with carry set if seek was successful
+	push bc			;0d49 Save retry counter again
+	call sub_0b1ch		;0d4a Call disk read operation to verify positioning
+	pop bc			;0d4d Restore retry counter
+	ret nc			;0d4e Return with carry clear if read operation failed
+	ld hl,(01244h)		;0d4f Load error counter from memory location 0x1244
+	inc hl			;0d52 Increment error counter (track retry attempt)
+	ld (01244h),hl		;0d53 Store updated error counter back to memory
+	djnz l0d3dh		;0d56 Decrement retry counter, loop if more attempts remain
+	or a			;0d58 Clear carry flag (all retries exhausted, operation failed)
+	ret			;0d59 Return with carry clear indicating failure
+;==============================================================================
+; FDC STATUS VALIDATION ROUTINE (l0d5ah) - 0x0D5A-0x0D66
+;==============================================================================
+; Purpose: Validate FDC status bits for specific disk operation conditions
+; Called by: Disk operation routines that need to check controller readiness
+;
+; Operation:
+; 1. Call sub_0bf2h to get current FDC status byte
+; 2. XOR with 0x20 (flip bit 5 - write ready indicator)
+; 3. AND with 0x60 (test bits 5&6 - data direction and write ready)
+; 4. Return with non-zero flag if status invalid (operation not ready)
+; 5. If status valid, load parameter table pointer and continue
+;
+; Status Bits: Bit 5=write ready, Bit 6=data direction
+; Memory: 0x120D=FDC status register (NOTE: Missing from main memory map)
+; Returns: Zero flag set=valid status, Zero flag clear=invalid status
+;==============================================================================
 l0d5ah:
-	call sub_0bf2h		;0d5a
-	xor 020h		;0d5d
-	and 060h		;0d5f
-	ret nz			;0d61
-	ld hl,l0c33h		;0d62
-	jr l0d6eh		;0d65
+	call sub_0bf2h		;0d5a Call FDC write setup, get status byte in A
+	xor 020h		;0d5d XOR with 0x20 (flip bit 5 - write ready bit)
+	and 060h		;0d5f AND with 0x60 (test bits 5&6 - data direction & write ready)
+	ret nz			;0d61 Return with non-zero if status invalid (not ready)
+	ld hl,l0c33h		;0d62 Load pointer to disk parameter table (valid status)
+	jr l0d6eh		;0d65 Jump to common parameter processing routine
+;==============================================================================
+; ALTERNATE FDC VALIDATION ENTRY POINT (l0d67h) - 0x0D67-0x0D6D
+;==============================================================================
+; Purpose: Alternative entry point for FDC validation with different table
+; Operation: Checks write readiness then uses alternate parameter table
+;==============================================================================
 l0d67h:
-	call sub_0d2eh		;0d67
-	ret nc			;0d6a
-	ld hl,l0c2fh		;0d6b
+	call sub_0d2eh		;0d67 Check if FDC is ready for write operations
+	ret nc			;0d6a Return with carry clear if FDC not ready
+	ld hl,l0c2fh		;0d6b Load pointer to alternate disk parameter table
+;==============================================================================
+; COMMON PARAMETER PROCESSING (l0d6eh) - 0x0D6E+
+;==============================================================================
+; Purpose: Common routine for processing disk parameters with retry logic
+; Input: HL = pointer to parameter table (l0c33h or l0c2fh)
+;==============================================================================
 l0d6eh:
-	ld b,005h		;0d6e
-l0d70h:
-	push bc			;0d70
-	push hl			;0d71
-	call sub_0da8h		;0d72
-	pop hl			;0d75
-	pop bc			;0d76
-	ret c			;0d77
-	push hl			;0d78
-	ld a,(0120dh)		;0d79
-	and 085h		;0d7c
-	jr z,l0d87h		;0d7e
-	ld hl,(01246h)		;0d80
-	inc hl			;0d83
-	ld (01246h),hl		;0d84
-l0d87h:
-	ld a,(0120dh)		;0d87
-	and 020h		;0d8a
-	jr z,l0d95h		;0d8c
-	ld hl,(01248h)		;0d8e
-	inc hl			;0d91
-	ld (01248h),hl		;0d92
-l0d95h:
-	ld a,(0120eh)		;0d95
-	and 012h		;0d98
-	jr z,l0da3h		;0d9a
-	ld hl,(01244h)		;0d9c
-	inc hl			;0d9f
-	ld (01244h),hl		;0da0
-l0da3h:
-	pop hl			;0da3
-	djnz l0d70h		;0da4
-	or a			;0da6
-	ret			;0da7
+	ld b,005h		;0d6e Set retry counter to 5 attempts
+l0d70h:					; Main retry loop entry point
+	push bc			;0d70 Save retry counter on stack
+	push hl			;0d71 Save parameter table pointer on stack
+	call sub_0da8h		;0d72 Call parameter table function via HL register
+	pop hl			;0d75 Restore parameter table pointer from stack
+	pop bc			;0d76 Restore retry counter from stack
+	ret c			;0d77 Return with carry set if operation successful
+	push hl			;0d78 Save parameter table pointer again
+	ld a,(0120dh)		;0d79 Load FDC status register (error condition flags)
+	and 085h		;0d7c Test bits 0,2,7 (specific error conditions)
+	jr z,l0d87h		;0d7e Skip error counter increment if no error
+	ld hl,(01246h)		;0d80 Load error counter A from memory
+	inc hl			;0d83 Increment error counter A
+	ld (01246h),hl		;0d84 Store updated error counter A back to memory
+l0d87h:					; Check additional error conditions
+	ld a,(0120dh)		;0d87 Load FDC status register again
+	and 020h		;0d8a Test bit 5 (write ready/direction error)
+	jr z,l0d95h		;0d8c Skip error counter B if bit 5 clear
+	ld hl,(01248h)		;0d8e Load error counter B from memory
+	inc hl			;0d91 Increment error counter B
+	ld (01248h),hl		;0d92 Store updated error counter B back to memory
+l0d95h:					; Check extended error conditions
+	ld a,(0120eh)		;0d95 Load FDC extended status register
+	and 012h		;0d98 Test bits 1,4 (additional error flags)
+	jr z,l0da3h		;0d9a Skip general error counter if no error
+	ld hl,(01244h)		;0d9c Load general error counter from memory
+	inc hl			;0d9f Increment general error counter
+	ld (01244h),hl		;0da0 Store updated general error counter back to memory
+l0da3h:					; End of retry loop
+	pop hl			;0da3 Restore parameter table pointer from stack
+	djnz l0d70h		;0da4 Decrement retry counter, loop if more attempts remain
+	or a			;0da6 Clear carry flag (all retries exhausted, operation failed)
+	ret			;0da7 Return with carry clear indicating failure
+;==============================================================================
+; INDIRECT FUNCTION CALL ROUTINES (0x0DA8-0x0DA9)
+;==============================================================================
+; Purpose: Dynamic function dispatching via register indirect calls
+; Used by: Parameter processing routines for flexible operation selection
+;==============================================================================
 sub_0da8h:
-	jp (hl)			;0da8
+	jp (hl)			;0da8 Jump to address stored in HL register (parameter table function)
 sub_0da9h:
-	jp (ix)		;0da9
-l0dabh:
-	ld ix,l0d67h		;0dab
-	jr l0db5h		;0daf
-l0db1h:
-	ld ix,l0d5ah		;0db1
-l0db5h:
-	ld iy,01205h		;0db5
-	ld b,002h		;0db9
-	ld a,(01202h)		;0dbb
-	ld e,a			;0dbe
-	ld d,000h		;0dbf
-	add iy,de		;0dc1
-	ld a,(01225h)		;0dc3
-	cp (iy+000h)		;0dc6
-	jr z,l0dd1h		;0dc9
-l0dcbh:
-	push bc			;0dcb
-	call sub_0d37h		;0dcc
-	pop bc			;0dcf
-	ret nc			;0dd0
-l0dd1h:
-	push bc			;0dd1
-	call sub_0da9h		;0dd2
-	pop bc			;0dd5
-	ret c			;0dd6
-	push bc			;0dd7
-	call sub_0b1ch		;0dd8
-	pop bc			;0ddb
-	djnz l0dcbh		;0ddc
-	or a			;0dde
-	ret			;0ddf
+	jp (ix)		;0da9 Jump to address stored in IX register (operation function)
+;==============================================================================
+; DISK READ OPERATION ENTRY POINTS (l0dabh/l0db1h) - 0x0DAB-0x0DDF
+;==============================================================================
+; Purpose: High-level disk read operations with different validation approaches
+; Two entry points using different FDC validation routines:
+; - l0dabh: Uses l0d67h validation (write readiness check)
+; - l0db1h: Uses l0d5ah validation (status bit manipulation)
+;==============================================================================
+l0dabh:					; Read operation entry point A
+	ld ix,l0d67h		;0dab Set IX to point to FDC validation routine (write check)
+	jr l0db5h		;0daf Jump to common read operation setup
+l0db1h:					; Read operation entry point B  
+	ld ix,l0d5ah		;0db1 Set IX to point to FDC validation routine (status bits)
+l0db5h:					; Common read operation setup
+	ld iy,01205h		;0db5 Point IY to drive status table base address
+	ld b,002h		;0db9 Set operation retry counter to 2 attempts
+	ld a,(01202h)		;0dbb Load current drive number from memory
+	ld e,a			;0dbe Copy drive number to E register
+	ld d,000h		;0dbf Clear D register (DE = drive number, 0-3)
+	add iy,de		;0dc1 Add drive offset to status table pointer (IY += drive)
+	ld a,(01225h)		;0dc3 Load current track number from memory
+	cp (iy+000h)		;0dc6 Compare with track in drive status table
+	jr z,l0dd1h		;0dc9 Skip seek if already on correct track
+l0dcbh:					; Seek and read retry loop
+	push bc			;0dcb Save retry counter on stack
+	call sub_0d37h		;0dcc Call disk seek and retry operation
+	pop bc			;0dcf Restore retry counter from stack
+	ret nc			;0dd0 Return with carry clear if seek failed
+l0dd1h:					; Execute read operation
+	push bc			;0dd1 Save retry counter on stack
+	call sub_0da9h		;0dd2 Call FDC validation function via IX register
+	pop bc			;0dd5 Restore retry counter from stack
+	ret c			;0dd6 Return with carry set if validation successful
+	push bc			;0dd7 Save retry counter again
+	call sub_0b1ch		;0dd8 Call actual disk read operation
+	pop bc			;0ddb Restore retry counter
+	djnz l0dcbh		;0ddc Decrement retry counter, loop if more attempts remain
+	or a			;0dde Clear carry flag (all retries exhausted, read failed)
+	ret			;0ddf Return with carry clear indicating failure
 
 ;==============================================================================
 ; FLOPPY DISK STATUS CHECK ROUTINE (0x0DE0)
@@ -4065,107 +4196,171 @@ l0dd1h:
 ; Ports: 0xF0 (status), 0xF1 (data), 0xFC (control)
 ;==============================================================================
 l0de0h:
-	call sub_0bf2h		;0de0
-	rrca			;0de3
-	rrca			;0de4
-	rrca			;0de5
-	and 001h		;0de6
-	ld (01203h),a		;0de8
-	ret			;0deb
+	call sub_0bf2h		;0de0 Call FDC write setup, get status byte in A register
+	rrca			;0de3 Rotate right (bit 3 → bit 2)
+	rrca			;0de4 Rotate right (bit 2 → bit 1) 
+	rrca			;0de5 Rotate right (bit 1 → bit 0, original bit 3 now in bit 0)
+	and 001h		;0de6 Mask to keep only bit 0 (original FDC status bit 3)
+	ld (01203h),a		;0de8 Store extracted status bit at drive status location
+	ret			;0deb Return with extracted status bit in A
+;==============================================================================
+; DISK FORMAT OPERATION ROUTINE (sub_0dech) - 0x0DEC-0x0E1E
+;==============================================================================
+; Purpose: Execute complete disk format operation with FDC command setup
+; Called by: Format command routines that need to prepare and format tracks
+;
+; Operation Sequence:
+; 1. Check FDC write readiness via sub_0d2eh
+; 2. Set up FDC command 0x0D (FORMAT TRACK) in command buffer
+; 3. Configure disk parameters and DMA setup
+; 4. Execute format operation and wait for completion
+; 5. Validate completion status and return result
+;
+; FDC Command: 0x0D = FORMAT TRACK (formats entire track with sector headers)
+; Memory: 0x1213=command buffer, 0x124B=operation status, 0x120C=completion status
+;==============================================================================
 sub_0dech:
-	call sub_0d2eh		;0dec
-	ret nc			;0def
-	ld hl,01213h		;0df0
-	ld (hl),00dh		;0df3
-	call sub_0c6ah		;0df5
-	call sub_0b7bh		;0df8
-	call sub_0e1fh		;0dfb
-	call sub_0ca9h		;0dfe
-	call sub_0cbdh		;0e01
-	xor a			;0e04
-	ld (0124bh),a		;0e05
-	ld hl,01213h		;0e08
-	ld b,006h		;0e0b
-	call l0b64h		;0e0d
-	ret nc			;0e10
-l0e11h:
-	ld a,(0124bh)		;0e11
-	or a			;0e14
-	jr z,l0e11h		;0e15
-	ld a,(0120ch)		;0e17
-l0e1ah:
-	and 0c0h		;0e1a
-	ret nz			;0e1c
-	scf			;0e1d
-	ret			;0e1e
+	call sub_0d2eh		;0dec Check if FDC is ready for write operations
+	ret nc			;0def Return with carry clear if FDC not ready for format
+	ld hl,01213h		;0df0 Point HL to FDC command buffer
+	ld (hl),00dh		;0df3 Set command byte to 0x0D (FORMAT TRACK command)
+	call sub_0c6ah		;0df5 Call disk parameter configuration routine
+	call sub_0b7bh		;0df8 Call drive/head selection setup routine
+	call sub_0e1fh		;0dfb Call track/sector parameter table setup
+	call sub_0ca9h		;0dfe Call DMA controller configuration routine
+	call sub_0cbdh		;0e01 Call DMA transfer initialization routine
+	xor a			;0e04 Clear A register (A = 0)
+	ld (0124bh),a		;0e05 Clear operation status flag (0 = operation in progress)
+	ld hl,01213h		;0e08 Point HL to FDC command buffer start
+	ld b,006h		;0e0b Set command length to 6 bytes (FORMAT TRACK parameters)
+	call l0b64h		;0e0d Transmit 6-byte format command to FDC via port 0xF1
+	ret nc			;0e10 Return with carry clear if command transmission failed
+l0e11h:					; Wait for format operation completion
+	ld a,(0124bh)		;0e11 Load operation status flag from memory
+	or a			;0e14 Test if operation completed (non-zero = done)
+	jr z,l0e11h		;0e15 Loop until format operation completes
+	ld a,(0120ch)		;0e17 Load FDC completion status register
+l0e1ah:					; Validate format completion status
+	and 0c0h		;0e1a Test bits 6&7 (completion and error status flags)
+	ret nz			;0e1c Return with non-zero if format errors detected
+	scf			;0e1d Set carry flag (format operation successful)
+	ret			;0e1e Return with carry set indicating successful format
+;==============================================================================
+; FORMAT SECTOR DATA GENERATION ROUTINE (sub_0e1fh) - 0x0E1F-0x0E42
+;==============================================================================
+; Purpose: Generate sector data pattern for format track operation
+; Called by: Format operation routine (sub_0dech) to create sector headers
+;
+; Operation:
+; 1. Call sub_0c7bh to set up track/sector parameter tables
+; 2. Load drive configuration from memory (drive status, head flags, track)
+; 3. Set up DMA buffer at 0x1000 for format data generation
+; 4. Generate 26 sector entries (0x1A = 26 sectors) with format pattern:
+;    - Track number (from 0x1225)
+;    - Head/drive flags (from 0x1226) 
+;    - Sector number (incrementing: 1,2,3...26)
+;    - Sector size (from 0x1203)
+;
+; Memory Layout: Creates format data at 0x1000+ for FDC FORMAT TRACK command
+; Format: Each sector = 4 bytes (track, head, sector, size) × 26 sectors = 104 bytes
+;==============================================================================
 sub_0e1fh:
-	call sub_0c7bh		;0e1f
-	ld a,(01203h)		;0e22
-	ld e,a			;0e25
-	ld a,(01226h)		;0e26
-	ld c,a			;0e29
-	ld a,(01225h)		;0e2a
-	ld d,001h		;0e2d
-	ld b,01ah		;0e2f
-	ld hl,01000h		;0e31
-	ld (01200h),hl		;0e34
-l0e37h:
-	ld (hl),a			;0e37
-	inc hl			;0e38
-	ld (hl),c			;0e39
-	inc hl			;0e3a
-	ld (hl),d			;0e3b
-	inc hl			;0e3c
-	ld (hl),e			;0e3d
-	inc hl			;0e3e
-	inc d			;0e3f
-	djnz l0e37h		;0e40
-	ret			;0e42
+	call sub_0c7bh		;0e1f Call track/sector parameter table setup routine
+	ld a,(01203h)		;0e22 Load drive status/sector size from memory
+	ld e,a			;0e25 Store sector size parameter in E register
+	ld a,(01226h)		;0e26 Load drive control flags (head selection)
+	ld c,a			;0e29 Store head/drive flags in C register
+	ld a,(01225h)		;0e2a Load current track number from memory
+	ld d,001h		;0e2d Set initial sector number to 1 (first sector)
+	ld b,01ah		;0e2f Set loop counter to 0x1A (26 sectors per track)
+	ld hl,01000h		;0e31 Point HL to format data buffer at 0x1000
+	ld (01200h),hl		;0e34 Store buffer address in DMA address register
+l0e37h:					; Sector format data generation loop
+	ld (hl),a		;0e37 Store track number (A) in format buffer
+	inc hl			;0e38 Move to next byte in buffer
+	ld (hl),c		;0e39 Store head/drive flags (C) in format buffer
+	inc hl			;0e3a Move to next byte in buffer
+	ld (hl),d		;0e3b Store sector number (D) in format buffer
+	inc hl			;0e3c Move to next byte in buffer
+	ld (hl),e		;0e3d Store sector size (E) in format buffer
+	inc hl			;0e3e Move to next 4-byte sector entry
+	inc d			;0e3f Increment sector number (1→2→3...→26)
+	djnz l0e37h		;0e40 Decrement sector counter, loop until all 26 sectors done
+	ret			;0e42 Return with format data buffer prepared at 0x1000
+;==============================================================================
+; COMPLETE DISK FORMAT OPERATION (sub_0e43h) - 0x0E43-0x0E86
+;==============================================================================
+; Purpose: Format entire disk with comprehensive drive setup and validation
+; Called by: System initialization routines for complete disk preparation
+;
+; Operation Sequence:
+; 1. Validate FDC status and drive readiness
+; 2. Initialize drive status table and perform read test
+; 3. Format all tracks (0-76, total 77 tracks) with both head configurations
+; 4. Handle single/double-sided drive detection and formatting
+;
+; Track Coverage: Formats tracks 0 through 76 (0x4D-1 = 77 tracks total)
+; Head Support: Handles both head 0 and head 1 for double-sided drives
+;==============================================================================
 sub_0e43h:
-	call sub_0bf2h		;0e43
-	xor 020h		;0e46
-	and 060h		;0e48
-	ret nz			;0e4a
-	call l0de0h		;0e4b
-	ld iy,01205h		;0e4e
-	ld a,(01202h)		;0e52
-	ld e,a			;0e55
-	ld d,000h		;0e56
-	add iy,de		;0e58
-	call sub_0b1ch		;0e5a
-	ret nc			;0e5d
-	xor a			;0e5e
-	ld (01225h),a		;0e5f
-l0e62h:
-	call sub_0c05h		;0e62
-	ret nc			;0e65
-	xor a			;0e66
-	ld (01226h),a		;0e67
-	call sub_0dech		;0e6a
-	ret nc			;0e6d
-	ld a,(01203h)		;0e6e
-	or a			;0e71
-	jr z,l0e7bh		;0e72
-	ld (01226h),a		;0e74
-	call sub_0dech		;0e77
-	ret nc			;0e7a
-l0e7bh:
-	ld a,(01225h)		;0e7b
-	inc a			;0e7e
-	ld (01225h),a		;0e7f
-	cp 04dh		;0e82
-	jr c,l0e62h		;0e84
-	jp sub_0b1ch		;0e86
+	call sub_0bf2h		;0e43 Call FDC write setup, get status byte
+	xor 020h		;0e46 XOR with 0x20 (flip write ready bit)
+	and 060h		;0e48 Test bits 5&6 (data direction and write ready)
+	ret nz			;0e4a Return if FDC not ready for format operations
+	call l0de0h		;0e4b Call FDC status check, extract drive status bit
+	ld iy,01205h		;0e4e Point IY to drive status table base
+	ld a,(01202h)		;0e52 Load current drive number (0-3)
+	ld e,a			;0e55 Copy drive number to E register
+	ld d,000h		;0e56 Clear D register (DE = drive offset)
+	add iy,de		;0e58 Point IY to current drive's status entry
+	call sub_0b1ch		;0e5a Perform initial drive read test
+	ret nc			;0e5d Return if drive read test failed
+	xor a			;0e5e Clear A register (start with track 0)
+	ld (01225h),a		;0e5f Set starting track number to 0
+l0e62h:					; Main track formatting loop (tracks 0-76)
+	call sub_0c05h		;0e62 Call disk seek and status check for current track
+	ret nc			;0e65 Return if seek to track failed
+	xor a			;0e66 Clear head selection (start with head 0)
+	ld (01226h),a		;0e67 Set head selection to 0 (first head)
+	call sub_0dech		;0e6a Call format track operation for head 0
+	ret nc			;0e6d Return if head 0 format failed
+	ld a,(01203h)		;0e6e Load drive capabilities/head count from status
+	or a			;0e71 Test if drive supports multiple heads
+	jr z,l0e7bh		;0e72 Skip head 1 format if single-sided drive
+	ld (01226h),a		;0e74 Set head selection to 1 (second head)
+	call sub_0dech		;0e77 Call format track operation for head 1
+	ret nc			;0e7a Return if head 1 format failed
+l0e7bh:					; Advance to next track
+	ld a,(01225h)		;0e7b Load current track number
+	inc a			;0e7e Increment to next track (0→1→2...→76)
+	ld (01225h),a		;0e7f Store updated track number
+	cp 04dh		;0e82 Compare with 77 (0x4D = total tracks to format)
+	jr c,l0e62h		;0e84 Continue formatting if more tracks remain
+	jp sub_0b1ch		;0e86 Final drive validation read after complete format
+;==============================================================================
+; SYSTEM DIAGNOSTIC AND HARDWARE TEST SUITE (sub_0e89h) - 0x0E89-0x0EA1
+;==============================================================================
+; Purpose: Comprehensive system hardware testing and validation
+; Called by: System initialization to verify all hardware components
+;
+; Test Sequence:
+; 1. RAM memory boundary detection and testing
+; 2. Extended system component validation
+; 3. FDC initialization and drive testing
+; 4. Additional hardware subsystem verification
+;
+; Returns: Various status codes from individual test routines
+;==============================================================================
 sub_0e89h:
-	call sub_0ea2h		;0e89
-	call nz,sub_0f6bh		;0e8c
-	call sub_0ecch		;0e8f
-	call nz,sub_0f70h		;0e92
-	call sub_0a8dh		;0e95
-	call nc,sub_0f75h		;0e98
-	call sub_0f10h		;0e9b
-	call nz,sub_0f7ah		;0e9e
-	ret			;0ea1
+	call sub_0ea2h		;0e89 Call RAM memory diagnostic test
+	call nz,sub_0f6bh	;0e8c If RAM test indicates issues, call error handler
+	call sub_0ecch		;0e8f Call extended system component test
+	call nz,sub_0f70h	;0e92 If system test fails, call failure handler
+	call sub_0a8dh		;0e95 Call FDC initialization and drive setup
+	call nc,sub_0f75h	;0e98 If FDC init fails, call initialization error handler
+	call sub_0f10h		;0e9b Call additional hardware subsystem test
+	call nz,sub_0f7ah	;0e9e If hardware test fails, call diagnostic error handler
+	ret					;0ea1 Return from complete system diagnostic suite
 
 ;==============================================================================
 ; RAM MEMORY DIAGNOSTIC TEST (0x0EA2)