readme

[bootcard] / README.md

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..14cd5f6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,53 @@
+Bootable wedding card
+=====================
+
+About
+-----
+This is a bootable wedding card for our friends Michael (Samurai) and Athena.
+It was meant to be included alongside the regular wedding card as a QR code with
+the source code. The code starts with a comment with instructions for how to
+assemble it and write it to a USB stick, which would run the program when booted
+on a PC. Sortof like an easter egg to go along the regular wedding card. It also
+works from a floppy disk, for use in retro PCs.
+
+Hardware requirements:
+
+  - PC with "legacy boot" (BIOS) support.
+  - 386 or higher CPU with an FPU (386+x87, 486 DX, or anything newer).
+  - PC-speaker for sound (otherwise it runs silent).
+
+The main constraint for this project was that the source code should fit in
+a QR code, which means it should be no more than about 3kb. This in turn makes
+it impossible to have a complicated 2-stage boot loader which loads a protected
+mode C program; it had to be a tiny real mode assembly program which
+fits entirely inside the boot sector. Furthermore, the requirement to run on
+modern PCs, bootable from a USB stick, necessitates the presence of a dummy
+partition table in the boot sector, otherwise some BIOSes will refuse to load
+it. This leaves 446 bytes available for the whole program.
+
+Due to all the above, the wedding card program is very simple. It draws a nice
+backdrop, prints the names of the couple, and plays a few notes of Richard
+Wagner's Lohengrin bridal chorus on the PC speaker, with some visual feedback
+for the notes being played.
+
+Authors: John Tsiombikas <nuclear@mutantstargoat.com> and
+ Eleni Maria Stea <elene.mst@gmail.com>
+
+This program is in the public domain. Do whatever you like with it.
+
+Instructions
+------------
+
+  1. To build the bootable disk image, assuming you have `nasm` installed, just
+     type `make`. Or build it manually with: `nasm -f bin -o bootcard.img
+     bootcard.asm`.
+
+  2. Write the image to a USB stick or floppy disk:
+     `cat bootcard.img >/dev/whatever`
+
+  3. Insert the USB stick and reboot. If necessary use your BIOS boot menu
+     (usually pops up with F12 or ESC during POST) to select booting from the
+     USB stick, if it doesn't happen automatically. On modern PCs you need
+     "legacy boot" enabled.
+
+  4. Enjoy!