Make tests public. Rewrite most tests. Add tests.
[pintos-anon] / doc / filesys.texi
index 6ebc4d9707e1cb4da43a44058beb2d9fdd353974..32a6e8885d139df9f0457753ce66c7dbf17dce49 100644 (file)
@@ -2,52 +2,46 @@
 @chapter Project 4: File Systems
 
 In the previous two assignments, you made extensive use of a
-filesystem without actually worrying about how it was implemented
+file system without actually worrying about how it was implemented
 underneath.  For this last assignment, you will fill in the
-implementation of the filesystem.  You will be working primarily in
+implementation of the file system.  You will be working primarily in
 the @file{filesys} directory.
 
-You should build on the code you wrote for the previous assignments.
-However, if you wish, you may turn off your VM features, as they are
-not vital to making the filesystem work.  (You will need to edit
-@file{filesys/Makefile.vars} to fully disable VM.)  All of the
-functionality needed for project 2 (argument passing, syscalls and
-multiprogramming) must work in your filesys submission.
+You may build project 4 on top of project 2 or project 3.  In either
+case, all of the functionality needed for project 2 must work in your
+filesys submission.  If you build on project 3, then all of the project
+3 functionality must work also, and you will need to edit
+@file{filesys/Make.vars} to enable VM functionality.  A small amount of
+extra credit is available if you do build on project 3.
 
-On the other hand, one of the particular charms of working on
-operating systems is being able to use what you build, and building
-full-featured systems.  Therefore, you should strive to make all the
-parts work together so that you can run VM and your filesystem at the
-same time.  Plus, keeping VM is a great way to stress-test your
-filesystem implementation.
+@menu
+* Project 4 Background::        
+* Project 4 Requirements::      
+* File System FAQ::             
+@end menu
+
+@node Project 4 Background
+@section Background
 
 @menu
 * File System New Code::        
-* File System Synchronization::  
-* Problem 4-1 Indexed Files::     
-* Problem 4-2 File Growth::     
-* Problem 4-3 Subdirectories::  
-* Problem 4-4 Buffer Cache::    
-* File System Design Document Requirements::  
-* File System FAQ::             
 @end menu
 
 @node File System New Code
-@section New Code
+@subsection New Code
 
 Here are some files that are probably new to you.  These are in the
 @file{filesys} directory except where indicated:
 
 @table @file
 @item fsutil.c
-Simple utilities for the filesystem that are accessible from the
+Simple utilities for the file system that are accessible from the
 kernel command line.
 
 @item filesys.h
 @itemx filesys.c
-Top-level interface to the file system.  Please read the long comment
-near the top of @file{filesys.c}, which introduces some details of the
-file system code as provided.
+Top-level interface to the file system.  @xref{Using the File System},
+for an introduction.
 
 @item directory.h
 @itemx directory.c
@@ -77,56 +71,40 @@ system has calls that are similar, but not identical, to these.  The
 file system translates these calls into physical disk operations.  
 
 All the basic functionality is there in the code above, so that the
-filesystem is usable right off the bat.  In fact, you've been using it
+file system is usable from the start, as you've seen
 in the previous two projects.  However, it has severe limitations
 which you will remove.
 
 While most of your work will be in @file{filesys}, you should be
 prepared for interactions with all previous parts (as usual).
 
-@node File System Synchronization
-@section Synchronization
+@node Project 4 Requirements
+@section Requirements
 
