From: Svjatoslav Agejenko <svjatoslav@svjatoslav.eu>
Date: Mon, 16 Feb 2026 23:28:57 +0000 (+0200)
Subject: Document and clarify keyboard interrupt routines in `kbdrive.inc`: added detailed... 
X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=d2f53a4d093f10e2de14a748e36dbee02d063b73;p=fifth.git

Document and clarify keyboard interrupt routines in `kbdrive.inc`: added detailed comments for `KB_init`, `KB_restore`, `KB_IntHandler`, and `KB_read` describing functionality and usage.
---

diff --git a/emulator/kbdrive.inc b/emulator/kbdrive.inc
index 235ad71..9291131 100644
--- a/emulator/kbdrive.inc
+++ b/emulator/kbdrive.inc
@@ -1,57 +1,83 @@
-; Keyboard driver.
-
-KB_init:
-        push    es              
-        push    0
-        pop     es
-        mov     eax, [es:9*4]           ; save old int vectar
-        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:
-        mov     eax, [KB_OldVect]
-        push    es
-        push    0
-        pop     es
-        mov     [es:9*4], eax 
-        pop     es
-        ret
-
-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:	; 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
+; 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