From 89a40c68846aeaac735a86ac252246cc7389a615 Mon Sep 17 00:00:00 2001
From: Val <val@soft.fish>
Date: Fri, 2 Sep 2022 06:22:36 -0500
Subject: [PATCH] Add more annotations

---
 17-Chernobyl/mc-disasm.asm | 35 +++++++++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 8 deletions(-)

diff --git a/17-Chernobyl/mc-disasm.asm b/17-Chernobyl/mc-disasm.asm
index 44f85f1..0cd8d2e 100644
--- a/17-Chernobyl/mc-disasm.asm
+++ b/17-Chernobyl/mc-disasm.asm
@@ -288,9 +288,9 @@
 
 4678 <malloc>
 4678:  0b12           push	r11
-467a:  c293 0424      tst.b	&0x2404
-467e:  0f24           jz	$+0x20 <malloc+0x26>
-4680:  1e42 0024      mov	&0x2400, r14
+467a:  c293 0424      tst.b	&0x2404           ; if initialized:
+467e:  0f24           jz	$+0x20 <malloc+0x26> ;  skip, else
+4680:  1e42 0024      mov	&0x2400, r14         ; initialize
 4684:  8e4e 0000      mov	r14, 0x0(r14)
 4688:  8e4e 0200      mov	r14, 0x2(r14)
 468c:  1d42 0224      mov	&0x2402, r13
@@ -301,22 +301,26 @@
 ; malloc+0x26:
 469e:  1b42 0024      mov	&0x2400, r11
 46a2:  0e4b           mov	r11, r14
+; malloc+0x2c
 46a4:  1d4e 0400      mov	0x4(r14), r13
-46a8:  1db3           bit	#0x1, r13
-46aa:  2820           jnz	$+0x52 <malloc+0x84>
-; This is all initialization
+46a8:  1db3           bit	#0x1, r13            ; if not-empty
+46aa:  2820           jnz	$+0x52 <malloc+0x84> ; skip, else
+; check whether there's enough space in this freeblock to satisfy rq
 46ac:  0c4d           mov	r13, r12
 46ae:  12c3           clrc
 46b0:  0c10           rrc	r12
 46b2:  0c9f           cmp	r15, r12
 46b4:  2338           jl	$+0x48 <malloc+0x84>
+; Ensure the requested size plus header size is lt available space
 46b6:  0b4f           mov	r15, r11
 46b8:  3b50 0600      add	#0x6, r11
 46bc:  0c9b           cmp	r11, r12
 46be:  042c           jc	$+0xa <malloc+0x50>
+; Success! Allocate the memory
 46c0:  1dd3           bis	#0x1, r13
 46c2:  8e4d 0400      mov	r13, 0x4(r14)
 46c6:  163c           jmp	$+0x2e <malloc+0x7c>
+; malloc+0x50
 46c8:  0d4f           mov	r15, r13
 46ca:  0d5d           add	r13, r13
 46cc:  1dd3           bis	#0x1, r13
@@ -331,15 +335,20 @@
 46ea:  0c5c           add	r12, r12
 46ec:  8d4c 0400      mov	r12, 0x4(r13)
 46f0:  8e4d 0200      mov	r13, 0x2(r14)
+; malloc+0x7c
+; Return the address of the new block
 46f4:  0f4e           mov	r14, r15
 46f6:  3f50 0600      add	#0x6, r15
-46fa:  0e3c           jmp	$+0x1e <malloc+0xa0>
+46fa:  0e3c           jmp	$+0x1e <malloc+0xa0> ; goto pop r11, ret
+; malloc+0x84
+; ensure r14->next - r14 is positive
 46fc:  0d4e           mov	r14, r13
 46fe:  1e4e 0200      mov	0x2(r14), r14
 4702:  0e9d           cmp	r13, r14
 4704:  0228           jnc	$+0x6 <malloc+0x92>
+; if r14 - 5000 == 0
 4706:  0e9b           cmp	r11, r14
-4708:  cd23           jnz	$-0x64 <malloc+0x2c>
+4708:  cd23           jnz	$-0x64 <malloc+0x2c> ; try next block
 ; puts("Heap exhausted. Aborting")
 470a:  3f40 5e46      mov	#0x465e, r15
 470e:  b012 504d      call	#0x4d50 <puts>
@@ -350,17 +359,27 @@
 
 471c <free>
 471c:  0b12           push	r11
+; Turn datablock pointer into metadata pointer
 471e:  3f50 faff      add	#0xfffa, r15
+; move this->size into r15
 4722:  1d4f 0400      mov	0x4(r15), r13
+; clear the usedbit
 4726:  3df0 feff      and	#0xfffe, r13
+; move the result into this->size
 472a:  8f4d 0400      mov	r13, 0x4(r15)
+; move this->prev into r14
 472e:  2e4f           mov	@r15, r14
+; move this->prev->size into r12
 4730:  1c4e 0400      mov	0x4(r14), r12
+; if this->prev->size & 1
 4734:  1cb3           bit	#0x1, r12
+; ... != 0, skip down
 4736:  0d20           jnz	$+0x1c <free+0x36>
+; update prev->size
 4738:  3c50 0600      add	#0x6, r12
 473c:  0c5d           add	r13, r12
 473e:  8e4c 0400      mov	r12, 0x4(r14)
+; update prev->next
 4742:  9e4f 0200 0200 mov	0x2(r15), 0x2(r14)
 4748:  1d4f 0200      mov	0x2(r15), r13
 474c:  8d4e 0000      mov	r14, 0x0(r13)