fix: remove stack fault checks for page faults outside user non-present addresses

Implement helper functions for managing the supplemental page table

See merge request lab2425_autumn/pintos_22!55

.gitlab-ci.yml

@@ -16,18 +16,13 @@ stages:
   script:
     - cd src/$DIR
     - make check | tee build.log
-    - grep -q "FAIL tests/$DIR" build.log && exit 1 || exit 0
+    - grep -vE "^FAIL $IGNORE\$" build.log | grep -q "FAIL tests/$DIR" && exit 1 || exit 0
 
 test_devices:
   extends: .pintos_tests
   variables:
     DIR: devices
 
-test_filesys:
-  extends: .pintos_tests
-  variables:
-    DIR: filesys
-
 test_threads:
   extends: .pintos_tests
   variables:
@@ -42,3 +37,4 @@ test_vm:
   extends: .pintos_tests
   variables:
     DIR: vm
+    IGNORE: (tests/vm/pt-overflowstk|tests/vm/page-linear|tests/vm/page-parallel|tests/vm/page-merge-seq|tests/vm/page-merge-par|tests/vm/page-merge-stk|tests/vm/page-merge-mm|tests/vm/mmap-read|tests/vm/mmap-close|tests/vm/mmap-overlap|tests/vm/mmap-twice|tests/vm/mmap-write|tests/vm/mmap-exit|tests/vm/mmap-shuffle|tests/vm/mmap-clean|tests/vm/mmap-inherit|tests/vm/mmap-misalign|tests/vm/mmap-null|tests/vm/mmap-over-code|tests/vm/mmap-over-data|tests/vm/mmap-over-stk|tests/vm/mmap-remove)

src/Makefile.build

@@ -62,7 +62,10 @@ userprog_SRC += userprog/gdt.c		# GDT initialization.
 userprog_SRC += userprog/tss.c		# TSS management.
 
 # Virtual memory code.
+vm_SRC += vm/frame.c                    # Frame table manager.
+vm_SRC += vm/page.c                     # Page table manager.
 vm_SRC += devices/swap.c		# Swap block manager.
+vm_SRC += vm/stackgrowth.c              # Stack growth functions.
 #vm_SRC = vm/file.c			# Some other file.
 
 # Filesystem code.

src/examples/Makefile

@@ -4,7 +4,7 @@ SRCDIR = ..
 # To add a new test, put its name on the PROGS list
 # and then add a name_SRC line that lists its source files.
 PROGS = cat cmp cp echo halt hex-dump mcat mcp rm \
-	bubsort insult lineup matmult recursor
+	bubsort insult lineup matmult recursor args-ovf
 
 # Should work from task 2 onward.
 cat_SRC = cat.c
@@ -18,6 +18,7 @@ lineup_SRC = lineup.c
 ls_SRC = ls.c
 recursor_SRC = recursor.c
 rm_SRC = rm.c
+args-ovf_SRC = args-ovf.c
 
 # Should work in task 3; also in task 4 if VM is included.
 bubsort_SRC = bubsort.c

src/threads/init.c

@@ -32,6 +32,7 @@
 #include "tests/threads/tests.h"
 #endif
 #ifdef VM
+#include "vm/frame.h"
 #include "devices/swap.h"
 #endif
 #ifdef FILESYS
@@ -101,6 +102,9 @@ main (void)
   palloc_init (user_page_limit);
   malloc_init ();
   paging_init ();
+#ifdef VM
+  frame_init ();
+#endif
 
   /* Segmentation. */
 #ifdef USERPROG

src/threads/synch.c

@@ -119,14 +119,14 @@ sema_up (struct semaphore *sema)
 
   old_level = intr_disable ();
   if (!list_empty (&sema->waiters))
-  {
-    /* Enforces wake-up of the highest priority thread waiting for the
-       semaphore. */
-    struct list_elem *e = list_max (&sema->waiters, priority_less, NULL);
-    list_remove (e);
-    thread_unblock (list_entry (e, struct thread, elem));
-    thread_unblocked = true;
-  }
+    {
+      /* Enforces wake-up of the highest priority thread waiting for the
+         semaphore. */
+      struct list_elem *e = list_max (&sema->waiters, priority_less, NULL);
+      list_remove (e);
+      thread_unblock (list_entry (e, struct thread, elem));
+      thread_unblocked = true;
+    }
   sema->value++;
   intr_set_level (old_level);
 
@@ -134,12 +134,12 @@ sema_up (struct semaphore *sema)
      priority that the current running thread, including the case when called
      within an interrupt handler. */
   if (thread_unblocked)
-  {
-    if (intr_context ())
-      intr_yield_on_return ();
-    else
-      thread_yield ();
-  }
+    {
+      if (intr_context ())
+        intr_yield_on_return ();
+      else
+        thread_yield ();
+    }
 }
 
 static void sema_test_helper (void *sema_);

src/threads/thread.c

@@ -71,7 +71,7 @@ static void kernel_thread (thread_func *, void *aux);
 static void idle (void *aux UNUSED);
 static struct thread *running_thread (void);
 static struct thread *next_thread_to_run (void);
-static void init_process_result (struct thread *t);
+static bool init_process_result (struct thread *t);
 static void init_thread (struct thread *, const char *name, int nice,
                          int priority, fp32_t recent_cpu);
 static bool is_thread (struct thread *) UNUSED;
@@ -84,6 +84,10 @@ void thread_schedule_tail (struct thread *prev);
 static tid_t allocate_tid (void);
 static bool donor_priority_less (const struct list_elem *a_,
                                  const struct list_elem *b_, void *aux UNUSED);
+static unsigned process_result_hash (const struct hash_elem *e,
+                                     void *aux UNUSED);
+static bool process_result_less (const struct hash_elem *a,
+                                 const struct hash_elem *b, void *aux UNUSED);
 
 /* Initializes the threading system by transforming the code
    that's currently running into a thread.  This can't work in
@@ -122,6 +126,13 @@ thread_init (void)
 void
 thread_start (void) 
 {
+  /* Malloc has been initalised, we can allocate the child results table
+     for the main thread. */
+  struct thread *t = thread_current ();
+  if (!hash_init (&t->child_results, process_result_hash, process_result_less,
+                  t))
+    PANIC ("Failed to initialise child results table for main thread.");
+
   /* Create the idle thread. */
   struct semaphore idle_started;
   sema_init (&idle_started, 0);
@@ -241,11 +252,25 @@ thread_create (const char *name, int priority,
   struct thread *parent_thread = thread_current ();
   init_thread (t, name, parent_thread->nice, priority, parent_thread->recent_cpu);
   tid = t->tid = allocate_tid ();
-  init_process_result (t);
+  if (!init_process_result (t))
+    {
+      palloc_free_page (t);
+      return TID_ERROR;
+    }
 
-  #ifdef USERPROG
-    hash_init (&t->open_files, fd_hash, fd_less, NULL);
-  #endif
+#ifdef USERPROG
+  /* Initialize the thread's file descriptor table. */
+  t->fd_counter = MINIMUM_USER_FD;
+
+  if (!hash_init (&t->open_files, fd_hash, fd_less, NULL)
+      || !hash_init (&t->child_results, process_result_hash,
+                     process_result_less, t))
+    {
+      palloc_free_page (t);
+      free (t->result);
+      return TID_ERROR;
+    }
+#endif
 
   /* Prepare thread for first run by initializing its stack.
      Do this atomically so intermediate values for the 'stack' 
@@ -269,9 +294,7 @@ thread_create (const char *name, int priority,
 
   intr_set_level (old_level);
 
-  /* No need to synchronise child_results since it is only ever accessed by one
-     thread. By the nature of increasing TIDs, this list is ordered. */
-  list_push_back (&parent_thread->child_results, &t->result->elem);
+  hash_insert (&parent_thread->child_results, &t->result->elem);
 
   /* Add to run queue. */
   thread_unblock (t);
@@ -649,15 +672,18 @@ is_thread (struct thread *t)
 }
 
 /* Allocate and initialise a process result for given thread. */
