Clarify page fault handler for get/put_user().

[pintos-anon] / doc / userprog.texi

diff --git a/doc/userprog.texi b/doc/userprog.texi
index ab6115ce6c67b348a40f5eb1c7e9707c8e1d29c9..d5eee6d0814675ef5195935dc61be786ae74c1b2 100644 (file)
--- a/doc/userprog.texi
+++ b/doc/userprog.texi
@@ -19,6 +19,12 @@ start with a fresh copy.  No code from project 1 is required for this
 assignment.  The ``alarm clock'' functionality may be useful in
 projects 3 and 4, but it is not strictly required.
 
 assignment.  The ``alarm clock'' functionality may be useful in
 projects 3 and 4, but it is not strictly required.
 

+You might find it useful to go back and reread how to run the tests
+(@pxref{Testing}).  In particular, the tests for project 2 and later
+projects will probably run faster if you use the qemu emulator, e.g.@:
+via @code{make check PINTOSOPTS='--qemu'}.  The qemu emulator is
+available only on the Linux machines.
+

 @menu
 * Project 2 Background::        
 * Project 2 Suggested Order of Implementation::  
 @menu
 * Project 2 Background::        
 * Project 2 Suggested Order of Implementation::  


@@ -222,9 +228,10 @@ pintos -p ../../examples/echo -a echo -- -f -q run 'echo x'
 
 If you don't want to keep the file system disk around for later use or
 inspection, you can even combine all four steps into a single command.
 
 If you don't want to keep the file system disk around for later use or
 inspection, you can even combine all four steps into a single command.

-The @code{--fs-disk=2} option creates a temporary disk just for the
-duration of the @command{pintos} run.  The Pintos automatic test suite
-makes extensive use of this syntax:
+The @code{--fs-disk=@var{n}} option creates a temporary disk
+approximately @var{n} megabytes in size just for the duration of the
+@command{pintos} run.  The Pintos automatic test suite makes extensive
+use of this syntax:

 
 @example
 pintos --fs-disk=2 -p ../../examples/echo -a echo -- -f -q run 'echo x'
 
 @example
 pintos --fs-disk=2 -p ../../examples/echo -a echo -- -f -q run 'echo x'


@@ -251,7 +258,8 @@ programs.  The @file{Makefile} in this directory
 compiles the provided examples, and you can edit it
 compile your own programs as well.
 
 compiles the provided examples, and you can edit it
 compile your own programs as well.
 

-Pintos loads @dfn{ELF} executables.  ELF is a file format used by Linux,
+Pintos can load @dfn{ELF} executables with the loader provided for you
+in @file{userprog/process.c}.  ELF is a file format used by Linux,

 Solaris, and many other operating systems for object files,
 shared libraries, and executables.  You can actually use any compiler
 and linker that output 80@var{x}86 ELF executables to produce programs
 Solaris, and many other operating systems for object files,
 shared libraries, and executables.  You can actually use any compiler
 and linker that output 80@var{x}86 ELF executables to produce programs


@@ -287,8 +295,8 @@ Kernel virtual memory is global.  It is always mapped the same way,
 regardless of what user process or kernel thread is running.  In
 Pintos, kernel virtual memory is mapped one-to-one to physical
 memory, starting at @code{PHYS_BASE}.  That is, virtual address
 regardless of what user process or kernel thread is running.  In
 Pintos, kernel virtual memory is mapped one-to-one to physical
 memory, starting at @code{PHYS_BASE}.  That is, virtual address

-@code{PHYS_ADDR} accesses physical
-address 0, virtual address @code{PHYS_ADDR} + @t{0x1234} access
+@code{PHYS_BASE} accesses physical
+address 0, virtual address @code{PHYS_BASE} + @t{0x1234} access

 physical address @t{0x1234}, and so on up to the size of the machine's
 physical memory.
 
 physical address @t{0x1234}, and so on up to the size of the machine's
 physical memory.
 


