From: Ben Pfaff <blp@cs.stanford.edu>
Date: Sun, 8 Jan 2006 18:59:11 +0000 (+0000)
Subject: Add explanatory comments to filesys tests.
X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?p=pintos-anon;a=commitdiff_plain;h=3cdb3abe959f205785f0f4fc7101a48bdbc90485

Add explanatory comments to filesys tests.
---

diff --git a/src/tests/filesys/base/child-syn-read.c b/src/tests/filesys/base/child-syn-read.c
index 8f3ccc4..a7801d4 100644
--- a/src/tests/filesys/base/child-syn-read.c
+++ b/src/tests/filesys/base/child-syn-read.c
@@ -1,3 +1,9 @@
+/* Child process for syn-read test.
+   Reads the contents of a test file a byte at a time, in the
+   hope that this will take long enough that we can get a
+   significant amount of contention in the kernel filesystem
+   code. */
+
 #include <random.h>
 #include <stdio.h>
 #include <stdlib.h>
diff --git a/src/tests/filesys/base/child-syn-wrt.c b/src/tests/filesys/base/child-syn-wrt.c
index 43ca2a3..48f1640 100644
--- a/src/tests/filesys/base/child-syn-wrt.c
+++ b/src/tests/filesys/base/child-syn-wrt.c
@@ -1,3 +1,7 @@
+/* Child process for syn-read test.
+   Writes into part of a test file.  Other processes will be
+   writing into other parts at the same time. */
+
 #include <random.h>
 #include <stdlib.h>
 #include <syscall.h>
diff --git a/src/tests/filesys/base/lg-create.c b/src/tests/filesys/base/lg-create.c
index e84866e..5c45eee 100644
--- a/src/tests/filesys/base/lg-create.c
+++ b/src/tests/filesys/base/lg-create.c
@@ -1,2 +1,5 @@
+/* Tests that create properly zeros out the contents of a fairly
+   large file. */
+
 #define TEST_SIZE 75678
 #include "tests/filesys/create.inc"
diff --git a/src/tests/filesys/base/lg-full.c b/src/tests/filesys/base/lg-full.c
index 50a7ffa..5f7234d 100644
--- a/src/tests/filesys/base/lg-full.c
+++ b/src/tests/filesys/base/lg-full.c
@@ -1,2 +1,6 @@
+/* Writes out the contents of a fairly large file all at once,
+   and then reads it back to make sure that it was written
+   properly. */
+
 #define TEST_SIZE 75678
 #include "tests/filesys/base/full.inc"
diff --git a/src/tests/filesys/base/lg-random.c b/src/tests/filesys/base/lg-random.c
index c3027cc..b6f8873 100644
--- a/src/tests/filesys/base/lg-random.c
+++ b/src/tests/filesys/base/lg-random.c
@@ -1,3 +1,7 @@
+/* Writes out the content of a fairly large file in random order,
+   then reads it back in random order to verify that it was
+   written properly. */
+
 #define BLOCK_SIZE 512
 #define TEST_SIZE (512 * 150)
 #include "tests/filesys/base/random.inc"
diff --git a/src/tests/filesys/base/lg-seq-block.c b/src/tests/filesys/base/lg-seq-block.c
index 568fbb7..580c30b 100644
--- a/src/tests/filesys/base/lg-seq-block.c
+++ b/src/tests/filesys/base/lg-seq-block.c
@@ -1,3 +1,7 @@
+/* Writes out a fairly large file sequentially, one fixed-size
+   block at a time, then reads it back to verify that it was
+   written properly. */
+
 #define TEST_SIZE 75678
 #define BLOCK_SIZE 513
 #include "tests/filesys/base/seq-block.inc"
diff --git a/src/tests/filesys/base/lg-seq-random.c b/src/tests/filesys/base/lg-seq-random.c
index 2840c7f..fbb6bba 100644
--- a/src/tests/filesys/base/lg-seq-random.c
+++ b/src/tests/filesys/base/lg-seq-random.c
@@ -1,2 +1,6 @@
+/* Writes out a fairly large file sequentially, one random-sized
+   block at a time, then reads it back to verify that it was
+   written properly. */
+
 #define TEST_SIZE 75678
 #include "tests/filesys/base/seq-random.inc"
