-@node Global Requirements
-@section Global Requirements
-
-For testing and grading purposes, we have some simple requirements for
-your output. The kernel should print out the program's name and exit
-status whenever a process exits, e.g.@: @code{shell: exit(-1)}. Aside
-from this, it should print out no other messages. You may understand
-all those debug messages, but we won't, and it just clutters our
-ability to see the stuff we care about.
-
-Additionally, while it may be useful to hard-code which process will
-run at startup while debugging, before you submit your code you must
-make sure that it takes the start-up process name and arguments from
-the @samp{-ex} argument. For example, running @code{pintos run -ex
-"testprogram 1 2 3 4"} will spawn @samp{testprogram 1 2 3 4} as the
-first process.
-
-@node Problem 2-1 Argument Passing
-@section Problem 2-1: Argument Passing
-
-Currently, @code{process_execute()} does not support passing arguments
-to new processes. UNIX and other operating systems do allow passing
-command line arguments to a program, which accesses them via the argc,
-argv arguments to main. You must implement this functionality by
-extending @code{process_execute()} so that instead of simply taking a
-program file name, it can take a program name with arguments as a
-single string. That is, @code{process_execute("grep foo *.c")} should
-be a legal call. @xref{80x86 Calling Convention}, for information on
-exactly how this works.
-
-@strong{This functionality is extremely important.} Almost all our
-test cases rely on being able to pass arguments, so if you don't get
-this right, a lot of things will not appear to work correctly with our
-tests. If the tests fail, so do you. Fortunately, this part
-shouldn't be too hard.
-
-@node Problem 2-2 System Calls
-@section Problem 2-2: System Calls
-
-Implement the system call handler in @file{userprog/syscall.c} to
-properly deal with all the system calls described below. Currently,
-it ``handles'' system calls by terminating the process. You will need
-to decipher system call arguments and take the appropriate action for
-each.
-
-You are required to support the following system calls, whose syscall
-numbers are defined in @file{lib/syscall-nr.h} and whose C functions
-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.
-
-@item SYS_exit
-@itemx void exit (int @var{status})
+You must handle memory fragmentation gracefully, that is, a process that
+needs @var{N} pages of user virtual memory must not require those pages
+to be contiguous in kernel virtual memory.
+
+@menu
+* Typical Memory Layout::
+@end menu
+
+@node Typical Memory Layout
+@subsubsection Typical Memory Layout
+
+Conceptually, each process is
+free to lay out its own user virtual memory however it
+chooses. In practice, user virtual memory is laid out like this:
+
+@html
+<CENTER>
+@end html
+@example
+@group
+ PHYS_BASE +----------------------------------+
+ | user stack |
+ | | |
+ | | |
+ | V |
+ | grows downward |
+ | |
+ | |
+ | |
+ | |
+ | grows upward |
+ | ^ |
+ | | |
+ | | |
+ +----------------------------------+
+ | uninitialized data segment (BSS) |
+ +----------------------------------+
+ | initialized data segment |
+ +----------------------------------+
+ | code segment |
+ 0x08048000 +----------------------------------+
+ | |
+ | |
+ | |
+ | |
+ | |
+ 0 +----------------------------------+
+@end group
+@end example
+@html
+</CENTER>
+@end html
+
+In this project, the user stack is fixed in size, but in project 3 it
+will be allowed to grow. Traditionally, the size of the uninitialized
+data segment can be adjusted with a system call, but you will not have
+to implement this.
+
+The code segment in Pintos starts at user virtual address
+@t{0x08084000}, approximately 128 MB from the bottom of the address
+space. This value is specified in @bibref{SysV-i386} and has no deep
+significance.
+
+The linker sets the layout of a user program in memory, as directed by a
+``linker script'' that tells it the names and locations of the various
+program segments. You can learn more about linker scripts by reading
+the ``Scripts'' chapter in the linker manual, accessible via @samp{info
+ld}.
+
+To view the layout of a particular executable, run @command{objdump}
+(80@var{x}86) or @command{i386-elf-objdump} (SPARC) with the @option{-p}
+option.
+
+@node Accessing User Memory
+@subsection Accessing User Memory
+
+As part of a system
+call, the kernel must often access memory through pointers provided by a user
+program. The kernel must be very careful about doing so, because
+the user can pass a null pointer, a pointer to
+unmapped virtual memory, or a pointer to kernel virtual address space
+(above @code{PHYS_BASE}). All of these types of invalid pointers must
+be rejected without harm to the kernel or other running processes, by
+terminating the offending process and freeing its resources.
+
+There are at least two reasonable ways to do this correctly. The
+first method is to verify
+the validity of a user-provided pointer, then dereference it. If you
+choose this route, you'll want to look at the functions in
+@file{userprog/pagedir.c} and in @file{threads/mmu.h}. This is the
+simplest way to handle user memory access.
+
+The second method is to check only that a user
+pointer points below @code{PHYS_BASE}, then dereference it.
+An invalid user pointer will cause a ``page fault'' that you can
+handle by modifying the code for @func{page_fault} in
+@file{userprog/exception.cc}. This technique is normally faster
+because it takes advantage of the processor's MMU, so it tends to be
+used in real kernels (including Linux).
+
+In either case, you need to make sure not to ``leak'' resources. For
+example, suppose that your system call has acquired a lock or
+allocated a page of memory. If you encounter an invalid user pointer
+afterward, you must still be sure to release the lock or free the page
+of memory. If you choose to verify user pointers before dereferencing
+them, this should be straightforward. It's more difficult to handle
+if an invalid pointer causes a page fault,
+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:
+
+@verbatim
+/* Tries to copy a byte from user address USRC to kernel address KDST.
+ Returns true if successful, false if USRC is invalid. */
+static inline bool get_user (uint8_t *kdst, const uint8_t *usrc) {
+ int eax;
+ asm ("mov %%eax, offset 1f; mov %%al, %2; mov %0, %%al; 1:"
+ : "=m" (*kdst), "=&a" (eax) : "m" (*usrc));
+ return eax != 0;
+}
+
+/* Tries to write BYTE to user address UDST.
+ Returns true if successful, false if UDST is invalid. */
+static inline bool put_user (uint8_t *udst, uint8_t byte) {
+ int eax;
+ asm ("mov %%eax, offset 1f; mov %0, %b2; 1:"
+ : "=m" (*udst), "=&a" (eax) : "r" (byte));
+ return eax != 0;
+}
+@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
+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}.
+
+@node Project 2 Requirements
+@section Requirements
+
+@menu
+* Project 2 Design Document::
+* Process Termination Messages::
+* Argument Passing::
+* System Calls::
+* Denying Writes to Executables::
+@end menu
+
+@node Project 2 Design Document
+@subsection Design Document
+
+Before you turn in your project, you must copy @uref{userprog.tmpl, ,
+the project 2 design document template} into your source tree under the
+name @file{pintos/src/userprog/DESIGNDOC} and fill it in. We recommend
+that you read the design document template before you start working on
+the project. @xref{Project Documentation}, for a sample design document
+that goes along with a fictitious project.
+
+@node Process Termination Messages
+@subsection Process Termination Messages
+
+Whenever a user process terminates, because it called @code{exit}
+or for any other reason, print the process's name
+and exit code, formatted as if printed by @code{printf ("%s:
+exit(%d)\n", @dots{});}. The name printed should be the full name
+passed to @func{process_execute}, omitting command-line arguments.
+Do not print these messages when a kernel thread that is not a user
+process terminates, or
+when the @code{halt} system call is invoked. The message is optional
+when a process fails to load.
+
+Aside from this, don't print any other
+messages that Pintos as provided doesn't already print. You may find
+extra messages useful during debugging, but they will confuse the
+grading scripts and thus lower your score.
+
+@node Argument Passing
+@subsection Argument Passing
+
+Currently, @func{process_execute} does not support passing arguments to
+new processes. Implement this functionality, by extending
+@func{process_execute} so that instead of simply taking a program file
+name as its argument, it divides it into words at spaces. The first
+word is the program name, the second word is the first argument, and so
+on. That is, @code{process_execute("grep foo bar")} should run
+@command{grep} passing two arguments @code{foo} and @code{bar}.
+
+Within a command line, multiple spaces are equivalent to a single space,
+so that @code{process_execute("grep foo bar")} is equivalent to our
+original example. You can impose a reasonable limit on the length of
+the command line arguments. For example, you could limit the arguments
+to those that will fit in a single page (4 kB).
+
+You can parse argument strings any way you like. If you're lost,
+look at @func{strtok_r}, prototyped in @file{lib/string.h} and
+implemented with thorough comments in @file{lib/string.c}. You can
+find more about it by looking at the man page (run @code{man strtok_r}
+at the prompt).
+
+@xref{Program Startup Details}, for information on exactly how you
+need to set up the stack.
+
+@node System Calls
+@subsection System Calls
+
+Implement the system call handler in @file{userprog/syscall.c}. The
+skeleton implementation we provide ``handles'' system calls by
+terminating the process. It will need to retrieve the system call
+number, then any system call arguments, and carry appropriate actions.
+
+Implement the following system calls. The prototypes listed are those
+seen by a user program that includes @file{lib/user/syscall.h}. System
+call numbers for each system call are defined in
+@file{lib/syscall-nr.h}:
+
+@deftypefn {System Call} void halt (void)
+Terminates 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.
+@end deftypefn
+
+@deftypefn {System Call} void exit (int @var{status})