Update documentation.
authorBen Pfaff <blp@cs.stanford.edu>
Sat, 5 Mar 2005 05:31:47 +0000 (05:31 +0000)
committerBen Pfaff <blp@cs.stanford.edu>
Sat, 5 Mar 2005 05:31:47 +0000 (05:31 +0000)
doc/filesys.texi
doc/userprog.texi

index 02808bb821c74902187a7f6b51886383860a5d71..6ebc4d9707e1cb4da43a44058beb2d9fdd353974 100644 (file)
@@ -146,16 +146,20 @@ is specified when the file is created.  One advantage of this is that
 the inode data structure, once created, never changes.  In UNIX and
 most other file systems, a file is initially created with size 0 and
 is then expanded every time a write is made off the end of the file.
-Modify the file system to allow this.  As one test case, allow the
-root directory file to expand beyond its current limit of ten files.
+Modify the file system to allow this.  
 Make sure that concurrent accesses to the inode remain properly
 synchronized.
 
+There should be no predetermined limit on the size of a file, except
+that a disk cannot exceed the size of the disk (minus metadata).  This
+also applies to the root directory file, which should now be allowed
+to expand beyond its initial limit of ten files.
+
 The user is allowed to seek beyond the current end-of-file (EOF).  The
 seek itself does not extend the file.  Writing at a position past EOF
 extends the file to the position being written, and any gap between the
 previous EOF and the start of the write must be filled with zeros.  A
-read past EOF returns zero bytes.
+read starting from a position past EOF returns no bytes.
 
 Writing far beyond EOF can cause many blocks to be entirely zero.  Some
 file systems allocate and write real data blocks for these implicitly
@@ -168,28 +172,39 @@ your file system.
 @section Problem 4-3: Subdirectories
 
 Implement a hierarchical name space.  In the basic file system, all
-files live in a single directory.  Modify this to allow directories to
-point to either files or other directories.  To do this, you will need
-to implement routines that parse path names into a sequence of
-directories, as well as routines that change the current working
-directory and that list the contents of the current directory.  For
-performance, allow concurrent updates to different directories, but
-use mutual exclusion to ensure that updates to the same directory are
-performed atomically (for example, to ensure that a file is deleted
-only once).
+files live in a single directory.  Modify this to allow directory
+entries to point to files or to other directories.  You will need
+routines to parse a path name into a sequence of directories, to
+change the current working directory, and to list the contents of the
+current directory.  For performance, allow concurrent updates to
+different directories, but use mutual exclusion to ensure that updates
+to the same directory are performed atomically (for example, to ensure
+that a file is deleted only once).
 
 Make sure that directories can expand beyond their original size just
-as any other file can.
+as any other file can.  
+
+The basic file system has a 14-character limit on file names.  You may
+retain this limit for individual file name components, or may extend
+it, at your option.  In any case you must allow full path names to be
+much longer than 14 characters.
 
-Each process has its own current directory.  When one process starts
-another with the @code{exec} system call, the child process inherits its
-parent's current directory.  After that, the two processes' current
-directories are independent, so that either changing its own current
-directory has no effect on the other.
+The current directory is maintained separately for each process.  At
+startup, the initial process has the root directory as its current
+directory.  When one process starts another with the @code{exec}
+system call, the child process inherits its parent's current
+directory.  After that, the two processes' current directories are
+independent, so that either changing its own current directory has no
+effect on the other.
 
 Update the existing system calls so that, anywhere a file name is
 provided by the caller, an absolute or relative path name may used.
-Also, implement the following new system calls:
+
+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 files or subdirectories.
+
+Implement the following new system calls:
 
 @table @code
 @item SYS_chdir
@@ -202,18 +217,27 @@ successful, false on failure.
 @itemx bool mkdir (const char *dir)
 Attempts to create the directory named @var{dir}, which may be either
 relative or absolute.  Returns true if successful, false on failure.