diff --git a/src/tests/filesys/base/sm-create.c b/src/tests/filesys/base/sm-create.c
index 522dbd0..6b97ac1 100644
--- a/src/tests/filesys/base/sm-create.c
+++ b/src/tests/filesys/base/sm-create.c
@@ -1,2 +1,5 @@
+/* Tests that create properly zeros out the contents of a fairly
+   small file. */
+
 #define TEST_SIZE 5678
 #include "tests/filesys/create.inc"
diff --git a/src/tests/filesys/base/sm-full.c b/src/tests/filesys/base/sm-full.c
index 10b5703..23ff3d4 100644
--- a/src/tests/filesys/base/sm-full.c
+++ b/src/tests/filesys/base/sm-full.c
@@ -1,2 +1,6 @@
+/* Writes out the contents of a fairly small file all at once,
+   and then reads it back to make sure that it was written
+   properly. */
+
 #define TEST_SIZE 5678
 #include "tests/filesys/base/full.inc"
diff --git a/src/tests/filesys/base/sm-random.c b/src/tests/filesys/base/sm-random.c
index 3639a16..42d670f 100644
--- a/src/tests/filesys/base/sm-random.c
+++ b/src/tests/filesys/base/sm-random.c
@@ -1,3 +1,7 @@
+/* Writes out the content of a fairly small file in random order,
+   then reads it back in random order to verify that it was
+   written properly. */
+
 #define BLOCK_SIZE 13
 #define TEST_SIZE (13 * 123)
 #include "tests/filesys/base/random.inc"
diff --git a/src/tests/filesys/base/sm-seq-block.c b/src/tests/filesys/base/sm-seq-block.c
index 5196eac..e368327 100644
--- a/src/tests/filesys/base/sm-seq-block.c
+++ b/src/tests/filesys/base/sm-seq-block.c
@@ -1,3 +1,7 @@
+/* Writes out a fairly small file sequentially, one fixed-size
+   block at a time, then reads it back to verify that it was
+   written properly. */
+
 #define TEST_SIZE 5678
 #define BLOCK_SIZE 513
 #include "tests/filesys/base/seq-block.inc"
diff --git a/src/tests/filesys/base/sm-seq-random.c b/src/tests/filesys/base/sm-seq-random.c
index 84b6bd3..89e5b71 100644
--- a/src/tests/filesys/base/sm-seq-random.c
+++ b/src/tests/filesys/base/sm-seq-random.c
@@ -1,2 +1,6 @@
+/* Writes out a fairly large file sequentially, one random-sized
+   block at a time, then reads it back to verify that it was
+   written properly. */
+
 #define TEST_SIZE 5678
 #include "tests/filesys/base/seq-random.inc"
diff --git a/src/tests/filesys/base/syn-read.c b/src/tests/filesys/base/syn-read.c
index 27154db..27db471 100644
--- a/src/tests/filesys/base/syn-read.c
+++ b/src/tests/filesys/base/syn-read.c
@@ -1,3 +1,7 @@
+/* Spawns 10 child processes, all of which read from the same
+   file and make sure that the contents are what they should
+   be. */
+
 #include <random.h>
 #include <stdio.h>
 #include <syscall.h>
diff --git a/src/tests/filesys/base/syn-remove.c b/src/tests/filesys/base/syn-remove.c
index 7f0cb61..7f6cd9f 100644
--- a/src/tests/filesys/base/syn-remove.c
+++ b/src/tests/filesys/base/syn-remove.c
@@ -1,3 +1,6 @@
+/* Verifies that a deleted file may still be written to and read
+   from. */
+
 #include <random.h>
 #include <string.h>
 #include <syscall.h>
