from a raw disk into a file or visa versa. However, operating systems generally provide extra

functionality on top of disk devices such as the ability to partition disks and mount filesystems

from them.

2.1 vnd(4)

The vnd(4) driver in OpenBSD provides a ”disk-like interface to a file”. This means the

OpenBSD kernel can open a file and present it as a block device to the rest of the system,

which in turn allows for the creation and use of filesystems on these disk images.

The vnd(4) driver currently only supports using raw disk images as backing files. There’s

a one-to-one mapping of data offsets for data in the end disk device and the byte offset of that

data in the underlying file. This makes the implementation very simple, with the downside that

the backing file has to be the same size as the disk vnd is presenting. If you have a 32G disk

image, the file will be 32G regardless of how much data is actually stored inside a filesystem

mounted on top of it. Similar functionality exists in the loop driver in Linux, and the lofi

driver in Solaris and Illumos.

2.2 Virtual Hard Disk (VHD)

Virtual Hard Disk (VHD) is a file format for disk images used by Connectix’s Virtual PC

hypervisor, which was later acquired by Microsoft and renamed to Microsoft Virtual PC. A

defining feature of VHD files is that they allocate space and extend the size of the file backing

a disk image on demand. This is different to raw disk images where the backing file has to

pre-allocate space for the entire disk image up front. With VHD, you can also have fixed-size

images, works in a very similar way to the raw images used by vnd.

VHD also supports using a read-only file as a base image and making writing changes to a

separate file. When used by a hypervisor, this allows for thin provisioning of virtual machines

where only changes made by each virtual machine are stored rather than repeated copies of

disks. Due to the popularity of Connectix/Microsoft Virtual PC, it is common for disk images

to be distributed as VHD files.

The VHD format used by this assignment is documented at:

https://stluc.manta.uqcloud.net/comp3301/public/2024/comp3301-vhd-spec.pdf

The same file can be found on Blackboard. This specification differs from the official Microsoft

specification in that it includes annotations for ease of understanding and contains corrections

to errors in the official specification. The official VHD format is documented by Microsoft in

Virtual Hard Disk Format Spec_10_18_06.doc.

4 Specifications

You will be extending the OpenBSD kernel to add support for using VHD files as a backend for

a vhd(4) virtual block device. vhd(4) is roughly based on vnd(4). Boilerplate code for the

device entry points and command line utility will be provided, but you will be implementing

the handling of the file and the VHD file format within the provided kernel driver.

Only a subset of the VHD functionality listed in Microsoft’s specification of the file format

is required. The following functionality is required:

• Read support

• Write support

• Fixed-size images

• Dynamic images

Differencing images do not need to be supported. In addition to supporting the VHD file

format, the kernel should implement the following:

• Deny attaching VHD files which are invalid, corrupted or contain features not supported

by your kernel driver.

• Deny detaching VHD files when the disk is open unless the force flag is passed to the

VHDIOCDETACH ioctl.

• Return the name of the VHD file the device was attached to for the VHDIOCFNAME ioctl.

• Populate a struct stat for the currently attached VHD file for the VHDIOCSTAT ioctl.

4.1 VHD Disk I/O

Reads and writes against the vhd block device should be mapped to vn_rdrw() against the

VHD backing file. Writing to the vhd device must not corrupt the backing VHD disk image.

The read and write functionality contributes to the majority of the marks for this

assignment.

Caching of VHD structures (e.g., footer, dynamic disk header and block allocation table) and

data blocks should be implemented for dynamic images, for improved performance. For example,
if you read a sector from block 0x3301 and immediately read another sector from the

same block, you should not need to read the backing VHD file twice. Same goes for mixed

reads and writes, for example, read on block 0x3010 followed by a write on the same block

should result in one read and one write (not 2 reads and 1 write). The number of data block

cached, the cache replacement algorithm (if you intend on caching 2 or more blocks) and the

implementation details of the caching is up to you to decide, as long as some form of caching

is implemented.

4.2 ioctl interface

The following ioctls should only work on the raw partition of the character device associated

with each vhd disk. Except for VHDIOCATTACH, they should only work when a vhd disk is

attached to a backing file.

VHDIOCATTACH

Specify the VHD file to attach as a block device, and parameters for using the disk in the

kernel. The vhd_attach struct contains the following fields:

• vhd_file - The name of the VHD file to attach a vhd disk to.

• vhd_readonly - The vhd disk can be written to when set to 0, and if the VHD file is

read-only, the vhd disk should fail to attach. The vhd disk should be read-only when set

to a non-zero value, and the VHD file should be opened read-only.

VHDIOCDETACH

This ioctl requests the block device be detached, and the backing file closed. If the disk is

in use, the request should fail with EBUSY unless the unsigned int ioctl argument is set to a

non-zero value. A non zero value requests the forced removal of the block device and close of

the backing VHD file.

VHDIOCFNAME

This ioctl requests the name of the VHD file used for the currently attached block device.

The name should be the same as what was passed as the filename in the VHDIOCATTACH ioctl.

VHDIOCSTAT

This ioctl is equivalent to an fstat(2) system call against the backing file.

5 Provided Tools/Files

5.1 vhdctl

The patch includes source for a vhdctl utility that uses the ioctls defined above to control

vhd devices. It is similar to vnconfig. The source can be found after the patch is applied in

src/usr.sbin/vhdctl.

5.2 rawtest.img

This is a raw disk of size 10 MiB which contains a filesystem with the following files:

-rw -r - -r - - 1 root wheel 10 Oct 4 21:37 comp3301 . txt

drwxr - xr - x 2 root wheel 512 Oct 4 21:39 folder /

- rwxr - xr - x 1 root wheel 6496 Oct 4 21:40 hello *

-rw -r - -r - - 1 root wheel 94 Oct 4 21:40 hello . c

-rw -r - -r - - 1 root wheel 13 Oct 4 21:36 hello . txt

-rw -r - -r - - 1 root wheel 2739 Oct 4 21:38 test . txt

Download:

https://stluc.manta.uqcloud.net/comp3301/public/2024/rawtest.img.

5.3 fixedtest.vhd

This is a fixed-size VHD version of rawtest.img. Download:

https://stluc.manta.uqcloud.net/comp3301/public/2024/fixedtest.vhd.

5.4 dynatest.vhd

This is a dynamic VHD version of rawtest.img. Download:

https://stluc.manta.uqcloud.net/comp3301/public/2024/dynatest.vhd.

5.5 vhdtool

This tool is not available yet. It will allow you to create VHD files and convert disk images

between raw and VHD. It will also allow you to perform basic consistency checks on VHD files.

You do not need this tool at the current stage, it will be released later.