From ade8faf0f4abe285c103f8085dd2d8fe22c58197 Mon Sep 17 00:00:00 2001
From: sBubshait <s.bobshit@gmail.com>
Date: Mon, 4 Nov 2024 00:20:09 +0000
Subject: [PATCH] Update syscall to add more comments explaining the basic
 handler

---
 src/userprog/syscall.c | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/src/userprog/syscall.c b/src/userprog/syscall.c
index 5e53cd3..2926bbd 100644
--- a/src/userprog/syscall.c
+++ b/src/userprog/syscall.c
@@ -13,24 +13,27 @@ static void syscall_handler (struct intr_frame *);
    in size. */
 typedef uintptr_t (*syscall_function) (uintptr_t, uintptr_t, uintptr_t);
 
-/* System Call Functions */
+/* System call function prototypes */
 static void halt (void);
 static void exit (int status);
 
 static void *validate_user_pointer(void *ptr, size_t size);
 
-/* A struct defining a pair of a syscall_function along with its arity. */
+/* A struct defining a syscall_function pointer along with its arity. */
 typedef struct {
-  syscall_function function;
-  int arity;
+  syscall_function function;    /* Function pointer. */
+  int arity;                    /* Number of arguments of the function. */
 } syscall_arguments;
 
-/* A look-up table for system call functions mapped using their numbers. */
+/* A look-up table mapping numbers to system call functions with their number of
+   arguments. */
 static const syscall_arguments syscall_lookup[] = {
   [SYS_HALT] = {(syscall_function) halt, 0},
   [SYS_EXIT] = {(syscall_function) exit, 1},
 };
 
+/* The number of syscall functions (i.e, number of elements) within the
+   syscall_lookup table. */
 static const int lookup_size
   = sizeof (syscall_lookup) / sizeof (syscall_arguments);
 
@@ -43,20 +46,24 @@ syscall_init (void)
 static void
 syscall_handler (struct intr_frame *f)
 {
+  /* First, read the system call number from the stack. */
   validate_user_pointer(f->esp, 1);
   int syscall_number = *(int *) f->esp;
 
+  /* Ensures the number corresponds to a system call that can be handled. */
   if (syscall_number < 0 || syscall_number >= lookup_size)
     thread_exit ();
 
   syscall_arguments syscall = syscall_lookup[syscall_number];
 
+  /* Next, read and copy the arguments from the stack pointer. */
   validate_user_pointer (f->esp, syscall.arity);
   uintptr_t args[3];
-
   for (int i=0; i < syscall.arity; i++)
       args[i] = *(uintptr_t *) (f->esp + 1 + i);
 
+  /* Call the function that handles this system call with the arguments. When
+     there is a return value it is stored in f->eax. */
   f->eax = syscall.function(args[0], args[1], args[2]);
 }
 
@@ -67,13 +74,13 @@ halt (void)
 }
 
 static void
-exit (int status)
+exit (int status UNUSED)
 {
   //TODO
 }
 
-/* A function to validate if a block of memory starting at PTR and of
-   size SIZE bytes is fully contained within user virtual memory.  */
+/* Validates if a block of memory starting at PTR and of size SIZE bytes is
+   fully contained within user virtual memory. */
 static void *
 validate_user_pointer (void *ptr, size_t size)
 {