Update docs.
[pintos-anon] / doc / vm.texi
index b7f766ea2a50fdef73c7a958fd3440a70a4bd1b2..64619c8d4829430774d1aecfc5d8074b68851aa2 100644 (file)
@@ -77,7 +77,7 @@ table contained all the virtual-to-physical translations for the
 process.  Whenever the processor needed to look up a translation, it
 consulted the page table.  As long as the process only accessed
 memory that it didn't own, all was well.  If the process accessed
-memory it didn't own, it ``page faulted'' and @code{page_fault()}
+memory it didn't own, it ``page faulted'' and @func{page_fault}
 terminated the process.
 
 When we implement virtual memory, the rules have to change.  A page
@@ -112,25 +112,26 @@ can effectively ignore this CPU feature.}
 
 @enumerate 1
 @item
-The top 10 bits of the virtual address (bits 22:31) are used to index
+The top 10 bits of the virtual address (bits 22:32) are used to index
 into the page directory.  If the PDE is marked ``present,'' the
 physical address of a page table is read from the PDE thus obtained.
 If the PDE is marked ``not present'' then a page fault occurs.
 
 @item
-The next 10 bits of the virtual address (bits 12:21) are used to index
+The next 10 bits of the virtual address (bits 12:22) are used to index
 into the page table.  If the PTE is marked ``present,'' the physical
 address of a data page is read from the PTE thus obtained.  If the PTE
 is marked ``not present'' then a page fault occurs.
 
 
 @item
-The bottom 12 bits of the virtual address (bits 0:11) are added to the
+The bottom 12 bits of the virtual address (bits 0:12) are added to the
 data page's physical base address, producing the final physical
 address.
 @end enumerate
 
 @example
+@group
 32                    22                     12                      0
 +--------------------------------------------------------------------+
 | Page Directory Index |   Page Table Index   |    Page Offset       |
@@ -158,6 +159,7 @@ address.
        1|____________|  |   1|____________|  |     |____________|
        0|____________|  \__\0|____________|  \____\|____________|
                            /                      /
+@end group
 @end example
 
 Header @file{threads/mmu.h} has useful functions for various
@@ -269,7 +271,7 @@ need this data structure until part 2, but planning ahead is a good
 idea.
 @end itemize
 
-The page fault handler, @code{page_fault()} in
+The page fault handler, @func{page_fault} in
 @file{threads/exception.c}, needs to do roughly the following:
 
 @enumerate 1
@@ -304,6 +306,12 @@ 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.
 
+You should use the @func{palloc_get_page} function to get the page
+frames that you use for storing user virtual pages.  Be sure to pass
+the @code{PAL_USER} flag to this function when you do so, because that
+allocates pages from a ``user pool'' separate from the ``kernel pool''
+that other calls to @func{palloc_get_page} make.
+
 There are many possible ways to implement virtual memory.  The above
 is simply an outline of our suggested implementation.
 
@@ -353,7 +361,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/process.c}.  Each time
+@func{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
@@ -465,7 +473,7 @@ true if the first is less than the second.  These two functions have
 to be compatible with the prototypes for @code{hash_hash_func} and
 @code{hash_less_func} in @file{lib/kernel/hash.h}.
 
-Here's a quick example.  Suppose you want to put @code{struct thread}s
+Here's a quick example.  Suppose you want to put @struct{thread}s
 in a hash table.  First, add a @code{hash_elem} to the thread
 structure by adding a line to its definition:
 
@@ -473,7 +481,7 @@ structure by adding a line to its definition:
 hash_elem h_elem;               /* Hash table element. */
 @end example
 
-We'll choose the @code{tid} member in @code{struct thread} as the key,
+We'll choose the @code{tid} member in @struct{thread} as the key,
 and write a hash function and a comparison function:
 
 @example
@@ -487,7 +495,8 @@ thread_hash (const hash_elem *e, void *aux UNUSED)
 
 /* Returns true if A's tid is less than B's tid. */
 bool
-thread_less (const hash_elem *a_, const hash_elem *b_, void *aux UNUSED)
+thread_less (const hash_elem *a_, const hash_elem *b_, 
+             void *aux UNUSED)
 @{
   struct thread *a = hash_entry (a_, struct thread, h_elem);
   struct thread *b = hash_entry (b_, struct thread, h_elem);
@@ -503,7 +512,7 @@ struct hash threads;
 hash_init (&threads, thread_hash, thread_less, NULL);
 @end example
 
-Finally, if @code{@var{t}} is a pointer to a @code{struct thread},
+Finally, if @code{@var{t}} is a pointer to a @struct{thread},
 then we can insert it into the hash table with:
 
 @example
@@ -519,7 +528,7 @@ to any of the TA's office hours for further clarification.
 for?}
 
 In simple cases you won't have any need for the @var{aux} parameters.
-In these cases you can just pass a null pointer to @code{hash_init()}
+In these cases you can just pass a null pointer to @func{hash_init}
 for @var{aux} and ignore the values passed to the hash function and
 comparison functions.  (You'll get a compiler warning if you don't use
 the @var{aux} parameter, but you can turn that off with the
@@ -599,6 +608,20 @@ heuristic to figure this out.
 
 Make a reasonable decision and document it in your code and in
 your design document.  Please make sure to justify your decision.
+
+@item
+@b{Why do I need to pass @code{PAL_USER} to @func{palloc_get_page}
+when I allocate physical page frames?}@anchor{Why PAL_USER?}
+
+You can layer some other allocator on top of @func{palloc_get_page}
+if you like, but it should be the underlying mechanism, directly or
+indirectly, for two reasons.  First, running out of pages in the user
+pool just causes user programs to page, but running out of pages in
+the kernel pool will cause all kinds of problems, because many kernel
+functions depend on being able to allocate memory.  Second, you can
+use the @option{-ul} option to @command{pintos} to limit the size of
+the user pool, which makes it easy to test your VM implementation with
+various user memory sizes.
 @end enumerate
 
 @node Problem 3-3 Memory Mapped File FAQ