Add file system persistence tests:

[pintos-anon] / doc / filesys.texi

diff --git a/doc/filesys.texi b/doc/filesys.texi
index 8e4dc4f964b4f352f7ffc30c6b672f2bda8573c5..db4d94810b63426f91ee03c6783bd63b5c1060be 100644 (file)
--- a/doc/filesys.texi
+++ b/doc/filesys.texi
@@ -14,10 +14,6 @@ filesys submission.  If you build on project 3, then all of the project
 @file{filesys/Make.vars} to enable VM functionality.  You can receive up
 to 5% extra credit if you do enable VM.
 
 @file{filesys/Make.vars} to enable VM functionality.  You can receive up
 to 5% extra credit if you do enable VM.
 

-The tests for project 4 will probably run faster if
-you use the qemu emulator, e.g.@: via @code{make check
-PINTOSOPTS='--qemu'}.
-

 @menu
 * Project 4 Background::        
 * Project 4 Requirements::      
 @menu
 * Project 4 Background::        
 * Project 4 Requirements::      


@@ -29,6 +25,7 @@ PINTOSOPTS='--qemu'}.
 
 @menu
 * File System New Code::        
 
 @menu
 * File System New Code::        

+* Testing File System Persistence::  

 @end menu
 
 @node File System New Code
 @end menu
 
 @node File System New Code


@@ -82,6 +79,35 @@ which you will remove.
 While most of your work will be in @file{filesys}, you should be
 prepared for interactions with all previous parts.
 
 While most of your work will be in @file{filesys}, you should be
 prepared for interactions with all previous parts.
 

+@node Testing File System Persistence
+@subsection Testing File System Persistence
+
+By now, you should be familiar with the basic process of running the
+Pintos tests.  @xref{Testing}, for review, if necessary.
+
+Until now, each test invoked Pintos just once.  However, an important
+purpose of a file system is to ensure that data remains accessible from
+one boot to another.  Thus, the tests that are part of the file system
+project invoke Pintos a second time.  The second run combines all the
+files and directories in the file system into a single file, then copies
+that file out of the Pintos file system into the host (Unix) file
+system.
+
+The grading scripts check the file system's correctness based on the
+contents of the file copied out in the second run.  This means that your
+project will not pass any of the extended file system tests until the
+file system is implemented well enough to support @program{tar}, the
+Pintos user program that produces the file that is copied out.  The
+@program{tar} program is fairly demanding (it requires both extensible
+file and subdirectory support), so this will take some work.  Until
+then, you can ignore errors from @command{make check} regarding the
+extracted file system.
+
+Incidentally, as you may have surmised, the file format used for copying
+out the file system contents is the standard Unix ``tar'' format.  You
+can use the Unix @command{tar} program to examine them.  The tar file
+for test @var{t} is named @file{@var{t}.tar}.
+

 @node Project 4 Requirements
 @section Requirements
 
 @node Project 4 Requirements
 @section Requirements
 


@@ -176,18 +202,21 @@ not an external program.)
 Update the existing system calls so that, anywhere a file name is
 provided by the caller, an absolute or relative path name may used.
 The directory separator character is forward slash (@samp{/}).
 Update the existing system calls so that, anywhere a file name is
 provided by the caller, an absolute or relative path name may used.
 The directory separator character is forward slash (@samp{/}).

-You may support @file{.} and @file{..} for a small amount of extra
-credit.
-
-Update the @code{remove} system call so that it can delete empty
-directories in addition to regular files.  Directories can only be
-deleted if they do not contain any files or subdirectories.
+You must also support special file names @file{.} and @file{..}, which
+have the same meanings as they do in Unix.

 
 Update the @code{open} system call so that it can also open directories.
 
 Update the @code{open} system call so that it can also open directories.

-Passing @file{.} as the argument to @code{open} must open the current
-directory, regardless of whether @file{.} and @file{..} are fully
-implemented.  Of the existing system calls, only @code{close} needs to
-accept a file descriptor for a directory.
+Of the existing system calls, only @code{close} needs to accept a file
+descriptor for a directory.
+
+Update the @code{remove} system call so that it can delete empty
+directories (other than the root) in addition to regular files.
+Directories may only be deleted if they do not contain any files or
+subdirectories (other than @file{.} and @file{..}).  You may decide
+whether to allow deletion of a directory that is open by a process or in
+use as a process's current working directory.  If it is allowed, then
+attempts to open files (including @file{.} and @file{..}) or create new
+files in a deleted directory must be disallowed.

 
 Implement the following new system calls:
 
 
 Implement the following new system calls:
 


