From: Ben Pfaff Date: Sun, 8 Jan 2006 01:08:06 +0000 (+0000) Subject: Add explanatory comments to userprog tests. X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f0c22ece2e3d6864ac6585cf72e3c38fc3c1b3e8;p=pintos-anon Add explanatory comments to userprog tests. --- diff --git a/src/tests/userprog/args.c b/src/tests/userprog/args.c index 504b1c2..20eda44 100644 --- a/src/tests/userprog/args.c +++ b/src/tests/userprog/args.c @@ -1,3 +1,8 @@ +/* Prints the command-line arguments. + This program is used for all of the args-* tests. Grading is + done differently for each of the args-* tests based on the + output. */ + #include "tests/lib.h" int diff --git a/src/tests/userprog/boundary.c b/src/tests/userprog/boundary.c index 50f2618..59907ec 100644 --- a/src/tests/userprog/boundary.c +++ b/src/tests/userprog/boundary.c @@ -1,3 +1,7 @@ +/* Utility function for tests that try to break system calls by + passing them data that crosses from one virtual page to + another. */ + #include #include #include diff --git a/src/tests/userprog/child-bad.c b/src/tests/userprog/child-bad.c index 185617c..77d7a69 100644 --- a/src/tests/userprog/child-bad.c +++ b/src/tests/userprog/child-bad.c @@ -1,3 +1,8 @@ +/* Child process run by wait-killed test. + Sets the stack pointer (%esp) to an invalid value and invokes + a system call, which should then terminate the process with a + -1 exit code. */ + #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/child-close.c b/src/tests/userprog/child-close.c index 83e3d06..ac948c8 100644 --- a/src/tests/userprog/child-close.c +++ b/src/tests/userprog/child-close.c @@ -1,3 +1,12 @@ +/* Child process run by multi-child-fd test. + + Attempts to close the file descriptor passed as the first + command-line argument. This is invalid, because file + descriptors are not inherited in Pintos. Two results are + allowed: either the system call should return without taking + any action, or the kernel should terminate the process with a + -1 exit code. */ + #include #include #include diff --git a/src/tests/userprog/child-rox.c b/src/tests/userprog/child-rox.c index fdff97b..aba808b 100644 --- a/src/tests/userprog/child-rox.c +++ b/src/tests/userprog/child-rox.c @@ -1,3 +1,9 @@ +/* Child process run by rox-child and rox-multichild tests. + Opens and tries to write to its own executable, verifying that + that is disallowed. + Then recursively executes itself to the depth indicated by the + first command-line argument. */ + #include #include #include diff --git a/src/tests/userprog/child-simple.c b/src/tests/userprog/child-simple.c index eb4cb63..0d2dacf 100644 --- a/src/tests/userprog/child-simple.c +++ b/src/tests/userprog/child-simple.c @@ -1,3 +1,7 @@ +/* Child process run by exec-multiple, exec-one, wait-simple, and + wait-twice tests. + Just prints a single message and terminates. */ + #include #include "tests/lib.h" diff --git a/src/tests/userprog/close-bad-fd.c b/src/tests/userprog/close-bad-fd.c index a69cdfd..f63bb9a 100644 --- a/src/tests/userprog/close-bad-fd.c +++ b/src/tests/userprog/close-bad-fd.c @@ -1,3 +1,6 @@ +/* Tries to close an invalid fd, which must either fail silently + or terminate with exit code -1. */ + #include #include "tests/main.h" diff --git a/src/tests/userprog/close-normal.c b/src/tests/userprog/close-normal.c index 0fb2006..8ce04e3 100644 --- a/src/tests/userprog/close-normal.c +++ b/src/tests/userprog/close-normal.c @@ -1,3 +1,5 @@ +/* Opens a file and then closes it. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/close-stdin.c b/src/tests/userprog/close-stdin.c index 0b64ef9..9bbf9f2 100644 --- a/src/tests/userprog/close-stdin.c +++ b/src/tests/userprog/close-stdin.c @@ -1,3 +1,6 @@ +/* Tries to close the keyboard input stream, which must either + fail silently or terminate with exit code -1. */ + #include #include "tests/main.h" diff --git a/src/tests/userprog/close-stdout.c b/src/tests/userprog/close-stdout.c index 72f30d7..886523f 100644 --- a/src/tests/userprog/close-stdout.c +++ b/src/tests/userprog/close-stdout.c @@ -1,3 +1,6 @@ +/* Tries to close the console output stream, which must either + fail silently or terminate with exit code -1. */ + #include #include "tests/main.h" diff --git a/src/tests/userprog/close-twice.c b/src/tests/userprog/close-twice.c index d3f1e57..830bccf 100644 --- a/src/tests/userprog/close-twice.c +++ b/src/tests/userprog/close-twice.c @@ -1,3 +1,7 @@ +/* Opens a file and then tries to close it twice. The second + close must either fail silently or terminate with exit code + -1. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/create-bad-ptr.c b/src/tests/userprog/create-bad-ptr.c index f5df1f0..4a07bb3 100644 --- a/src/tests/userprog/create-bad-ptr.c +++ b/src/tests/userprog/create-bad-ptr.c @@ -1,3 +1,7 @@ +/* Passes a bad pointer to the create system call, + which must cause the process to be terminated with exit code + -1. */ + #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/create-bound.c b/src/tests/userprog/create-bound.c index 7ce0ae3..0a829f3 100644 --- a/src/tests/userprog/create-bound.c +++ b/src/tests/userprog/create-bound.c @@ -1,3 +1,6 @@ +/* Opens a file whose name spans the boundary between two pages. + This is valid, so it must succeed. */ + #include #include "tests/userprog/boundary.h" #include "tests/lib.h" diff --git a/src/tests/userprog/create-empty.c b/src/tests/userprog/create-empty.c index 4cb74d8..fa26b43 100644 --- a/src/tests/userprog/create-empty.c +++ b/src/tests/userprog/create-empty.c @@ -1,3 +1,5 @@ +/* Tries to create a file with the empty string as its name. */ + #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/create-exists.c b/src/tests/userprog/create-exists.c index a947ab7..d395008 100644 --- a/src/tests/userprog/create-exists.c +++ b/src/tests/userprog/create-exists.c @@ -1,3 +1,6 @@ +/* Verifies that trying to create a file under a name that + already exists will fail. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/create-long.c b/src/tests/userprog/create-long.c index 005a8b8..16b31bd 100644 --- a/src/tests/userprog/create-long.c +++ b/src/tests/userprog/create-long.c @@ -1,3 +1,6 @@ +/* Tries to create a file with a name that is much too long, + which must fail. */ + #include #include #include "tests/lib.h" diff --git a/src/tests/userprog/create-normal.c b/src/tests/userprog/create-normal.c index 10eba33..3cbc463 100644 --- a/src/tests/userprog/create-normal.c +++ b/src/tests/userprog/create-normal.c @@ -1,3 +1,5 @@ +/* Creates an ordinary empty file. */ + #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/create-null.c b/src/tests/userprog/create-null.c index 98b2bed..287cb23 100644 --- a/src/tests/userprog/create-null.c +++ b/src/tests/userprog/create-null.c @@ -1,3 +1,6 @@ +/* Tries to create a file with the null pointer as its name. + The process must be terminated with exit code -1. */ + #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/exec-arg.c b/src/tests/userprog/exec-arg.c index b49304e..82d0744 100644 --- a/src/tests/userprog/exec-arg.c +++ b/src/tests/userprog/exec-arg.c @@ -1,3 +1,5 @@ +/* Tests argument passing to child processes. */ + #include #include "tests/main.h" diff --git a/src/tests/userprog/exec-bad-ptr.c b/src/tests/userprog/exec-bad-ptr.c index a70c504..0abadd3 100644 --- a/src/tests/userprog/exec-bad-ptr.c +++ b/src/tests/userprog/exec-bad-ptr.c @@ -1,3 +1,6 @@ +/* Passes an invalid pointer to the exec system call. + The process must be terminated with -1 exit code. */ + #include #include "tests/main.h" diff --git a/src/tests/userprog/exec-missing.c b/src/tests/userprog/exec-missing.c index 53617e0..bf08cad 100644 --- a/src/tests/userprog/exec-missing.c +++ b/src/tests/userprog/exec-missing.c @@ -1,3 +1,6 @@ +/* Tries to execute a nonexistent process. + The exec system call must return -1. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/exec-multiple.c b/src/tests/userprog/exec-multiple.c index 02345fa..ba4c26e 100644 --- a/src/tests/userprog/exec-multiple.c +++ b/src/tests/userprog/exec-multiple.c @@ -1,3 +1,5 @@ +/* Executes and waits for multiple child processes. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/exec-once.c b/src/tests/userprog/exec-once.c index aa043fa..7bae5a1 100644 --- a/src/tests/userprog/exec-once.c +++ b/src/tests/userprog/exec-once.c @@ -1,3 +1,5 @@ +/* Executes and waits for a single child process. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/exit.c b/src/tests/userprog/exit.c index ca59969..cb4eb8f 100644 --- a/src/tests/userprog/exit.c +++ b/src/tests/userprog/exit.c @@ -1,3 +1,5 @@ +/* Tests the exit system call. */ + #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/halt.c b/src/tests/userprog/halt.c index b4fd9e1..4a99bce 100644 --- a/src/tests/userprog/halt.c +++ b/src/tests/userprog/halt.c @@ -1,3 +1,5 @@ +/* Tests the halt system call. */ + #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/multi-child-fd.c b/src/tests/userprog/multi-child-fd.c index 019708e..48de4b4 100644 --- a/src/tests/userprog/multi-child-fd.c +++ b/src/tests/userprog/multi-child-fd.c @@ -1,3 +1,8 @@ +/* Opens a file and then runs a subprocess that tries to close + the file. (Pintos does not have inheritance of file handles, + so this must fail.) The parent process then attempts to use + the file handle, which must succeed. */ + #include #include #include "tests/userprog/sample.inc" diff --git a/src/tests/userprog/multi-recurse.c b/src/tests/userprog/multi-recurse.c index 7786831..7172ec3 100644 --- a/src/tests/userprog/multi-recurse.c +++ b/src/tests/userprog/multi-recurse.c @@ -1,3 +1,6 @@ +/* Executes itself recursively to the depth indicated by the + first command-line argument. */ + #include #include #include @@ -10,8 +13,6 @@ int main (int argc UNUSED, char *argv[]) { int n = atoi (argv[1]); - if (n == 0) - n = atoi (argv[0]); msg ("begin %d", n); if (n != 0) diff --git a/src/tests/userprog/open-bad-ptr.c b/src/tests/userprog/open-bad-ptr.c index 8176aa2..9cd4edf 100644 --- a/src/tests/userprog/open-bad-ptr.c +++ b/src/tests/userprog/open-bad-ptr.c @@ -1,3 +1,6 @@ +/* Passes an invalid pointer to the open system call. + The process must be terminated with -1 exit code. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/open-boundary.c b/src/tests/userprog/open-boundary.c index adf04d8..cc8ff8b 100644 --- a/src/tests/userprog/open-boundary.c +++ b/src/tests/userprog/open-boundary.c @@ -1,3 +1,6 @@ +/* Creates a file whose name spans the boundary between two pages. + This is valid, so it must succeed. */ + #include #include "tests/userprog/boundary.h" #include "tests/lib.h" diff --git a/src/tests/userprog/open-empty.c b/src/tests/userprog/open-empty.c index 28e7b80..3ea9907 100644 --- a/src/tests/userprog/open-empty.c +++ b/src/tests/userprog/open-empty.c @@ -1,3 +1,5 @@ +/* Tries to open a file with the empty string as its name. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/open-missing.c b/src/tests/userprog/open-missing.c index 58661af..13ecbda 100644 --- a/src/tests/userprog/open-missing.c +++ b/src/tests/userprog/open-missing.c @@ -1,3 +1,5 @@ +/* Tries to open a nonexistent file. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/open-normal.c b/src/tests/userprog/open-normal.c index 4040fc2..5132465 100644 --- a/src/tests/userprog/open-normal.c +++ b/src/tests/userprog/open-normal.c @@ -1,3 +1,5 @@ +/* Open a file. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/open-null.c b/src/tests/userprog/open-null.c index ba30807..bb418b8 100644 --- a/src/tests/userprog/open-null.c +++ b/src/tests/userprog/open-null.c @@ -1,3 +1,6 @@ +/* Tries to open a file with the null pointer as its name. + The process must be terminated with exit code -1. */ + #include #include #include "tests/main.h" diff --git a/src/tests/userprog/open-twice.c b/src/tests/userprog/open-twice.c index c884191..dd333af 100644 --- a/src/tests/userprog/open-twice.c +++ b/src/tests/userprog/open-twice.c @@ -1,3 +1,7 @@ +/* Tries to open the same file twice, + which must succeed and must return a different file descriptor + in each case. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/read-bad-fd.c b/src/tests/userprog/read-bad-fd.c index 029f647..a8b190d 100644 --- a/src/tests/userprog/read-bad-fd.c +++ b/src/tests/userprog/read-bad-fd.c @@ -1,3 +1,7 @@ +/* Tries to read from an invalid fd, + which must either fail silently or terminate the process with + exit code -1. */ + #include #include #include "tests/lib.h" diff --git a/src/tests/userprog/read-bad-ptr.c b/src/tests/userprog/read-bad-ptr.c index 9506427..8fe756e 100644 --- a/src/tests/userprog/read-bad-ptr.c +++ b/src/tests/userprog/read-bad-ptr.c @@ -1,3 +1,6 @@ +/* Passes an invalid pointer to the read system call. + The process must be terminated with -1 exit code. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/read-boundary.c b/src/tests/userprog/read-boundary.c index b5843a8..9c19966 100644 --- a/src/tests/userprog/read-boundary.c +++ b/src/tests/userprog/read-boundary.c @@ -1,3 +1,6 @@ +/* Reads data spanning two pages in virtual address space, + which must succeed. */ + #include #include #include "tests/userprog/boundary.h" diff --git a/src/tests/userprog/read-normal.c b/src/tests/userprog/read-normal.c index a688818..16d15cc 100644 --- a/src/tests/userprog/read-normal.c +++ b/src/tests/userprog/read-normal.c @@ -1,3 +1,5 @@ +/* Try reading a file in the most normal way. */ + #include "tests/userprog/sample.inc" #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/read-stdout.c b/src/tests/userprog/read-stdout.c index 0018e4f..d0630b9 100644 --- a/src/tests/userprog/read-stdout.c +++ b/src/tests/userprog/read-stdout.c @@ -1,3 +1,7 @@ +/* Try reading from fd 1 (stdout), + which may just fail or terminate the process with -1 exit + code. */ + #include #include #include "tests/main.h" diff --git a/src/tests/userprog/read-zero.c b/src/tests/userprog/read-zero.c index db9d206..e441817 100644 --- a/src/tests/userprog/read-zero.c +++ b/src/tests/userprog/read-zero.c @@ -1,3 +1,6 @@ +/* Try a 0-byte read, which should return 0 without reading + anything. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/rox-child.c b/src/tests/userprog/rox-child.c index 257c4d9..30afba2 100644 --- a/src/tests/userprog/rox-child.c +++ b/src/tests/userprog/rox-child.c @@ -1,2 +1,5 @@ +/* Ensure that the executable of a running process cannot be + modified, even by a child process. */ + #define CHILD_CNT "1" #include "tests/userprog/rox-child.inc" diff --git a/src/tests/userprog/rox-multichild.c b/src/tests/userprog/rox-multichild.c index 602d767..8e74dab 100644 --- a/src/tests/userprog/rox-multichild.c +++ b/src/tests/userprog/rox-multichild.c @@ -1,2 +1,5 @@ +/* Ensure that the executable of a running process cannot be + modified, even in the presence of multiple children. */ + #define CHILD_CNT "5" #include "tests/userprog/rox-child.inc" diff --git a/src/tests/userprog/rox-simple.c b/src/tests/userprog/rox-simple.c index d024394..e84a064 100644 --- a/src/tests/userprog/rox-simple.c +++ b/src/tests/userprog/rox-simple.c @@ -1,3 +1,6 @@ +/* Ensure that the executable of a running process cannot be + modified. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/sc-bad-arg.c b/src/tests/userprog/sc-bad-arg.c index b990468..e0cad15 100644 --- a/src/tests/userprog/sc-bad-arg.c +++ b/src/tests/userprog/sc-bad-arg.c @@ -1,3 +1,9 @@ +/* Sticks a system call number (SYS_exit) at the very top of the + stack, then invokes a system call with the stack pointer + (%esp) set to its address. The process must be terminated + with -1 exit code because the argument to the system call + would be above the top of the user address space. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/sc-bad-sp.c b/src/tests/userprog/sc-bad-sp.c index 2ae20e9..56a5b8d 100644 --- a/src/tests/userprog/sc-bad-sp.c +++ b/src/tests/userprog/sc-bad-sp.c @@ -1,3 +1,7 @@ +/* Invokes a system call with the stack pointer (%esp) set to a + bad address. The process must be terminated with -1 exit + code. */ + #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/sc-boundary-2.c b/src/tests/userprog/sc-boundary-2.c index 47d28c6..de357fc 100644 --- a/src/tests/userprog/sc-boundary-2.c +++ b/src/tests/userprog/sc-boundary-2.c @@ -1,3 +1,7 @@ +/* Invokes a system call with one byte of the system call's + argument on a separate page from the rest of the bytes. This + must work. */ + #include #include "tests/userprog/boundary.h" #include "tests/lib.h" diff --git a/src/tests/userprog/sc-boundary.c b/src/tests/userprog/sc-boundary.c index 86371d6..2852568 100644 --- a/src/tests/userprog/sc-boundary.c +++ b/src/tests/userprog/sc-boundary.c @@ -1,3 +1,6 @@ +/* Invokes a system call with the system call number and its + argument on separate pages. This must work. */ + #include #include "tests/userprog/boundary.h" #include "tests/lib.h" diff --git a/src/tests/userprog/wait-bad-pid.c b/src/tests/userprog/wait-bad-pid.c index 12a2ae4..3fe8ee4 100644 --- a/src/tests/userprog/wait-bad-pid.c +++ b/src/tests/userprog/wait-bad-pid.c @@ -1,3 +1,6 @@ +/* Waits for an invalid pid. This may fail or terminate the + process with -1 exit code. */ + #include #include "tests/main.h" diff --git a/src/tests/userprog/wait-killed.c b/src/tests/userprog/wait-killed.c index bc1e9c7..6a2a6b5 100644 --- a/src/tests/userprog/wait-killed.c +++ b/src/tests/userprog/wait-killed.c @@ -1,3 +1,5 @@ +/* Wait for a process that will be killed for bad behavior. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/wait-simple.c b/src/tests/userprog/wait-simple.c index f4e209b..d3afcf3 100644 --- a/src/tests/userprog/wait-simple.c +++ b/src/tests/userprog/wait-simple.c @@ -1,3 +1,5 @@ +/* Wait for a subprocess to finish. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/wait-twice.c b/src/tests/userprog/wait-twice.c index 9386ffe..785e684 100644 --- a/src/tests/userprog/wait-twice.c +++ b/src/tests/userprog/wait-twice.c @@ -1,3 +1,7 @@ +/* Wait for a subprocess to finish, twice. + The first call must wait in the usual way and return the exit code. + The second wait call must return -1 immediately. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/write-bad-fd.c b/src/tests/userprog/write-bad-fd.c index af9a7f2..f3b1151 100644 --- a/src/tests/userprog/write-bad-fd.c +++ b/src/tests/userprog/write-bad-fd.c @@ -1,3 +1,7 @@ +/* Tries to write to an invalid fd, + which must either fail silently or terminate the process with + exit code -1. */ + #include #include #include "tests/main.h" diff --git a/src/tests/userprog/write-bad-ptr.c b/src/tests/userprog/write-bad-ptr.c index bf0dead..5336479 100644 --- a/src/tests/userprog/write-bad-ptr.c +++ b/src/tests/userprog/write-bad-ptr.c @@ -1,3 +1,6 @@ +/* Passes an invalid pointer to the write system call. + The process must be terminated with -1 exit code. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/write-boundary.c b/src/tests/userprog/write-boundary.c index 639e981..d2de1d4 100644 --- a/src/tests/userprog/write-boundary.c +++ b/src/tests/userprog/write-boundary.c @@ -1,3 +1,6 @@ +/* Writes data spanning two pages in virtual address space, + which must succeed. */ + #include #include #include "tests/userprog/boundary.h" diff --git a/src/tests/userprog/write-normal.c b/src/tests/userprog/write-normal.c index b13da9a..e0297aa 100644 --- a/src/tests/userprog/write-normal.c +++ b/src/tests/userprog/write-normal.c @@ -1,3 +1,5 @@ +/* Try writing a file in the most normal way. */ + #include #include "tests/userprog/sample.inc" #include "tests/lib.h" diff --git a/src/tests/userprog/write-stdin.c b/src/tests/userprog/write-stdin.c index 9c42bd2..491ea53 100644 --- a/src/tests/userprog/write-stdin.c +++ b/src/tests/userprog/write-stdin.c @@ -1,3 +1,7 @@ +/* Try writing to fd 0 (stdin), + which may just fail or terminate the process with -1 exit + code. */ + #include #include "tests/lib.h" #include "tests/main.h" diff --git a/src/tests/userprog/write-zero.c b/src/tests/userprog/write-zero.c index 4634e5b..d8dac9b 100644 --- a/src/tests/userprog/write-zero.c +++ b/src/tests/userprog/write-zero.c @@ -1,3 +1,6 @@ +/* Try a 0-byte write, which should return 0 without writing + anything. */ + #include #include "tests/lib.h" #include "tests/main.h"