Implement a proper block layer with partition support.

[pintos-anon] / doc / vm.texi

diff --git a/doc/vm.texi b/doc/vm.texi
index 3210bbcc83dd021a16f48ad78f7a9284ead20f21..ab64a4de57f4b60a09ad35fc26c17e6029128169 100644 (file)
--- a/doc/vm.texi
+++ b/doc/vm.texi
@@ -49,10 +49,10 @@ files or in files introduced in earlier projects.
 You will probably be encountering just a few files for the first time:
 
 @table @file
 You will probably be encountering just a few files for the first time:
 
 @table @file

-@item devices/disk.h
-@itemx devices/disk.c
-Provides access to the physical disk, abstracting away the rather awful
-IDE interface.  You will use this interface to access the swap disk.
+@item devices/block.h
+@itemx devices/block.c
+Provides sector-based read and write access to block device.  You will
+use this interface to access the swap partition as a block device.

 @end table
 
 @node Memory Terminology
 @end table
 
 @node Memory Terminology


@@ -162,8 +162,8 @@ address, on the right.
 @node Swap Slots
 @subsubsection Swap Slots
 
 @node Swap Slots
 @subsubsection Swap Slots
 

-A @dfn{swap slot} is a continuous, page-size region of disk space on the
-swap disk.  Although hardware limitations dictating the placement of
+A @dfn{swap slot} is a continuous, page-size region of disk space in the
+swap partition.  Although hardware limitations dictating the placement of

 slots are looser than for pages and frames, swap slots should be
 page-aligned because there is no downside in doing so.
 
 slots are looser than for pages and frames, swap slots should be
 page-aligned because there is no downside in doing so.
 


@@ -260,7 +260,7 @@ page fault might only indicate that the page must be brought in from a
 file or swap.  You will have to implement a more sophisticated page
 fault handler to handle these cases.  Your page fault handler, which you
 should implement by modifying @func{page_fault} in
 file or swap.  You will have to implement a more sophisticated page
 fault handler to handle these cases.  Your page fault handler, which you
 should implement by modifying @func{page_fault} in

-@file{threads/exception.c}, needs to do roughly the following:
+@file{userprog/exception.c}, needs to do roughly the following:

 
 @enumerate 1
 @item
 
 @enumerate 1
 @item


@@ -377,17 +377,19 @@ to work with accessed and dirty bits.
 
 The swap table tracks in-use and free swap slots.  It should allow
 picking an unused swap slot for evicting a page from its frame to the
 
 The swap table tracks in-use and free swap slots.  It should allow
 picking an unused swap slot for evicting a page from its frame to the

-swap disk.  It should allow freeing a swap slot when its page is read
+swap partition.  It should allow freeing a swap slot when its page is read

 back or the process whose page was swapped is terminated.
 
 back or the process whose page was swapped is terminated.
 

-You may use the disk on interface @code{hd1:1} as the swap disk, using
-the disk interface prototyped in @code{devices/disk.h}.  From the
+You may use the @code{BLOCK_SWAP} block device for swapping, obtaining
+the @struct{block} that represents it by calling @func{block_get_role}.
+From the

 @file{vm/build} directory, use the command @code{pintos-mkdisk swap.dsk
 @file{vm/build} directory, use the command @code{pintos-mkdisk swap.dsk

-@var{n}} to create an @var{n} MB swap disk named @file{swap.dsk}.
-Afterward, @file{swap.dsk} will automatically be attached as
-@code{hd1:1} when you run @command{pintos}.  Alternatively, you can tell
+--swap-size=@var{n}} to create an disk named @file{swap.dsk} that
+contains a @var{n}-MB swap partition.
+Afterward, @file{swap.dsk} will automatically be attached as an extra disk
+when you run @command{pintos}.  Alternatively, you can tell

 @command{pintos} to use a temporary @var{n}-MB swap disk for a single
 @command{pintos} to use a temporary @var{n}-MB swap disk for a single

-run with @option{--swap-disk=@var{n}}.
+run with @option{--swap-size=@var{n}}.

 
 Swap slots should be allocated lazily, that is, only when they are
 actually required by eviction.  Reading data pages from the executable
 
 Swap slots should be allocated lazily, that is, only when they are
 actually required by eviction.  Reading data pages from the executable


@@ -485,7 +487,7 @@ little as possible about how to do things.  Instead we will focus on
 what functionality we require your OS to support.  We will expect
 you to come up with a design that makes sense.  You will have the
 freedom to choose how to handle page faults, how to organize the swap
 what functionality we require your OS to support.  We will expect
 you to come up with a design that makes sense.  You will have the
 freedom to choose how to handle page faults, how to organize the swap

-disk, how to implement paging, etc.
+partition, how to implement paging, etc.

 
 @menu
 * Project 3 Design Document::   
 
 @menu
 * Project 3 Design Document::   


@@ -534,7 +536,7 @@ variables' values:
 @itemize @bullet
 @item
 If @code{page_read_bytes} equals @code{PGSIZE}, the page should be demand
 @itemize @bullet
 @item
 If @code{page_read_bytes} equals @code{PGSIZE}, the page should be demand

-paged from disk on its first access.
+paged from the underlying file on its first access.

 
 @item
 If @code{page_zero_bytes} equals @code{PGSIZE}, the page does not need to
 
 @item
 If @code{page_zero_bytes} equals @code{PGSIZE}, the page does not need to


