X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fuserprog.texi;h=0746b2e68f791af7545793a3458bd5d6ed4851a3;hb=0f5c19ccf179b35b39ae46dffec60592baeeec00;hp=38810e72f4c3bab38e960a6ab6d6cef0145b642f;hpb=c9490e43447da80e36d37adc432494238997009e;p=pintos-anon diff --git a/doc/userprog.texi b/doc/userprog.texi index 38810e7..0746b2e 100644 --- a/doc/userprog.texi +++ b/doc/userprog.texi @@ -247,11 +247,32 @@ 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 @@ -341,10 +362,11 @@ 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. +@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). If +there is an error loading this program, may return pid -1, which +otherwise should not be a valid id number. @item SYS_join @itemx int join (pid_t @var{pid}) @@ -384,8 +406,9 @@ Returns the size, in bytes, of the file open as @var{fd}. @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 @@ -400,6 +423,14 @@ Changes the next byte to be read or written in open file @var{fd} to @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 @@ -435,7 +466,7 @@ the @file{filesys} directory, and release it afterward. Don't forget 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 @@ -496,7 +527,8 @@ isn't properly set up yet, this causes a page fault. @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 @@ -807,7 +839,7 @@ After we push all of the strings onto the stack, we adjust the stack 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 @@ -939,3 +971,9 @@ In this example, the caller's stack pointer would be at 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.