Comment syscall functions and handlers

src/userprog/syscall.c

@@ -79,6 +79,9 @@ static const syscall_arguments syscall_lookup[] =
 static const int LOOKUP_SIZE
   = sizeof (syscall_lookup) / sizeof (syscall_arguments);
 
+
+/* Initialises the syscall handling system, as well as a global lock to
+   synchronise all file access between processes. */
 void
 syscall_init (void) 
 {
@@ -86,6 +89,9 @@ syscall_init (void)
   lock_init (&filesys_lock);
 }
 
+/* Function that takes a interrupt frame containing a syscall and its args.
+   Validates the arguments and pointers before calling the relevant
+   high-level system call function, storing its output (if any) in f->eax */
 static void
 syscall_handler (struct intr_frame *f)
 {
@@ -111,6 +117,8 @@ syscall_handler (struct intr_frame *f)
   f->eax = syscall.function (args[0], args[1], args[2]);
 }
 
+/* Called upon a "halt" syscall, resulting in a complete shutdown of the
+   process, via shutdown_power_off (); */
 static void
 syscall_halt (void)
 {
@@ -126,6 +134,10 @@ syscall_exit (int status)
   thread_exit ();
 }
 
+/* Executes a given command with the relevant args, by calling process_execute.
+   Acquires the filesystem lock as process_execute accesses the file system.
+   Returns PID for the process that is running the CMD_LINE
+ */
 static pid_t
 syscall_exec (const char *cmd_line)
 {
@@ -138,12 +150,17 @@ syscall_exec (const char *cmd_line)
   return pid;
 }
 
+/* Handles the syscall of wait. Effectively a wrapper for process_wait as the
+   necessary validation and such all happens in process_wait anyway. */
 static int
 syscall_wait (pid_t pid)
 {
   return process_wait (pid);
 }
 
+/* Handles the syscall for file creation. First validates the user file
+   pointer. Acquires the file system lock to prevent synchronisation issues,
+   and then uses FILESYS_CREATE to create the file, returning the same status */
 static bool
 syscall_create (const char *file UNUSED, unsigned initial_size UNUSED)
 {
@@ -156,6 +173,9 @@ syscall_create (const char *file UNUSED, unsigned initial_size UNUSED)
   return status;
 }
 
+/* Handles the syscall for file removal. First validates the user file pointer.
+   Acquires the file system lock to prevent synchronisation issues, and then
+   uses FILESYS_REMOVE to remove the file, returning the same success status */
 static bool
 syscall_remove (const char *file)
 {
@@ -168,6 +188,10 @@ syscall_remove (const char *file)
   return status;
 }
 
+/* Handles the syscall for opening a file connection. First, validates the file
+   pointer. Then it acquires a lock for the file system, in order to open the
+   connection without synchronisation issues. It then maps a new fd to this file
+   in the hash table before returning the fd. */
 static int
 syscall_open (const char *file)
 {
@@ -179,19 +203,27 @@ syscall_open (const char *file)
   if (ptr == NULL)
     return -1;
 
+  /* Allocate space for a struct representing a mapping from an FD to a struct
+     file. */
   struct open_file *file_info
     = (struct open_file*) malloc (sizeof (struct open_file));
   if (file_info == NULL)
     return -1;
 
+  /* Populate the above struct, with a unique FD and the current open file */
   file_info->fd = fd_counter++;
   file_info->file = ptr;
 
+  /* Add the new FD->file mapping to the hashtable for the current thread */
   hash_insert (&thread_current ()->open_files, &file_info->elem);
 
+  /* Return the new FD */
   return file_info->fd;
 }
 
+/* Handles the syscall for getting a file's size. Converts a provided FD into
+   the asssociated file struct. Acquire the lock for the filesystem and use
+   FILE_LENGTH to calculate the length for return. */
 static int
 syscall_filesize (int fd)
 {
@@ -206,6 +238,10 @@ syscall_filesize (int fd)
   return bytes;
 }
 
+/* Handles the syscall for reading SIZE bytes from a file referenced by FD.
+   If the FD references the console, use input_getc (), otherwise convert the
+   FD to its associated file struct, acquire the filesystem lock, read up to
+   SIZE bytes and then return the number of bytes read.*/
 static int
 syscall_read (int fd, void *buffer, unsigned size)
 {
@@ -239,6 +275,10 @@ syscall_read (int fd, void *buffer, unsigned size)
     }
 }
 
+/* Handles the syscall for writing SIZE bytes to a file referenced by FD.
+   If the FD references the console, use put_buf (), otherwise convert the
+   FD to its associated file struct, acquire the filesystem lock, write up to
+   SIZE bytes and then return the number of bytes written.*/
 static int
 syscall_write (int fd, const void *buffer, unsigned size)
 {
@@ -270,6 +310,10 @@ syscall_write (int fd, const void *buffer, unsigned size)
     }
 }
 
+/* Handles the syscall for seeking to POSITION bytes in a file referenced by
+   FD. Converts the FD to its associated file struct, acquires the filesystem
+   lock and then uses file_seek to adjust the cursor to a specific position in
+   the file.*/
 static void
 syscall_seek (int fd, unsigned position)
 {
@@ -282,6 +326,9 @@ syscall_seek (int fd, unsigned position)
   }
 }
 
+/* Handles the syscall for returning the next byte in a file referenced by
+   FD. Converts the FD to its associated file struct, acquires the filesystem
+   lock and then uses file_tell to read the next byte.*/
 static unsigned
 syscall_tell (int fd)
 {
@@ -296,6 +343,9 @@ syscall_tell (int fd)
   return pos;
 }
 
+/* Handles the syscall for closing a connection to a file. Converts the FD to
+   its associated file struct. If it exists, it removes it from the hash table,
+   acquires the filesystem lock, and uses file_close to close the connection.*/
 static void
 syscall_close (int fd)
 {
@@ -311,12 +361,16 @@ syscall_close (int fd)
     }
 }
 
+/* Hashing function needed for the open_file table. Returns a hash for an entry,
+   based on its FD. */
 unsigned
 fd_hash (const struct hash_elem *element, void *aux UNUSED)
 {
   return hash_int (hash_entry (element, struct open_file, elem)->fd);
 }
 
+/* Comparator function for the open_file table. Compares two entries based on
+   the FDs. */
 bool
 fd_less (const struct hash_elem *a_, const struct hash_elem *b_,
         void *aux UNUSED)