readme

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!

diff --git a/bootcard.asm b/bootcard.asm
index 26f3cd9..dddf846 100644 (file)
--- a/bootcard.asm
+++ b/bootcard.asm
@@ -1,7 +1,6 @@
 ; ---- boot me! ----
 ; nasm -f bin -o bootcard.img bootcard.asm
 ; cat bootcard.img >/dev/<usbstick>
-; reboot
 
        org 7c00h
        bits 16
@@ -95,7 +94,7 @@ drawbg:
 .fillgrad:
        mov ax, bx
        mov ah, al
-       mov cx, 2400    ; 15 lines
+       mov cx, 2400 ; 15 lines
        rep stosw
        inc bx
        cmp bx, 208
@@ -224,5 +223,4 @@ w30:        dw 30
 
        times 510-($-$$) db 0
        dw 0aa55h
-
 ; vi:ft=nasm ts=8 sts=8 sw=8: