From fe6ca72429bba8ac7a51eecabcfe6922e8420dfc Mon Sep 17 00:00:00 2001
From: Nahum Shalman <nshalman@equinix.com>
Date: Mon, 11 Sep 2023 16:28:05 +0000
Subject: [PATCH] Build EFI bootable floppy ipxe.img

Provide notes on how and why someone might weant to do this.

Signed-off-by: Nahum Shalman <nshalman@equinix.com>
---
 Makefile                      | 13 ++++++++++--
 binary/script/build_and_pr.sh |  2 ++
 docs/DifficultHardware.md     | 39 +++++++++++++++++++++++++++++++++++
 3 files changed, 52 insertions(+), 2 deletions(-)
 create mode 100644 docs/DifficultHardware.md

diff --git a/Makefile b/Makefile
index 31bfda1..5443dc4 100644
--- a/Makefile
+++ b/Makefile
@@ -4,6 +4,7 @@ IPXE_BUILD_SCRIPT := binary/script/build_ipxe.sh
 IPXE_FETCH_SCRIPT := binary/script/fetch_and_extract_ipxe.sh
 IPXE_NIX_SHELL := binary/script/shell.nix
 IPXE_ISO_BUILD_PATCH := binary/script/iso.patch
+BINARIES := binary/ipxe.efi binary/snp.efi binary/undionly.kpxe binary/ipxe.iso binary/ipxe-efi.img
 
 help: ## show this help message
 	@grep -E '^[a-zA-Z_-]+.*:.*?## .*$$' Makefile | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}'
@@ -11,7 +12,7 @@ help: ## show this help message
 include lint.mk
 
 .PHONY: binary
-binary: binary/ipxe.efi binary/snp.efi binary/undionly.kpxe binary/ipxe.iso ## build all upstream ipxe binaries
+binary: $(BINARIES) ## build all upstream ipxe binaries
 
 # ipxe_sha_or_tag := v1.21.1 # could not get this tag to build ipxe.efi
 # https://github.com/ipxe/ipxe/tree/2265a65191d76ce367913a61c97752ab88ab1a59
@@ -39,9 +40,17 @@ binary/snp.efi: $(ipxe_readme) ## build snp.efi
 binary/ipxe.iso: $(ipxe_readme) ## build ipxe.iso
 	+${IPXE_BUILD_SCRIPT} bin-x86_64-efi/ipxe.iso "$(ipxe_sha_or_tag)" $(ipxe_build_in_docker) $@  "${IPXE_NIX_SHELL}"
 
+binary/ipxe-efi.img: binary/ipxe.efi
+	qemu-img create -f raw $@.t 1440K
+	mkfs.vfat --mbr=y -F 12 -n IPXE $@.t
+	mmd -i $@.t ::/EFI
+	mmd -i $@.t ::/EFI/BOOT
+	mcopy -i $@.t $< ::/EFI/BOOT/BOOTX64.efi
+	mv $@.t $@
+
 .PHONY: binary/clean
 binary/clean: ## clean ipxe binaries, upstream ipxe source code directory, and ipxe source tarball
-	rm -rf binary/ipxe.efi binary/snp.efi binary/undionly.kpxe binary/ipxe.iso
+	rm -rf $(BINARIES)
 	rm -rf upstream-*
 	rm -rf ipxe-*
 
diff --git a/binary/script/build_and_pr.sh b/binary/script/build_and_pr.sh
index 4fbcd74..21fbdee 100755
--- a/binary/script/build_and_pr.sh
+++ b/binary/script/build_and_pr.sh
@@ -19,6 +19,7 @@ tracked_files=(
     "./snp.efi"
     "./undionly.kpxe"
     "./ipxe.iso"
+    "./ipxe-efi.img"
 )
 
 # binaries defines the files that will be built if any tracked_files changes are detected.
@@ -28,6 +29,7 @@ binaries=(
     "ipxe.efi"
     "undionly.kpxe"
     "ipxe.iso"
+    "ipxe-efi.img"
 )
 
 git_email="github-actions[bot]@users.noreply.github.com"
diff --git a/docs/DifficultHardware.md b/docs/DifficultHardware.md
new file mode 100644
index 0000000..cef2fd4
--- /dev/null
+++ b/docs/DifficultHardware.md
@@ -0,0 +1,39 @@
+# Difficult Hardware
+
+Most modern hardware is capable of PXE booting just fine.
+Sometimes strange combinations of different NIC hardware / firmware connected
+to specific switches can misbehave.
+
+In those situations you might want to boot into a build of iPXE but completely
+sidestep the PXE stack in your NIC firmware.
+
+We already ship ipxe.iso that can be used in many situations, but most of the
+time that requires either an active connection from a virtual KVM client
+or network access from the BMC to a storage target hosting the ISO.
+
+Some BMCs support uploading a floppy image into BMC memory and booting from that.
+To support that use case we have started packaging our EFI build into a bootable
+floppy image that can be used for this purpose.
+
+For other projects or use cases that wish to replicate this functionality, with
+the appropriate versions of qemu-img, dosfstools and mtools you can build something
+similar yourself from upstream iPXE like so:
+
+```
+# create a 1440K raw disk image
+qemu-img create -f raw ipxe-efi.img 1440K
+# format it with an MBR and a FAT12 filesystem
+mkfs.vfat --mbr=y -F 12 -n IPXE ipxe-efi.img
+
+# Create the EFI expected directory structure
+mmd -i ipxe-efi.img ::/EFI
+mmd -i ipxe-efi.img ::/EFI/BOOT
+
+# Copy ipxe.efi as the default x86_64 efi boot file
+curl -LO https://boot.ipxe.org/ipxe.efi
+mcopy -i ipxe-efi.img ipxe.efi ::/EFI/BOOT/BOOTX64.efi
+```
+
+As of writing other projects are working on automating the upload
+of this floppy to a BMC.
+See draft PR https://github.com/bmc-toolbox/bmclib/pull/347