From 695a79e1068c5c477ef6f3849488a6055ba24679 Mon Sep 17 00:00:00 2001
From: dwrz <dwrz@dwrz.net>
Date: Fri, 13 Nov 2020 17:14:52 +0000
Subject: [PATCH] Document x86 assembly examples

---
 x86-assembly/src/exit/exit.s |  4 ++++
 x86-assembly/src/func/func.s | 18 ++++++++++++++----
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/x86-assembly/src/exit/exit.s b/x86-assembly/src/exit/exit.s
index ff05933..32f946c 100644
--- a/x86-assembly/src/exit/exit.s
+++ b/x86-assembly/src/exit/exit.s
@@ -3,10 +3,14 @@
 
 _start:
 	# Store system call 1 in the EAX register.
+	# mov = instruction
+	# $1, %eax = operands
+	# %eax = register
 	mov $1, %eax
 
 	# Store the exit code 0 in the EBX register.
 	mov $0, %ebx
 
 	# Call interrupt handler 0x80 (128) -- on Linux, this is the kernel.
+	# Kernel will take over and see 1 in %eax, 0 in %ebx.
 	int $0x80
diff --git a/x86-assembly/src/func/func.s b/x86-assembly/src/func/func.s
index bd73a82..f957b22 100644
--- a/x86-assembly/src/func/func.s
+++ b/x86-assembly/src/func/func.s
@@ -14,18 +14,28 @@ _start:
 # square expects an integer on the stack, 16 bytes down from RBP.
 # The squared value is returned on %rax.
 square:
-	# Function Epilogue --> {
+	# Function Prologue --> {
 	push %rbp
         mov %rsp, %rbp
 
 	# Retrieve the parameter from the stack.
 	# 8 bytes down from RSP is the return address from square.
-	# 8 bytes down from that is the parameter to multiple.
+	# 8 bytes down from that is the parameter to multiply.
 	mov 16(%rbp), %rax
 	mul %rax
 
-	# Function Prologue --> }
+	# Function Epilogue --> }
 	mov %rbp, %rsp
         pop %rbp
-	# ret pops and return to address on stack.
+	# ret pops and returns to address on stack.
 	ret
+
+# |----------------+-----------+----------------|
+# |        Address |      Data | Stack Pointers |
+# |----------------+-----------+----------------|
+# | 0x7fffffffe8f8 |           |                |
+# | 0x7fffffffe900 | 0x0 (rbp) |                |
+# | 0x7fffffffe908 |  0x401002 |                |
+# | 0x7fffffffe910 |         3 | ←rsp           |
+# |----------------+-----------+----------------|
+#  ←rbp