diff --git a/src/tests/filesys/base/syn-write.c b/src/tests/filesys/base/syn-write.c
index 5147a57..19e9d59 100644
--- a/src/tests/filesys/base/syn-write.c
+++ b/src/tests/filesys/base/syn-write.c
@@ -1,3 +1,7 @@
+/* Spawns several child processes to write out different parts of
+   the contents of a file and waits for them to finish.  Then
+   reads back the file and verifies its contents. */
+
 #include <random.h>
 #include <stdio.h>
 #include <string.h>
diff --git a/src/tests/filesys/extended/child-syn-rw.c b/src/tests/filesys/extended/child-syn-rw.c
index 6334bda..434a542 100644
--- a/src/tests/filesys/extended/child-syn-rw.c
+++ b/src/tests/filesys/extended/child-syn-rw.c
@@ -1,3 +1,12 @@
+/* Child process for syn-rw.
+   Reads from a file created by our parent process, which is
+   growing it.  We loop until we've read the whole file
+   successfully.  Many iterations through the loop will return 0
+   bytes, because the file has not grown in the meantime.  That
+   is, we are "busy waiting" for the file to grow.
+   (This test could be improved by adding a "yield" system call
+   and calling yield whenever we receive a 0-byte read.) */
+
 #include <random.h>
 #include <stdlib.h>
 #include <syscall.h>
diff --git a/src/tests/filesys/extended/dir-empty-name.c b/src/tests/filesys/extended/dir-empty-name.c
index d1f5132..43bc5e6 100644
--- a/src/tests/filesys/extended/dir-empty-name.c
+++ b/src/tests/filesys/extended/dir-empty-name.c
@@ -1,3 +1,6 @@
+/* Tries to create a directory named as the empty string,
+   which must return failure. */
+
 #include <syscall.h>
 #include "tests/lib.h"
 #include "tests/main.h"
diff --git a/src/tests/filesys/extended/dir-lsdir.c b/src/tests/filesys/extended/dir-lsdir.c
index 1896de3..091fec5 100644
--- a/src/tests/filesys/extended/dir-lsdir.c
+++ b/src/tests/filesys/extended/dir-lsdir.c
@@ -1,3 +1,5 @@
+/* Just runs lsdir(). */
+
 #include <syscall.h>
 #include "tests/lib.h"
 #include "tests/main.h"
diff --git a/src/tests/filesys/extended/dir-mk-tree.c b/src/tests/filesys/extended/dir-mk-tree.c
index 2b5907d..a714ff3 100644
--- a/src/tests/filesys/extended/dir-mk-tree.c
+++ b/src/tests/filesys/extended/dir-mk-tree.c
@@ -1,3 +1,6 @@
+/* Creates directories /0/0/0 through /3/2/2 and creates files in
+   the leaf directories. */
+
 #include "tests/filesys/extended/mk-tree.h"
 #include "tests/main.h"
 
diff --git a/src/tests/filesys/extended/dir-mk-vine.c b/src/tests/filesys/extended/dir-mk-vine.c
index e873238..7ac18a1 100644
--- a/src/tests/filesys/extended/dir-mk-vine.c
+++ b/src/tests/filesys/extended/dir-mk-vine.c
@@ -1,3 +1,8 @@
+/* Creates a "vine" of directories /0/1/2/3/4/5/6/7/8/9
+   and changes directory into each of them,
+   then creates a test file in the bottommost
+   and verifies that it can be opened by absolute name. */
+
 #include <syscall.h>
 #include "tests/lib.h"
 #include "tests/main.h"
diff --git a/src/tests/filesys/extended/dir-mkdir.c b/src/tests/filesys/extended/dir-mkdir.c
index a031ba0..994f41c 100644
--- a/src/tests/filesys/extended/dir-mkdir.c
+++ b/src/tests/filesys/extended/dir-mkdir.c
@@ -1,3 +1,5 @@
+/* Tests mkdir(). */
+
 #include <syscall.h>
 #include "tests/lib.h"
 #include "tests/main.h"