@@ -434,8 +442,8 @@ static inline bool put_user (uint8_t *udst, uint8_t byte) {
 
 Each of these functions assumes that the user address has already been
 verified to be below @code{PHYS_BASE}.  They also assume that you've
 
 Each of these functions assumes that the user address has already been
 verified to be below @code{PHYS_BASE}.  They also assume that you've

-modified @func{page_fault} so that a page fault in the kernel causes
-@code{eax} to be set to 0 and its former value copied into @code{eip}.
+modified @func{page_fault} so that a page fault in the kernel merely sets
+@code{eax} to 0 and copies its former value into @code{eip}.

 
 @node Project 2 Suggested Order of Implementation
 @section Suggested Order of Implementation
 
 @node Project 2 Suggested Order of Implementation
 @section Suggested Order of Implementation


@@ -445,7 +453,7 @@ parallel:
 
 @itemize
 @item
 
 @itemize
 @item

-Argument passing (@pxref{Argument Passing}).  Every user programs will
+Argument passing (@pxref{Argument Passing}).  Every user program will

 page fault immediately until argument passing is implemented.
 
 For now, you may simply wish to change
 page fault immediately until argument passing is implemented.
 
 For now, you may simply wish to change


@@ -460,6 +468,11 @@ in @func{setup_stack}.  That will work for any test program that doesn't
 examine its arguments, although its name will be printed as
 @code{(null)}.
 
 examine its arguments, although its name will be printed as
 @code{(null)}.
 

+Until you implement argument passing, you should only run programs
+without passing command-line arguments.  Attempting to pass arguments to
+a program will include those arguments in the name of the program, which
+will probably fail.
+

 @item
 User memory access (@pxref{Accessing User Memory}).  All system calls
 need to read user memory.  Few system calls need to write to user
 @item
 User memory access (@pxref{Accessing User Memory}).  All system calls
 need to read user memory.  Few system calls need to write to user


@@ -599,7 +612,7 @@ the program cannot load or run for any reason.
 @deftypefn {System Call} int wait (pid_t @var{pid})
 Waits for process @var{pid} to die and returns the status it passed to
 @code{exit}.  Returns -1 if @var{pid}
 @deftypefn {System Call} int wait (pid_t @var{pid})
 Waits for process @var{pid} to die and returns the status it passed to
 @code{exit}.  Returns -1 if @var{pid}

-was terminated by the kernel (i.e.@: killed due to an exception).  If
+was terminated by the kernel (e.g.@: killed due to an exception).  If

 @var{pid} is does not refer to a child of the
 calling thread, or if @code{wait} has already been successfully
 called for the given @var{pid}, returns -1 immediately, without
 @var{pid} is does not refer to a child of the
 calling thread, or if @code{wait} has already been successfully
 called for the given @var{pid}, returns -1 immediately, without


@@ -648,8 +661,12 @@ when the process exits or is terminated.
 
 File descriptors numbered 0 and 1 are reserved for the console: fd 0
 is standard input (@code{stdin}), fd 1 is standard output
 
 File descriptors numbered 0 and 1 are reserved for the console: fd 0
 is standard input (@code{stdin}), fd 1 is standard output

-(@code{stdout}).  These special file descriptors are valid as system
-call arguments only as explicitly described below.
+(@code{stdout}).  The @code{open} system call will never return either
+of these file descriptors, which are valid as system call arguments only
+as explicitly described below.
+
+Each process has an independent set of file descriptors.  File
+descriptors are not inherited by child processes.

 
 Consider implementing this function in terms of @func{filesys_open}.
 @end deftypefn
 
 Consider implementing this function in terms of @func{filesys_open}.
 @end deftypefn


@@ -665,7 +682,8 @@ Reads @var{size} bytes from the file open as @var{fd} into
 @var{buffer}.  Returns the number of bytes actually read (0 at end of
 file), or -1 if the file could not be read (due to a condition other
 than end of file).  Fd 0 reads from the keyboard using
 @var{buffer}.  Returns the number of bytes actually read (0 at end of
 file), or -1 if the file could not be read (due to a condition other
 than end of file).  Fd 0 reads from the keyboard using

-@func{kbd_getc}.
+@func{kbd_getc}.  (Keyboard input will not work if you pass the
+@option{-v} option to @command{pintos}.)

 
 Consider implementing this function in terms of @func{file_read}.
 @end deftypefn
 
 Consider implementing this function in terms of @func{file_read}.
 @end deftypefn


@@ -682,7 +700,8 @@ actual number written, or -1 if no bytes could be written at all.
 
 Fd 1 writes to the console.  Your code to write to the console should
 write all of @var{buffer} in one call to @func{putbuf}, at least as
 
 Fd 1 writes to the console.  Your code to write to the console should
 write all of @var{buffer} in one call to @func{putbuf}, at least as

-long as @var{size} is not bigger than a few hundred bytes.  Otherwise,
+long as @var{size} is not bigger than a few hundred bytes.  (It is
+reasonable to break up larger buffers.)  Otherwise,

 lines of text output by different processes may end up interleaved on
 the console, confusing both human readers and our grading scripts.
 
 lines of text output by different processes may end up interleaved on
 the console, confusing both human readers and our grading scripts.
 


@@ -776,7 +795,8 @@ hurt even now.
 You can use @func{file_deny_write} to prevent writes to an open file.
 Calling @func{file_allow_write} on the file will re-enable them (unless
 the file is denied writes by another opener).  Closing a file will also
 You can use @func{file_deny_write} to prevent writes to an open file.
 Calling @func{file_allow_write} on the file will re-enable them (unless
 the file is denied writes by another opener).  Closing a file will also

-re-enable writes.
+re-enable writes.  Thus, to deny writes to process's executable, you
+must keep it open as long as the process is still running.

 
 @node Project 2 FAQ
 @section FAQ
 
 @node Project 2 FAQ
 @section FAQ


@@ -788,6 +808,12 @@ Here's a summary of our reference solution, produced by the
 @command{diffstat} program.  The final row gives total lines inserted
 and deleted; a changed line counts as both an insertion and a deletion.
 
 @command{diffstat} program.  The final row gives total lines inserted
 and deleted; a changed line counts as both an insertion and a deletion.
 

+The reference solution represents just one possible solution.  Many
+other solutions are also possible and many of those differ greatly from
+the reference solution.  Some excellent solutions may not modify all the
+files modified by the reference solution, and some may modify files not
+modified by the reference solution.
+

 @verbatim
  threads/thread.c     |   13 
  threads/thread.h     |   26 +
 @verbatim
  threads/thread.c     |   13 
  threads/thread.h     |   26 +