+Fails if @var{dir} already exists or if any directory name in
+@var{dir}, besides the last, does not already exist.  That is,
+@code{mkdir("/a/b/c")} succeeds only if @file{/a/b} already exists and
+@file{/a/b/c} does not.
 
 @item SYS_lsdir
 @itemx void lsdir (void)
 Prints a list of files in the current directory to @code{stdout}, one
-per line.
+per line, in no particular order.
 @end table
 
-Also write the @command{ls} and @command{mkdir} user programs.  This
-is straightforward once the above syscalls are implemented.  In Unix,
+We have provided @command{ls} and @command{mkdir} user programs, which
+are straightforward once the above syscalls are implemented.  In Unix,
 these are programs rather than built-in shell commands, but
 @command{cd} is a shell command.  (Why?)
 
+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.
+
 @node Problem 4-4 Buffer Cache
 @section Problem 4-4: Buffer Cache
 
@@ -360,9 +384,9 @@ pintos -ci shell 12345
 pintos -ex "shell"
 @end example
 
-If you don't change the filesystem interface, then this should already
-be implemented properly in @file{threads/init.c} and
-@file{filesys/fsutil.c}.
+If you don't change the filesystem interface, none of this should
+require any special effort on your part.  They are already implemented
+properly in @file{threads/init.c} and @file{filesys/fsutil.c}.
 
 You must also implement the @option{-q} option and make sure that data
 gets flushed out to disk properly when it is used.
@@ -420,17 +444,6 @@ easier to change the current working directory of the shell process if
 user process.  In fact, Unix-like systems don't provide any way for
 one process to change another process's current working directory.
 
-@item
-@b{When the spec states that directories should be able to grow beyond
-ten files, does this mean that there can still be a set maximum number
-of files per directory that is greater than ten, or should directories
-now support unlimited growth (bounded by the maximum supported file
-size)?}
-
-We're looking for directories that can support arbitrarily large
-numbers of files.  Now that directories can grow, we want you to
-remove the concept of a preset maximum file limit.
-
 @item
 @b{When should the @code{lsdir} system call return?}
 
@@ -448,7 +461,7 @@ This code should create the following output:
 
 @example
 Start of directory
-...  directory contents ...
+@dots{}directory contents@dots{}
 End of directory
 @end example
 
@@ -456,13 +469,6 @@ End of directory
 @b{Do we have to implement both absolute and relative pathnames?}
 
 Yes.  Implementing @file{.} and @file{..} is extra credit, though.
-
-@item
-@b{Should @func{remove} also be able to remove directories?}
-
-Yes.  The @code{remove} system call should handle removal of both
-regular files and directories.  You may assume that directories can
-only be deleted if they are empty, as in Unix.
 @end enumerate
 
 @node Problem 4-4 Buffer Cache FAQ
index fa3b4b8deb23d0a097249e7f1beefcb94d9cff9c..9ca19a58645a7fe89f3a05ed0d454e19248f5b8f 100644 (file)
@@ -278,8 +278,8 @@ that needs @var{N} pages of memory must not require that all @var{N}
 be contiguous.  In fact, it must not require that any of the pages be
 contiguous.
 
-@node Global Requirements
-@section Global Requirements
+@node Grading Requirements
+@section Grading Requirements
 
 For testing and grading purposes, we have some simple overall
 requirements:
@@ -326,6 +326,16 @@ make sure that it takes the start-up process name and arguments from
 the @samp{-ex} argument.  For example, running @code{pintos run -ex
 "testprogram 1 2 3 4"} will spawn @samp{testprogram 1 2 3 4} as the
 first process.
+
+@item
+In the previous project, we required that you provided some specific
+function interfaces, because we tested your project by compiling our
+test code into it.  For this project and all later projects, this is
+no longer necessary, because we will do all of our testing with user
+programs.  You must make sure that the user program interface meets
+the specifications described in the assignments, but given that
+constraint you are free to restructure or rewrite kernel code however
+you wish.
 @end itemize
 
 @node Problem 2-1 Argument Passing