doc: document project

README

@@ -1,2 +1,42 @@
-firmware template for ST STM8S micro-controller.
-includes register definitions using macros and structures.
+This is the firmware for the [HDMI firewall programmer](https://git.cuvoodoo.info/kingkevin/board/src/branch/hdmi_firewall_programmer).
+The HDMI firewall programmer copies EDID information onto the [HDMI firewall](https://git.cuvoodoo.info/kingkevin/board/src/branch/hdmi_firewall).
+
+usage
+=====
+
+see [hardware description](https://git.cuvoodoo.info/kingkevin/board/src/branch/hdmi_firewall_programmer/README.md).
+
+mode of operation
+=================
+
+the EDID can be accessed using the I²C lines on the HDMI port.
+the firmware reads and writes the data from slave device address 0x50.
+
+connections
+===========
+
+the programmer can be flashed using the micro-USB port (not USB signals):
+
+- the SWIM signal is on USB pin 2 D-
+- the NRST signal is on USB pin 4 ID
+
+there is also debugging output using UART (115200 8N1) on STM8S pin 2 PD5/UART_TX.
+
+code
+====
+
+the source code is for a STM8S103F3 micro-controller.
+
+compile
+=======
+
+requirement: SDCC, make
+
+to compile the source code into a firmware, run `make`.
+
+flash
+=====
+
+requirement: stm8flash, a ST-LINK/V2 programmer
+
+to flash the firmware on the micro-controller, run `make flash`.