Homebrew file system

In this homework, we create our own filesystem kernel module. The template code provides a "skeleton" file system module, which can be loaded and mounted. However, although it has all the pieces you need, it doesn't do what we want, and that's where you come in.

To try out the template code, you will need the virtual machine and custom kernel that you set up in homeworks 1 and 2. Check out the template, and run make to build the module. Assuming that worked, you can now run:

sudo insmod ./hw9fs.ko

to load the module. To see if the module is loaded, take a look in /proc/filesystems and look for hw9fs. Also, try running tail /var/log/messages, to see some debug output. With the module loaded, we can now use our filesystem. Run

sudo mount -t hw9fs -o ro,loop test.img mnt

to mount the disk image test.img in read-only mode, using our filesystem hw9fs, and

sudo mount -t hw9fs -o loop test.img mnt

for read-write access (the last several parts below). Read-only access is less demanding, you might want to try that first.

The directory mnt, which used to be a regular directory, now contains our mounted filesystem. See if your output looks like mine:

jakob@ubuntu:~/hw9$ ls mnt
ls: cannot access mnt/nonexisting_file: No such file or directory
existing_file  nonexisting_file

Clearly, there is something wrong with nonexisting_file, but let's not worry about it. Let's see what's in existing_file.

jakob@ubuntu:~/hw9$ cat mnt/existing_file
File 3 comes second to last, and it is a long file.
File 3 comes second to last, and it is a long file.
File 3 comes second to last, and it is a long file.
...
File 3 comes second to last, and it is a long file.
File 3 comes second to last, and it jakob@ubuntu:~/hw9$

If you got this far, you're ready to get started. To remove the module, first unmount the filesystem:

sudo umount mnt

then unload the module

sudo rmmod hw9fs

Disk Format

Let's take a peek at the disk image hexdump -C test.img. It consists of two types of 1024-byte blocks: a single disk header block (superblock) which comes first, followed by a number of data blocks. The header consists of up to 30 adjacent structs like this:

Filename	Size
char[26]	int

The header is then followed by the file contents. Each file uses one or more consecutive, full blocks. Though the file may be smaller than a 1024-byte block, the block is zero-padded so that the next file starts on an even block boundary. This filesystem does not support subdirectories.

You can create your own disk images using the included mkcs385fs tool. For example, mkcs385fs test_directory/ test.img creates the supplied disk image.

HINT: check your logs in a separate window, using tail -f var/log/kern.log. You will be docked points for kernel warning messages appearing in this file (not your debug output).

1. Directory Listing (3 pts)

Update the module to show a correct file listing. The order is not important, but both ls mnt and ls -l mnt should show no error messages or question marks. For an example output, try ls -l test_directory. Filename and size must be correct, and the files must be readable, the rest is not important, but no question marks or error messages are allowed.

2. File contents (2 pts)

Update the module to support correct listing of file contents with cat. To do this, you will mostly need a way to map a "file block" into a disk block. The output of cat mnt/* should be identical to cat test_directory/*.

3. File creation (2 pts)

Support the creation of new files in the mounted directory. Again, our filesystem does not support directories, so all you need to handle is regular file creation. Test it like this:

touch mnt/mynewfile
ls -l mnt

you should now see "mynewfile" appear in the listing, with a size of zero.

hint: you'll need to add a function pointer to your inode_operations struct.

4. Persistent file creation (4 pts)

Make sure your file still exists after unmounting and re-mounting your image. To do this, you'll need to write out your updated superblock to disk.

hint: This template does not memcpy the superblock to a kmalloced bit of memory. Instead, it holds on to the buffer_head* from sb_bread. See how other filesystems (fat or ext2) use sync_dirty_buffer to write this out to disk in an easy way. Double-check your updated disk image with hexdump -C test.img | less

5. Writing to files (2 pts)

Support writing data to files. Test this as follows:

echo my test > mnt/testfile
ls -l mnt
cat mnt/testfile

the ls -l should show the new file with size 8, and the cat should output "my test". Make sure that your written output survives an unmount/mount.

hint: you'll need to add several function pointers to your address_space_operations and file_operations. Look at the fat implementation to get some ideas.

6. Writing large files (2 pts)

Make sure you can handle writes of more than one block correctly. Try cat hw10fs.c > mnt/testfile to try with a large file.

7. Handle "out of space" errors correctly (1 pts)

Our filesystem does not support growing files that are "wedged" between other files (we use contiguous allocation without any support for moving files around). Make sure writing to a "wedged" file does not overwrite the contents of other files, and instead makes the terminal display "out of space" or some other user-friendly error.

HINTS

Kernel programming is a different beast. There is no printf, no malloc, no math library, etc. Sometimes there are alternatives: printk and kmalloc, for example, but library support is limited within the kernel.

If you make a mistake in a kernel module, you may crash the kernel, hang your program (permanently, unkillably), get the kernel into a funky state, wipe your whole disk, or get pleasantly kicked out by the kernel with no ill effects, all depending on how unlucky you get. Use VMWare's "Snapshot" facility regularly, and consider editing your code outside of the VM, and copying it into the VM for each test (using scp or rsync). You'll likely get to restart your VM a bunch of times even if you take the precautions.

• Excellent intro document here: simple file system
• The fs.h - all the main filesystem structs are in here
• BeFS implementation - I used this to learn how to do things
• alternative link for the above

This homework requires very little coding: However, it will take a lot of looking at other kernel code, and probably a bunch of reboots, before you get it right.

Debugging Kernel Code

A first great step is to increase the kernel log level:

sudo sysctl kernel.printk=7

Next, switch your virtual machine to a text console, by hitting ctrl-alt-f1, or cmd-ctrl-fn-f1 on a mac. This is for monitoring kernel output only: do not use this console for running things or editing text.