Clarify how termination treats file descriptors.

[pintos-anon] / doc / userprog.texi

diff --git a/doc/userprog.texi b/doc/userprog.texi
index e4e6098b5e8f77acdaf691b967af34d6cc0ef89d..59186129ca02ce05234a58f1f62f34dba5f081c6 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.
 
+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::  
@@ -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.
-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'
@@ -288,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
-@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.
 
@@ -435,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
-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
@@ -446,7 +453,7 @@ parallel:
 
 @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
@@ -461,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)}.
 
+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
@@ -644,13 +656,16 @@ Consider implementing this function in terms of @func{filesys_remove}.
 @deftypefn {System Call} int open (const char *@var{file})
 Opens the file called @var{file}.  Returns a nonnegative integer handle
 called a ``file descriptor'' (fd), or -1 if the file could not be
-opened.  All open files associated with a process should be closed
-when the process exits or is terminated.
+opened.  
 
 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
@@ -716,7 +731,9 @@ Consider implementing this function in terms of @func{file_tell}.
 @end deftypefn
 
 @deftypefn {System Call} void close (int @var{fd})
-Closes file descriptor @var{fd}.
+Closes file descriptor @var{fd}.  
+Exiting or terminating a process implicitly closes all its open file
+descriptors, as if by calling this function for each one.
 
 Consider implementing this function in terms of @func{file_close}.
 @end deftypefn
@@ -792,6 +809,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.
 
+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 +