add documentation

messages.asm

@@ -1,9 +1,11 @@
-org 0x7C00
-bits 16
+org 0x7C00      ; The boot code on a drive always gets loaded at address 0x7C00
+bits 16         ; .bin defaults to 16 bits
 
-WIDTH equ 0x50
-HEIGHT equ 0x18
-VIDEO_MODE equ 0x3
+;; FIXME: possible problem with HEIGHT being defined
+;; as one less than what VIDEO_MODE implies?
+WIDTH equ 0x50		; 60
+HEIGHT equ 0x18		; 24 (?)
+VIDEO_MODE equ 0x3	; 80x25 screen, text mode
 
 ;; see http://www.ctyme.com/intr/int-10.htm for interrupts
 
@@ -13,33 +15,36 @@ mov	ax, VIDEO_MODE
 int	10h
 
 ;; Clear screen
-mov ah, 0x06
-mov al, 0x00
-mov bh, 0x0F
-mov cx, 0x0000
-mov dh, HEIGHT
-mov dl, WIDTH
+mov ah, 0x06	; scroll screen up
+mov al, 0x00	; lines to scroll (0 = clear)
+mov bh, 0x0F	; bg/fg colour
+mov cx, 0x0000	; upper row number, left col number (both 0)
+mov dh, HEIGHT	; lower row number (24)
+mov dl, WIDTH	; right col number (80)
 int 0x10
 
 ;; Set cursor to bottom of screen
-mov dh, HEIGHT
-mov dl, 0x00
-mov bh, 0x00
-mov ah, 0x02
+mov ah, 0x02	; set cursor position
+mov bh, 0x00	; page number
+mov dh, HEIGHT	; row (bottommost row)
+mov dl, 0x00	; col (leftmost col)
 int 0x10
-mov sp, 0x2000
+
+mov sp, 0x2000	; initialise stack pointer
 
 .loop:
-        ;; Read character
-        mov ah, 0x00
+	mov ah, 0x00	; Read character
 	int 0x16
 
 	cmp al, 0x0d 	; newline
 	je .newline
+
 	cmp al, 0x08 	; delete character
 	je .change_color_mode
+
 	cmp al, 0x1b 	; escape character
 	je .beep
+
 	jmp .nonewline
 
 .change_color_mode:
@@ -151,22 +156,33 @@ mov sp, 0x2000
 	int 0x10
 	jmp .loop
 
-
+;; Reads two characters from the keyboard buffer and converts them into a single byte
+;;
+;; The conversion happens as follows:
+;; 	ASCII 'a' is subtracted from each character (so 'a' = 0, 'b' = 1, ...)
+;;	the first character is shifted left by 4
+;;	the shifted and non-shifted values are then or'ed together to form a byte
+;;
+;; CLOBBERS
+;; - ax
+;; - bl
 .readbyte:
-        ;; Read character
-        mov ah, 0x00
+	mov ah, 0x00	; Read character
 	int 0x16
-        ;; Read character is in al
-        sub al, 'a'
-        mov bl, al
-        shl bl, 0x4
 
-        ;; Read character
-        mov ah, 0x00
-        int 0x16
 	;; Read character is in al
-        sub al, 'a'
-        or al, bl
+	sub al, 'a'	; Normalise
+	mov bl, al
+	shl bl, 0x4	; First character is upper 4 bits
+
+	mov ah, 0x00	; Read character
+	int 0x16
+
+	;; Read character is in al
+	sub al, 'a'	; Normalise
+
+	or al, bl	; Combine both characters
+
 	ret
 
 .readduration:
@@ -181,5 +197,8 @@ halt:	hlt
 
 color_mode: db 0x02
 
+;; Magic number must be in the last 2 bytes of the sector so
+;; fill the binary with zeroes until it is 510 bytes in size
+;; (magic number will use up the remaining 2)
 times 510 - ($ - $$) db 0
-dw 0xAA55
+dw 0xAA55 ;; Magic number to mark sector as bootable