1 files changed, 52 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ceba168
--- /dev/null
+++ b/README.md
@@ -0,0 +1,52 @@
+# Readme
+
+This is a test to get a PIC32MZ2048ECG064 running without the MPLAB IDE. There
+is an Assembly file and a Makefile. The generated HEX can be uploaded using the
+MPLAB IPE. Generating C code is fairly similar, but uses `gcc` instead of `as`.
+
+### Links
+
+About the chip: https://www.microchip.com/wwwproducts/en/PIC32MZ2048ECG064  
+About the architecture: https://www.cs.cornell.edu/courses/cs3410/2008fa/MIPS_Vol1.pdf  
+About the instruction set: https://www.cs.cornell.edu/courses/cs3410/2008fa/MIPS_Vol2.pdf
+
+## Notes to self
+
+### Instruction set
+
+This chip has a somewhat larger instruction set than MIPS32; it is a MIPS32
+microAptiv. For this extension, see §50 of the PIC32 reference manual (to be
+found on the chip information page linked above). It is not clear to me how
+widespread this instructions set is (i.e. whether it would make sense to rely
+on it being available for code generation or so).
+
+### Branch delay slots
+
+Watch out for the branch/jump instructions. The following instruction is always
+executed, regardless of whether the branch is taken or not. This instruction is
+said to be in the 'branch delay slot'. For example, this does not loop
+endlessly even though the body of `main_loop_delay` seems empty:
+
+```
+	lui	$2,0xf
+	ori	$5,0xffff
+main_loop_delay:
+	bne	$2,$0,main_loop_delay
+	addiu	$2,-1
+```
+
+Also note that when the file ends with a branch/jump, a `nop` *must* follow to
+avoid unpredictable behaviour (the following instruction could be anything
+otherwise).
+
+### `lw` and `lui`
+
+One needs `lui` to load an address, e.g. to clear `TRISB`:
+
+```
+	lui	$2,%hi(TRISB)
+	sw	$0,%lo(TRISB)($2)
+``` 
+
+Using `lw` instead of `lui` is an easy mistake, assembles fine, but you usually
+end up reading out of memory leading to a reset.