-The provided file system requires external synchronization, that is,
-callers must ensure that only one thread can be running in the file
-system code at once.  Your submission should use a finer-grained
-synchronization strategy.  You will need to consider synchronization
-issues for each type of file system object.  The provided code uses the
-following strategies:
-
-@itemize @bullet
-@item
-The free map and root directory are read each time they are needed for
-an operation, and if they are modified, they are written back before the
-operation completes.  Thus, the free map is always consistent from an
-external viewpoint.
-
-@item
-Inodes are immutable in the provided file system, that is, their content
-never changes between creation and deletion.  Furthermore, only one copy
-of an inode's data is maintained in memory at once, even if the file is
-open in multiple contexts.
-
-@item
-File data doesn't have to be consistent because it's just not part of
-the model.  In Unix and many other operating systems, a read of a file
-by one process when the file is being written by another process can
-show inconsistent results: it can show that none, all, or part of the
-write has completed.  (However, after the write system call returns to
-its caller, all subsequent readers must see the change.)  Similarly,
-when two threads write to the same part of a file at the same time,
-their data may be interleaved.  External synchronization of the provided
-file system ensures that reads and writes are fully serialized, but your
-file system doesn't have to maintain full serialization as long as it
-follows the rules above.
-@end itemize
+@menu
+* Project 4 Design Document::   
+* Indexed and Extensible Files::  
+* Subdirectories::              
+* Buffer Cache::                
+* File System Synchronization::  
+@end menu
+
+@node Project 4 Design Document
+@subsection Design Document
 
-@node Problem 4-1 Indexed Files
-@section Problem 4-1: Indexed Files
+Before you turn in your project, you must copy @uref{filesys.tmpl, , the
+project 4 design document template} into your source tree under the name
+@file{pintos/src/filesys/DESIGNDOC} and fill it in.  We recommend that
+you read the design document template before you start working on the
+project.  @xref{Project Documentation}, for a sample design document
+that goes along with a fictitious project.
+
+@node Indexed and Extensible Files
+@subsection Indexed and Extensible Files
 
 The basic file system allocates files as a single extent, making it
 vulnerable to external fragmentation.  Eliminate this problem by
-modifying the inode structure.  In practice, this probably means using
+modifying the on-disk inode structure.  In practice, this probably means using
 an index structure with direct, indirect, and doubly indirect blocks.
 (You are welcome to choose a different scheme as long as you explain the
 rationale for it in your design documentation, and as long as it does
@@ -138,22 +116,18 @@ stored in one disk sector, limiting the number of block pointers that it
 can contain.  Supporting 8 MB files will require you to implement
 doubly-indirect blocks.
 
-@node Problem 4-2 File Growth
-@section Problem 4-2: File Growth
-
-Implement extensible files.  In the basic file system, the file size
-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.  
-Make sure that concurrent accesses to the inode remain properly
-synchronized.
+An extent-based file can only grow if it is followed by empty space, but
+with indexed inodes file growth is possible whenever free space is
+available.  Implement file growth.  In the basic file system, the file
+size is specified when the file is created.  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.  Your file system
+must allow this.
 
 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.
+to expand beyond its initial limit of 16 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
@@ -168,317 +142,261 @@ until they are explicitly written.  The latter file systems are said to
 support ``sparse files.''  You may adopt either allocation strategy in
 your file system.
 
-@node Problem 4-3 Subdirectories
-@section Problem 4-3: Subdirectories
+@node Subdirectories
+@subsection Subdirectories
 
 Implement a hierarchical name space.  In the basic file system, all
 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).
+entries to point to files or to other directories.
 
 Make sure that directories can expand beyond their original size just
 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
+it, at your option.  You must allow full path names to be
 much longer than 14 characters.
 
 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.
+startup, the initial process's current directory is the root 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.
 
 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.
+deleted if they do not contain any files or subdirectories.
 
 Implement the following new system calls:
 
-@table @code
-@item SYS_chdir
-@itemx bool chdir (const char *@var{dir})
-Attempts to change the current working directory of the process to
-@var{dir}, which may be either relative or absolute.  Returns true if
+@deftypefn {System Call} bool chdir (const char *@var{dir})
+Changes the current working directory of the process to
+@var{dir}, which may be relative or absolute.  Returns true if
 successful, false on failure.
+@end deftypefn
 
