diff --git a/.gitignore b/.gitignore
index aab2aad..a7389f5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
 emu6502
 *.o65
-*.bin
\ No newline at end of file
+*.bin
+*.map
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..770a473
--- /dev/null
+++ b/README.md
@@ -0,0 +1,95 @@
+# Commodore CBM 3001 Memtest
+
+## Memtest for the Commodore PET 2001 / CBM 3001 series
+
+This is a memtest routine written in MOS 6502 assembly.  Its purpose
+is to detect faulty RAM in Commodore PET 2001 / CBM 3001 computers.
+
+In order to test the entire memory range, this routine must be
+executed directly when the CPU resets, i.e. if loaded e.g. via a BASIC
+`SYS` command, it will overwrite memory used by the BASIC interpreter
+and KERNAL, leading to undefined behaviour.
+
+Instead, the test routine should be flashed to an ((E)E)PROM, which
+can then be inserted in the ROM socket mapped to `$F000:$FFFF` (the
+one which normally holds the KERNAL code).
+
+The test routine only uses the 7 first bytes of memory to store its
+state, the entire remaining memory range starting at `$0007` can be
+tested.  The memory is tested in multiple passes, using different
+patterns.
+
+**USE AT YOUR OWN RISK**
+
+## Getting Started
+
+* Install the [xa65][xa6e5] toolchain.
+* Clone this repository.
+* Run `make`.  This will produce (among other) the following files:
+  * `memtest-f000.901465.bin`: The binary you'll later flash to an ((E)E)PROM.
+  * `memtest-f000.901465+ascii.bin`: The same code, but text is rendered as ASCII instead of PETSCII.  Used by the emulator.
+  * `emu6502`: A MOS 6502 emulator for testing.
+
+## Testing in the Emulator
+
+The emulator uses [Fake6502][fake6502] to emulate the MOS 6502 CPU.
+The following memory regions are mapped into the emulator's address
+space, compatible with the PET 2001 / CBM 3001 memory map:
+
+* `$0000:$0fff`: RAM with simulated failures (reduced size for faster testing)
+* `$8000:$8fff`: Video buffer, printed to stdout after each instruction
+* `$f000:$ffff`: The `memtest-f000.901465+ascii.bin` ROM
+
+Run `./emu6502`.
+
+## Run on a Real PET / CBM
+
+* Flash the `memtest-f000.901465.bin` binary to a ((E)E)PROM compatible to the MOS 901465 ROM chip.
+  * Most parallel ROMs of at least 4KiB should be usable, just short the excess uppermost address pins to GND and ensure pin compatibility, e.g. through an adapter PCB.
+* Remove the KERNAL ROM from your PET / CBM.
+* Place the memtest ROM into the same socket.
+* Power up the computer.  It should immediately start testing the memory.
+
+## Output Interpretation
+
+After starting up, most of the screen will be empty.
+
+* In the top left you can see a `#` character.  This is the cursor.  If more defects are found than fit on the screen, the output will start over at the top, overwriting previous entries.  The cursor indicates the position after the last printed output.
+* Each faulty memory access looks like this: `DEAD>BEEF`.
+  * The part left of the `>` sign is the memory address at which the fault occured.
+  * The part right of the `>` sign is two bytes: First the byte that was written to this address, then the byte that was returned when reading from the same address.
+  * If the written byte reads `XX` instead of a hex byte, the byte that was actually written is the XOR of the high and low bytes of the address, i.e. `(DE xor AD)`.  If you only see `XX` faults, there may be a fault in the address lines, rather than individual memory cells or output lines.
+* In the bottom right you can see 3 quickly alternating characters.  The first two chars are the textual (PETSCII characters, not hexdumped) representation of the memory address currently being tested.  The third char is the character written to said memory address in the current pass.
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ 0FF0>FFF7 0FF1>FFF7 0FF2>FFF7 0FF3>FFF7┃
+┃ 0FF4>FFF7 0FF5>FFF7 0FF6>FFF7 0FF7>FFF7┃
+┃ 0FF8>FFF7 0FF9>FFF7 0FFA>FFF7 0FFB>FFF7┃
+┃ 0FFC>FFF7 0FFD>FFF7 0FFE>FFF7 0FFF>FFF7┃
+┃#                                       ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃                                        ┃
+┃ CBM 3001 memtest, 2022 s3lph.me    *** ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+```
+
+[xa65]: https://www.floodgap.com/retrotech/xa/
+[fake6502]: http://rubbermallet.org/fake6502.c