diff --git a/src/tests/filesys/extended/dir-open.c b/src/tests/filesys/extended/dir-open.c
index 9bfe2e0..c1f6da5 100644
--- a/src/tests/filesys/extended/dir-open.c
+++ b/src/tests/filesys/extended/dir-open.c
@@ -1,3 +1,7 @@
+/* Tries to open a directory.
+   This is allowed to succeed or fail,
+   but if it succeeds then attempts to write to it must fail. */
+
 #include <syscall.h>
 #include "tests/lib.h"
 #include "tests/main.h"
diff --git a/src/tests/filesys/extended/dir-over-file.c b/src/tests/filesys/extended/dir-over-file.c
index a7866f7..cdd2c62 100644
--- a/src/tests/filesys/extended/dir-over-file.c
+++ b/src/tests/filesys/extended/dir-over-file.c
@@ -1,3 +1,6 @@
+/* Tries to create a file with the same name as an existing
+   directory, which must return failure. */
+
 #include <syscall.h>
 #include "tests/lib.h"
 #include "tests/main.h"
diff --git a/src/tests/filesys/extended/dir-rm-cwd-cd.c b/src/tests/filesys/extended/dir-rm-cwd-cd.c
index 7c362ae..c9a6e61 100644
--- a/src/tests/filesys/extended/dir-rm-cwd-cd.c
+++ b/src/tests/filesys/extended/dir-rm-cwd-cd.c
@@ -1,3 +1,10 @@
+/* Tries to remove the current directory.
+   This is allowed to succeed or fail.
+   If it succeeds, then it must not be possible to chdir back to
+   the current directory by name (because it's been deleted).
+   If it fails, then it must be possible to chdir back to the
+   current directory by name (because it still exists). */
+
 #include <syscall.h>
 #include "tests/lib.h"
 #include "tests/main.h"
diff --git a/src/tests/filesys/extended/dir-rm-cwd.c b/src/tests/filesys/extended/dir-rm-cwd.c
index 3e6fc44..7f81a0b 100644
--- a/src/tests/filesys/extended/dir-rm-cwd.c
+++ b/src/tests/filesys/extended/dir-rm-cwd.c
@@ -1,3 +1,8 @@
+/* Tries to remove the current directory.
+   This is allowed to succeed or fail.
+   Then creates a file in the root to make sure that we haven't
+   corrupted any directory state. */
+
 #include <syscall.h>
 #include "tests/lib.h"
 #include "tests/main.h"
diff --git a/src/tests/filesys/extended/dir-rm-parent.c b/src/tests/filesys/extended/dir-rm-parent.c
index e18d6fd..9db212a 100644
--- a/src/tests/filesys/extended/dir-rm-parent.c
+++ b/src/tests/filesys/extended/dir-rm-parent.c
@@ -1,3 +1,7 @@
+/* Tries to remove the change of parents of the current
+   directory.
+   This can succeed or fail as long as it doesn't crash. 8/
+
 #include <syscall.h>
 #include "tests/lib.h"
 #include "tests/main.h"
diff --git a/src/tests/filesys/extended/dir-rm-root.c b/src/tests/filesys/extended/dir-rm-root.c
index d44b880..5f9cb61 100644
--- a/src/tests/filesys/extended/dir-rm-root.c
+++ b/src/tests/filesys/extended/dir-rm-root.c
@@ -1,3 +1,6 @@
+/* Try to remove the root directory.
+   This must return failure. */
+
 #include <syscall.h>
 #include "tests/lib.h"
 #include "tests/main.h"
diff --git a/src/tests/filesys/extended/dir-rm-tree.c b/src/tests/filesys/extended/dir-rm-tree.c
index c4186f9..bab41a6 100644
--- a/src/tests/filesys/extended/dir-rm-tree.c
+++ b/src/tests/filesys/extended/dir-rm-tree.c
@@ -1,3 +1,6 @@
+/* Creates directories /0/0/0 through /3/2/2 and files in the
+   leaf directories, then removes them. */
+
 #include <stdarg.h>
 #include <stdio.h>
 #include <syscall.h>