-@item SYS_mkdir
-@itemx bool mkdir (const char *dir)
-Attempts to create the directory named @var{dir}, which may be either
+@deftypefn {System Call} bool mkdir (const char *@var{dir})
+Creates the directory named @var{dir}, which may be
 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.
+@end deftypefn
 
-@item SYS_lsdir
-@itemx void lsdir (void)
+@deftypefn {System Call} void lsdir (void)
 Prints a list of files in the current directory to @code{stdout}, one
 per line, in no particular order.
-@end table
+@end deftypefn
 
 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?)
+@command{cd} is a shell command.
 
 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
+You may support @file{.} and @file{..} for a small amount of extra
+credit.
+
+@node Buffer Cache
+@subsection Buffer Cache
 
 Modify the file system to keep a cache of file blocks.  When a request
 is made to read or write a block, check to see if it is stored in the
 cache, and if so, fetch it immediately from the cache without going to
-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.  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.)  Document your
-replacement algorithm in your design document.
-
-The provided file system code uses a ``bounce buffer'' in @struct{file}
-to translate the disk's sector-by-sector interface into the system call
-interface's byte-by-byte interface.  It needs per-file buffers because,
-without them, there's no other good place to put sector
-data.@footnote{The stack is not a good place because large objects
-should not be allocated on the stack.  A 512-byte sector is pushing the
-limit there.}  As part of implementing the buffer cache, you should get
-rid of these bounce buffers.  Instead, copy data into and out of sectors
-in the buffer cache directly.  You will probably need some
-synchronization to prevent sectors from being evicted from the cache
-while you are using them.
-
-In addition to the basic file caching scheme, your implementation
-should also include the following enhancements:
+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.
 
-@table @b
-@item write-behind:
-Instead of always immediately writing modified data to disk, dirty
-blocks can be kept in the cache and written out sometime later.  Your
-buffer cache should write behind whenever a block is evicted from the
-cache.
+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.
 
-@item read-ahead:
-Your buffer cache should automatically fetch the next block of a file
-into the cache when one block of a file is read, in case that block is
-about to be read.
-@end table
+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.
 
-For each of these three optimizations, design a file I/O workload that
-is likely to benefit from the enhancement, explain why you expect it
-to perform better than on the original file system implementation, and
-demonstrate the performance improvement.
+The provided inode code uses a ``bounce buffer'' allocated with
+@func{malloc} to translate the disk's sector-by-sector interface into
+the system call interface's byte-by-byte interface.  You should get rid
+of these bounce buffers.  Instead, copy data into and out of sectors in
+the buffer cache directly.
 
-Note that write-behind makes your filesystem more fragile in the face
-of crashes.  Therefore, you should
-periodically write all cached blocks to disk.  If you have
-@func{timer_sleep} from the first project working, this is an
-excellent application for it.  (If you're still using the base
+Your implementation should also include the following features:
+
+@table @b
+@item write-behind:
+Keep dirty blocks in the cache, instead of immediately writing modified
+data to disk.  Write dirty blocks to disk whenever they are evicted.
+Because write-behind makes your file system more fragile in the face of
+crashes, in addition you should periodically write all dirty, cached
+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, this is
+an excellent application for it.  If you're still using the base
 implementation of @func{timer_sleep}, be aware that it busy-waits, which
-is not an acceptable solution.) If @func{timer_sleep}'s delays seem too
+is not an acceptable solution. 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}).
 
-Likewise, read-ahead is only really useful when done asynchronously.
-That is, if a process wants disk block 1 from the file, it needs to
-block until disk block 1 is read in, but once that read is complete,
-control should return to the process immediately while the read
-request for disk block 2 is handled asynchronously.  In other words,
-the process will block to wait for disk block 1, but should not block
-waiting for disk block 2.
-
-When you're implementing this, please make sure you have a scheme for
-making any read-ahead and write-behind threads halt when Pintos is
-``done'' (when the user program has completed, etc), so that Pintos
-will halt normally and the disk contents will be consistent.
-
-@node File System Design Document Requirements
-@section Design Document Requirements
+@item read-ahead:
+Your buffer cache should automatically fetch the next block of a file
+into the cache when one block of a file is read, in case that block is
+about to be read.
 
