Note that struct file, struct dir are per-thread.

[pintos-anon] / doc / filesys.texi

diff --git a/doc/filesys.texi b/doc/filesys.texi
index a93481cca37da657cf8ec50890691e12f2d39dfe..f245daa48ea1e6d592a86146ddddf9947ca9cffe 100644 (file)
--- a/doc/filesys.texi
+++ b/doc/filesys.texi
@@ -16,6 +16,7 @@ to 5% extra credit if you do enable VM.
 
 @menu
 * Project 4 Background::        
 
 @menu
 * Project 4 Background::        

+* Project 4 Suggested Order of Implementation::  

 * Project 4 Requirements::      
 * Project 4 FAQ::               
 @end menu
 * Project 4 Requirements::      
 * Project 4 FAQ::               
 @end menu


@@ -25,6 +26,7 @@ to 5% extra credit if you do enable VM.
 
 @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


@@ -78,6 +80,62 @@ 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 @command{tar}, the
+Pintos user program that produces the file that is copied out.  The
+@command{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 Suggested Order of Implementation
+@section Suggested Order of Implementation
+
+We suggest implementing the parts of this project in the following
+order to make your job easier:
+
+@enumerate
+@item
+Buffer cache (@pxref{Buffer Cache}).  Implement the buffer cache and
+integrate it into the existing file system.  At this point all the
+tests from project 2 (and project 3, if you're building on it) should
+still pass.
+
+@item
+Extensible files (@pxref{Indexed and Extensible Files}).  After this
+step, your project should pass the file growth tests.
+
+@item
+Subdirectories (@pxref{Subdirectories}).  Afterward, your project
+should pass the directory tests.
+
+@item
+Remaining miscellaneous items.
+@end enumerate
+
+You should think about synchronization throughout.
+

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


@@ -175,15 +233,19 @@ The directory separator character is forward slash (@samp{/}).
 You must also support special file names @file{.} and @file{..}, which
 have the same meanings as they do in Unix.
 
 You must also support special file names @file{.} and @file{..}, which
 have the same meanings as they do in Unix.
 

-Update the @code{remove} system call so that it can delete empty
-directories in addition to regular files.  Directories may only be
-deleted if they do not contain any files or subdirectories (other than
-@file{.} and @file{..}).
-

 Update the @code{open} system call so that it can also open directories.
 Of the existing system calls, only @code{close} needs to accept a file
 descriptor for a directory.
 
 Update the @code{open} system call so that it can also open directories.
 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:
 
 @deftypefn {System Call} bool chdir (const char *@var{dir})
 Implement the following new system calls:
 
 @deftypefn {System Call} bool chdir (const char *@var{dir})


@@ -225,8 +287,8 @@ false if it represents an ordinary file.
 @end deftypefn
 
 @deftypefn {System Call} int inumber (int @var{fd})
 @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.
+Returns the @dfn{inode number} of the inode associated with @var{fd},
+which may represent an ordinary file or a directory.

 
 An inode number persistently identifies a file or directory.  It is
 unique during the file's existence.  In Pintos, the sector number of the
 
 An inode number persistently identifies a file or directory.  It is
 unique during the file's existence.  In Pintos, the sector number of the


@@ -253,11 +315,12 @@ disk.  Otherwise, fetch the block from disk into cache, evicting an
 older entry if necessary.  You are limited to a cache no greater than 64
 sectors in size.
 
 older entry if necessary.  You are limited to a cache no greater than 64
 sectors in size.
 

-Be sure to choose an intelligent cache replacement algorithm.
-Experiment to see what combination of accessed, dirty, and other
-information results in the best performance, as measured by the number
-of disk accesses.  For example, metadata is generally more valuable to
-cache than data.
+You must implement a cache replacement algorithm that is at least as
+good as the ``clock'' algorithm.  Your algorithm must also account for
+the generally greater value of metadata compared to data.  Experiment
+to see what combination of accessed, dirty, and other information
+results in the best performance, as measured by the number of disk
+accesses.

 
 You can keep a cached copy of the free map permanently in memory if you
 like.  It doesn't have to count against the cache size.
 
 You can keep a cached copy of the free map permanently in memory if you
 like.  It doesn't have to count against the cache size.


@@ -277,11 +340,8 @@ blocks back to disk.  The cache should also be written back to disk in
 @func{filesys_done}, so that halting Pintos flushes the cache.
 
 If you have @func{timer_sleep} from the first project working, write-behind is
 @func{filesys_done}, so that halting Pintos flushes the cache.
 
 If you have @func{timer_sleep} from the first project working, write-behind is

-an excellent application.  If you're still using the base
-implementation of @func{timer_sleep}, be aware that it busy-waits, which
-is not acceptable here (or elsewhere).  If @func{timer_sleep}'s delays seem too
-short or too long, reread the explanation of the @option{-r} option to
-@command{pintos} (@pxref{Debugging versus Testing}).
+an excellent application.  Otherwise, you may implement a less general
+facility, but make sure that it does not exhibit busy-waiting.

 
 You should also implement @dfn{read-ahead}, that is,
 automatically fetch the next block of a file
 
 You should also implement @dfn{read-ahead}, that is,
 automatically fetch the next block of a file


@@ -334,6 +394,10 @@ if B's data is all nonzero bytes, A is not allowed to see any zeros.
 Operations on different directories should take place concurrently.
 Operations on the same directory may wait for one another.
 
 Operations on different directories should take place concurrently.
 Operations on the same directory may wait for one another.
 

+Keep in mind that only data shared by multiple threads needs to be
+synchronized.  In the base file system, @struct{file} and @struct{dir}
+are accessed only by a single thread.
+

 @node Project 4 FAQ
 @section FAQ
 
 @node Project 4 FAQ
 @section FAQ