From: Jonas Hvid <mail@johv.dk>
Date: Fri, 20 Mar 2020 18:32:15 +0000 (+0100)
Subject: Add instructions for running on real hardware
X-Git-Url: https://git.rrq.au/?a=commitdiff_plain;h=5f99d5c9d6450fe6cbb0c6cd9b030de4fdc2380b;p=rrq%2Fjonasforth.git

Add instructions for running on real hardware
---

diff --git a/README.md b/README.md
index 0eb41c6..fa7ca9a 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,32 @@ interesting.)
 
 ## Running on real hardware
 
-* [ ] This is not supported yet
+Making the program run on physical hardware is pretty easy. Just create a
+FAT32-formatted USB drive, and copy `out/main` to it. Then, you can execute the
+program in the same way that you did from inside QEMU, assuming your system
+comes with a UEFI shell built-in.
+
+If your system doesn't have a UEFI shell, then you can copy the executable to
+`\EFI\BOOT\BOOTx64.EFI` on the USB drive. Then, the system should be able to
+boot from the USB drive and directly into JONASFORTH. The way to do this is a
+little bit different depending on the exact firmware, but most firmwares will
+have some way to enter a boot menu where you can select the USB drive. You may
+need to disable Secure Boot first.
+
+To format a USB drive as FAT32, you can run
+
+    # mkfs.vfat -F32 /dev/sdx
+
+with `/dev/sdx` replaced by the path of your USB drive. Then mount the drive,
+and copy `out/main` to `\EFI\BOOT\BOOTx64.EFI`:
+
+    $ mkdir mnt
+    # mount /dev/sdx mnt
+    $ mkdir -p mnt/EFI/BOOT
+    $ make out/main
+    $ cp out/main mnt/EFI/BOOT/BOOTx64.EFI
+
+Now you should be able to boot directly from the USB drive.
 
 # Notes on implementation