diff --git a/src/tests/filesys/extended/dir-rm-vine.c b/src/tests/filesys/extended/dir-rm-vine.c
index 990bcb4..c424c04 100644
--- a/src/tests/filesys/extended/dir-rm-vine.c
+++ b/src/tests/filesys/extended/dir-rm-vine.c
@@ -1,3 +1,7 @@
+/* Creates a "vine" of directories /0/1/2/3/4/5/6/7/8/9
+   and changes directory into each of them,
+   then remove them. */
+
 #include <string.h>
 #include <syscall.h>
 #include "tests/lib.h"
diff --git a/src/tests/filesys/extended/dir-rmdir.c b/src/tests/filesys/extended/dir-rmdir.c
index 38317dc..b3cbc6f 100644
--- a/src/tests/filesys/extended/dir-rmdir.c
+++ b/src/tests/filesys/extended/dir-rmdir.c
@@ -1,3 +1,6 @@
+/* Creates and removes a directory, then makes sure that it's
+   really gone. */
+
 #include <syscall.h>
 #include "tests/lib.h"
 #include "tests/main.h"
diff --git a/src/tests/filesys/extended/dir-under-file.c b/src/tests/filesys/extended/dir-under-file.c
index 88a633b..973a8b1 100644
--- a/src/tests/filesys/extended/dir-under-file.c
+++ b/src/tests/filesys/extended/dir-under-file.c
@@ -1,3 +1,6 @@
+/* Tries to create a directory with the same name as an existing
+   file, which must return failure. */
+
 #include <syscall.h>
 #include "tests/lib.h"
 #include "tests/main.h"
diff --git a/src/tests/filesys/extended/grow-create.c b/src/tests/filesys/extended/grow-create.c
index 45d8d54..9ccc4ea 100644
--- a/src/tests/filesys/extended/grow-create.c
+++ b/src/tests/filesys/extended/grow-create.c
@@ -1,2 +1,4 @@
+/* Create a file of size 0. */
+
 #define TEST_SIZE 0
 #include "tests/filesys/create.inc"
diff --git a/src/tests/filesys/extended/grow-dir-lg.c b/src/tests/filesys/extended/grow-dir-lg.c
index bd05dad..20a194b 100644
--- a/src/tests/filesys/extended/grow-dir-lg.c
+++ b/src/tests/filesys/extended/grow-dir-lg.c
@@ -1,3 +1,6 @@
+/* Creates a directory,
+   then creates 50 files in that directory. */
+
 #define FILE_CNT 50
 #define DIRECTORY "/x"
 #include "tests/filesys/extended/grow-dir.inc"
diff --git a/src/tests/filesys/extended/grow-file-size.c b/src/tests/filesys/extended/grow-file-size.c
index e7c269f..3ce8588 100644
--- a/src/tests/filesys/extended/grow-file-size.c
+++ b/src/tests/filesys/extended/grow-file-size.c
@@ -1,3 +1,7 @@
+/* Grows a file from 0 bytes to 2,134 bytes, 37 bytes at a time,
+   and checks that the file's size is reported correctly at each
+   step. */
+
 #include <syscall.h>
 #include "tests/filesys/seq-test.h"
 #include "tests/lib.h"
diff --git a/src/tests/filesys/extended/grow-root-lg.c b/src/tests/filesys/extended/grow-root-lg.c
index b4731b2..d8d6c09 100644
--- a/src/tests/filesys/extended/grow-root-lg.c
+++ b/src/tests/filesys/extended/grow-root-lg.c
@@ -1,2 +1,4 @@
+/* Creates 50 files in the root directory. */
+
 #define FILE_CNT 50
 #include "tests/filesys/extended/grow-dir.inc"
diff --git a/src/tests/filesys/extended/grow-root-sm.c b/src/tests/filesys/extended/grow-root-sm.c
index db7d1f3..ee375d5 100644
--- a/src/tests/filesys/extended/grow-root-sm.c
+++ b/src/tests/filesys/extended/grow-root-sm.c
@@ -1,2 +1,4 @@
+/* Creates 20 files in the root directory. */
+
 #define FILE_CNT 20
 #include "tests/filesys/extended/grow-dir.inc"