-static void
+static bool
 init_process_result (struct thread *t)
 {
   struct process_result *result = malloc (sizeof (struct process_result));
+  if (result == NULL)
+    return false;
   result->tid = t->tid;
-  result->exit_status = t->exit_status;
+  result->exit_status = -1;
   lock_init (&result->lock);
   sema_init (&result->sema, 0);
   t->result = result;
+  return true;
 }
 
 /* Does basic initialization of T as a blocked thread named
@@ -688,9 +714,6 @@ init_thread (struct thread *t, const char *name, int nice, int priority,
   t->recent_cpu = recent_cpu;
   t->priority = t->base_priority;
 
-  t->exit_status = -1;
-  list_init (&t->child_results);
-
   old_level = intr_disable ();
   list_push_back (&all_list, &t->allelem);
   intr_set_level (old_level);
@@ -821,6 +844,29 @@ allocate_tid (void)
   return tid;
 }
 
+/* Hashing function needed for child_results table.
+   Returns hash of process_result's TID. */
+static unsigned
+process_result_hash (const struct hash_elem *e, void *aux UNUSED)
+{
+  const struct process_result *result
+      = hash_entry (e, struct process_result, elem);
+  return hash_int (result->tid);
+}
+
+/* Comparator function needed for child_results table.
+   Returns less than comparison on process_results' TIDs. */
+static bool
+process_result_less (const struct hash_elem *a_, const struct hash_elem *b_,
+                     void *aux UNUSED)
+{
+  const struct process_result *a
+      = hash_entry (a_, struct process_result, elem);
+  const struct process_result *b
+      = hash_entry (b_, struct process_result, elem);
+  return a->tid < b->tid;
+}
+
 /* Offset of `stack' member within `struct thread'.
    Used by switch.S, which can't figure it out on its own. */
 uint32_t thread_stack_ofs = offsetof (struct thread, stack);

src/threads/thread.h

@@ -32,6 +32,9 @@ typedef int tid_t;
 #define NICE_DEFAULT 0 /* Default niceness. */
 #define NICE_MAX 20    /* Highest niceness. */
 
+/* File Descriptors. */
+#define MINIMUM_USER_FD 2 /* Minimum file descriptor for user programs. */
+
 /* A process result, synchronised between parent and child. */
 struct process_result
 {
@@ -41,7 +44,7 @@ struct process_result
   struct lock lock;      /* Lock the exit_status and sema. */
   struct semaphore sema; /* Semaphore to signal the parent that the exit_status
                             has been set. */
-  struct list_elem elem; /* List element for the parent's children list. */
+  struct hash_elem elem; /* Hash element for the parent's children map. */
 };
 
 /* A kernel thread or user process.
@@ -125,21 +128,23 @@ struct thread
 
     /* Process wait properties. */
     struct process_result *result;      /* Result of the process. */
-    struct list child_results;          /* List of children's of this thread
-                                           process results. */
+    struct hash child_results;          /* Map of children's of this thread
+                                           TID to process result. */
     struct file *exec_file;             /* Thread's currently running file */
 
     /* Shared between thread.c and synch.c. */
     struct list_elem elem;              /* List element. */
 
-    int exit_status;                    /* Exit Status: 0 = successful exit. */
-
 #ifdef USERPROG
     /* Owned by userprog/process.c. */
     uint32_t *pagedir;                  /* Page directory. */
-    struct hash open_files;             /* Hash Table of FD -> Struct File */
+    unsigned int fd_counter;            /* File descriptor counter for thread's
+                                           open files. */
+    struct hash open_files;             /* Hash Table of FD -> Struct File. */
 #endif
 
+    void *curr_esp;
+
     /* Owned by thread.c. */
     unsigned magic;                     /* Detects stack overflow. */
   };

src/userprog/exception.c

@@ -4,6 +4,7 @@
 #include "userprog/gdt.h"
 #include "threads/interrupt.h"
 #include "threads/thread.h"
+#include "vm/stackgrowth.h"
 
 /* Number of page faults processed. */
 static long long page_fault_cnt;
@@ -145,6 +146,19 @@ page_fault (struct intr_frame *f)
   write = (f->error_code & PF_W) != 0;
   user = (f->error_code & PF_U) != 0;
 
+#ifdef VM
+  if (user && not_present)
+    {
+      if (handle_stack_fault (fault_addr, f->esp)) return;
+    }
+  else
+    {
+      f->eip = (void *)f->eax;
+      f->eax = 0xffffffff;
+      return;
+    }
+#endif
+
   /* To implement virtual memory, delete the rest of the function
      body, and replace it with code that brings in the page to
      which fault_addr refers. */

src/userprog/pagedir.c

@@ -53,7 +53,7 @@ pagedir_destroy (uint32_t *pd)
    on CREATE.  If CREATE is true, then a new page table is
    created and a pointer into it is returned.  Otherwise, a null
    pointer is returned. */
-static uint32_t *
+uint32_t *
 lookup_page (uint32_t *pd, const void *vaddr, bool create)
 {
   uint32_t *pt, *pde;

src/userprog/pagedir.h

@@ -6,6 +6,7 @@
 
 uint32_t *pagedir_create (void);
 void pagedir_destroy (uint32_t *pd);
+uint32_t *lookup_page (uint32_t *pd, const void *vaddr, bool create);
 bool pagedir_set_page (uint32_t *pd, void *upage, void *kpage, bool rw);
 void *pagedir_get_page (uint32_t *pd, const void *upage);
 void pagedir_clear_page (uint32_t *pd, void *upage);

src/userprog/process.c

@@ -1,5 +1,6 @@
 #include "userprog/process.h"
 #include <debug.h>
+#include <hash.h>
 #include <inttypes.h>
 #include <list.h>
 #include <round.h>
@@ -23,11 +24,18 @@
 #include "threads/vaddr.h"
 #include "threads/synch.h"
 #include "devices/timer.h"
+#ifdef VM
+#include "vm/frame.h"
+#endif
 
 /* Defines the native number of bytes processed by the processor
    (for the purposes of alignment). */
 #define WORD_SIZE 4
 
+/* Defines non-negative integer division wherein the result is always rounded
+   up. */
+#define DIV_CEIL(x, y) ((x + (y - 1)) / y)
+
 /* Keeps track of the position of pointers to user program arguments
    within a linked list. */
 struct arg_elem
@@ -40,8 +48,6 @@ struct arg_elem
    that executes process_start for the purpose of starting a user process. */
 struct process_start_data
   {
-    char *cmd; /* Pointer to a copy of the command used to execute the process.
-                  Allocated a page that must be freed by process_start. */
     char *cmd_saveptr; /* Value pointed to by 'saveptr' argument used by
                           successive calls to strtok_r to split 'cmd' into
                           tokens while maintaining state. */
@@ -49,10 +55,11 @@ struct process_start_data
                                       be started. */
     bool success; /* Indicates whether the process was successfully loaded. */
     struct semaphore loaded; /* Semaphore used to signal that the process has
-                                been loaded. */
+                                finished attempting to load. */
   };
 
 static thread_func start_process NO_RETURN;
+static void destruct_process_result (struct hash_elem *e, void *aux UNUSED);
 static bool load (const char *cmdline, void (**eip) (void), void **esp);
 
 /* Starts a new thread running a user program executed via
@@ -64,14 +71,7 @@ process_execute (const char *cmd)
 {
   char *cmd_copy;
   tid_t tid;
-  
-  struct process_start_data *data = malloc (sizeof (struct process_start_data));
-  if (data == NULL)
-    {
-      return TID_ERROR;
-    }
-  sema_init (&data->loaded, 0);
-  data->success = false;
+  struct process_start_data data;
 
   /* Make a copy of command.
      Otherwise there's a race between the caller and load(). */
@@ -85,38 +85,41 @@ process_execute (const char *cmd)
 
   /* Retrieve first argument of command, which is the file name
      of the process. */
-  char *file_name = strtok_r (cmd_copy, " ", &data->cmd_saveptr);
+  char *file_name = strtok_r (cmd_copy, " ", &data.cmd_saveptr);
 
-  /* NOTE: Currently, the file being executed is closed in load () and then
-          reopened here. Because load is an exported public function, this
-          might be necessary. */
+  /* Validates that the current file to be executed can be opened/exists. */
   lock_acquire (&filesys_lock);
-  /* Validates that the current file to be executed is a valid file */
-  bool valid_file = filesys_open (file_name) != NULL;
+  struct file *file = filesys_open (file_name);
   lock_release (&filesys_lock);
-  if (!valid_file)
+  if (file == NULL)
     return TID_ERROR;
 
   /* Create a new thread to execute the command, by initializing
      it running the function 'start_process' with the appropriate
      arguments. For details of arguments, see 'start_process'. */
-  data->cmd = cmd_copy;
-  strlcpy (data->file_name, file_name, FNAME_MAX_LEN + 1);
+  strlcpy (data.file_name, file_name, FNAME_MAX_LEN + 1);
+  sema_init (&data.loaded, 0);
+  data.success = false;
 
-  tid = thread_create (file_name, PRI_DEFAULT, start_process, data);
-  if (tid == TID_ERROR)
-    palloc_free_page (cmd_copy);
-  else
+  tid = thread_create (file_name, PRI_DEFAULT, start_process, &data);
+
+  /* Wait until process file has finished attempting to load via the child
+     thread before reporting success of starting execution. */
+  if (tid != TID_ERROR)
     {
-      sema_down (&data->loaded);
-      if (!data->success)
+      sema_down (&data.loaded);
+      if (!data.success)
         tid = TID_ERROR;
     }
-  free (data);
+
+  palloc_free_page (cmd_copy);
   return tid;
 }
 
