Add README

1 files changed, 39 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..22f99ce
--- /dev/null
+++ b/README.md
@@ -0,0 +1,39 @@
+# UXNPI
+
+This is a port of the [UXN virtual machine][uxn] for running on the Raspberry Pi
+3/4 without OS (baremetal).
+
+[uxn]: https://wiki.xxiivv.com/site/uxn.html
+
+## Building from source
+
+To build this software you need a compiler for the aarch64 architecture. More
+specifically you will need the following programs in your path:
+
+```
+aarch64-elf-as
+aarch64-elf-gcc
+aarch64-elf-ld
+aarch64-elf-objcopy
+```
+
+You can follow the instruction for installing these with your package manager of
+choice or [build them from source](https://github.com/bztsrc/raspi3-tutorial/tree/master/00_crosscompiler).
+
+Additionally you may want to test the compiled software with an emulator, since
+testing on real hardware can be a bit of a hassle. Luckily, you can use qemu for
+this. You will need to install `qemu-system-aarch64` for this to work.
+
+With all of this ready, you should be able to run `make` for compiling the
+kernel image and/or `make run` to run the kernel on a qemu VM.
+
+To see framebuffer output from qemu, you will need a VNC client. When developing
+this project I keep `gvncviewer` running at regular intervals so that when qemu
+is executed it automatically connects to the screen viewer:
+
+```
+while true; do gvncviewer ::1:5900; sleep 1; done
+```
+
+Note that qvncviewer by default smooths the output so if things look weird just
+make sure you disable smooths scaling and keep the original aspect ratio.