diff --git a/src/tests/filesys/extended/grow-seq-lg.c b/src/tests/filesys/extended/grow-seq-lg.c
index 4474d50..3108d17 100644
--- a/src/tests/filesys/extended/grow-seq-lg.c
+++ b/src/tests/filesys/extended/grow-seq-lg.c
@@ -1,2 +1,5 @@
+/* Grows a file from 0 bytes to 72,943 bytes, 1,234 bytes at a
+   time. */
+
 #define TEST_SIZE 72943
 #include "tests/filesys/extended/grow-seq.inc"
diff --git a/src/tests/filesys/extended/grow-seq-sm.c b/src/tests/filesys/extended/grow-seq-sm.c
index bf54c64..3656e2e 100644
--- a/src/tests/filesys/extended/grow-seq-sm.c
+++ b/src/tests/filesys/extended/grow-seq-sm.c
@@ -1,2 +1,5 @@
+/* Grows a file from 0 bytes to 5,678 bytes, 1,234 bytes at a
+   time. */
+
 #define TEST_SIZE 5678
 #include "tests/filesys/extended/grow-seq.inc"
diff --git a/src/tests/filesys/extended/grow-sparse.c b/src/tests/filesys/extended/grow-sparse.c
index 11e3b6e..135a918 100644
--- a/src/tests/filesys/extended/grow-sparse.c
+++ b/src/tests/filesys/extended/grow-sparse.c
@@ -1,3 +1,6 @@
+/* Tests that seeking past the end of a file and writing will
+   properly zero out the region in between. */
+
 #include <syscall.h>
 #include "tests/lib.h"
 #include "tests/main.h"
diff --git a/src/tests/filesys/extended/grow-tell.c b/src/tests/filesys/extended/grow-tell.c
index 3f1e211..5f5da5b 100644
--- a/src/tests/filesys/extended/grow-tell.c
+++ b/src/tests/filesys/extended/grow-tell.c
@@ -1,3 +1,6 @@
+/* Checks that growing a file updates the file position
+   correctly. */
+
 #include <syscall.h>
 #include "tests/filesys/seq-test.h"
 #include "tests/lib.h"
diff --git a/src/tests/filesys/extended/grow-too-big.c b/src/tests/filesys/extended/grow-too-big.c
index 9d7ddca..d49fcb2 100644
--- a/src/tests/filesys/extended/grow-too-big.c
+++ b/src/tests/filesys/extended/grow-too-big.c
@@ -1,3 +1,6 @@
+/* Checks that trying to grow a file beyond the capacity of the
+   file system behaves reasonably (does not crash). */
+
 #include <limits.h>
 #include <syscall.h>
 #include "tests/lib.h"
diff --git a/src/tests/filesys/extended/grow-two-files.c b/src/tests/filesys/extended/grow-two-files.c
index 69f17ae..cc0f5fa 100644
--- a/src/tests/filesys/extended/grow-two-files.c
+++ b/src/tests/filesys/extended/grow-two-files.c
@@ -1,3 +1,6 @@
+/* Grows two files in parallel and checks that their contents are
+   correct. */
+
 #include <random.h>
 #include <syscall.h>
 #include "tests/lib.h"
diff --git a/src/tests/filesys/extended/mk-tree.c b/src/tests/filesys/extended/mk-tree.c
index 66a3ae3..a36bb88 100644
--- a/src/tests/filesys/extended/mk-tree.c
+++ b/src/tests/filesys/extended/mk-tree.c
@@ -1,3 +1,5 @@
+/* Library function for creating a tree of directories. */
+
 #include <stdio.h>
 #include <syscall.h>
 #include "tests/filesys/extended/mk-tree.h"
diff --git a/src/tests/filesys/extended/syn-rw.c b/src/tests/filesys/extended/syn-rw.c
index a4c2f5d..f2900d0 100644
--- a/src/tests/filesys/extended/syn-rw.c
+++ b/src/tests/filesys/extended/syn-rw.c
@@ -1,3 +1,6 @@
+/* Grows a file in chunks while subprocesses read the growing
+   file. */
+
 #include <random.h>
 #include <syscall.h>
 #include "tests/filesys/extended/syn-rw.h"