Document and clarify stack operations in `emulator.asm`: added detailed comments...

diff --git a/emulator/emulator.asm b/emulator/emulator.asm
index 0f71d06..4c8839e 100644 (file)
--- a/emulator/emulator.asm
+++ b/emulator/emulator.asm
@@ -70,7 +70,8 @@ shl   bx, 1
 add    bx, table\r
 jmp    word [cs:bx]\r
 \r
-table  dw emu          ; 0\r
+table\r
+    dw emu             ; 0\r
        dw quit\r
        dw xkbd@\r
        dw xnum\r
@@ -99,25 +100,25 @@ table      dw emu          ; 0
        dw xmul\r
        dw xdiv\r
        dw xgreat\r
-       dw xless\r
-       dw xnot         ; 30\r
-       dw xi\r
-       dw xcprt@\r
-       dw xcprt!\r
-       dw xi2\r
-       dw xi3          ; 35\r
-       dw xshl\r
-       dw xshr\r
-       dw lor\r
-       dw lxor\r
-       dw xvidmap      ; 40\r
-       dw xmouse@\r
-       dw xvidput\r
-       dw xcmove\r
-       dw xcfill\r
-       dw xtvidput     ; 45\r
-       dw xdep\r
-       dw xcharput\r
+    dw xless    ; 29\r
+    dw xnot     ; 30\r
+    dw xi       ; 31\r
+    dw xcprt@   ; 32\r
+    dw xcprt!   ; 33\r
+    dw xi2      ; 34\r
+    dw xi3      ; 35\r
+    dw xshl     ; 36\r
+    dw xshr     ; 37\r
+    dw lor      ; 38\r
+    dw lxor     ; 39\r
+    dw xvidmap  ; 40\r
+    dw xmouse@  ; 41\r
+    dw xvidput  ; 42\r
+    dw xcmove   ; 43\r
+    dw xcfill   ; 44\r
+    dw xtvidput ; 45\r
+    dw xdep     ; 46\r
+    dw xcharput ; 47\r
 \r
 xkbd@: call    KB_read\r
        sub     edi, 4\r
@@ -153,19 +154,56 @@ xcall:    mov     edx, dword [es:esi]
        add     esi, [xms_addr]\r
        jmp     emu\r
 \r
-xinc:  inc     dword [es:edi]\r
-       jmp     emu\r
+xinc: ; Increment: ( n -- n+1 )\r
+; Increments the top of the data stack by 1.\r
 \r
-xdec:  dec     dword [es:edi]\r
+    inc        dword [es:edi]\r
        jmp     emu\r
 \r
-xdup:  mov     eax, [es:edi]\r
-       sub     edi, 4\r
-       mov     [es:edi], eax\r
-       jmp     emu\r
 \r
-xdrop: add     edi, 4\r
-       jmp     emu\r
+xdec:  ; Decrement: ( n -- n-1 )\r
+;\r
+; Decrements the top of the data stack by 1.\r
+;\r
+; Memory layout before execution:\r
+;   [es:edi] = n\r
+;\r
+; Memory layout after execution:\r
+;   [es:edi] = n-1\r
+\r
+    dec dword [es:edi]  ; decrement the top of the stack\r
+    jmp emu\r
+\r
+\r
+xdup:  ; Duplicate: ( n -- n n )\r
+;\r
+; Duplicates the top element of the data stack.\r
+;\r
+; Memory layout before execution:\r
+;   [es:edi] = n\r
+;\r
+; Memory layout after execution:\r
+;   [es:edi]   = n (new top)\r
+;   [es:edi+4] = n (original top)\r
+\r
+    mov eax, [es:edi]   ; copy top element to eax\r
+    sub edi, 4      ; move stack pointer down to make space\r
+    mov [es:edi], eax   ; push copy of top element onto stack\r
+    jmp emu\r
+\r
+\r
+xdrop: ; Drop: ( n -- )\r
+;\r
+; Removes the top element from the data stack.\r
+;\r
+; Memory layout before execution:\r
+;   [es:edi] = n\r
+;\r
+; Memory layout after execution:\r
+;   Stack pointer is adjusted; n is no longer on stack\r
+\r
+    add edi, 4      ; pop top element off the stack\r
+    jmp emu\r
 \r
 xif:   mov     eax, [es:edi]\r
        add     edi, 4\r