-As always, submit a design document file summarizing your design.  Be
-sure to cover the following points:
+Read-ahead is only really useful when done asynchronously.  That means,
+if a process requests disk block 1 from the file, it should block until disk
+block 1 is read in, but once that read is complete, control should
+return to the process immediately.  The read-ahead request for disk
+block 2 should be handled asynchronously, in the background.
+@end table
 
-@itemize @bullet
-@item
-How did you choose to synchronize file system operations?
+@node File System Synchronization
+@subsection Synchronization
 
-@item
-How did you structure your inodes? How many blocks did you access
-directly, via single-indirection, and/or via double-indirection?  Why?
+The provided file system requires external synchronization, that is,
+callers must ensure that only one thread can be running in the file
+system code at once.  Your submission must adopt a finer-grained
+synchronization strategy that does not require external synchronization.
+To the extent possible, operations on independent entities should be
+independent, so that they do not need to wait on each other.
+
+Operations on different cache blocks must be independent.  In
+particular, when I/O is required on a particular block, operations on
+other blocks that do not require I/O should proceed without having to
+wait for the I/O to complete.
+
+Multiple processes must be able to access a single file at once.
+Multiple reads of a single file must be able to complete without
+waiting for one another.  When writing to a file does not extend the
+file, multiple processes should also be able to write a single file at
+once.  A read of a file by one process when the file is being written by
+another process is allowed to show that none, all, or part of the write
+has completed.  (However, after the @code{write} system call returns to
+its caller, all subsequent readers must see the change.)  Similarly,
+when two processes simultaneously write to the same part of a file,
+their data may be interleaved.
 
-@item
-How did you structure your buffer cache? How did you perform a lookup
-in the cache? How did you choose elements to evict from the cache?
+On the other hand, extending a file and writing data into the new
+section must be atomic.  Suppose processes A and B both have a given
+file open and both are positioned at end-of-file.  If A reads and B
+writes the file at the same time, A may read all, part, or none of what
+B writes.  However, A may not read data other than what B writes, e.g.@:
+if B's data is all nonzero bytes, A is not allowed to see any zeros.
 
-@item
-How and when did you flush the cache?
-@end itemize
+Operations on different directories should take place concurrently.
+Operations on the same directory may wait for one another.
 
 @node File System FAQ
 @section FAQ
 