+static void *get_usr_kpage (enum palloc_flags flags, void *upage);
+static void free_usr_kpage (void *kpage);
 static bool install_page (void *upage, void *kpage, bool writable);
+
 static bool process_init_stack (char *cmd_saveptr, void **esp, char *file_name);
 static void *push_to_stack (void **esp, void *data, size_t data_size);
 #define push_var_to_stack(esp, var) (push_to_stack (esp, &var, sizeof (var)))
@@ -124,14 +127,15 @@ static void *push_to_stack (void **esp, void *data, size_t data_size);
 /* Make the current thread execute 'cmd', passing in a copy of the
    command string used for processing, the saveptr used by strtok_r
    (in order to further tokenize the same command and retrieve its
-   arguments), as well as the name of the file being executed. This
-   involves loading the specified file and starting it running. */
+   arguments), the name of the file being executed, and a semaphore that
+   calls sema_up to indicate that the 'success' variable passed to it
+   has been updated to indicate whether the process file loading succeeded. 
+   This involves loading the specified file and calling its main () function
+   with the specified command arguments. */
 static void
 start_process (void *proc_start_data)
 {
   struct intr_frame if_;
-  bool success;
-
   struct process_start_data *data = proc_start_data;
 
   /* Initialize interrupt frame and load executable. */
@@ -139,42 +143,47 @@ start_process (void *proc_start_data)
   if_.gs = if_.fs = if_.es = if_.ds = if_.ss = SEL_UDSEG;
   if_.cs = SEL_UCSEG;
   if_.eflags = FLAG_IF | FLAG_MBS;
-  
+
+  /* Acquire the file system lock to prevent race conditions. */
   lock_acquire (&filesys_lock);
-  
-  /* Prevent writing to the file being executed. */
+
   struct file *exec_file = filesys_open (data->file_name);
   if (exec_file == NULL)
     {
+      /* If the executable file cannot be opened, free resources and quit. */
       lock_release (&filesys_lock);
-      goto fail;
+      sema_up (&data->loaded);
+      thread_exit ();
     }
-  thread_current ()->exec_file = exec_file;
+
+  /* Deny write to the executable file to prevent writing to it and release the
+     file system lock. */
   file_deny_write (exec_file);
   lock_release (&filesys_lock);
 
-  success = load (data->file_name, &if_.eip, &if_.esp);
+  thread_current ()->exec_file = exec_file;
 
-  /* If load failed, quit. */
-  if (!success) 
+  /* Load the ELF executable file, and store the success of the operation in
+     the 'success' variable in data. */
+  data->success = load (data->file_name, &if_.eip, &if_.esp);
+
+  /* If load was sucessful, initialize user process stack and free page used
+ to store the command that executed the process. */
+  if (data->success)
     {
-      palloc_free_page (data->cmd);
-      goto fail;
+      data->success =
+        process_init_stack (data->cmd_saveptr, &if_.esp, data->file_name);
     }
 
-  /* Initialize user process stack and free page used to store the
-     command that executed the process. */
-  success = process_init_stack (data->cmd_saveptr, &if_.esp, data->file_name);
-  palloc_free_page (data->cmd);
-  
-  /* If stack initialization failed, free resources and quit. */
-  if (!success)
-    {
-      goto fail;
-    }
-
-  data->success = true;
+  /* Signal that the process has finished attempting to load. */
+  bool success = data->success;
   sema_up (&data->loaded);
+  
+  /* If the load was unsuccessful or if it was but the stack initialization
+     failed, exit the thread. */
+  if (!success)
+      thread_exit ();
+
   /* Start the user process by simulating a return from an
      interrupt, implemented by intr_exit (in
      threads/intr-stubs.S).  Because intr_exit takes all of its
@@ -183,12 +192,6 @@ start_process (void *proc_start_data)
      and jump to it. */
   asm volatile ("movl %0, %%esp; jmp intr_exit" : : "g" (&if_) : "memory");
   NOT_REACHED ();
-
-  /* If starting the process failed, exit. */
-fail:
-  data->success = false;
-  sema_up (&data->loaded);
-  thread_exit ();
 }
 
 /* Helper function that initializes the stack of a newly created 
@@ -196,6 +199,10 @@ fail:
 static bool
 process_init_stack (char *cmd_saveptr, void **esp, char *file_name)
   {
+    ASSERT (cmd_saveptr != NULL);
+    ASSERT (esp != NULL);
+    ASSERT (file_name != NULL);
+
     /* Load command line argument *data* to user process stack.
        This can't cause overflow due to enforcing that the size of
        command line input must fit in a page. Also keep track
@@ -207,8 +214,12 @@ process_init_stack (char *cmd_saveptr, void **esp, char *file_name)
     int arg_count = 0;
     while (arg != NULL)
       {
+        /* filename has already been validated to be a safe-to-access string,
+           so we can safely use strlen here. Filename has already been
+           split from the command line arguments. */
         push_to_stack (esp, arg, (strlen (arg) + 1) * sizeof (char));
-        
+
+        /* Try to allocate memory for the argument pointer. */
         struct arg_elem *arg_elem = malloc (sizeof (struct arg_elem));
         if (arg_elem == NULL)
           {
@@ -217,9 +228,11 @@ process_init_stack (char *cmd_saveptr, void **esp, char *file_name)
             return false;
           }
 
+        /* Store the argument pointer in the linked list. */
         arg_elem->arg = *esp;
         list_push_front (&arg_list, &arg_elem->elem);
 
+        /* Increment the argument count and get the next argument. */
         arg_count++;
         arg = strtok_r (NULL, " ", &cmd_saveptr);
       }
