In this assignment, you will be developing a working file system checker. A checker reads in a file system image and makes sure that it is consistent. When it isn’t, the checker takes steps to repair the problems it sees. However, you won’t be doing any repairs to keep this project a little simpler (well, unless you want a bit challenges and to earn some extra credits).
Some basic background about file system consistency is found in the textbook chapter on Crash Consistency: FSCK and Journaling
For this project, you will use the xv6 file system image as the basic image
that you will be reading and checking. The file
include/fs.h includes the
basic structures you need to understand, including the superblock, on disk
inode format (
struct dinode), and directory entry format (
dirent). The tool
tools/mkfs.c will also be useful to look at, in order to
see how an empty file-system image is created.
Much of this project will be puzzling out the exact on-disk format xv6 uses
for its simple file system, and then writing checks to see if various parts of
that structure are consistent. Thus, reading through
mkfs.c and the file
system code itself will help you understand how xv6 uses the bits in the image
to record persistent information.
Your checker should read through the file system image and determine the
consistency of a number of things, including the following. When a problem is
detected, print the error message (shown below), followed by
\n to standard error and
exit immediately with exit code 1 (i.e., call
For the metadata in the super block, the file-system size is larger than the number of blocks used by the super-block, inodes, bitmaps and data. If not, print
ERROR: superblock is corrupted.
Each inode is either unallocated or one of the valid types (
T_DEV). If not, print
ERROR: bad inode.
For in-use inodes, each address that is used by inode is valid (points to a
valid datablock address within the image). If the direct block is used and is
ERROR: bad direct address in inode.; if the indirect block is
in use and is invalid, print
ERROR: bad indirect address in inode. Update: If any of the
addresses within the indirect block is in use and is invalid, print
ERROR: bad indirect address in inode.
Each directory contains
.. entries, and the
. entry points to the
directory itself. (NOTE: The root directory
/ should also have both entries). If not, print
ERROR: directory not properly formatted.
For in-use inodes, each address in use is also marked in use in the
bitmap. If not, print
ERROR: address used by inode but marked free in bitmap.
For blocks marked in-use in bitmap, the block should actually be in-use in
an inode or indirect block somewhere. If not, print
ERROR: bitmap marks block in use but it is not in use.
For in-use inodes, each direct address in use is only used once. If not,
ERROR: direct address used more than once.
For in-use inodes, the file size stored must be within the actual number of blocks used for storage. That is if
b blocks are used with block size
s, then the file size must be
> (b-1)*s and
<= b*s. If not, print
ERROR: incorrect file size in inode.
For all inodes marked in use, each must be referred to in at least one directory.
If not, print
ERROR: inode marked used but not found in a directory.
For each inode number that is referred to in a valid directory, it is actually
marked in use. If not, print
ERROR: inode referred to in directory but marked free.
Reference counts (number of links) for regular files match the number of times
file is referred to in directories (i.e., hard links work correctly).
If not, print
ERROR: bad reference count for file. (NOTE: xv6 does not have support for soft links)
No extra links allowed for directories (each directory only appears in one
other directory). If not, print
ERROR: directory appears more than once in file system.
Your checker program, called
xfsck, must be invoked exactly as follows:
prompt> xfsck file_system_image
The image file is a file that contains the file system image. If no image file is provided, you should print the usage error shown below:
prompt> xfsck Usage: xfsck <file_system_image>
This output must be printed to standard error and exit with the error code of 1.
If the file system image does not exist, you should print the error
found. to standard error and exit with the error code of 1.
If the checker detects any one of the 12 errors above, it should print the specific error to standard error and exit with error code 1.
If the checker detects none of the problems listed above, it should exit with return code of 0 and not print anything.
For this project, you can gain some extra points (10% of the project weight) by implementing the following more challenging condition checks:
..entry in a directory refers to the proper parent inode and parent inode points back to it.
ERROR: parent directory mismatch.
ERROR: inaccessible directory exists.
"inode marked used but not found in a directory"error (Point 9). An xv6 image that has a number of in-use files and directories that are not linked by any directory. An example of such image is available:
/u/c/s/cs537-1/tests/p5/images/Repair. Your job is to collect these nodes and put them in
lost_founddirectory is already present in the root directory of the provided image.
For doing the last two points you will need to obtain the write access to file system image in order to modify it. The repair operation of the program should only be performed
-r flag is specified.
prompt> xfsck -r image_to_repair
It may be worth looking into using
mmap() for the project. Like, seriously,
mmap() to access the file-system image, it will make your life so much
It should be very helpful to read Chapter 6 of the xv6 book here. Note that the version of xv6 we’re using does not include the logging feature described in the book; you can safely ignore the parts that pertain to that.
Make sure to look at
fs.img, which is a file system image created when you
make xv6 by the tool mkfs (found in the
tools/ directory of xv6). The output
of this tool is the file
fs.img and it is a consistent file-system image. The
tests, of course, will put inconsistencies into this image, but your tool
should work over a consistent image as well. Study
mkfs and its output to
begin to make progress on this project.
It is a good habit to get basic functionalities working before moving to advanced features. We will provided a few tests for you, which can be run through the following command once they have been made available:
The test cases for the extra credit part will not be provided. One of challenging parts to earn extra credits is that you will need to create your own images and scripts to test your implementation.
23rd April 2020, 10:00 PM
The handin directory is
~cs537-1/handin/<cs-login>/p5/. To submit the
solutions copy all necessary source and headers files to the handin
directory. One way to do this would be to navigate to your solution and execute
cp -r . ~cs537-1/handin/<cs-login>/p5/
Consider the following when submitting the solution:
SLIP_DAYSfile in the
/<cs-login>/p5/directory otherwise we use the submission on the due date.
xfsck.cand other required header files which should be directly copied under the
fs.hyou should use the one provided in xv6 without any changes.
gcc xfsck.c. Meaning no other
cfiles should be needed to create the binary.
If you choose to work in pairs, only one of you needs to submit the source code. But, both of you need to submit an additional partner.login file, which contains one line that has the CS login of your partner (and nothing else). If there is no such file, we are assuming you are working alone. If both of you turn in your codes, we will just randomly choose one to grade.
This project is to be done in groups of size one or two (not three or more). Now, within a group, you can share as much as you like. However, copying code across groups is considered violation of plagiarism policy.
If you are planning to use
git or other version control systems (which are highly recommended for this project), just be careful not to put your code in a public repository.
The project uses material created by Prof. Remzi for his OS class offered in Spring 2018 and Prof. Michael Swift for his OS class in Fall 2017.