makevhd

makevhd is a small Go command-line tool for creating FAT-formatted disk image files, and was written specifically to create images for use with MiSTer FPGA. It can create both raw "superfloppy" images and fixed VHD images with an MBR and single FAT partition. The tool includes built-in FAT formatting code, so no external dependencies are required.

Can be run on the MiSTer itself or on a separate Linux or Windows machine. The resulting images can be mounted and populated with files on either platform before copying to the MiSTer, or mounted and populated directly on the MiSTer after creating an empty image.

It supports two output formats:

• .img: a raw "superfloppy" image with the FAT filesystem written directly at sector 0
• .vhd: a fixed VHD image with:
  • a raw disk image
  • an MBR
  • one FAT partition
  • a fixed VHD footer appended at the end

The code is split into:

• main.go: CLI entrypoint
• disktools/diskTools.go: reusable library code

Build Requirements

• Go 1.22+

Realease Binaries

Prebuilt binaries for Linux and Windows are available in the releases section. This contains binaries for Linux AMD64, Linux ARMv7, Linux ARM64, and Windows AMD64. The Linux ArMv7 binary is suitable for running directly on the MiSTer FPGA.

Usage

Run the program with a filename and size in megabytes:

makevhd mydisk.img 64
makevhd mydisk.vhd 64

To request a standard DOS floppy image, use an .img filename with --floppy:

makevhd floppy.img --floppy 1440k
makevhd floppy.img --floppy 1.44m
makevhd floppy.img --floppy 3.5hd

FAT Format Override

By default, makevhd chooses the FAT type from the image size:

Size	Default FAT type
16 MB or smaller	FAT12
over 16 MB through 512 MB	FAT16
over 512 MB	FAT32

For .img files, the size check uses the full image size. For .vhd files, it uses the partition size inside the VHD, which is about 1 MB smaller than the requested disk size because the partition starts at LBA 2048.

You can override the automatic choice with --fat <12|16|32> or --fat=<12|16|32>:

makevhd mydisk.img 64 --fat 16
makevhd mydisk.vhd 64 --fat=32

The override changes the actual filesystem layout, not just the label in the boot sector. makevhd recalculates the FAT size, cluster size, reserved sectors, root directory layout, and, for .vhd files, the MBR partition type to match the requested FAT variant.

The requested FAT type still has to be valid for the image size. If makevhd cannot derive a valid FAT12, FAT16, or FAT32 layout for the requested size, it exits with an error instead of writing a misleading image. DOS floppy presets do not use this override; they always use the fixed FAT12 layout for the selected floppy type.

Using on MiSTer FPGA

MiSTer FPGA uses a 32-bit ARM Linux environment, so use the Linux ARMv7 build:

scp dist/makevhd-linux-armv7 root@<mister-ip>:/media/fat/Scripts/makevhd
scp dist/mount-image.sh root@<mister-ip>:/media/fat/Scripts/mount-image.sh
ssh root@<mister-ip>
chmod +x /media/fat/Scripts/makevhd /media/fat/Scripts/mount-image.sh

The files can also be copied using Samba or FTP if you prefer.

Then run it directly on the MiSTer in the games folder of the core you want to use it with:

makevhd mydisk.vhd 64
makevhd floppy.img --floppy 1440k

Use .vhd when a MiSTer core expects a partitioned hard disk image. Use floppy .img output when a core expects a raw DOS floppy image.

To add files to an image, mount it with the helper script and copy files into the mounted filesystem. You can do this on a Linux machine before copying the finished image to the MiSTer, or you can do it directly on the MiSTer after creating the image.

./makevhd mydisk.vhd 64
sudo ./mount-image.sh ./mydisk.vhd /mnt/makevhd
sudo cp -a ./files-to-copy/. /mnt/makevhd/
sync

After copying, run the unmount command printed by mount-image.sh. For .vhd images this also detaches the loop device. Then copy the finished image to the MiSTer:

scp mydisk.vhd root@<mister-ip>:/media/fat/games/

You can also create and populate the image directly on the MiSTer. Copy source files to the MiSTer using Samba, FTP, or scp, then mount the image and copy those files in:

makevhd /media/fat/games/mydisk.vhd 64
mount-image.sh /media/fat/games/mydisk.vhd /tmp/makevhd
cp -a /media/fat/incoming/. /tmp/makevhd/ #or copy over the network from another machine using Samba or FTP
sync

Run the unmount command printed by mount-image.sh when you are done.

Rules:

• filename must end in .img or .vhd
• maximum size is 2048 MB
• .vhd files must be at least 3 MB
• floppy images must use .img
• floppy presets are selected with --floppy <preset> or --floppy=<preset>

Supported floppy presets:

Preset	Common aliases
160k	160kb
180k	180kb
320k	320kb
360k	360kb, 5.25dd, 5.25-dd
720k	720kb, 3.5dd, 3.5-dd
1200k	1200kb, 1.2m, 1.2mb, 5.25hd, 5.25-hd
1440k	1440kb, 1.44m, 1.44mb, 3.5hd, 3.5-hd
2880k	2880kb, 2.88m, 2.88mb, 3.5ed, 3.5-ed

Output Behavior

.img

Creates a raw superfloppy image:

• no partition table
• FAT filesystem starts at sector 0
• useful for direct loop mounting on Linux

DOS floppy .img

Creates a raw FAT12 floppy image using one of the standard DOS floppy layouts.

• no partition table
• output filename must end in .img
• size and disk geometry come from the named floppy preset
• common size and media aliases are normalized to the canonical preset

.vhd

Creates a fixed VHD:

• one MBR partition starting at LBA 2048
• FAT filesystem is written inside that partition
• fixed VHD footer is appended to the end of the file
• can be mounted by Windows as a VHD

Scripts

build.sh

Builds binaries into dist/ for:

• Linux AMD64 as dist/makevhd-linux-amd64
• Linux ARM 32-bit as dist/makevhd-linux-armv7
• Linux ARM 64-bit as dist/makevhd-linux-arm64
• Windows AMD64 as dist/makevhd-windows-amd64.exe

Run:

./build.sh

The build copies both mount helper scripts into dist/:

• mount-image.sh
• mount-image.ps1

build.cmd

Builds the same artifact set on Windows:

• dist\makevhd-linux-amd64
• dist\makevhd-linux-armv7
• dist\makevhd-linux-arm64
• dist\makevhd-windows-amd64.exe

Run from cmd.exe:

build.cmd

mount-image.sh

Mounts images produced by this project on Linux.

Run:

sudo ./mount-image.sh ./disk.img /mnt/disk
sudo ./mount-image.sh ./disk.vhd /mnt/disk

Behavior:

• .img: mounted directly with mount -o loop
• .vhd: attached with losetup --partscan and mounts partition 1

The script prints the unmount command after a successful mount.

mount-image.ps1

Mounts .vhd images produced by this project on Windows using PowerShell and the built-in Storage module.

Run from an elevated PowerShell session:

.\mount-image.ps1 .\disk.vhd C:\mnt\disk

Behavior:

• .vhd: attached with Mount-DiskImage and exposed at the requested NTFS folder mount point
• .img: not supported natively on Windows and rejected by the script

The script prints the dismount command after a successful mount.

Testing

Run the test suite with:

go test ./...

Notes

• FAT type is selected automatically from the image size unless --fat is used.
• FAT formatting is implemented in Go; no external formatter is required.
• .img and .vhd are intentionally different formats.
• .vhd is a disk image with a partition table.
• .img is a filesystem image without a partition table.