-system implementation.
-
-You need to be able to create and format simulated disks. The
-@command{pintos} program provides this functionality with its
-@option{make-disk} command. From the @file{userprog/build} directory,
-execute @code{pintos make-disk fs.dsk 2}. This command creates a 2 MB
-simulated disk named @file{fs.dsk}. (It does not actually start
-Pintos.) Then format the disk by passing the @option{-f} option to
-Pintos on the kernel's command line: @code{pintos run -f}.
-
-You'll need a way to get files in and out of the simulated file
-system. The @code{pintos} @option{put} and @option{get} commands are
-designed for this. To copy @file{@var{file}} into the Pintos file
-system, use the command @file{pintos put @var{file}}. To copy it to
-the Pintos file system under the name @file{@var{newname}}, add the
-new name to the end of the command: @file{pintos put @var{file}
-@var{newname}}. The commands for copying files out of a VM are
-similar, but substitute @option{get} for @option{get}.
-
-Incidentally, these commands work by passing special options
-@option{-ci} and @option{-co} on the kernel's command line and copying
-to and from a special simulated disk named @file{scratch.dsk}. If
-you're very curious, you can look at the @command{pintos} program as
-well as @file{filesys/fsutil.c} to learn the implementation details,
-but it's really not relevant for this project.
-
-Here's a summary of how you would create and format a disk, copy the
-@command{echo} program into the new disk, and then run @command{echo}.
-It assumes that you've already built the tests in
-@file{tests/userprog} and that the current directory is
-@file{userprog/build}:
+system implementation. Until then, you will have to tolerate the
+following limitations:
+
+@itemize @bullet
+@item
+No internal synchronization. Concurrent accesses will interfere with one
+another. You should use synchronization to ensure that only one process at a
+time is executing file system code.
+
+@item
+File size is fixed at creation time. The root directory is
+represented as a file, so the number of files that may be created is also
+limited.
+
+@item
+File data is allocated as a single extent, that is, data in a single
+file must occupy a contiguous range of sectors on disk. External
+fragmentation can therefore become a serious problem as a file system is
+used over time.
+
+@item
+No subdirectories.
+
+@item
+File names are limited to 14 characters.
+
+@item
+A system crash mid-operation may corrupt the disk in a way
+that cannot be repaired automatically. There is no file system repair
+tool anyway.
+@end itemize
+
+One important feature is included:
+
+@itemize @bullet
+@item
+Unix-like semantics for @func{filesys_remove} are implemented.
+That is, if a file is open when it is removed, its blocks
+are not deallocated and it may still be accessed by any
+threads that have it open, until the last one closes it. @xref{Removing
+an Open File}, for more information.
+@end itemize
+
+You need to be able to create a simulated disk with a file system
+partition. The @command{pintos-mkdisk} program provides this
+functionality. From the @file{userprog/build} directory, execute
+@code{pintos-mkdisk filesys.dsk --filesys-size=2}. This command
+creates a simulated disk named @file{filesys.dsk} that contains a @w{2
+MB} Pintos file system partition. Then format the file system
+partition by passing @option{-f -q} on the kernel's command line:
+@code{pintos -f -q}. The @option{-f} option causes the file system to
+be formatted, and @option{-q} causes Pintos to exit as soon as the
+format is done.
+
+You'll need a way to copy files in and out of the simulated file system.
+The @code{pintos} @option{-p} (``put'') and @option{-g} (``get'')
+options do this. To copy @file{@var{file}} into the
+Pintos file system, use the command @file{pintos -p @var{file} -- -q}.
+(The @samp{--} is needed because @option{-p} is for the @command{pintos}
+script, not for the simulated kernel.) To copy it to the Pintos file
+system under the name @file{@var{newname}}, add @option{-a
+@var{newname}}: @file{pintos -p @var{file} -a @var{newname} -- -q}. The
+commands for copying files out of a VM are similar, but substitute
+@option{-g} for @option{-p}.
+
+Incidentally, these commands work by passing special commands
+@command{extract} and @command{append} on the kernel's command line and copying
+to and from a special simulated ``scratch'' partition. If you're very
+curious, you can look at the @command{pintos} script as well as
+@file{filesys/fsutil.c} to learn the implementation details.
+
+Here's a summary of how to create a disk with a file system partition,
+format the file system, copy the @command{echo} program into the new
+disk, and then run @command{echo}, passing argument @code{x}.
+(Argument passing won't work until you implemented it.) It assumes
+that you've already built the examples in @file{examples} and that the
+current directory is @file{userprog/build}:
+
+@example
+pintos-mkdisk filesys.dsk --filesys-size=2
+pintos -f -q
+pintos -p ../../examples/echo -a echo -- -q
+pintos -q run 'echo x'
+@end example
+
+The three final steps can actually be combined into a single command:
+
+@example
+pintos-mkdisk filesys.dsk --filesys-size=2
+pintos -p ../../examples/echo -a echo -- -f -q run 'echo x'
+@end example
+
+If you don't want to keep the file system disk around for later use or
+inspection, you can even combine all four steps into a single command.
+The @code{--filesys-size=@var{n}} option creates a temporary file
+system partition
+approximately @var{n} megabytes in size just for the duration of the
+@command{pintos} run. The Pintos automatic test suite makes extensive
+use of this syntax: