other part of the code for this assignment. We will describe the
relevant parts below. If you are confident in your HW1 code, you can
build on top of it. However, if you wish you can start with a fresh
-copy of the code and re-implement @func{thread_join}, which is the
-only part of project #1 required for this assignment. Your submission
-should define @code{THREAD_JOIN_IMPLEMENTED} in @file{constants.h}
-(@pxref{Conditional Compilation}).
+copy of the code. No code from project 1 is required for this
+assignment.
Up to now, all of the code you have written for Pintos has been part
of the operating system kernel. This means, for example, that all the
* Using the File System::
* How User Programs Work::
* Virtual Memory Layout::
-* Global Requirements::
+* Grading Requirements::
* Problem 2-1 Argument Passing::
* Problem 2-2 System Calls::
* User Programs FAQ::
its many limitations. @strong{You should not modify the file system
code for this project}. Proper use of the file system routines now
will make life much easier for project 4, when you improve the file
-system implementation.
+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, so external synchronization is needed. @xref{Synchronizing
+File Access}, for more details.
+
+@item
+File size is fixed at creation time. Because the root directory is
+represented as a file, the number of files that may be created is also
+limited.
+
+@item
+File data is allocated as a single extent, that is, data in a single
+file must occupy a contiguous range of sectors on disk. External
+fragmentation can therefore become a serious problem as a file system is
+used over time.
+
+@item
+No subdirectories.
+
+@item
+File names are limited to 14 characters.
+
+@item
+A system crash mid-operation may corrupt the disk in a way
+that cannot be repaired automatically. No `fsck' tool is
+provided in any case.
+@end itemize
+
+However one important feature is included:
+
+@itemize @bullet
+@item
+Unix-like semantics for filesys_remove() are implemented.
+That is, if a file is open when it is removed, its blocks
+are not deallocated and it may still be accessed by the
+threads that have it open until the last one closes it. @xref{Removing
+an Open File}, for more information.
+@end itemize
You need to be able to create and format simulated disks. The
@command{pintos} program provides this functionality with its
be contiguous. In fact, it must not require that any of the pages be
contiguous.
-@node Global Requirements
-@section Global Requirements
+@node Grading Requirements
+@section Grading Requirements
For testing and grading purposes, we have some simple overall
requirements:
@itemize @bullet
@item
-The kernel should print out the program's name and exit status
-whenever a process exits, e.g.@: @code{shell: exit(-1)}. The name
-printed should be the full name passed to @func{process_execute},
-except that it is acceptable to truncate it to 15 characters to allow
-for the limited space in @struct{thread}.
+The kernel should print out the program's name and exit status whenever
+a process terminates, whether termination is caused by the @code{exit}
+system call or for another reason.
+
+@itemize @minus
+@item
+The message must be formatted exactly as if it was printed with
+@code{printf ("%s: exit(%d)\n", @dots{});} given appropriate arguments.
+
+@item
+The name printed should be the full name passed to
+@func{process_execute}, except that it is acceptable to truncate it to
+15 characters to allow for the limited space in @struct{thread}. The
+name printed need not include arguments.
+
+@item
+Do not print a message when a kernel thread that is not a process
+terminates.
+
+@item
+Do not print messages about process termination for the @code{halt}
+system call.
+
+@item
+No message need be printed when a process fails to load.
+@end itemize
@item
Aside from this, the kernel should print out no other messages that
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.
+
+@item
+In the previous project, we required that you provided some specific
+function interfaces, because we tested your project by compiling our
+test code into it. For this project and all later projects, this is
+no longer necessary, because we will do all of our testing with user
+programs. You must make sure that the user program interface meets
+the specifications described in the assignments, but given that
+constraint you are free to restructure or rewrite kernel code however
+you wish.
@end itemize
@node Problem 2-1 Argument Passing
@item SYS_exit
@itemx void exit (int @var{status})
Terminates the current user program, returning @var{status} to the
-kernel. If the process's parent @func{join}s it, this is the status
+kernel. If the process's parent @func{wait}s for it, this is the status
that will be returned. Conventionally, a @var{status} of 0 indicates
a successful exit. Other values may be used to indicate user-defined
conditions (usually errors).
@item SYS_exec
-@itemx pid_t exec (const char *@var{file})
-Run the executable in @var{file} and return the new process's program
-id (pid). If there is an error loading this program, returns pid -1,
-which otherwise should not be a valid id number.
-
-@item SYS_join
-@itemx int join (pid_t @var{pid})
-Joins the process @var{pid}, using the join rules from the last
-assignment, and returns the process's exit status. If the process was
-terminated by the kernel (i.e.@: killed due to an exception), the exit
-status should be -1. If the process was not a child of the calling
-process, the return value is undefined (but kernel operation must not
-be disrupted).
+@itemx pid_t exec (const char *@var{cmd_line})
+Runs the executable whose name is given in @var{cmd_line}, passing any
+given arguments, and returns the new process's program id (pid). Must
+return pid -1, which otherwise should not be a valid program id, if
+there is an error loading this program.
+
+@item SYS_wait
+@itemx int wait (pid_t @var{pid})
+Waits for process @var{pid} to die and returns its exit status. If it
+was terminated by the kernel (i.e.@: killed due to an exception),
+returns -1. If @var{pid} is invalid or if it was not a child of the
+calling thread, or if @code{wait} has already been successfully
+called for the given @var{pid}, returns -1 immediately, without
+waiting.
+
+You must ensure that Pintos does not terminate until the initial
+process exits. The supplied Pintos code tries to do this by calling
+@func{process_wait} (in @file{userprog/process.c}) from @func{main}
+(in @file{threads/init.c}). We suggest that you implement
+@func{process_wait} according to the comment at the top of the
+function and then implement the @code{wait} system call in terms of
+@func{process_wait}.
+
+All of a process's resources, including its @struct{thread}, must be
+freed whether its parent ever waits for it or not, and regardless of
+whether the child exits before or after its parent.
+
+Children are not inherited, that is, if @var{A} has child @var{B} and
+@var{B} has child @var{C}, then @var{A} always returns immediately
+should it try to wait for @var{C}, even if @var{B} is dead.
+
+Consider all the ways a wait can occur: nested waits (@var{A} waits
+for @var{B}, then @var{B} waits for @var{C}), multiple waits (@var{A}
+waits for @var{B}, then @var{A} waits for @var{C}), and so on. Does
+your @func{wait} work if it is called on a process that has not yet
+been scheduled for the first time?
@item SYS_create
@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.
+in size. Returns true if successful, false otherwise.
@item SYS_remove
@itemx bool remove (const char *@var{file})
-Delete the file called @var{file}. Returns -1 if failed, 0 if OK.
+Delete the file called @var{file}. Returns true if successful, false
+otherwise.
@item SYS_open
@itemx int open (const char *@var{file})
@item SYS_read
@itemx int read (int @var{fd}, void *@var{buffer}, unsigned @var{size})
Read @var{size} bytes from the file open as @var{fd} into
-@var{buffer}. Returns the number of bytes actually read, or -1 if the
-file could not be read. 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}.
@item SYS_write
@itemx int write (int @var{fd}, const void *@var{buffer}, unsigned @var{size})
Write @var{size} bytes from @var{buffer} to the open file @var{fd}.
Returns the number of bytes actually written, or -1 if the file could
-not be written. Fd 1 writes to the console.
+not be written.
+
+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,
+lines of text output by different processes may end up interleaved on
+the console, confusing both human readers and our grading scripts.
@item SYS_seek
@itemx void seek (int @var{fd}, unsigned @var{position})
@var{position}, expressed in bytes from the beginning of the file.
(Thus, a @var{position} of 0 is the file's start.)
+A seek past the current end of a file is not an error. A later read
+obtains 0 bytes, indicating end of file. A later write extends the
+file, filling any unwritten gap with zeros. (However, in Pintos files
+have a fixed length until project 4 is complete, so writes past end of
+file will return an error.) These semantics are implemented in the
+file system and do not require any special effort in system call
+implementation.
+
@item SYS_tell
@itemx unsigned tell (int @var{fd})
Returns the position of the next byte to be read or written in open
writing and testing this code before implementing any other system
call functionality.
+@anchor{Synchronizing File Access}
You must make sure that system calls are properly synchronized so that
any number of user processes can make them at once. In particular, it
is not safe to call into the filesystem code provided in the
that @func{process_execute} also accesses files. @strong{For now, we
recommend against modifying code in the @file{filesys} directory.}
-We have provided you a function for each system call in
+We have provided you a user-level function for each system call in
@file{lib/user/syscall.c}. These provide a way for user processes to
-invoke each system call from a C program. Each of them calls an
-assembly language routine in @file{lib/user/syscall-stub.S}, which in
-turn invokes the system call interrupt and returns.
+invoke each system call from a C program. Each uses a little inline
+assembly code to invoke the system call and (if appropriate) returns the
+system call's return value.
When you're done with this part, and forevermore, Pintos should be
bulletproof. Nothing that a user program can do should ever cause the
-OS to crash, halt, assert fail, or otherwise stop running. The sole
-exception is a call to the @code{halt} system call.
+OS to crash, halt, assert fail, or otherwise stop running. It is
+important to emphasize this point: our tests will try to break your
+system calls in many, many ways. You need to think of all the corner
+cases and handle them. The sole way a user program should be able to
+cause the OS to halt is by invoking the @code{halt} system call.
If a system call is passed an invalid argument, acceptable options
include returning an error value (for those calls that return a
@item
@b{Do we need a working project 1 to implement project 2?}
-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.
+No.
@item
@b{@samp{pintos put} always panics.}
The disk hasn't yet been formatted (with @samp{pintos run -f}).
@item
-The filename specified is too long. The file system limits file names
+The file name specified is too long. The file system limits file names
to 14 characters. If you're using a command like @samp{pintos put
../../tests/userprog/echo}, that overflows the limit. Use
@samp{pintos put ../../tests/userprog/echo echo} to put the file under
the name @file{echo} instead.
@item
-The file is too big. The file system has a 63 kB limit.
+The file system is full.
+
+@item
+The file system already contains 10 files. (There's a 10-file limit for
+the base Pintos file system.)
+
+@item
+The file system is so fragmented that there's not enough contiguous
+space for your file.
@end itemize
@item
@samp{system call!}.}
Every reasonable program tries to make at least one system call
-(@func{exit}) and most programs make more than that. The default
+(@func{exit}) and most programs make more than that. Notably,
+@func{printf} invokes the @code{write} system call. The default
system call handler just prints @samp{system call!} and terminates the
program. You'll have to implement 2-2 before you see anything more
interesting. Until then, you can use @func{hex_dump} to convince
in the kernel.
A @code{pid_t} identifies a user process. It is used by user
-processes and the kernel in the @code{exec} and @code{join} system
+processes and the kernel in the @code{exec} and @code{wait} system
calls.
You can choose whatever suitable types you like for @code{tid_t} and
Returns true if successful, false if USRC is invalid. */
static inline bool get_user (uint8_t *dst, const uint8_t *usrc) {
int eax;
- asm ("movl $1f, %%eax; movb %2, %%al; movb %%al, %0; 1:"
+ asm ("mov %%eax, offset 1f; mov %%al, %2; mov %0, %%al; 1:"
: "=m" (*dst), "=&a" (eax) : "m" (*usrc));
return eax != 0;
}
Returns true if successful, false if UDST is invalid. */
static inline bool put_user (uint8_t *udst, uint8_t byte) {
int eax;
- asm ("movl $1f, %%eax; movb %b2, %0; 1:"
+ asm ("mov %%eax, offset 1f; mov %0, %b2; 1:"
: "=m" (*udst), "=&a" (eax) : "r" (byte));
return eax != 0;
}
pointer so that it is word-aligned: that is, we move it down to the
next 4-byte boundary. This is required because we will next be
placing several words of data on the stack, and they must be aligned
-in order to be read correctly. In our example, as you'll see below,
+to be read correctly. In our example, as you'll see below,
the strings start at address @t{0xffed}. One word below that would be
at @t{0xffe9}, so we could in theory put the next word on the stack
there. However, since the stack pointer should always be
The 80@var{x}86 convention for function return values is to place them
in the @samp{EAX} register. System calls that return a value can do
so by modifying the @samp{eax} member of @struct{intr_frame}.
+
+You should try to avoid writing large amounts of repetitive code for
+implementing system calls. Each system call argument, whether an
+integer or a pointer, takes up 4 bytes on the stack. You should be able
+to take advantage of this to avoid writing much near-identical code for
+retrieving each system call's arguments from the stack.
projects / pintos-anon / blobdiff