diff --git a/README.md b/README.md
new file mode 100644
index 0000000..998b8cc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,91 @@
+libgfxinit
+==========
+
+*libgfxinit* is a graphics initialization (aka modesetting) library
+for embedded environments. It currently supports only Intel hardware,
+more specifically the Intel Core processor line.
+
+It can query and set up most kinds of displays based on their EDID
+information. You can, however, also specify particular mode lines.
+
+*libgfxinit* is written in SPARK, an Ada subset with formal verifica-
+tion aspects. Absence of runtime errors can be proved automatically
+with SPARK GPL 2016.
+
+
+Building on Linux
+=================
+
+Prerequisites
+-------------
+
+For compilation, the GNAT Ada compiler is required. Usual package
+names in Linux distributions are `gcc-ada` and `gnat`.
+
+Grab the Sources
+----------------
+
+You'll need *libhwbase* and *libgfxinit*. Best is to clone the reposi-
+tories into a common parent directory (this way *libgfxinit* will know
+where to find *libhwbase*).
+
+    $ mkdir gfxfun && cd gfxfun
+    $ git clone https://review.coreboot.org/p/libhwbase.git
+    $ git clone https://review.coreboot.org/p/libgfxinit.git
+
+Configure and Install libhwbase
+-------------------------------
+
+Both libraries are currently configured by hand-written config files.
+You can either write your own `.config`, link one of the shipped files
+in `configs/`, e.g.:
+
+    $ ln -s configs/posix libhwbase/.config
+
+or overwrite the config filename by specifying `cnf=<configfile>` on
+the make command line.
+
+Let's install *libhwbase*. We'll need `configs/posix` to build regular
+Linux executables:
+
+    $ cd libhwbase
+    $ make cnf=configs/posix install
+
+By default this installs into a new subdirectory `dest`. You can however
+overwrite this decision by specifying `DESTDIR=`.
+
+Build libgfxinit/`gfx_test`
+---------------------------
+
+*libgfxinit* is configured and installed in the same manner as de-
+scribed above. You will have to select a configuration matching your
+hardware.
+
+The makefile knows an additional target `gfx_test` to build a small
+Linux test application:
+
+    $ cd ../libgfxinit
+    $ make cnf=configs/sandybridge gfx_test
+
+The resulting binary is `build/gfx_test`.
+
+
+Testing libgfxinit on Linux
+===========================
+
+In its current state `gfx_test` doesn't know how to set up a frame-
+buffer. It just assumes that enough memory is mapped. This is known
+to work well, after running the VBIOS but before the Linux driver
+*i915* took over (e.g. when booting with `nomodeset` in the kernel
+command line or with *i915* blacklisted). After running *i915* it
+only works by chance.
+
+When running `gfx_test` (as root), it will ask for a single argument:
+The path to a sysfs PCI-device node, where it will find the graphics
+hardware. Usually this is PCI device 00:02.0:
+
+    $ sudo build/gfx_test /sys/devices/pci0000:00/0000:00:02.0/
+
+If you chose the right config above, you should be presented with a
+nice test image. However, `gfx_test` is one-way only: The graphics
+hardware will stay in this state, until another driver takes over.