1 @node Project 2--User Programs, Project 3--Virtual Memory, Project 1--Threads, Top
2 @chapter Project 2: User Programs
4 Now that you've worked with Pintos and are familiar with its
5 infrastructure and thread package, it's time to start working on the
6 parts of the system that will allow users to run programs on top of
7 your operating system. The base code already supports loading and
8 running a single user program at a time with little interactivity
9 possible. You will allow multiple programs to be loaded in at once,
10 and to interact with the OS via system calls.
12 You will be working out of the @file{userprog} directory for this
13 assignment. However, you will also be interacting with almost every
14 other part of the code for this assignment. We will describe the
15 relevant parts below. If you are confident in your HW1 code, you can
16 build on top of it. However, if you wish you can start with a fresh
17 copy of the code and re-implement @code{thread_join()}, which is the
18 only part of project #1 required for this assignment.
20 Up to now, all of the code you have written for Pintos has been part
21 of the operating system kernel. This means, for example, that all the
22 test code from the last assignment ran as part of the kernel, with
23 full access to privileged parts of the system. Once we start running
24 user programs on top of the operating system, this is no longer true.
25 This project deals with consequences of the change.
27 We allow more than one user program to run at a time. Because user
28 programs are written and compiled to work under the illusion that they
29 have the entire machine, when you load into memory and run more than
30 one process at a time, you must manage things correctly to maintain
34 Before we delve into the details of the new code that you'll be
35 working with, you should probably undo the test cases from project 1.
36 All you need to do is make sure the original @file{threads/test.c} is
37 in place. This will stop the tests from being run.
41 * Using the File System::
42 * How User Programs Work::
43 * Global Requirements::
44 * Problem 2-1 Argument Passing::
45 * Problem 2-2 System Calls::
47 * 80x86 Calling Convention::
54 The easiest way to get an overview of the programming you will be
55 doing is to simply go over each part you'll be working with. In
56 @file{userprog}, you'll find a small number of files, but here is
57 where the bulk of your work will be:
62 An address space keeps track of all the data necessary to execute a
63 user program. Address space data is stored in @code{struct thread},
64 but manipulated only by @file{addrspace.c}. Address spaces need to
65 keep track of things like paging information for the process (so that
66 it knows which memory the process is using). Address spaces also
67 handle loading the program into memory and starting up the process's
72 Whenever a user process wants to access some kernel functionality, it
73 needs to do so via a system call. This is a skeleton system call
74 handler. Currently, it just prints a message and terminates the user
75 process. In part 2 of this project you will add code to do everything
76 else needed by system calls.
80 When a user process performs a privileged or prohibited operation, it
81 traps into the kernel as an ``exception'' or ``fault.''@footnote{We
82 will treat these terms as synonymous. There is no standard
83 distinction between them, although the Intel processor manuals define
84 them slightly differently on 80@var{x}86.} These files handle
85 exceptions. Currently all exceptions simply print a message and
86 terminate the process. @strong{You should not need to modify this
91 The 80@var{x}86 is a segmented architecture. The Global Descriptor
92 Table (GDT) is a table that describes the segments in use. These
93 files set up the GDT. @strong{You should not need to modify these
94 files for any of the projects.} However, you can read the code if
95 you're interested in how the GDT works.
99 The Task-State Segment (TSS) is used for 80@var{x}86 architectural
100 task switching. Pintos uses the TSS only for switching stacks when a
101 user process enters an interrupt handler, as does Linux. @strong{You
102 should not need to modify these files for any of the projects.}
103 However, you can read the code if you're interested in how the GDT
107 Finally, in @file{lib/kernel}, you might want to use
108 @file{bitmap.[ch]}. A bitmap is basically an array of bits, each of
109 which can be true or false. Bitmaps are typically used to keep track
110 of the usage of a large array of (identical) resources: if resource
111 @var{n} is in use, then bit @var{n} of the bitmap is true. You might
112 find it useful for tracking memory pages, for example.
114 @node Using the File System
115 @section Using the File System
117 You will need to use some file system code for this project. First,
118 user programs are loaded from the file system. Second, many of the
119 system calls you must implement deal with the file system. However,
120 the focus of this project is not on the file system code, so we have
121 provided a simple file system in the @file{filesys} directory. You
122 will want to look over the @file{filesys.h} and @file{file.h}
123 interfaces to understand how to use the file system. @strong{You
124 should not modify the file system code for this project}. Proper use
125 of the file system routines now will make life much easier for project
126 4, when you improve the file system implementation.
128 You need to be able to create and format simulated disks. The
129 @command{pintos} program provides this functionality with its
130 @option{make-disk} command. From the @file{filesys/build} directory,
131 execute @code{pintos make-disk fs.dsk 2}. This command creates a 2 MB
132 simulated disk named @file{fs.dsk}. (It does not actually start
133 Pintos.) Then format the disk by passing the @option{-f} option to
134 Pintos on the kernel's command line: @code{pintos run -f}.
136 You'll need a way to get files in and out of the simulated file
137 system. The @code{pintos} @option{put} and @option{get} commands are
138 designed for this. To copy @file{@var{file}} into the Pintos file
139 system, use the command @file{pintos put @var{file}}. To copy it to
140 the Pintos file system under the name @file{@var{newname}}, add the
141 new name to the end of the command: @file{pintos put @var{file}
142 @var{newname}}. The commands for copying files out of a VM are
143 similar, but substitute @option{get} for @option{get}.
145 Incidentally, these commands work by passing special options
146 @option{-ci} and @option{-co} on the kernel's command line and copying
147 to and from a special simulated disk named @file{scratch.dsk}. If
148 you're very curious, you can look at the @command{pintos} program as
149 well as @file{filesys/fsutil.c} to learn the implementation details,
150 but it's really not relevant for this project.
152 You can delete a file from the Pintos file system using the @option{-r
153 @var{file}} kernel option, e.g.@: @code{pintos run -r @var{file}}.
154 Also, @option{-ls} lists the files in the file system and @option{-p
155 @var{file}} prints a file's contents to the display.
157 @node How User Programs Work
158 @section How User Programs Work
160 Pintos can run normal C programs. In fact, it can run any program you
161 want, provided it's compiled into the proper file format, and uses
162 only the system calls you implement. (For example, @code{malloc()}
163 makes use of functionality that isn't provided by any of the syscalls
164 we require you to support.) The only other limitation is that Pintos
165 can't run programs using floating point operations, since it doesn't
166 include the necessary kernel functionality to save and restore the
167 processor's floating-point unit when switching threads. You can look
168 in @file{test} directory for some examples.
170 Pintos loads ELF executables, where ELF is an executable format used
171 by Linux, Solaris, and many other Unix and Unix-like systems.
172 Therefore, you can use any compiler and linker that produce
173 80@var{x}86 ELF executables to produce programs for Pintos. We
174 recommend using the tools we provide in the @file{tests} directory. By
175 default, the @file{Makefile} in this directory will compile the test
176 programs we provide. You can edit the @file{Makefile} to compile your
177 own test programs as well.
179 One thing you should realize immediately is that, until you use the
180 above operation to copy a test program to the emulated disk, Pintos
181 will be unable to do very much useful work. You will also find that
182 you won't be able to do interesting things until you copy a variety of
183 programs to the disk. A useful technique is to create a clean
184 reference disk and copy that over whenever you trash your
185 @file{fs.dsk} beyond a useful state, which may happen occasionally
188 @node Global Requirements
189 @section Global Requirements
191 For testing and grading purposes, we have some simple requirements for
192 your output. The kernel should print out the program's name and exit
193 status whenever a process exits. Aside from this, it should print out
194 no other messages. You may understand all those debug messages, but
195 we won't, and it just clutters our ability to see the stuff we care
198 Additionally, while it may be useful to hard-code which process will
199 run at startup while debugging, before you submit your code you must
200 make sure that it takes the start-up process name and arguments from
201 the @samp{-ex} argument. For example, running @code{pintos run -ex
202 "testprogram 1 2 3 4"} will spawn @samp{testprogram 1 2 3 4} as the
205 @node Problem 2-1 Argument Passing
206 @section Problem 2-1: Argument Passing
208 Currently, @code{thread_execute()} does not support passing arguments
209 to new processes. UNIX and other operating systems do allow passing
210 command line arguments to a program, which accesses them via the argc,
211 argv arguments to main. You must implement this functionality by
212 extending @code{thread_execute()} so that instead of simply taking a
213 program file name, it can take a program name with arguments as a
214 single string. That is, @code{thread_execute("grep foo *.c")} should
215 be a legal call. @xref{80x86 Calling Convention}, for information on
216 exactly how this works.
218 @strong{This functionality is extremely important.} Almost all our
219 test cases rely on being able to pass arguments, so if you don't get
220 this right, a lot of things will not appear to work correctly with our
221 tests. If the tests fail, so do you. Fortunately, this part
222 shouldn't be too hard.
224 @node Problem 2-2 System Calls
225 @section Problem 2-2: System Calls
227 Implement the system call handler in @file{userprog/syscall.c} to
228 properly deal with all the system calls described below. Currently,
229 it ``handles'' system calls by terminating the process. You will need
230 to decipher system call arguments and take the appropriate action for
233 You are required to support the following system calls, whose syscall
234 numbers are defined in @file{lib/syscall-nr.h} and whose C functions
235 called by user programs are prototyped in @file{lib/user/syscall.h}:
239 @itemx void halt (void)
240 Stops Pintos and prints out performance statistics. Note that this
241 should be seldom used, since then you lose some information about
242 possible deadlock situations, etc.
245 @itemx void exit (int @var{status})
246 Terminates the current user program, returning @var{status} to the
247 kernel. A @var{status} of 0 indicates a successful exit. Other
248 values may be used to indicate user-defined error conditions.
251 @itemx pid_t exec (const char *@var{file})
252 Run the executable in @var{file} and return the new process's program
253 id (pid). If there is an error loading this program, returns pid -1,
254 which otherwise should not be a valid id number.
257 @itemx int join (pid_t @var{pid})
258 Joins the process @var{pid}, using the join rules from the last
259 assignment, and returns the process's exit status. If the process was
260 terminated by the kernel (i.e.@: killed due to an exception), the exit
261 status should be -1. If the process was not a child of the calling
262 process, the return value is undefined (but kernel operation must not
266 @itemx bool create (const char *@var{file})
267 Create a new file called @var{file}. Returns -1 if failed, 0 if OK.
270 @itemx bool remove (const char *@var{file})
271 Delete the file called @var{file}. Returns -1 if failed, 0 if OK.
274 @itemx int open (const char *@var{file})
275 Open the file called @var{file}. Returns a nonnegative integer handle
276 called a ``file descriptor'' (fd), or -1 if the file could not be
277 opened. File descriptors numbered 0 and 1 are reserved for the
278 console. All open files associated with a process should be closed
279 when the process exits or is terminated.
282 @itemx int filesize (int @var{fd})
283 Returns the size, in bytes, of the file open as @var{fd}, or -1 if the
287 @itemx int read (int @var{fd}, void *@var{buffer}, unsigned @var{size})
288 Read @var{size} bytes from the file open as @var{fd} into
289 @var{buffer}. Returns the number of bytes actually read, or -1 if the
290 file could not be read.
293 @itemx int write (int @var{fd}, const void *@var{buffer}, unsigned @var{size})
294 Write @var{size} bytes from @var{buffer} to the open file @var{fd}.
295 Returns the number of bytes actually written, or -1 if the file could
299 @itemx void seek (int @var{fd}, unsigned @var{position})
300 Changes the next byte to be read or written in open file @var{fd} to
301 @var{position}, expressed in bytes from the beginning of the file.
302 (Thus, a @var{position} of 0 is the file's start.)
305 @itemx unsigned tell (int @var{fd})
306 Returns the position of the next byte to be read or written in open
307 file @var{fd}, expressed in bytes from the beginning of the file.
310 @itemx void close (int @var{fd})
311 Close file descriptor @var{fd}.
314 The file defines other syscalls. Ignore them for now. You will
315 implement some of them in project 3 and the rest in project 4, so be
316 sure to design your system with extensibility in mind.
318 To implement syscalls, you will need to provide a way of copying data
319 from the user's virtual address space into the kernel and vice versa.
320 This can be a bit tricky: what if the user provides an invalid
321 pointer, a pointer into kernel memory, or points to a block that is
322 partially in one of those regions? You should handle these cases by
323 terminating the user process. You will need this code before you can
324 even obtain the system call number, because the system call number is
325 on the user's stack in the user's virtual address space. We recommend
326 writing and testing this code before implementing any other system
329 You must make sure that system calls are properly synchronized so that
330 any number of user processes can make them at once. In particular, it
331 is not safe to call into the filesystem code provided in the
332 @file{filesys} directory from multiple threads at once. For now, we
333 recommend adding a single lock that controls access to the filesystem
334 code. You should acquire this lock before calling any functions in
335 the @file{filesys} directory, and release it afterward. Don't forget
336 that @file{addrspace_load()} also accesses files. @strong{For now, we
337 recommend against modifying code in the @file{filesys} directory.}
339 We have provided you a function for each system call in
340 @file{lib/user/syscall.c}. These provide a way for user processes to
341 invoke each system call from a C program. Each of them calls an
342 assembly language routine in @file{lib/user/syscall-stub.S}, which in
343 turn invokes the system call interrupt and returns.
345 When you're done with this part, and forevermore, Pintos should be
346 bulletproof. Nothing that a user program can do should ever cause the
347 OS to crash, halt, assert fail, or otherwise stop running. The sole
348 exception is a call to the @code{halt} system call.
350 @xref{System Calls}, for more information on how syscalls work.
352 @node User Programs FAQ
360 @b{Do we need a working project 1 to implement project 2?}
362 You may find the code for @code{thread_join()} to be useful in
363 implementing the join syscall, but besides that, you can use
364 the original code provided for project 1.
367 @b{Is there a way I can disassemble user programs?}
369 The @command{i386-elf-objdump} utility can disassemble entire user
370 programs or object files. Invoke it as @code{i386-elf-objdump -d
371 @var{file}}. You can also use @code{i386-elf-gdb}'s
372 @command{disassemble} command to disassemble individual functions in
373 object files compiled with debug information.
376 @b{Why can't I use many C include files in my Pintos programs?}
378 The C library we provide is very limited. It does not include many of
379 the features that are expected of a real operating system's C library.
380 The C library must be built specifically for the operating system (and
381 architecture), since it must make system calls for I/O and memory
382 allocation. (Not all functions do, of course, but usually the library
383 is compiled as a unit.) If you wish to port libraries to Pintos, feel
387 @b{How do I compile new user programs? How do I make 'echo' compile?}
389 You need to modify @file{tests/Makefile}.
392 @b{What's the difference between @code{tid_t} and @code{pid_t}?}
394 A @code{tid_t} identifies a kernel thread, which may have a user
395 process running in it (if created with @code{thread_execute()}) or not
396 (if created with @code{thread_create()}). It is a data type used only
399 A @code{pid_t} identifies a user process. It is used by user
400 processes and the kernel in the @code{exec} and @code{join} system
403 You can choose whatever suitable types you like for @code{tid_t} and
404 @code{pid_t}. By default, they're both @code{int}. You can make them
405 a one-to-one mapping, so that the same values in both identify the
406 same process, or you can use a more complex mapping. It's up to you.
409 @b{I can't seem to figure out how to read from and write to
410 memory. What should I do?}
412 Here are some pointers:
417 @b{I'm also confused about reading from and writing to the stack. Can
424 Only non-@samp{char} values will have issues when writing them to
425 memory. If a digit is in a string, it is considered a character.
426 However, the value of @code{argc} would be a non-char.
429 You will need to write characters and non-characters into main memory.
432 When you add items to the stack, you will be decrementing the stack
433 pointer. You'll need to decrement the stack pointer before writing to
437 Each character is 1 byte.
441 @item Argument Passing FAQs
445 @b{What will be the format of command line arguments?}
447 You should assume that command line arguments are delimited by white
451 @b{What is the maximum length of the command line arguments?}
453 You can impose some reasonable maximum as long as you're prepared to
454 defend it in your @file{DESIGNDOC}.
457 @b{How do I parse all these argument strings?}
459 You're welcome to use any technique you please, as long as it works.
460 If you're lost, look at @code{strtok_r()}, prototyped in
461 @file{lib/string.h} and implemented with thorough comments in
462 @file{lib/string.c}. You can find more about it by looking at the man
463 page (run @code{man strtok_r} at the prompt).
466 @b{Why is the top of the stack at @t{0xc0000000}? Isn't that off the
467 top of user virtual memory? Shouldn't it be @t{0xbfffffff}?}
469 When the processor pushes data on the stack, it decrements the stack
470 pointer first. Thus, the first (4-byte) value pushed on the stack
471 will be at address @t{0xbffffffc}.
473 Also, the stack should always be aligned to a 4-byte boundary, but
474 @t{0xbfffffff} isn't.
477 @b{Is @code{PHYS_BASE} fixed?}
479 No. You should be able to support @code{PHYS_BASE} values that are
480 any multiple of @t{0x10000000} from @t{0x80000000} to @t{0xc0000000},
481 simply via recompilation.
484 @item System Calls FAQs
488 @b{What should I do with the parameter passed to @code{exit()}?}
490 This value, the exit status of the process, must be returned to the
491 thread's parent when @code{join()} is called.
494 @b{Can I just cast a pointer to a @code{struct file} object to get a
495 unique file descriptor? Can I just cast a @code{struct thread *} to a
496 @code{pid_t}? It's so much simpler that way!}
498 This is a design decision you will have to make for yourself.
499 However, note that most operating systems do distinguish between file
500 descriptors (or pids) and the addresses of their kernel data
501 structures. You might want to give some thought as to why they do so
502 before committing yourself.
505 @b{Can I set a maximum number of open files per process?}
507 From a design standpoint, it would be better not to set an arbitrary
508 maximum. That said, if your design calls for it, you may impose a
509 limit of 128 open files per process (as the Solaris machines here do).
512 @b{What happens when two (or more) processes have a file open and one of
515 You should copy the standard Unix semantics for files. That is, when
516 a file is removed an process which has a file descriptor for that file
517 may continue to do operations on that descriptor. This means that
518 they can read and write from the file. The file will not have a name,
519 and no other processes will be able to open it, but it will continue
520 to exist until all file descriptors referring to the file are closed
521 or the machine shuts down.
524 @b{What happens if a system call is passed an invalid argument, such
525 as Open being called with an invalid filename?}
527 Pintos should not crash. Acceptable options include returning an
528 error value (for those calls that return a value), returning an
529 undefined value, or terminating the process.
532 @b{I've discovered that some of my user programs need more than one 4
533 kB page of stack space. What should I do?}
535 You may modify the stack setup code to allocate more than one page of
536 stack space for each process.
539 @b{What do I need to print on thread completion?}
541 You should print the complete thread name (as specified in the
542 @code{SYS_exec} call) followed by the exit status code,
543 e.g.@: @samp{example 1 2 3 4: 0}.
547 @node 80x86 Calling Convention
548 @section 80@var{x}86 Calling Convention
550 What follows is a quick and dirty discussion of the 80@var{x}86
551 calling convention. Some of the basics should be familiar from CS
552 107, and if you've already taken CS 143 or EE 182, then you should
553 have seen even more of it. I've omitted some of the complexity, since
554 this isn't a class in how function calls work, so don't expect this to
555 be exactly correct in full, gory detail. If you do want all the
556 details, you can refer to @cite{[SysV-i386]}.
558 Whenever a function call happens, you need to put the arguments on the
559 call stack for that function, before the code for that function
560 executes, so that the callee has access to those values. The caller
561 has to be responsible for this (be sure you understand why).
562 Therefore, when you compile a program, the assembly code emitted will
563 have in it, before every function call, a bunch of instructions that
564 prepares for the call in whatever manner is conventional for the
565 machine you're working on. This includes saving registers as needed,
566 putting stuff on the stack, saving the location to return to somewhere
567 (so that when the callee finishes, it knows where the caller code is),
568 and some other bookkeeping stuff. Then you do the jump to the
569 callee's code, and it goes along, assuming that the stack and
570 registers are prepared in the appropriate manner. When the callee is
571 done, it looks at the return location as saved earlier, and jumps back
572 to that location. The caller may then have to do some cleanup:
573 clearing arguments and the return value off the stack, restoring
574 registers that were saved before the call, and so on.
576 If you think about it, some of these things should remind you of
579 As an aside, in general, function calls are not cheap. You have to do
580 a bunch of memory writes to prepare the stack, you need to save and
581 restore registers before and after a function call, you need to write
582 the stack pointer, you have a couple of jumps which probably wrecks
583 some of your caches. This is why inlining code can be much faster.
586 * Argument Passing to main::
589 @node Argument Passing to main
590 @subsection Argument Passing to @code{main()}
592 In @code{main()}'s case, there is no caller to prepare the stack
593 before it runs. Therefore, the kernel needs to do it. Fortunately,
594 since there's no caller, there are no registers to save, no return
595 address to deal with, etc. The only difficult detail to take care of,
596 after loading the code, is putting the arguments to @code{main()} on
599 (The above is a small lie: most compilers will emit code where main
600 isn't strictly speaking the first function. This isn't an important
601 detail. If you want to look into it more, try disassembling a program
602 and looking around a bit. However, you can just act as if
603 @code{main()} is the very first function called.)
605 Pintos is written for the 80@var{x}86 architecture. Therefore, we
606 need to adhere to the 80@var{x}86 calling convention. Basically, you
607 put all the arguments on the stack and move the stack pointer
608 appropriately. You also need to insert space for the function's
609 ``return address'': even though the initial function doesn't really
610 have a caller, its stack frame must have the same layout as any other
611 function's. The program will assume that the stack has been laid out
612 this way when it begins running.
614 So, what are the arguments to @code{main()}? Just two: an @samp{int}
615 (@code{argc}) and a @samp{char **} (@code{argv}). @code{argv} is an
616 array of strings, and @code{argc} is the number of strings in that
617 array. However, the hard part isn't these two things. The hard part
618 is getting all the individual strings in the right place. As we go
619 through the procedure, let us consider the following example command:
620 @samp{/bin/ls -l *.h *.c}.
622 The first thing to do is to break the command line into individual
623 strings: @samp{/bin/ls}, @samp{-l}, @samp{*.h}, and @samp{*.c}. These
624 constitute the arguments of the command, including the program name
625 itself (which belongs in @code{argv[0]}).
627 These individual, null-terminated strings should be placed on the user
628 stack. They may be placed in any order, as you'll see shortly,
629 without affecting how main works, but for simplicity let's assume they
630 are in reverse order (keeping in mind that the stack grows downward on
631 an 80@var{x}86 machine). As we copy the strings onto the stack, we
632 record their (virtual) stack addresses. These addresses will become
633 important when we write the argument vector (two paragraphs down).
635 After we push all of the strings onto the stack, we adjust the stack
636 pointer so that it is word-aligned: that is, we move it down to the
637 next 4-byte boundary. This is required because we will next be
638 placing several words of data on the stack, and they must be aligned
639 in order to be read correctly. In our example, as you'll see below,
640 the strings start at address @t{0xffed}. One word below that would be
641 at @t{0xffe9}, so we could in theory put the next word on the stack
642 there. However, since the stack pointer should always be
643 word-aligned, we instead leave the stack pointer at @t{0xffe8}.
645 Once we align the stack pointer, we then push the elements of the
646 argument vector, that is, a null pointer, then the addresses of the
647 strings @samp{/bin/ls}, @samp{-l}, @samp{*.h}, and @samp{*.c}) onto
648 the stack. This must be done in reverse order, such that
649 @code{argv[0]} is at the lowest virtual address, again because the
650 stack is growing downward. (The null pointer pushed first is because
651 @code{argv[argc]} must be a null pointer.) This is because we are now
652 writing the actual array of strings; if we write them in the wrong
653 order, then the strings will be in the wrong order in the array. This
654 is also why, strictly speaking, it doesn't matter what order the
655 strings themselves are placed on the stack: as long as the pointers
656 are in the right order, the strings themselves can really be anywhere.
657 After we finish, we note the stack address of the first element of the
658 argument vector, which is @code{argv} itself.
660 Then we push @code{argv} (that is, the address of the first element of
661 the @code{argv} array) onto the stack, along with the length of the
662 argument vector (@code{argc}, 4 in this example). This must also be
663 done in this order, since @code{argc} is the first argument to
664 @code{main()} and therefore is on first (smaller address) on the
665 stack. Finally, we push a fake ``return address'' and leave the stack
666 pointer to point to its location.
668 All this may sound very confusing, so here's a picture which will
669 hopefully clarify what's going on. This represents the state of the
670 stack and the relevant registers right before the beginning of the
671 user program (assuming for this example that the stack bottom is
677 @multitable {@t{0xbfffffff}} {``return address''} {@t{/bin/ls\0}}
678 @item Address @tab Name @tab Data
679 @item @t{0xbffffffc} @tab @code{*argv[3]} @tab @samp{*.c\0}
680 @item @t{0xbffffff8} @tab @code{*argv[2]} @tab @samp{*.h\0}
681 @item @t{0xbffffff5} @tab @code{*argv[1]} @tab @samp{-l\0}
682 @item @t{0xbfffffed} @tab @code{*argv[0]} @tab @samp{/bin/ls\0}
683 @item @t{0xbfffffec} @tab word-align @tab @samp{\0}
684 @item @t{0xbfffffe8} @tab @code{argv[4]} @tab @t{0}
685 @item @t{0xbfffffe4} @tab @code{argv[3]} @tab @t{0xbffffffc}
686 @item @t{0xbfffffe0} @tab @code{argv[2]} @tab @t{0xbffffff8}
687 @item @t{0xbfffffdc} @tab @code{argv[1]} @tab @t{0xbffffff5}
688 @item @t{0xbfffffd8} @tab @code{argv[0]} @tab @t{0xbfffffed}
689 @item @t{0xbfffffd4} @tab @code{argv} @tab @t{0xbffffffd8}
690 @item @t{0xbfffffd0} @tab @code{argc} @tab 4
691 @item @t{0xbfffffcc} @tab ``return address'' @tab 0
697 In this example, the stack pointer would be initialized to
700 As shown above, your code should start the stack at the very top of
701 the user virtual address space, in the page just below virtual address
702 @code{PHYS_BASE} (defined in @file{threads/mmu.h}).
704 You may find the non-standard @code{hex_dump()} function, declared in
705 @file{<stdio.h>}, useful for debugging your argument passing code.
706 Here's what it would show in the above example, given that
707 @code{PHYS_BASE} is @t{0xc0000000}, so that the dump starts at virtual
708 address @t{0xbfffffcc}:
711 00 00 00 00 04 00 00 00-d8 ff ff bf ed ff ff bf |................|
712 f5 ff ff bf f8 ff ff bf-fc ff ff bf 00 00 00 00 |................|
713 00 2f 62 69 6e 2f 6c 73-00 2d 6c 00 2a 2e 68 00 |./bin/ls.-l.*.h.|
718 @section System Calls
720 We have already been dealing with one way that the operating system
721 can regain control from a user program: interrupts from timers and I/O
722 devices. These are ``external'' interrupts, because they are caused
723 by entities outside the CPU.
725 The operating system is also called to deal with software exceptions,
726 which are events generated in response to the code. These can be
727 errors such as a page fault or division by zero. However, exceptions
728 are also the means by which a user program can request services
729 (``system calls'') from the operating system.
731 In the 80@var{x}86 architecture, the @samp{int} instruction is the
732 most commonly used means for invoking system calls. This instruction
733 is handled in the same way as other software exceptions. In Pintos,
734 user program invoke @samp{int $0x30} to make a system call. The
735 system call number and any additional arguments are expected to be
736 pushed on the stack in the normal fashion before invoking the
739 The normal calling convention pushes function arguments on the stack
740 from right to left and the stack grows downward. Thus, when the
741 system call handler @code{syscall_handler()} gets control, the system
742 call number is in the 32-bit word at the caller's stack pointer, the
743 first argument is in the 32-bit word at the next higher address, and
744 so on. The caller's stack pointer is accessible to
745 @code{syscall_handler()} as the @samp{esp} member of the @code{struct
746 intr_frame} passed to it.
748 Here's an example stack frame for calling a system call numbered 10
749 with three arguments passed as 1, 2, and 3. The stack addresses are
755 @multitable {Address} {Value}
756 @item Address @tab Value
757 @item @t{0xbffffe7c} @tab 3
758 @item @t{0xbffffe78} @tab 2
759 @item @t{0xbffffe74} @tab 1
760 @item @t{0xbffffe70} @tab 10
766 In this example, the caller's stack pointer would be at
769 The 80@var{x}86 convention for function return values is to place them
770 in the @samp{EAX} register. System calls that return a value can do
771 so by modifying the @samp{eax} member of @code{struct intr_frame}.