From 6597e8a75a15f868b40e432844986f62c3971128 Mon Sep 17 00:00:00 2001
From: Virgil Dupras <hsoft@hardcoded.net>
Date: Tue, 16 Apr 2019 11:35:15 -0400
Subject: [PATCH] doc: add emulate section

---
 doc/README.md  |  1 +
 doc/emulate.md | 30 ++++++++++++++++++++++++++++++
 2 files changed, 31 insertions(+)
 create mode 100644 doc/emulate.md

diff --git a/doc/README.md b/doc/README.md
index bbeaf19..6a7a51e 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -3,6 +3,7 @@
 ## Assembly guide
 
 * [Writing the glue code](glue-code.md)
+* [Running Collapse OS on an emulated RC2014](emulate.md)
 
 ## User guide
 
diff --git a/doc/emulate.md b/doc/emulate.md
new file mode 100644
index 0000000..eee6d2e
--- /dev/null
+++ b/doc/emulate.md
@@ -0,0 +1,30 @@
+# Running Collapse OS on an emulated RC2014
+
+To give Collapse OS a whirl or to use emulation as a development tool, I
+recommend using Alan Cox's [RC2014 emulator][rc2014-emul]. It runs Collapse OS
+fine. One caveat, however, is that it requires a ROM image bigger than 8K, so
+you have to pad the binary.
+
+A working Makefile for a project with a glue code being called `main.asm` could
+look like:
+
+    TARGET = os.bin
+    PARTS = ~/collapseos/parts
+    ROM = os.rom
+
+    .PHONY: all
+    all: $(ROM)
+    $(TARGET): main.asm
+            scas -o $@ -L map -I $(PARTS) $<
+
+    $(ROM): $(TARGET)
+            cp $< $@
+            dd if=/dev/null of=$@ bs=1 count=1 seek=8192
+
+    .PHONY: run
+    run: $(ROM)
+            ~/RC2014/rc2014 -r $(ROM)
+
+`CTRL+\` stops the emulation.
+
+[rc2014-emul]: https://github.com/EtchedPixels/RC2014