-@enumerate 1
-@item
-@b{What extra credit opportunities are available for this assignment?}
-
-@itemize @bullet
-@item
-We'll give out extra credit to groups that implement Unix-style
-support for @file{.} and @file{..} in relative paths in their projects.
-
-@item
-We'll give some extra credit if you submit with VM enabled.  If you do
-this, make sure you show us that you can run multiple programs
-concurrently.  A particularly good demonstration is running
-@file{capitalize} (with a reduced words file that fits comfortably on
-your disk, of course).  So submit a file system disk that contains a
-VM-heavy program like @file{capitalize}, so we can try it out.  And also
-include the results in your test case file.
-
-We feel that you will be much more satisfied with your cs140 ``final
-product'' if you can get your VM working with your file system.  It's
-also a great stress test for your FS, but obviously you have to be
-pretty confident with your VM if you're going to submit this extra
-credit, since you'll still lose points for failing FS-related tests,
-even if the problem is in your VM code.
-
-@item
-A point of extra credit can be assigned if a user can recursively
-remove directories from the shell command prompt.  Note that the
-typical semantic is to just fail if a directory is not empty.
-@end itemize
-
-Make sure that you discuss any extra credit in your @file{README}
-file.  We're likely to miss it if it gets buried in your design
-document.
-
-@item
-@b{What exec modes for running Pintos do I absolutely need to
-support?}
-
-You also need to support the @option{-f}, @option{-ci}, @option{-co},
-and @option{-ex} flags individually, and you need to handle them when
-they're combined, like this: @samp{pintos -f -ci shell 12345 -ex
-"shell"}.  Thus, you should be able to treat the above as equivalent to:
-
-@example
-pintos -f
-pintos -ci shell 12345
-pintos -ex "shell"
-@end example
-
-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.
-
-@item
-@b{Will you test our file system with a different @code{DISK_SECTOR_SIZE}?}
+@table @b
+@item How much code will I need to write?
+
+Here's a summary of our reference solution, produced by the
+@command{diffstat} program.  The final row gives total lines inserted
+and deleted; a changed line counts as both an insertion and a deletion.
+
+This summary is relative to the Pintos base code, but we started from
+the reference solution to project 3.  Thus, the reference solution runs
+with virtual memory enabled.  @xref{Project 3 FAQ}, for the summary
+of project 3.
+
+@verbatim
+ Makefile.build       |    5 
+ devices/timer.c      |   42 ++
+ filesys/Make.vars    |    6 
+ filesys/cache.c      |  473 +++++++++++++++++++++++++
+ filesys/cache.h      |   23 +
+ filesys/directory.c  |   99 ++++-
+ filesys/directory.h  |    3 
+ filesys/file.c       |    4 
+ filesys/filesys.c    |  194 +++++++++-
+ filesys/filesys.h    |    5 
+ filesys/free-map.c   |   45 +-
+ filesys/free-map.h   |    4 
+ filesys/fsutil.c     |    8 
+ filesys/inode.c      |  444 ++++++++++++++++++-----
+ filesys/inode.h      |   11 
+ threads/init.c       |    5 
+ threads/interrupt.c  |    2 
+ threads/thread.c     |   32 +
+ threads/thread.h     |   38 +-
+ userprog/exception.c |   12 
+ userprog/pagedir.c   |   10 
+ userprog/process.c   |  332 +++++++++++++----
+ userprog/syscall.c   |  582 ++++++++++++++++++++++++++++++-
+ userprog/syscall.h   |    1 
+ vm/frame.c           |  161 ++++++++
+ vm/frame.h           |   23 +
+ vm/page.c            |  297 +++++++++++++++
+ vm/page.h            |   50 ++
+ vm/swap.c            |   85 ++++
+ vm/swap.h            |   11 
+ 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
 of IDE disk hardware.
 
-@item
-@b{Will the @struct{inode} take up space on the disk too?}
-
-Yes.  Anything stored in @struct{inode} takes up space on disk,
-so you must include this in your calculation of how many entires will
-fit in a single disk sector.
-
-@item
-@b{What's the directory separator character?}
+@item What's the directory separator character?
 
 Forward slash (@samp{/}).
-@end enumerate
+@end table
 
 @menu
-* Problem 4-2 File Growth FAQ::  
-* Problem 4-3 Subdirectory FAQ::  
-* Problem 4-4 Buffer Cache FAQ::  
+* Indexed Files FAQ::           
+* Subdirectories FAQ::          
+* Buffer Cache FAQ::            
 @end menu
 
-@node Problem 4-2 File Growth FAQ
-@subsection Problem 4-2: File Growth FAQ
+@node Indexed Files FAQ
+@subsection Indexed Files FAQ
 
-@enumerate 1
-@item
-@b{What is the largest file size that we are supposed to support?}
+@table @b
+@item What is the largest file size that we are supposed to support?
 
 The disk we create will be 8 MB or smaller.  However, individual files
 will have to be smaller than the disk to accommodate the metadata.
-You'll need to consider this when deciding your @struct{inode}
-organization.
-@end enumerate
-
-@node Problem 4-3 Subdirectory FAQ
-@subsection Problem 4-3: Subdirectory FAQ
-
-@enumerate 1
-@item
-@b{What's the answer to the question in the spec about why
-@command{ls} and @command{mkdir} are user programs, while @command{cd}
-is a shell command?}
-
-Each process maintains its own current working directory, so it's much
-easier to change the current working directory of the shell process if
-@command{cd} is implemented as a shell command rather than as another
-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 should the @code{lsdir} system call return?}
-
-The @code{lsdir} system call should not return until after the
-directory has been printed.  Here's a code fragment, and the desired
-output:
-
-@example
-printf ("Start of directory\n");
-lsdir ();
-printf ("End of directory\n");
-@end example
-
-This code should create the following output:
+You'll need to consider this when deciding your inode organization.
+@end table
 
-@example
-Start of directory
-@dots{}directory contents@dots{}
-End of directory
-@end example
+@node Subdirectories FAQ
+@subsection Subdirectories FAQ
 
-@item
-@b{Do we have to implement both absolute and relative pathnames?}
+@table @b
+@item Why is @command{cd} a shell command?
 
-Yes.  Implementing @file{.} and @file{..} is extra credit, though.
-@end enumerate
+The current directory of each process is independent.  A @command{cd}
+program could change its own current directory, but that would have no
+effect on the shell.  In fact, Unix-like systems don't provide any way
+for one process to change another process's current working directory.
+@end table
 
-@node Problem 4-4 Buffer Cache FAQ
-@subsection Problem 4-4: Buffer Cache FAQ
+@node Buffer Cache FAQ
+@subsection Buffer Cache FAQ
 
-@enumerate 1
-@item
-@b{We're limited to a 64-block cache, but can we also keep an
-@struct{inode_disk} inside @struct{inode}, the way the provided code
-does?}
+@table @b
+@item Can we keep a @struct{inode_disk} inside @struct{inode}?
 
 The goal of the 64-block limit is to bound the amount of cached file
 system data.  If you keep a block of disk data---whether file data or
@@ -487,26 +405,24 @@ the 64-block limit.  The same rule applies to anything that's
 ``similar'' to a block of disk data, such as a @struct{inode_disk}
 without the @code{length} or @code{sector_cnt} members.
 
-You can keep a cached copy of the free map in memory permanently if you
-like.  It doesn't have to count against the cache size.
-
 That means you'll have to change the way the inode implementation
 accesses its corresponding on-disk inode right now, since it currently
 just embeds a @struct{inode_disk} in @struct{inode} and reads the
-corresponding sector in from disk when it's created.  Keeping extra
-copies of inodes would be cheating the 64-block limitation that we place
+corresponding sector from disk when it's created.  Keeping extra
+copies of inodes would subvert the 64-block limitation that we place
 on your cache.
 
-You can store pointers to inode data in @struct{inode}, if you want, and
-you can store some other small amount of information to help you find
-the inode when you need it.  Similarly, if you want to store one block
-of data plus some small amount of metadata for each of your 64 cache
-entries, that's fine.
-
-If you look at @func{inode_byte_to_sector}, it uses the
-@struct{inode_disk} directly without having first read in that sector
-from wherever it was in the storage hierarchy.  This will no longer
-work.  You will need to change @func{inode_byte_to_sector} so that it
-reads the @struct{inode_disk} from the storage hierarchy before using
-it.
-@end enumerate
+You can store a pointer to inode data in @struct{inode}, if you want,
+and you can store other information to help you find the inode when you
+need it.  Similarly, you may store some metadata along each of your 64
+cache entries.
+
+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.
+
+@func{byte_to_sector} in @file{filesys/inode.c} uses the
+@struct{inode_disk} directly, without first reading that sector from
+wherever it was in the storage hierarchy.  This will no longer work.
+You will need to change @func{inode_byte_to_sector} so that it reads the
+@struct{inode_disk} from the storage hierarchy before using it.
+@end table