Clarifications.

[pintos-anon] / doc / userprog.texi

diff --git a/doc/userprog.texi b/doc/userprog.texi
index 67d7853bc94ee4da9910fce62bf3d90832e0abaf..9277b087f5d9d9ba30e5a90d20ab8951f9b1284d 100644 (file)
--- a/doc/userprog.texi
+++ b/doc/userprog.texi
@@ -129,7 +129,7 @@ system implementation.
 
 You need to be able to create and format simulated disks.  The
 @command{pintos} program provides this functionality with its
-@option{make-disk} command.  From the @file{filesys/build} directory,
+@option{make-disk} command.  From the @file{userprog/build} directory,
 execute @code{pintos make-disk fs.dsk 2}.  This command creates a 2 MB
 simulated disk named @file{fs.dsk}.  (It does not actually start
 Pintos.)  Then format the disk by passing the @option{-f} option to
@@ -273,9 +273,10 @@ called by user programs are prototyped in @file{lib/user/syscall.h}:
 @table @code
 @item SYS_halt
 @itemx void halt (void)
-Stops Pintos and prints out performance statistics.  Note that this
-should be seldom used, since then you lose some information about
-possible deadlock situations, etc.
+Stops Pintos by calling @func{power_off} (declared in
+@file{threads/init.h}).  Note that this should be seldom used, since
+then you lose some information about possible deadlock situations,
+etc.
 
 @item SYS_exit
 @itemx void exit (int @var{status})
@@ -299,8 +300,9 @@ process, the return value is undefined (but kernel operation must not
 be disrupted).
 
 @item SYS_create
-@itemx bool create (const char *@var{file})
-Create a new file called @var{file}.  Returns -1 if failed, 0 if OK.
+@itemx bool create (const char *@var{file}, unsigned @var{initial_size})
+Create a new file called @var{file} initially @var{initial_size} bytes
+in size.  Returns -1 if failed, 0 if OK.
 
 @item SYS_remove
 @itemx bool remove (const char *@var{file})
@@ -396,6 +398,14 @@ You may find the code for @func{thread_join} to be useful in
 implementing the join syscall, but besides that, you can use
 the original code provided for project 1.
 
+@item
+@b{All my user programs die with page faults.}
+
+This will generally happen if you haven't implemented problem 2-1
+yet.  The reason is that the basic C library for user programs tries
+to read @var{argc} and @var{argv} off the stack.  Because the stack
+isn't properly set up yet, this causes a page fault.
+
 @item
 @b{Is there a way I can disassemble user programs?}
 
@@ -417,7 +427,7 @@ is compiled as a unit.)  If you wish to port libraries to Pintos, feel
 free.
 
 @item
-@b{How do I compile new user programs? How do I make 'echo' compile?}
+@b{How do I compile new user programs?}
 
 You need to modify @file{tests/Makefile}.
 
@@ -476,7 +486,7 @@ because there's no way to return an error code from a memory access.
 Therefore, for those who want to try the latter technique, we'll
 provide a little bit of helpful code:
 
-@example
+@verbatim
 /* Tries to copy a byte from user address USRC to kernel address DST.
    Returns true if successful, false if USRC is invalid. */
 static inline bool get_user (uint8_t *dst, const uint8_t *usrc) {
@@ -494,7 +504,7 @@ static inline bool put_user (uint8_t *udst, uint8_t byte) {
        : "=m" (*udst), "=&a" (eax) : "r" (byte));
   return eax != 0;
 }
-@end example
+@end verbatim
 
 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
@@ -805,12 +815,12 @@ You may find the non-standard @func{hex_dump} function, declared in
 Here's what it would show in the above example, given that
 @code{PHYS_BASE} is @t{0xc0000000}:
 
-@example
+@verbatim
 bfffffc0                                      00 00 00 00 |            ....|
 bfffffd0  04 00 00 00 d8 ff ff bf-ed ff ff bf f5 ff ff bf |................|
 bfffffe0  f8 ff ff bf fc ff ff bf-00 00 00 00 00 2f 62 69 |............./bi|
 bffffff0  6e 2f 6c 73 00 2d 6c 00-2a 2e 68 00 2a 2e 63 00 |n/ls.-l.*.h.*.c.|
-@end example
+@end verbatim
 
 @node System Calls
 @section System Calls
@@ -850,7 +860,7 @@ arbitrary:
 @html
 <CENTER>
 @end html
-@multitable {Address} {Value}
+@multitable {@t{0xbffffe7c}} {Value}
 @item Address @tab Value
 @item @t{0xbffffe7c} @tab 3
 @item @t{0xbffffe78} @tab 2