1 files changed, 70 insertions, 0 deletions
diff --git a/bba/README.md b/bba/README.md
new file mode 100644
index 00000000..7e64b582
--- /dev/null
+++ b/bba/README.md
@@ -0,0 +1,70 @@
+Binary Blob Assembler (bba)
+===========================
+
+This tools read a text file describing binary data, and write that binary data
+file. The usual flow is that the input to bbasm is generated by a python
+script, and the output is linked or loaded into a C program, using (packed)
+structs to interpret the binary data.
+
+All references (pointers) are encoded als 32 bit byte offset relative to the
+location of the pointer. This way the resulting binary blob is position
+independent.
+
+Valid commands for the input are as follows.
+
+pre <string>
+------------
+
+When a C file is generated as output, all the "pre" strings will be included
+before the binary blob.
+
+post <string>
+-------------
+
+When a C file is generated as output, all the "post" strings will be included
+after the binary blob.
+
+push <name>
+-----------
+
+All following commands up until the matching "pop" will be writen to stream
+<name>. Everything written to the same stream will end up in a continous
+region of the output.
+
+pop
+---
+
+End of a push..pop block.
+
+label <name> [<comment>]
+------------------------
+
+Add a label for the current position.
+
+ref <name> [<comment>]
+----------------------
+
+Add a 32-bit reference to the specified label. The reference will be a byte
+offset relative to the memory location of the reference itself.
+
+u8 <value> [<comment>]
+----------------------
+
+Add a 8-bit value to the binary blob.
+
+u16 <value> [<comment>]
+-----------------------
+
+Add a 16-bit value to the binary blob. Note that the input must be structured
+in a way that ensures that all u16 are aligned to 2-byte addresses.
+
+u32 <value> [<comment>]
+----------------------
+
+Add a 32-bit value to the binary blob. Note that the input must be structured
+in a way that ensures that all u32 are aligned to 4-byte addresses.
+
+str <string>
+------------
+
+Add a reference to a zero-terminated copy of the specified string.