Document and clarify keyboard interrupt routines in `kbdrive.inc`: added detailed...

diff --git a/emulator/kbdrive.inc b/emulator/kbdrive.inc
index 235ad71..9291131 100644 (file)
--- a/emulator/kbdrive.inc
+++ b/emulator/kbdrive.inc
@@ -1,57 +1,83 @@
-; Keyboard driver.\r
-\r
-KB_init:\r
-        push    es              \r
-        push    0\r
-        pop     es\r
-        mov     eax, [es:9*4]           ; save old int vectar\r
-        mov     [KB_OldVect], eax \r
-        mov     ax, cs                  ; set new int vector\r
-        shl     eax, 16\r
-        mov     ax, KB_IntHandler\r
-        mov     [es:9*4], eax\r
-        pop     es\r
-        ret\r
-\r
-KB_restore:\r
-        mov     eax, [KB_OldVect]\r
-        push    es\r
-        push    0\r
-        pop     es\r
-        mov     [es:9*4], eax \r
-        pop     es\r
-        ret\r
-\r
-KB_IntHandler:\r
-        pusha\r
-        in      al, 60h\r
-        mov     bx, [cs:KB_pntin]\r
-        mov     byte [cs:bx+KB_buf], al\r
-       inc     bx\r
-       cmp     bx, 128\r
-       jng     KB_l1\r
-       mov     bx, 0\r
-KB_l1: mov     [cs:KB_pntin], bx\r
-        popa\r
-        pushf                   ; Execute default code in old int vector\r
-        call    dword [cs:KB_OldVect]\r
-        iret\r
-\r
-KB_read:       ; returns scan code in: dl\r
-       mov     dl, 0\r
-       mov     bx, [KB_pntout]\r
-       cmp     bx, [KB_pntin]\r
-       je      KB_l2\r
-       mov     dl, [bx+KB_buf]\r
-       inc     bx\r
-       cmp     bx, 128\r
-       jng     KB_l3\r
-       mov     bx, 0\r
-KB_l3: mov     [KB_pntout], bx\r
-KB_l2: ret\r
-\r
-KB_OldVect dd 0\r
-KB_pntin dw 0\r
-KB_pntout dw 0\r
-KB_buf db 0\r
-times 127 db 0\r
+; Keyboard driver routines
+
+; KB_init
+;
+; Initializes the keyboard interrupt handler.
+; Saves the old interrupt vector for INT 9h and sets up the new handler.
+;
+; Notes:
+; - INT 9h is the keyboard interrupt vector.
+; - The handler stores scan codes in a circular buffer.
+
+KB_init:
+        push    es              
+        push    0
+        pop     es
+        mov     eax, [es:9*4]           ; save old int vector
+        mov     [KB_OldVect], eax 
+        mov     ax, cs                  ; set new int vector
+        shl     eax, 16
+        mov     ax, KB_IntHandler
+        mov     [es:9*4], eax
+        pop     es
+        ret
+
+; KB_restore
+;
+; Restores the original keyboard interrupt handler.
+; Used when exiting the emulator to restore the system's default handler.
+
+KB_restore:
+        mov     eax, [KB_OldVect]
+        push    es
+        push    0
+        pop     es
+        mov     [es:9*4], eax 
+        pop     es
+        ret
+
+; KB_IntHandler
+;
+; Keyboard interrupt handler.
+; Reads scan code from port 60h and stores it in the circular buffer.
+; Then calls the original interrupt handler.
+
+KB_IntHandler:
+        pusha
+        in      al, 60h
+        mov     bx, [cs:KB_pntin]
+        mov     byte [cs:bx+KB_buf], al
+       inc     bx
+       cmp     bx, 128
+       jng     KB_l1
+       mov     bx, 0
+KB_l1: mov     [cs:KB_pntin], bx
+        popa
+        pushf                   ; Execute default code in old int vector
+        call    dword [cs:KB_OldVect]
+        iret
+
+; KB_read
+;
+; Reads a scan code from the keyboard buffer.
+; Returns the scan code in DL.
+; If buffer is empty, returns 0.
+
+KB_read:       ; returns scan code in: dl
+       mov     dl, 0
+       mov     bx, [KB_pntout]
+       cmp     bx, [KB_pntin]
+       je      KB_l2
+       mov     dl, [bx+KB_buf]
+       inc     bx
+       cmp     bx, 128
+       jng     KB_l3
+       mov     bx, 0
+KB_l3: mov     [KB_pntout], bx
+KB_l2: ret
+
+KB_OldVect dd 0
+KB_pntin dw 0
+KB_pntout dw 0
+KB_buf db 0
+times 127 db 0