@@ -213,8 +242,7 @@ name in @var{name}, which must have room for @code{READDIR_MAX_LEN + 1}
 bytes, and returns true.  If no entries are left in the directory,
 returns false.
 
 bytes, and returns true.  If no entries are left in the directory,
 returns false.
 

-@file{.} and @file{..} should not be returned by @code{readdir},
-regardless of whether they are implemented.
+@file{.} and @file{..} should not be returned by @code{readdir}.

 
 If the directory changes while it is open, then it is acceptable for
 some entries not to be read at all or to be read multiple times.
 
 If the directory changes while it is open, then it is acceptable for
 some entries not to be read at all or to be read multiple times.


@@ -230,14 +258,24 @@ Returns true if @var{fd} represents a directory,
 false if it represents an ordinary file.
 @end deftypefn
 
 false if it represents an ordinary file.
 @end deftypefn
 

+@deftypefn {System Call} int inumber (int @var{fd})
+Returns the @dfn{inode number} of the inode associated with @var{fd}.
+Applicable to file descriptors for both files and directories.
+
+An inode number persistently identifies a file or directory.  It is
+unique during the file's existence.  In Pintos, the sector number of the
+inode is suitable for use as an inode number.
+@end deftypefn
+

 We have provided @command{ls} and @command{mkdir} user programs, which
 We have provided @command{ls} and @command{mkdir} user programs, which

-are straightforward once the above syscalls are implemented.  The
-@command{shell} program implements @command{cd} internally.
+are straightforward once the above syscalls are implemented.  
+We have also provided @command{pwd}, which is not so straightforward.
+The @command{shell} program implements @command{cd} internally.

 
 The @code{pintos} @option{put} and @option{get} commands should now
 accept full path names, assuming that the directories used in the
 
 The @code{pintos} @option{put} and @option{get} commands should now
 accept full path names, assuming that the directories used in the

-paths have already been created.  This should not require any extra
-effort on your part.
+paths have already been created.  This should not require any significant
+extra effort on your part.

 
 @node Buffer Cache
 @subsection Buffer Cache
 
 @node Buffer Cache
 @subsection Buffer Cache


@@ -385,13 +423,6 @@ modified by the reference solution.
  30 files changed, 2721 insertions(+), 286 deletions(-)
 @end verbatim
 
  30 files changed, 2721 insertions(+), 286 deletions(-)
 @end verbatim
 

-@item What extra credit opportunities are available?
-
-You may implement Unix-style support for @file{.} and @file{..} in
-relative paths in their projects.
-
-You may submit with VM enabled.
-

 @item Can @code{DISK_SECTOR_SIZE} change?
 
 No, @code{DISK_SECTOR_SIZE} is fixed at 512.  This is a fixed property
 @item Can @code{DISK_SECTOR_SIZE} change?
 
 No, @code{DISK_SECTOR_SIZE} is fixed at 512.  This is a fixed property


@@ -419,16 +450,20 @@ You'll need to consider this when deciding your inode organization.
 @subsection Subdirectories FAQ
 
 @table @b
 @subsection Subdirectories FAQ
 
 @table @b

-@item How should a file name like @samp{//a//b} be interpreted?
+@item How should a file name like @samp{a//b} be interpreted?

 
 Multiple consecutive slashes are equivalent to a single slash, so this
 
 Multiple consecutive slashes are equivalent to a single slash, so this

-file name is the same as @samp{/a/b}.
+file name is the same as @samp{a/b}.

 
 @item How about a file name like @samp{/../x}?
 
 
 @item How about a file name like @samp{/../x}?
 

-If you don't implement @file{.} and @file{..}, then this is not a
-special case.  If you do, then it is equivalent to @samp{/x}.  That is,
-the root directory is its own parent.
+The root directory is its own parent, so it is equivalent to @samp{/x}.
+
+@item How should a file name that ends in @samp{/} be treated?
+
+Most Unix systems allow a slash at the end of the name for a directory,
+and reject other names that end in slashes.  We will allow this
+behavior, as well as simply rejecting a name that ends in a slash.

 @end table
 
 @node Buffer Cache FAQ
 @end table
 
 @node Buffer Cache FAQ