Update docs.
[pintos-anon] / doc / vm.texi
index 59e88ca4dffccbe19c3ab90d1fb36621abe8363c..fa511cdf99c540153afa215bad7a5779fc89c37b 100644 (file)
@@ -12,16 +12,22 @@ You will be using the @file{vm} directory for this project.  There is
 no new code to get acquainted with for this assignment.  The @file{vm}
 directory contains only the @file{Makefile}s.  The only change from
 @file{userprog} is that this new @file{Makefile} turns on the setting
-@option{-DVM}, which you will need for this assignment.  All code you
-write will either be newly generated files (e.g.@: if you choose to
-implement your paging code in their own source files), or will be
-modifications to pre-existing code (e.g.@: you will change the
-behavior of @file{addrspace.c} significantly).
+@option{-DVM}.  All code you write will either be newly generated
+files (e.g.@: if you choose to implement your paging code in their own
+source files), or will be modifications to pre-existing code (e.g.@:
+you will change the behavior of @file{process.c} significantly).
 
 You will be building this assignment on the last one.  It will benefit
 you to get your project 2 in good working order before this assignment
 so those bugs don't keep haunting you.
 
+All the test programs from the previous project should also work with
+this project.  You should also write programs to test the new features
+introduced in this project.
+
+Your submission should define @code{THREAD_JOIN_IMPLEMENTED} in
+@file{constants.h} (@pxref{Conditional Compilation}).
+
 @menu
 * VM Design::                   
 * Page Faults::                 
@@ -137,12 +143,27 @@ address.
                            /                      /
 @end example
 
+Header @file{threads/mmu.h} has useful functions for various
+operations on virtual addresses.  You should look over the header
+yourself, but its most important functions include these:
+
+@table @code
+@item pd_no(@var{va})
+Returns the page directory index in virtual address @var{va}.
+
+@item pt_no(@var{va})
+Returns the page table index in virtual address @var{va}.
+
+@item pg_ofs(@var{va})
+Returns the page offset in virtual address @var{va}.
 
-FIXME need to explain virtual and physical memory layout - probably
-back in userprog project
+@item pg_round_down(@var{va})
+Returns @var{va} rounded down to the nearest page boundary, that is,
+@var{va} but with its page offset set to 0.
 
-FIXME need to mention that there are many possible implementations and
-that the above is just an outline
+@item pg_round_up(@var{va})
+Returns @var{va} rounded up to the nearest page boundary.
+@end table
 
 @node Disk as Backing Store
 @section Disk as Backing Store
@@ -268,7 +289,7 @@ Follow the PDE to the page table.  Point the PTE for the faulting
 virtual address to the physical page found in step 2.
 @end enumerate
 
-You'll need to modify the ELF loader in @file{userprog/addrspace.c} to
+You'll need to modify the ELF loader in @file{userprog/process.c} to
 do page table management according to your new design.  As supplied,
 it reads all the process's pages from disk and initializes the page
 tables for them at the same time.  For testing purposes, you'll
@@ -276,6 +297,10 @@ probably want to leave the code that reads the pages from disk, but
 use your new page table management code to construct the page tables
 only as page faults occur for them.
 
+There are many possible ways to implement virtual memory.  The above
+is simply an outline of our suggested implementation.  You may choose
+any implementation you like, as long as it accomplishes the goal.
+
 @node Problem 3-2 Paging To and From Disk
 @section Problem 3-2: Paging To and From Disk
 
@@ -327,7 +352,7 @@ file itself as backing store for read-only segments, since these
 segments won't change.
 
 There are a few special cases.  Look at the loop in
-@code{load_segment()} in @file{userprog/addrspace.c}.  Each time
+@code{load_segment()} in @file{userprog/process.c}.  Each time
 around the loop, @code{read_bytes} represents the number of bytes to
 read from the executable file and @code{zero_bytes} represents the number
 of bytes to initialize to zero following the bytes read.  The two
@@ -348,14 +373,18 @@ first page fault.
 @item
 If neither @code{read_bytes} nor @code{zero_bytes} equals
 @code{PGSIZE}, then part of the page is to be read from disk and the
-remainder zeroed.  This is a special case, which you should handle by
+remainder zeroed.  This is a special case.  You may handle it by
 reading the partial page from disk at executable load time and zeroing
-the rest of the page.  It is the only case in which loading should not
-be ``lazy''; even real OSes such as Linux do not load partial pages
-lazily.
+the rest of the page.  This is the only case in which we will allow
+you to load a page in a non-``lazy'' fashion.  Many real OSes such as
+Linux do not load partial pages lazily.
 @end itemize
 
-FIXME mention that you can test with these special cases eliminated
+Incidentally, if you have trouble handling the third case above, you
+can eliminate it temporarily by linking the test programs with a
+special ``linker script.''  Read @file{tests/userprog/Makefile} for
+details.  We will not test your submission with this special linker
+script, so the code you turn in must properly handle all cases.
 
 You may optionally implement sharing: when multiple processes are
 created that use the same executable file, share read-only pages among
@@ -458,12 +487,7 @@ that we need it to do. What gives?}
 
 You are welcome to modify it.  It is not used by any of the code we
 provided, so modifying it won't affect any code but yours.  Do
-whatever it takes to make it work like you want it to.
-
-@item
-@b{Is the data segment page-aligned?}
-
-No.
+whatever it takes to make it work the way you want.
 
 @item
 @b{What controls the layout of user programs?}