Documentation and structure

makefile

@@ -1,77 +1,101 @@
 # Inspired by https://www.codemadness.org/openbsd-riscv64-vm.html
 # mirror list: https://www.openbsd.org/ftp.html
-# mirror := https://mirror.hs-esslingen.de/pub/OpenBSD/
 mirror := https://ftp.lysator.liu.se/pub/OpenBSD/
+
+# Version of OpenBSD to install
 release := 7.5
 release_short := $(shell echo ${release} | sed 's/\.//g')# Without dots (7.5 -> 75)
 
-diskname := openBSD$(release_short).qcow2
+# Name of the disk image, named after the release
+vmname := openBSD$(release_short)
+diskname := $(vmname).qcow2
+
+# Timestamp used for backup
+UNIXTIME := $(shell date +%s)
+
+# These are the packages that will be fetched from the OpenBSD mirror
 opensbiname := opensbi-1.2.tgz
 ubootname := u-boot-riscv64-2021.10p8.tgz
 
+# PK used for release (not package, apparently) verification.
+# Note that this is explicitly fetched from the OpenBSD mirror.
 release_pubkey := openbsd-$(release_short)-base.pub
-release_pubkey_url := https://ftp.openbsd.org/pub/OpenBSD/7.5/$(release_pubkey)
+release_pubkey_url := https://ftp.openbsd.org/pub/OpenBSD/$(release)/$(release_pubkey)
+
+# Specify how we want curl to behave
 CURL := @curl --progress-bar -O
 
+# The miniroot image is the installer image
 minirootname := miniroot$(release_short).img
 
+# QEMU arguments
+QEMU_ARGS := -machine virt -nographic -m 2048M -smp 2 
+QEMU_ARGS += -bios share/opensbi/generic/fw_jump.bin 
+QEMU_ARGS += -kernel share/u-boot/qemu-riscv64_smode/u-boot.bin 
+QEMU_ARGS += -netdev user,id=net0,ipv6=off -device virtio-net-device,netdev=net0
+QEMU_ARGS += -drive file=$(diskname),format=qcow2,id=hd0 -device virtio-blk-device,drive=hd0
+
+# Fetch the public key used to verify the release
 $(release_pubkey):
 	$(CURL) ${release_pubkey_url}
 
+# Fetch the miniroot image and its checksums -> verify with signify
 $(minirootname): $(release_pubkey)
 	$(CURL) ${mirror}/${release}/riscv64/${minirootname}
 	$(CURL) ${mirror}/${release}/riscv64/SHA256
 	$(CURL) ${mirror}/${release}/riscv64/SHA256.sig
 	signify -C -p ${release_pubkey} -x SHA256.sig $(minirootname)
 
+# Allocate a qcow2 disk image, this is analogous to a hard drive
 $(diskname):
 	qemu-img create -f qcow2 ${diskname} 10G
 
+# Fetches the amd64 repository keys and checksums
 repokeys: $(release_pubkey)
 	$(CURL) ${mirror}/${release}/packages/amd64/SHA256
 	$(CURL) ${mirror}/${release}/packages/amd64/SHA256.sig
 
+# Verify the checksums of the packages in the current directory
 checksums: repokeys
 	cksum -a sha256 --ignore-missing -c SHA256
 
+# Fetch OpenSBI
 $(opensbiname): repokeys
 	$(CURL) ${mirror}/${release}/packages/amd64/${opensbiname}
 	@# signify -C -p ${release_pubkey} -x SHA256.sig $(opensbiname)
 	@tar -xzf ${opensbiname} share/opensbi/generic/fw_jump.bin
 
+# Fetch U-Boot
 $(ubootname): repokeys
 	$(CURL) ${mirror}/${release}/packages/amd64/${ubootname}
 	@# signify -C -p ${release_pubkey} -x SHA256.sig $(ubootname)
 	@tar -xzf ${ubootname} share/u-boot/qemu-riscv64_smode/u-boot.bin
 
+# Installer pulls all the pieces together and starts the VM with the installer attached as a drive (with correct boot order)
 installer: $(minirootname) $(diskname) $(opensbiname) $(ubootname)
 	make checksums
 	@echo "Starting VM with installer..."
-	@qemu-system-riscv64 \
+	@qemu-system-riscv64 -drive file=$(minirootname),format=raw,id=cd0 -device virtio-blk-device,drive=cd0 $(QEMU_ARGS)
-		-machine virt \
-		-nographic \
-		-m 2048M \
-		-smp 2 \
-		-bios share/opensbi/generic/fw_jump.bin \
-		-kernel share/u-boot/qemu-riscv64_smode/u-boot.bin \
-		-drive file=$(minirootname),format=raw,id=cd0 -device virtio-blk-device,drive=cd0 \
-		-drive file=$(diskname),format=qcow2,id=hd0 -device virtio-blk-device,drive=hd0 \
-		-netdev user,id=net0,ipv6=off -device virtio-net-device,netdev=net0
 
+# Run doesn't fetch anything, it just starts the VM with the disk (qcow2) image
 run:
 	@echo "Starting VM from disk image..."
-	@qemu-system-riscv64 \
+	@qemu-system-riscv64 $(QEMU_ARGS)
-		-machine virt \
-		-nographic \
-		-m 2048M \
-		-smp 2 \
-		-bios share/opensbi/generic/fw_jump.bin \
-		-kernel share/u-boot/qemu-riscv64_smode/u-boot.bin \
-		-drive file=$(diskname),format=qcow2,id=hd0 -device virtio-blk-device,drive=hd0 \
-		-netdev user,id=net0,ipv6=off -device virtio-net-device,netdev=net0
 
+# Creates a compressed archive of the disk image
+backup:
+	@echo "Backing up disk image..."
+	qemu-img convert -c -O qcow2 $(diskname) $(vmname)_$(UNIXTIME).qcow2
+	qemu-img info $(vmname)_$(UNIXTIME).qcow2
+	tar -czvf $(vmname)_$(UNIXTIME).tar.gz $(vmname)_$(UNIXTIME).qcow2
+
+# Clean up the directory
 clean:
 	rm -f ${minirootname} ${diskname} ${opensbiname} ${ubootname} ${release_pubkey} SHA256 SHA256.sig
 	rm -rf share
 
-.PHONY: installer run clean
+# Clean, but also remove backups and disk images
+superclean: clean
+	rm -f $(vmname)_*.qcow2 $(vmname)_*.tar.gz
+
+.PHONY: installer run clean backup