@@ -235,13 +248,23 @@ process_init_stack (char *cmd_saveptr, void **esp, char *file_name)
                             + return_addr_size;
 
     /* If pushing the rest of the data required for the stack would cause
-       overflow, allocate an extra page that is contiguous within the
-       virtual address space (below the current address range). */ 
-    if (PHYS_BASE - *esp + remaining_size > PGSIZE)
+       overflow, allocate as many extra pages as needed to the user process
+       contiguously in the virtual address space below the initial page. */
+    int overflow_bytes = (PHYS_BASE - *esp) + remaining_size - PGSIZE;
+    if (overflow_bytes > 0)
       {
-        uint8_t *kpage = palloc_get_page (PAL_USER | PAL_ZERO);
-        if (!install_page (((uint8_t *) PHYS_BASE) - PGSIZE * 2, kpage, true))
-          return false;
+        /* Calculate the number of pages needed to allocate. */
+        int pages_needed = DIV_CEIL (overflow_bytes, PGSIZE);
+
+        /* Allocate the pages and map them to the user process. */
+        void *upage;
+        uint8_t *kpage;
+        for (int i = 1; i < pages_needed + 1; i++)
+          {
+            upage = ((uint8_t *) PHYS_BASE) - PGSIZE * (i + 1);
+            kpage = get_usr_kpage (PAL_ZERO, upage);
+            if (!install_page (upage, kpage, true)) return false;
+          }
       }
 
     /* Align stack pointer to word size before pushing argv elements for
@@ -299,39 +322,35 @@ push_to_stack (void **esp, void *data, size_t data_size)
  * This function will be implemented in task 2.
  * For now, it does nothing. */
 int
-process_wait (tid_t child_tid UNUSED) 
+process_wait (tid_t child_tid)
 {
-  struct process_result *child_result = NULL;
-  struct list_elem *e;
-  struct thread *cur = thread_current ();
-  for (e = list_begin (&cur->child_results);
-       e != list_end (&cur->child_results); e = list_next (e))
-    {
-      struct process_result *result
-          = list_entry (e, struct process_result, elem);
-      if (result->tid == child_tid)
-        {
-          child_result = result;
-          break;
-        }
-      /* List is ordered, allowing us to break early. */
-      else if (result->tid > child_tid)
-        break;
-    }
-  if (child_result == NULL)
+  struct thread *t = thread_current ();
+  struct process_result fake_result;
+  fake_result.tid = child_tid;
+  struct hash_elem *e = hash_find (&t->child_results, &fake_result.elem);
+  if (e == NULL)
     return -1;
+
+  struct process_result *child_result
+      = hash_entry (e, struct process_result, elem);
   /* Wait for child to die. */
   sema_down (&child_result->sema);
+
   /* We need lock release in process_exit, so we need to acquire (and possibly
      wait) for it here to ensure we don't free the lock memory before it is
      released in process_exit. */
   lock_acquire (&child_result->lock);
-  /* To prevent waiting for child twice, remove it from the list.
+  /* To prevent waiting for child twice, remove it from the table.
      No need to use lock since this is the only thread with access to
      the struct process_result now. */
-  list_remove (&child_result->elem);
+  hash_delete (&t->child_results, &child_result->elem);
+
+  /* Get the exit status of the child */
   int exit_status = child_result->exit_status;
+
+  /* Release the lock */
   lock_release (&child_result->lock);
+  /* Result no-longer used by parent, nor child. Deallocate it. */
   free (child_result);
   return exit_status;
 }
@@ -343,62 +362,27 @@ process_exit (void)
   struct thread *cur = thread_current ();
   uint32_t *pd;
 
-  printf ("%s: exit(%d)\n", cur->name, cur->exit_status);
-
   /* Clean up all open files */
   hash_destroy (&cur->open_files, fd_cleanup);
 
-  /* Close the executable file. */
+  /* Close the executable file, implicitly allowing it to be written to. */
   if (cur->exec_file != NULL)
     {
+      /* Acquire the file system lock to prevent race conditions. */
       lock_acquire (&filesys_lock);
       file_close (cur->exec_file);
       lock_release (&filesys_lock);
     }
 
-  /* Update process result. */
   if (cur->result != NULL)
     {
-      lock_acquire (&cur->result->lock);
-      cur->result->exit_status = cur->exit_status;
-      /* Parent has died, child has to free the struct process_result * */
-      if (sema_try_down (&cur->result->sema))
-        {
-          lock_release (&cur->result->lock);
-          free (cur->result);
-        }
-      /* Parent is still alive and will be the one to free the
-         struct process_result *, and may be waiting so call sema_up */
-      else
-        {
-          sema_up (&cur->result->sema);
-          lock_release (&cur->result->lock);
-        }
+      printf ("%s: exit(%d)\n", cur->name, cur->result->exit_status);
+      /* Update own process result. */
+      destruct_process_result (&cur->result->elem, cur);
     }
 
   /* Free child process results or signal parent's death. */
-  struct list_elem *e;
-  for (e = list_begin (&cur->child_results);
-       e != list_end (&cur->child_results);)
-    {
-      struct process_result *result
-          = list_entry (e, struct process_result, elem);
-      struct list_elem *next = list_next (e);
-      lock_acquire (&result->lock);
-      /* Child has died (and was not waited for). Free the result. */
-      if (sema_try_down (&result->sema))
-        {
-          lock_release (&result->lock);
-          free (result);
-        }
-      /* Child is still alive, signal via sema that parent has died. */
-      else
-        {
-          sema_up (&result->sema);
-          lock_release (&result->lock);
-        }
-      e = next;
-    }
+  hash_destroy (&cur->child_results, destruct_process_result);
 
   /* Destroy the current process's page directory and switch back
      to the kernel-only page directory. */
@@ -418,6 +402,28 @@ process_exit (void)
     }
 }
 
+/* Destruct a process_result, with multi-thread awareness.
+   If the other thread is running, simply signals death. Otherwise
+   frees the result. */
+static void
+destruct_process_result (struct hash_elem *e, void *aux UNUSED)
+{
+  struct process_result *result = hash_entry (e, struct process_result, elem);
+  lock_acquire (&result->lock);
+  /* Other thread has died (and was not waited for). Free the result. */
+  if (sema_try_down (&result->sema))
+    {
+      lock_release (&result->lock);
+      free (result);
+    }
+  /* Other thread is still alive, signal via sema that parent has died. */
+  else
+    {
+      sema_up (&result->sema);
+      lock_release (&result->lock);
+    }
+}
+
 /* Sets up the CPU for running user code in the current
    thread.
    This function is called on every context switch. */
