From 42a67e9ac6854ec56c35c82e1ad9c4e2c8662139 Mon Sep 17 00:00:00 2001
From: Ben Pfaff <blp@cs.stanford.edu>
Date: Sun, 8 Jan 2006 01:08:06 +0000
Subject: [PATCH] Add explanatory comments to userprog tests.

---
 src/tests/userprog/args.c           | 5 +++++
 src/tests/userprog/boundary.c       | 4 ++++
 src/tests/userprog/child-bad.c      | 5 +++++
 src/tests/userprog/child-close.c    | 9 +++++++++
 src/tests/userprog/child-rox.c      | 6 ++++++
 src/tests/userprog/child-simple.c   | 4 ++++
 src/tests/userprog/close-bad-fd.c   | 3 +++
 src/tests/userprog/close-normal.c   | 2 ++
 src/tests/userprog/close-stdin.c    | 3 +++
 src/tests/userprog/close-stdout.c   | 3 +++
 src/tests/userprog/close-twice.c    | 4 ++++
 src/tests/userprog/create-bad-ptr.c | 4 ++++
 src/tests/userprog/create-bound.c   | 3 +++
 src/tests/userprog/create-empty.c   | 2 ++
 src/tests/userprog/create-exists.c  | 3 +++
 src/tests/userprog/create-long.c    | 3 +++
 src/tests/userprog/create-normal.c  | 2 ++
 src/tests/userprog/create-null.c    | 3 +++
 src/tests/userprog/exec-arg.c       | 2 ++
 src/tests/userprog/exec-bad-ptr.c   | 3 +++
 src/tests/userprog/exec-missing.c   | 3 +++
 src/tests/userprog/exec-multiple.c  | 2 ++
 src/tests/userprog/exec-once.c      | 2 ++
 src/tests/userprog/exit.c           | 2 ++
 src/tests/userprog/halt.c           | 2 ++
 src/tests/userprog/multi-child-fd.c | 5 +++++
 src/tests/userprog/multi-recurse.c  | 5 +++--
 src/tests/userprog/open-bad-ptr.c   | 3 +++
 src/tests/userprog/open-boundary.c  | 3 +++
 src/tests/userprog/open-empty.c     | 2 ++
 src/tests/userprog/open-missing.c   | 2 ++
 src/tests/userprog/open-normal.c    | 2 ++
 src/tests/userprog/open-null.c      | 3 +++
 src/tests/userprog/open-twice.c     | 4 ++++
 src/tests/userprog/read-bad-fd.c    | 4 ++++
 src/tests/userprog/read-bad-ptr.c   | 3 +++
 src/tests/userprog/read-boundary.c  | 3 +++
 src/tests/userprog/read-normal.c    | 2 ++
 src/tests/userprog/read-stdout.c    | 4 ++++
 src/tests/userprog/read-zero.c      | 3 +++
 src/tests/userprog/rox-child.c      | 3 +++
 src/tests/userprog/rox-multichild.c | 3 +++
 src/tests/userprog/rox-simple.c     | 3 +++
 src/tests/userprog/sc-bad-arg.c     | 6 ++++++
 src/tests/userprog/sc-bad-sp.c      | 4 ++++
 src/tests/userprog/sc-boundary-2.c  | 4 ++++
 src/tests/userprog/sc-boundary.c    | 3 +++
 src/tests/userprog/wait-bad-pid.c   | 3 +++
 src/tests/userprog/wait-killed.c    | 2 ++
 src/tests/userprog/wait-simple.c    | 2 ++
 src/tests/userprog/wait-twice.c     | 4 ++++
 src/tests/userprog/write-bad-fd.c   | 4 ++++
 src/tests/userprog/write-bad-ptr.c  | 3 +++
 src/tests/userprog/write-boundary.c | 3 +++
 src/tests/userprog/write-normal.c   | 2 ++
 src/tests/userprog/write-stdin.c    | 4 ++++
 src/tests/userprog/write-zero.c     | 3 +++
 57 files changed, 186 insertions(+), 2 deletions(-)

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 <inttypes.h>
 #include <round.h>
 #include <string.h>
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 <ctype.h>
 #include <stdio.h>
 #include <stdlib.h>
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 <ctype.h>
 #include <stdio.h>
 #include <stdlib.h>
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 <stdio.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <string.h>
 #include <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <stdio.h>
 #include <syscall.h>
 #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 <debug.h>
 #include <stdlib.h>
 #include <stdio.h>
@@ -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 <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <stddef.h>
 #include <syscall.h>
 #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 <syscall.h>
 #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 <limits.h>
 #include <syscall.h>
 #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 <syscall.h>
 #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 <string.h>
 #include <syscall.h>
 #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 <stdio.h>
 #include <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <syscall-nr.h>
 #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 <syscall-nr.h>
 #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 <syscall-nr.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <limits.h>
 #include <syscall.h>
 #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 <syscall.h>
 #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 <string.h>
 #include <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #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 <syscall.h>
 #include "tests/lib.h"
 #include "tests/main.h"
-- 
2.30.2