@@ -545,7 +547,7 @@ first page fault.
 @item
 Otherwise, neither @code{page_read_bytes} nor @code{page_zero_bytes}
 equals @code{PGSIZE}.  In this case, an initial part of the page is to
 @item
 Otherwise, neither @code{page_read_bytes} nor @code{page_zero_bytes}
 equals @code{PGSIZE}.  In this case, an initial part of the page is to

-be read from disk and the remainder zeroed.
+be read from the underlying file and the remainder zeroed.

 @end itemize
 
 @node Stack Growth
 @end itemize
 
 @node Stack Growth


@@ -576,7 +578,7 @@ bytes below the stack pointer.
 
 You will need to be able to obtain the current value of the user
 program's stack pointer.  Within a system call or a page fault generated
 
 You will need to be able to obtain the current value of the user
 program's stack pointer.  Within a system call or a page fault generated

-by a user program, you can retrieve it from @code{esp} member of the
+by a user program, you can retrieve it from the @code{esp} member of the

 @struct{intr_frame} passed to @func{syscall_handler} or
 @func{page_fault}, respectively.  If you verify user pointers before
 accessing them (@pxref{Accessing User Memory}), these are the only cases
 @struct{intr_frame} passed to @func{syscall_handler} or
 @func{page_fault}, respectively.  If you verify user pointers before
 accessing them (@pxref{Accessing User Memory}), these are the only cases


@@ -590,16 +592,14 @@ user stack pointer.  You will need to arrange another way, such as
 saving @code{esp} into @struct{thread} on the initial transition 
 from user to kernel mode.
 
 saving @code{esp} into @struct{thread} on the initial transition 
 from user to kernel mode.
 

-You may impose some absolute limit on stack size, as do most OSes.
+You should impose some absolute limit on stack size, as do most OSes.

 Some OSes make the limit user-adjustable, e.g.@: with the
 @command{ulimit} command on many Unix systems.  On many GNU/Linux systems,
 the default limit is 8 MB.
 
 Some OSes make the limit user-adjustable, e.g.@: with the
 @command{ulimit} command on many Unix systems.  On many GNU/Linux systems,
 the default limit is 8 MB.
 

-The first stack page need not be allocated lazily.  You can initialize
-it with the command line arguments at load time, with no need to wait
-for it to be faulted in.  (Even if you did wait, the very first
-instruction in the user program is likely to be one that faults in the
-page.)
+The first stack page need not be allocated lazily.  You can allocate
+and initialize it with the command line arguments at load time, with 
+no need to wait for it to be faulted in.

 
 All stack pages should be candidates for eviction.  An evicted stack
 page should be written to swap.
 
 All stack pages should be candidates for eviction.  An evicted stack
 page should be written to swap.


@@ -615,13 +615,14 @@ space.  The entire file is mapped into consecutive virtual pages
 starting at @var{addr}.
 
 Your VM system must lazily load pages in @code{mmap} regions and use the
 starting at @var{addr}.
 
 Your VM system must lazily load pages in @code{mmap} regions and use the

-@code{mmap}'d file itself as backing store for the mapping.  That is,
+@code{mmap}ed file itself as backing store for the mapping.  That is,

 evicting a page mapped by @code{mmap} writes it back to the file it was
 mapped from.
 
 If the file's length is not a multiple of @code{PGSIZE}, then some
 bytes in the final mapped page ``stick out'' beyond the end of the
 evicting a page mapped by @code{mmap} writes it back to the file it was
 mapped from.
 
 If the file's length is not a multiple of @code{PGSIZE}, then some
 bytes in the final mapped page ``stick out'' beyond the end of the

-file.  Set these bytes to zero when the page is faulted in from disk,
+file.  Set these bytes to zero when the page is faulted in from the
+file system,

 and discard them when the page is written back to disk.
 
 If successful, this function returns a ``mapping ID'' that
 and discard them when the page is written back to disk.
 
 If successful, this function returns a ``mapping ID'' that


@@ -716,6 +717,12 @@ process.  If you carefully designed your data structures,
 sharing of read-only pages should not make this part significantly
 harder.
 
 sharing of read-only pages should not make this part significantly
 harder.
 

+@item How do we resume a process after we have handled a page fault?
+
+Returning from @func{page_fault} resumes the current user process
+(@pxref{Internal Interrupt Handling}).
+It will then retry the instruction to which the instruction pointer points.
+

 @item Does the virtual memory system need to support data segment growth?
 
 No.  The size of the data segment is determined by the linker.  We still
 @item Does the virtual memory system need to support data segment growth?
 
 No.  The size of the data segment is determined by the linker.  We still


@@ -735,7 +742,7 @@ kernel functions need to obtain memory.
 You can layer some other allocator on top of @func{palloc_get_page} if
 you like, but it should be the underlying mechanism.
 
 You can layer some other allocator on top of @func{palloc_get_page} if
 you like, but it should be the underlying mechanism.
 

-Also, you can use the @option{-ul} option to @command{pintos} to limit
+Also, you can use the @option{-ul} kernel command-line option to limit

 the size of the user pool, which makes it easy to test your VM
 implementation with various user memory sizes.
 @end table
 the size of the user pool, which makes it easy to test your VM
 implementation with various user memory sizes.
 @end table