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::
provided a simple file system in the @file{filesys} directory. You
will want to look over the @file{filesys.h} and @file{file.h}
interfaces to understand how to use the file system, and especially
-its many limitations. @strong{You should not modify the file system
-code for this project.} Proper use of the file system routines now
+its many limitations.
+
+There is no need to modify the file system code for this project, and so
+we recommend that you do not. Working on the file system is likely to
+distract you from this project's focus.
+
+Proper use of the file system routines now
will make life much easier for project 4, when you improve the file
system implementation. Until then, you will have to put up with the
following limitations:
@itemize @bullet
@item
No synchronization. Concurrent accesses will interfere with one
-another. You should use a global lock to ensure that only one process at a
+another. You should use a lock to ensure that only one process at a
time is executing file system code.
@item
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'
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
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.
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
@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
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
@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
@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
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
@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 +
The @command{objdump} (80@var{x}86) or @command{i386-elf-objdump}
(SPARC) utility can disassemble entire user
programs or object files. Invoke it as @code{objdump -d
-@var{file}}. You can use @code{gdb}'s
-@command{disassemble} command to disassemble individual functions
-(@pxref{gdb}).
+@var{file}}. You can use GDB's
+@code{disassemble} command to disassemble individual functions
+(@pxref{GDB}).
@item Why do many C include files not work in Pintos programs?