@@ -705,7 +711,7 @@ load_segment (struct file *file, off_t ofs, uint8_t *upage,
       if (kpage == NULL){
         
         /* Get a new page of memory. */
-        kpage = palloc_get_page (PAL_USER);
+        kpage = get_usr_kpage (0, upage);
         if (kpage == NULL){
           return false;
         }
@@ -713,7 +719,7 @@ load_segment (struct file *file, off_t ofs, uint8_t *upage,
         /* Add the page to the process's address space. */
         if (!install_page (upage, kpage, writable)) 
         {
-          palloc_free_page (kpage);
+          free_usr_kpage (kpage);
           return false; 
         }     
         
@@ -747,19 +753,53 @@ setup_stack (void **esp)
 {
   uint8_t *kpage;
   bool success = false;
-
-  kpage = palloc_get_page (PAL_USER | PAL_ZERO);
+  
+  void *upage = ((uint8_t *) PHYS_BASE) - PGSIZE;
+  
+  kpage = get_usr_kpage (PAL_ZERO, upage);
   if (kpage != NULL) 
     {
-      success = install_page (((uint8_t *) PHYS_BASE) - PGSIZE, kpage, true);
+      success = install_page (upage, kpage, true);
       if (success)
         *esp = PHYS_BASE;
       else
-        palloc_free_page (kpage);
+        free_usr_kpage (kpage);
     }
   return success;
 }
 
+/* Claims a page from the user pool for ownership by the current thread
+   and returns its kernel address, updating the frame table if VM
+   is enabled. Requires the intended virtual address for where the page
+   will be installed. */
+static void *
+get_usr_kpage (enum palloc_flags flags, void *upage)
+{
+  void *page;
+#ifdef VM
+  struct thread *t = thread_current ();
+  if (pagedir_get_page (t->pagedir, upage) != NULL)
+    return NULL;
+  else
+    page = frame_alloc (flags, upage, t);
+#else
+  page = palloc_get_page (flags | PAL_USER);
+#endif
+  return page;
+}
+
+/* Frees a page belonging to a user process given its kernel address,
+   updating the frame table if VM is enabled. */
+static void
+free_usr_kpage (void *kpage)
+{
+#ifdef VM
+  frame_free (kpage);
+#else
+  palloc_free_page (kpage);
+#endif
+}
+
 /* Adds a mapping from user virtual address UPAGE to kernel
    virtual address KPAGE to the page table.
    If WRITABLE is true, the user process may modify the page;

src/userprog/syscall.c

@@ -11,13 +11,12 @@
 #include "userprog/process.h"
 #include "userprog/pagedir.h"
 #include <stdio.h>
+#include <stdbool.h>
 #include <syscall-nr.h>
 
 #define MAX_SYSCALL_ARGS 3
 #define EXIT_FAILURE -1
 
-static unsigned fd_counter = MIN_USER_FD;
-
 struct open_file
   {
     int fd;                     /* File Descriptor / Identifier */
@@ -48,8 +47,11 @@ static unsigned syscall_tell (int fd);
 static void syscall_close (int fd);
 
 static struct open_file *fd_get_file (int fd);
-static void validate_user_pointer (const void *start, size_t size);
-static void validate_user_string (const char *str);
+static void validate_user_pointer (const void *ptr, size_t size,
+                                   bool check_write);
+static void validate_user_string (const char *str, bool check_write);
+static int get_user (const uint8_t *);
+static bool put_user (uint8_t *, uint8_t);
 
 /* A struct defining a syscall_function pointer along with its arity. */
 struct syscall_arguments
@@ -98,8 +100,9 @@ static void
 syscall_handler (struct intr_frame *f)
 {
   /* First, read the system call number from the stack. */
-  validate_user_pointer (f->esp, sizeof (uintptr_t));
-  uintptr_t syscall_number = *(int *) f->esp;
+  validate_user_pointer (f->esp, sizeof (uintptr_t), false);
+  uintptr_t syscall_number = *(int *)f->esp;
+  thread_current ()->curr_esp = f->esp;
 
   /* Ensures the number corresponds to a system call that can be handled. */
   if (syscall_number >= LOOKUP_SIZE)
@@ -109,11 +112,10 @@ syscall_handler (struct intr_frame *f)
 
   /* Next, read and copy the arguments from the stack pointer. */
   validate_user_pointer (f->esp + sizeof (uintptr_t),
-                         syscall.arity * sizeof (uintptr_t));
-
-  uintptr_t args[MAX_SYSCALL_ARGS] = {0};
+                         syscall.arity * sizeof (uintptr_t), false);
+  uintptr_t args[MAX_SYSCALL_ARGS] = { 0 };
   for (int i = 0; i < syscall.arity && i < MAX_SYSCALL_ARGS; i++)
-    args[i] = *(uintptr_t *) (f->esp + sizeof (uintptr_t) * (i + 1));
+    args[i] = *(uintptr_t *)(f->esp + sizeof (uintptr_t) * (i + 1));
 
   /* Call the function that handles this system call with the arguments. When
      there is a return value it is stored in f->eax. */
@@ -133,7 +135,7 @@ syscall_exit (int status)
 {
   /* Sets exit_status of the thread to status. thread_exit () will call
      process_exit () if user programs are allowed. */
-  thread_current ()->exit_status = status;
+  thread_current ()->result->exit_status = status;
   thread_exit ();
 }
 
@@ -142,7 +144,7 @@ syscall_exit (int status)
 static pid_t
 syscall_exec (const char *cmd_line)
 {
-  validate_user_string (cmd_line);
+  validate_user_string (cmd_line, false);
 
   return process_execute (cmd_line); /* Returns the PID of the new process */
 }
@@ -161,12 +163,14 @@ syscall_wait (pid_t pid)
 static bool
 syscall_create (const char *file, unsigned initial_size)
 {
-  validate_user_string (file);
+  validate_user_string (file, false);
 
+  /* Acquire the file system lock to prevent race conditions. */
   lock_acquire (&filesys_lock);
   bool status = filesys_create (file, initial_size);
   lock_release (&filesys_lock);
 
+  /* Return the status of the file creation. */
   return status;
 }
 
@@ -176,12 +180,14 @@ syscall_create (const char *file, unsigned initial_size)
 static bool
 syscall_remove (const char *file)
 {
-  validate_user_string (file);
+  validate_user_string (file, false);
 
+  /* Acquire the file system lock to prevent race conditions. */
   lock_acquire (&filesys_lock);
   bool status = filesys_remove (file);
   lock_release (&filesys_lock);
 
+  /* Return the status of the file removal. */
   return status;
 }
 
@@ -192,11 +198,14 @@ syscall_remove (const char *file)
 static int
 syscall_open (const char *file)
 {
-  validate_user_string (file);
+  validate_user_string (file, false);
 
+  /* Acquire the file system lock to prevent race conditions. */
   lock_acquire (&filesys_lock);
   struct file *ptr = filesys_open (file);
   lock_release (&filesys_lock);
+
+  /* If the file could not be opened, return failure. */
   if (ptr == NULL)
     return EXIT_FAILURE;
 
@@ -206,12 +215,14 @@ syscall_open (const char *file)
     = (struct open_file*) malloc (sizeof (struct open_file));
   if (file_info == NULL)
     {
+      /* If we could not allocate memory for the file_info struct, close the
+         file and return failure. */
       file_close (ptr);
       return EXIT_FAILURE;
     }
 
   /* Populate the above struct, with a unique FD and the current open file */
-  file_info->fd = fd_counter++;
+  file_info->fd = thread_current ()->fd_counter++;
   file_info->file = ptr;
 
   /* Add the new FD->file mapping to the hashtable for the current thread */
@@ -227,14 +238,17 @@ syscall_open (const char *file)
 static int
 syscall_filesize (int fd)
 {
+  /* Try to get the file from the FD. If it does not exist, return failure. */
   struct open_file *file_info = fd_get_file (fd);
   if (file_info == NULL)
       return EXIT_FAILURE;
 
+  /* Acquire the file system lock to prevent any race conditions. */
   lock_acquire (&filesys_lock);
   int bytes = file_length (file_info->file);
   lock_release (&filesys_lock);
 
+  /* Return the number of bytes in the file. */
   return bytes;
 }
 
@@ -247,30 +261,36 @@ syscall_read (int fd, void *buffer, unsigned size)
 {
   /* Only console (fd = 0) or other files, not including STDOUT, (fd > 1) are
      allowed. */
-  if (fd < 0 || fd == STDOUT_FILENO)
+  if (fd < STDIN_FILENO || fd == STDOUT_FILENO)
     return EXIT_FAILURE;
 
-  validate_user_pointer (buffer, size);
+  validate_user_pointer (buffer, size, true);
 
   if (fd == STDIN_FILENO)
     {
       /* Reading from the console. */
       char *write_buffer = buffer;
-      for (int i = 0; i < size; i++)
+      for (unsigned i = 0; i < size; i++)
         write_buffer[i] = input_getc ();
 
+      /* In case of console, read is always (eventually) successful. So return
+         the size for the number of bytes read. */
       return size;
     }
   else
     {
       /* Reading from a file. */
+      /* Find the file from the FD. If it does not exist, return failure. */
       struct open_file *file_info = fd_get_file (fd);
       if (file_info == NULL)
         return EXIT_FAILURE;
 
+      /* Acquire the file system lock to prevent race-conditions. */
       lock_acquire (&filesys_lock);
       int bytes_written = file_read (file_info->file, buffer, size);
       lock_release (&filesys_lock);
+
+      /* Return the number of bytes read. */
       return bytes_written;
     }
 }
@@ -287,25 +307,31 @@ syscall_write (int fd, const void *buffer, unsigned size)
   if (fd <= 0)
     return 0;
 
-  validate_user_pointer (buffer, size);
+  validate_user_pointer (buffer, size, false);
 
   if (fd == STDOUT_FILENO)
     {
       /* Writing to the console. */
       putbuf (buffer, size);
+
+      /* In case of console, write is always successful. So return the size for
+         the number of bytes written. */
       return size;
     }
   else
     {
       /* Writing to a file. */
+      /* Find the file from the FD. If it does not exist, return failure. */
       struct open_file *file_info = fd_get_file (fd);
       if (file_info == NULL)
         return 0;
 
+      /* Acquire the file system lock to prevent race conditions. */
       lock_acquire (&filesys_lock);
       int bytes = file_write (file_info->file, buffer, size);
       lock_release (&filesys_lock);
 
+      /* Return the number of bytes written. */
       return bytes;
     }
 }
@@ -317,13 +343,10 @@ syscall_write (int fd, const void *buffer, unsigned size)
 static void
 syscall_seek (int fd, unsigned position)
 {
+  /* Find the file from the FD. If it does not exist, do nothing. */
   struct open_file *file_info = fd_get_file (fd);
   if (file_info != NULL)
-  {
-    lock_acquire (&filesys_lock);
     file_seek (file_info->file, position);
-    lock_release (&filesys_lock);
-  }
 }
 
 /* Handles the syscall for returning the next byte in a file referenced by
@@ -332,14 +355,14 @@ syscall_seek (int fd, unsigned position)
 static unsigned
 syscall_tell (int fd)
 {
+  /* Find the file from the FD. If it does not exist, return 0. */
   struct open_file *file_info = fd_get_file (fd);
   if (file_info == NULL)
     return 0;
 
-  lock_acquire (&filesys_lock);
   unsigned pos = file_tell (file_info->file);
-  lock_release (&filesys_lock);
 
+  /* Return the current position in the file. */
   return pos;
 }
 
@@ -349,14 +372,21 @@ syscall_tell (int fd)
 static void
 syscall_close (int fd)
 {
+  /* Find the file from the FD. If it does not exist, do nothing. */
   struct open_file *file_info = fd_get_file (fd);
   if (file_info != NULL)
     {
+      /* File exists */
+      /* First, remove the file from the hash table of open files. */
       hash_delete (&thread_current ()->open_files, &file_info->elem);
 
+      /* Then, close the file, acquiring the file system lock to prevent race
+         conditions. */
       lock_acquire (&filesys_lock);
       file_close (file_info->file);
       lock_release (&filesys_lock);
+
+      /* Free the memory allocated for the file_info struct. */
       free (file_info);
     }
 }
@@ -366,7 +396,12 @@ syscall_close (int fd)
 unsigned
 fd_hash (const struct hash_elem *element, void *aux UNUSED)
 {
-  return hash_int (hash_entry (element, struct open_file, elem)->fd);
+  /* We use the FD as the hash value. This is because the FD is incremented
+     sequentially and is therefore unique for each file. It positively affects
+     the performance of the hash table: 1. It is unique so no need to call
+     expensive hash functions. 2. It being sequential means that the hash table
+     is more likely to be weight balanced. */
+  return hash_entry (element, struct open_file, elem)->fd;
 }
 
 /* Comparator function for the open_file table. Compares two entries based on
@@ -414,57 +449,91 @@ fd_get_file (int fd)
   return hash_entry (e, struct open_file, elem);
 }
 
-/* Validates if a block of memory starting at START and of size SIZE bytes is
-   fully contained within user virtual memory. Kills the thread (by exiting with
-   failure) if the memory is invalid. Otherwise, returns (nothing) normally.
-   If the size is 0, the function does no checks and returns the given ptr. */
+/* Validates if a block of memory starting at PTR and of size SIZE bytes is
+   fully contained within valid user virtual memory. thread_exit () if the
+   memory is invalid.
+   If the size is 0, the function does no checks and returns PTR. */
 static void
-validate_user_pointer (const void *start, size_t size)
+validate_user_pointer (const void *ptr, size_t size, bool check_write)
 {
   if (size == 0)
     return;
-
-  const void *end = start + size - 1;
-
-  if (start == NULL || !is_user_vaddr (start) || !is_user_vaddr (end))
+  /* ptr < ptr + size - 1, so sufficient to check that (ptr + size -1) is a
+     valid user virtual memory address. */
+  void *last = ptr + size - 1;
+  if (!is_user_vaddr (last))
     syscall_exit (EXIT_FAILURE);
-
-  /* We now need to check if the entire memory block is mapped to physical
-     memory by the page table. */
-  for (const void *ptr = start; ptr <= end; ptr += PGSIZE)
-    if (pagedir_get_page (thread_current ()->pagedir, ptr) == NULL)
-      syscall_exit (EXIT_FAILURE);
+  ptr = pg_round_down (ptr);
+  while (ptr <= last)
+    {
+      int result;
+      /* Check read access to pointer. */
+      if ((result = get_user (ptr)) == -1)
+        syscall_exit (EXIT_FAILURE);
+      /* Check write access to pointer (if required). */
+      if (check_write && !put_user (ptr, result))
+        syscall_exit (EXIT_FAILURE);
+      ptr += PGSIZE;
+    }
 }
 
-/* Validates if a string is fully contained within user virtual memory. Kills
-   the thread (by exiting with failure) if the memory is invalid. Otherwise,
-   returns (nothing) normally. */
+/* Validates of a C-string starting at ptr is fully contained within valid
+   user virtual memory. thread_exit () if the memory is invalid. */
 static void
-validate_user_string (const char *str)
+validate_user_string (const char *ptr, bool check_write)
 {
-  if (str == NULL || !is_user_vaddr (str))
-    syscall_exit (EXIT_FAILURE);
+  size_t offset = (uintptr_t) ptr % PGSIZE;
 
-  size_t offset = (uintptr_t) str % PGSIZE;
-
-  /* We move page by page, checking if the page is mapped to physical memory. */
   for (;;)
-  {
-    void *page = pg_round_down (str);
+    {
+      void *page = pg_round_down (ptr);
 
-    if (!is_user_vaddr(page) ||
-        pagedir_get_page (thread_current ()->pagedir, page) == NULL)
-      syscall_exit (EXIT_FAILURE);
+      if (!is_user_vaddr (page))
+        syscall_exit (EXIT_FAILURE);
+      if (!is_user_vaddr (ptr))
+        syscall_exit (EXIT_FAILURE);
+      int result;
+      if ((result = get_user ((const uint8_t *)ptr)) == -1)
+        syscall_exit (EXIT_FAILURE);
+      if (check_write && !put_user ((uint8_t *)ptr, result))
+        syscall_exit (EXIT_FAILURE);
 
-    while (offset < PGSIZE)
+      while (offset < PGSIZE)
       {
-        if (*str == '\0')
+        if (*ptr == '\0')
           return; /* We reached the end of the string without issues. */
 
-        str++;
+        ptr++;
         offset++;
       }
 
-    offset = 0; /* Next page will start at the beginning. */
-  }
+      offset = 0;
+
+    }
 }
+
+/* PROVIDED BY SPEC.
+   Reads a byte at user virtual address UADDR.
+   UADDR must be below PHYS_BASE.
+   Returns the byte value if successful, -1 if a segfault occurred. */
+static int
+get_user (const uint8_t *uaddr)
+{
+  int result;
+  asm ("movl $1f, %0; movzbl %1, %0; 1:" : "=&a"(result) : "m"(*uaddr));
+  return result;
+}
+
+/* PROVIDED BY SPEC.
+   Writes BYTE to user address UDST.
+   UDST must be below PHYS_BASE.
+   Returns true if successful, false if a segfault occurred. */
+static bool
+put_user (uint8_t *udst, uint8_t byte)
+{
+  int error_code;
+  asm ("movl $1f, %0; movb %b2, %1; 1:"
+       : "=&a"(error_code), "=m"(*udst)
+       : "q"(byte));
+  return error_code != -1;
+}

src/userprog/syscall.h

@@ -4,8 +4,6 @@
 #include <hash.h>
 #include "threads/synch.h"
 
-#define MIN_USER_FD 2
-
 typedef int pid_t;
 
 struct lock filesys_lock;

src/vm/frame.c

@@ -0,0 +1,256 @@
+#include <debug.h>
+#include <hash.h>
+#include <list.h>
+#include <string.h>
+
+#include "frame.h"
+#include "page.h"
+#include "threads/malloc.h"
+#include "threads/vaddr.h"
+#include "userprog/pagedir.h"
+#include "threads/synch.h"
+#include "devices/swap.h"
+
+/* Hash table that maps every active frame's kernel virtual address
+   to its corresponding 'frame_metadata'.*/
+struct hash frame_table;
+
+/* Linked list used to represent the circular queue in the 'clock'
+   algorithm for page eviction. Iterating from the element that is
+   currently pointed at by 'next_victim' yields an ordering of the entries
+   from oldest to newest (in terms of when they were added or checked
+   for having been referenced by a process). */
+struct list lru_list;
+
+/* The next element in lru_list to be considered for eviction (oldest added
+   or referenced page in the circular queue). If this page has has an
+   'accessed' bit of 0 when considering eviction, then it will be the next
+   victim. Otherwise, the next element in the queue is similarly considered. */
+struct list_elem *next_victim = NULL;
+
+/* Synchronisation variables. */
+/* Protects access to 'lru_list'. */
+struct lock lru_lock;
+
+struct frame_metadata
+  {
+     void *frame;  /* The kernel virtual address holding the frame. */
+     void *upage; /* The user virtual address pointing to the frame. */
+     struct thread *owner; /* Pointer to the thread that owns the frame. */
+     struct hash_elem hash_elem;  /* Tracks the position of the frame metadata
+                                     within 'frame_table', whose key is the 
+                                     kernel virtual address of the frame. */
+     struct list_elem list_elem;  /* Tracks the position of the frame metadata
+                                     in either the 'active' or 'inactive' list,
+                                     so a victim can be chosen for eviction. */
+  };
+
+hash_hash_func frame_metadata_hash;
+hash_less_func frame_metadata_less;
+
+static struct list_elem *lru_next (struct list_elem *e);
+static struct list_elem *lru_prev (struct list_elem *e);
+static struct frame_metadata *get_victim (void);
+
+/* Initialize the frame system by initializing the frame (hash) table with
+   the frame_metadata hashing and comparison functions, as well as initializing
+   'lru_list' and its associated synchronisation primitives. */
+void
+frame_init (void)
+{
+  hash_init (&frame_table, frame_metadata_hash, frame_metadata_less, NULL);
+
+  list_init (&lru_list);
+  lock_init (&lru_lock);
+}
+
+/* TODO: Consider synchronisation more closely (i.e. just for hash
+         table). */
+/* Attempt to allocate a frame for a user process, either by direct
+   allocation of a user page if there is sufficient RAM, or by
+   evicting a currently active page if memory allocated for user
+   processes is fulled and storing it in swap. If swap is full in
+   the former case, panic the kernel. */
+void *
+frame_alloc (enum palloc_flags flags, void *upage, struct thread *owner)
+{
+  struct frame_metadata *frame_metadata;
+  flags |= PAL_USER;
+  
+  lock_acquire (&lru_lock);
+  void *frame = palloc_get_page (flags);
+
+  /* If a frame couldn't be allocated we must be out of main memory. Thus,
+     obtain a victim page to replace with our page, and swap the victim
+     into disk. */
+  if (frame == NULL)
+    {
+      /* 1. Obtain victim. */
+      if (next_victim == NULL)
+        PANIC ("Couldn't allocate a single page to main memory!\n");
+
+      struct frame_metadata *victim = get_victim ();
+      ASSERT (victim != NULL); /* get_victim () should never return null. */
+
+      /* 2. Swap out victim into disk. */
+      size_t swap_slot = swap_out (victim->frame);
+      page_set_swap (victim->owner, victim->upage, swap_slot);
+
+      /* If zero flag is set, zero out the victim page. */
+      if (flags & PAL_ZERO)
+        memset (victim->frame, 0, PGSIZE);
+
+      /* 3. Indicate that the new frame's metadata will be stored
+            inside the same structure that stored the victim's metadata.
+            As both the new frame and the victim frame share the same kernel
+            virtual address, the hash map need not be updated, and neither
+            the list_elem value as both share the same lru_list position. */
+      frame_metadata = victim;
+    }
+
+  /* If sufficient main memory allows the frame to be directly allocated,
+     we must update the frame table with a new entry, and grow lru_list. */
+  else
+    {
+      /* Must own lru_lock here, as otherwise there is a race condition
+         with next_victim either being NULL or uninitialized. */
+      frame_metadata = malloc (sizeof (struct frame_metadata));
+      frame_metadata->frame = frame;
+
+      /* Newly allocated frames are pushed to the back of the circular queue
+         represented by lru_list. Must explicitly handle the case where the
+         circular queue is empty (when next_victim == NULL). */
+      if (next_victim == NULL)
+        {
+          list_push_back (&lru_list, &frame_metadata->list_elem);
+          next_victim = &frame_metadata->list_elem;
+        }
+      else
+        {
+          struct list_elem *lru_tail = lru_prev (next_victim);
+          list_insert (lru_tail, &frame_metadata->list_elem);
+        }
+
+      hash_insert (&frame_table, &frame_metadata->hash_elem);
+    }
+
+  frame_metadata->upage = upage;
+  frame_metadata->owner = owner;
+  lock_release (&lru_lock);
+
+  return frame_metadata->frame;
+}
+
+/* Attempt to deallocate a frame for a user process by removing it from the
+   frame table as well as lru_list, and freeing the underlying page
+   memory & metadata struct. Panics if the frame isn't active in memory. */
+void
+frame_free (void *frame)
+  {
+    struct frame_metadata key_metadata;
+    key_metadata.frame = frame;
+
+    struct hash_elem *e =
+      hash_delete (&frame_table, &key_metadata.hash_elem);
+    if (e == NULL) PANIC ("Attempted to free a frame at kernel address %p, "
+                          "but this address is not allocated!\n", frame);
+
+    struct frame_metadata *frame_metadata =
+      hash_entry (e, struct frame_metadata, hash_elem);
+    
+    lock_acquire (&lru_lock);
+    list_remove (&frame_metadata->list_elem);
+
+    /* If we're freeing the frame marked as the next victim, update
+       next_victim to either be the next least recently used page, or NULL
+       if no pages are loaded in main memory. */
+    if (&frame_metadata->list_elem == next_victim)
+      {
+        if (list_empty (&lru_list))
+          next_victim = NULL;
+        else
+          next_victim = lru_next (next_victim);
+      }
+    lock_release (&lru_lock);
+
+    free (frame_metadata);
+    palloc_free_page (frame);
+  }
+
+/* TODO: Account for page aliases when checking accessed bit. */
+/* A pre-condition for calling this function is that the calling thread
+   owns lru_lock and that lru_list is non-empty. */
+static struct frame_metadata *
+get_victim (void)
+  {
+    struct list_elem *e = next_victim;
+    struct frame_metadata *frame_metadata;
+    uint32_t *pd;
+    void *upage;
+    for (;;)
+      {
+        frame_metadata = list_entry (e, struct frame_metadata, list_elem);
+        pd = frame_metadata->owner->pagedir;
+        upage = frame_metadata->upage;
+        e = lru_next (e);
+
+        if (!pagedir_is_accessed (pd, upage))
+          break;
+
+        pagedir_set_accessed (pd, upage, false);
+      }
+
+    next_victim = e;
+    return frame_metadata;
+  }
+
+/* Hash function for frame metadata, used for storing entries in the
+   frame table. */
+unsigned
+frame_metadata_hash (const struct hash_elem *e, void *aux UNUSED)
+  {
+    struct frame_metadata *frame_metadata = 
+      hash_entry (e, struct frame_metadata, hash_elem);
+
+    return hash_bytes (&frame_metadata->frame, sizeof (frame_metadata->frame));
+  }
+
+/* 'less_func' comparison function for frame metadata, used for comparing 
+   the keys of the frame table. Returns true iff the kernel virtual address
+   of the first frame is less than that of the second frame. */
+bool
+frame_metadata_less (const struct hash_elem *a_, const struct hash_elem *b_,
+                     void *aux UNUSED)
+  {
+    struct frame_metadata *a =
+      hash_entry (a_, struct frame_metadata, hash_elem);
+    struct frame_metadata *b =
+      hash_entry (b_, struct frame_metadata, hash_elem);
+
+    return a->frame < b->frame;
+  }
+
+/* Returns the next recently used element after the one provided, which
+   is achieved by iterating through lru_list like a circular queue
+   (wrapping around the list at the tail). */
+static struct list_elem *
+lru_next (struct list_elem *e)
+{
+  if (!list_empty (&lru_list) && e == list_back (&lru_list))
+    return list_front (&lru_list);
+
+  return list_next (e);
+}
+
+/* Returns the previous recently used element after the one provided, which
+   is achieved by iterating through lru_list like a circular queue
+   (wrapping around the list at the head). */
+static struct list_elem *
+lru_prev (struct list_elem *e)
+{
+  if (!list_empty (&lru_list) && e == list_front (&lru_list))
+    return list_back (&lru_list);
+
+  return list_prev (e);
+}
+

src/vm/frame.h

@@ -0,0 +1,11 @@
+#ifndef VM_FRAME_H
+#define VM_FRAME_H
+
+#include "threads/thread.h"
+#include "threads/palloc.h"
+
+void frame_init (void);
+void *frame_alloc (enum palloc_flags, void *, struct thread *);
+void frame_free (void *frame);
+
+#endif /* vm/frame.h */

src/vm/page.c

@@ -0,0 +1,41 @@
+#include "page.h"
+#include "userprog/pagedir.h"
+#include "threads/pte.h"
+
+#define SWAP_FLAG_BIT 9
+#define ADDR_START_BIT 12
+
+/* Updates the 'owner' thread's page table entry for virtual address 'upage'
+   to have a present bit of 0 and stores the specified swap slot value in the
+   entry for later retrieval from disk. */
+void
+page_set_swap (struct thread *owner, void *upage, size_t swap_slot)
+{
+   uint32_t *pte = lookup_page (owner->pagedir, upage, false);
+
+   /* Store the provided swap slot in the address bits of the page table
+      entry, truncating excess bits. */
+   *pte |= (1 << SWAP_FLAG_BIT);
+   uint32_t swap_slot_bits = (swap_slot << ADDR_START_BIT) & PTE_ADDR;
+   *pte = (*pte & PTE_FLAGS) | swap_slot_bits;
+
+   /* Mark page as 'not present' and flag the page directory as having
+      been modified. */
+   pagedir_clear_page (owner->pagedir, upage);
+}
+
+/* Given that the page with user address 'upage' owned by 'owner' is flagged
+   to be in the swap disk via the owner's page table, returns its stored
+   swap slot. Otherwise panics the kernel. */
+size_t
+page_get_swap (struct thread *owner, void *upage)
+{
+   uint32_t *pte = lookup_page (owner->pagedir, upage, false);
+
+   ASSERT ((*pte & PTE_P) == 0);
+   ASSERT ((*pte & (1 << SWAP_FLAG_BIT)) != 0);
+
+   /* Masks the address bits and returns truncated value. */
+   return ((*pte & PTE_ADDR) >> ADDR_START_BIT);
+}
+

src/vm/page.h

@@ -0,0 +1,9 @@
+#ifndef VM_PAGE_H
+#define VM_PAGE_H
+
+#include "threads/thread.h"
+
+void page_set_swap (struct thread *, void *, size_t);
+size_t page_get_swap (struct thread *, void *);
+
+#endif /* vm/frame.h */

src/vm/stackgrowth.c

@@ -0,0 +1,59 @@
+#include <stdio.h>
+#include "stackgrowth.h"
+#include "frame.h"
+#include "threads/palloc.h"
+#include "threads/thread.h"
+#include "threads/vaddr.h"
+#include "userprog/pagedir.h"
+
+#define MAX_STACK_ACCESS_DIST 32
+
+static bool is_stack_fault (const void *addr, const void *esp);
+static bool grow_stack (const void *addr);
+
+/* Determine whether a particular page fault occured due to a stack
+   access below the stack pointer that should induce stack growth, and
+   if so grow the stack by a single page (capped at MAX_STACK_SIZE). */
+bool
+handle_stack_fault (const void *ptr, const void *esp)
+{
+  return is_stack_fault (ptr, esp) && grow_stack (ptr);
+}
+
+/* Determines whether a particular page fault appears to be caused by
+   a stack access that should induce dynamic stack growth. Stack size
+   is capped at MAX_STACK_SIZE. */
+static bool
+is_stack_fault (const void *addr, const void *esp)
+{
+  return ((uint32_t*)addr >= ((uint32_t*)esp - MAX_STACK_ACCESS_DIST) &&
+          ((PHYS_BASE - pg_round_down (addr)) <= MAX_STACK_SIZE));
+}
+
+/* Grows the stack of the process running inside the current thread by a single
+   page given a user virtual address inside of the page wherein the new section
+   of the stack should be allocated. */
+static bool
+grow_stack (const void *addr)
+{
+  struct thread *t = thread_current ();
+  void *last_page = pg_round_down (addr);
+
+  /* This function should only be called when dealing with a faulting stack
+     access that induces stack growth, so the provided address shouldn't be
+     present in a page within the current thread's page directory. */
+  ASSERT (pagedir_get_page (t->pagedir, last_page) == NULL);
+
+  uint8_t *new_page = frame_alloc (PAL_ZERO, last_page, t);
+  if (new_page == NULL)
+    return false;
+
+  if (!pagedir_set_page (t->pagedir, last_page, new_page, true))
+  {
+    frame_free (new_page);
+    return false;
+  }
+
+  return true;
+}
+

src/vm/stackgrowth.h

@@ -0,0 +1,10 @@
+#ifndef VM_GROWSTACK_H
+#define VM_GROWSTACK_H
+
+#include <stdio.h>
+
+#define MAX_STACK_SIZE 8388608 // (8MB)
+
+bool handle_stack_fault (const void *ptr, const void *esp);
+
+#endif /* vm/frame.h */