Add bba README

Signed-off-by: Clifford Wolf <clifford@clifford.at>

2 files changed, 90 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.
diff --git a/bba/main.cc b/bba/main.cc
index ee6129ac..cd09f804 100644
--- a/bba/main.cc
+++ b/bba/main.cc
@@ -1,3 +1,23 @@
+/*
+ *  nextpnr -- Next Generation Place and Route
+ *
+ *  Copyright (C) 2018  Clifford Wolf <clifford@symbioticeda.com>
+ *  Copyright (C) 2018  Miodrag Milanovic <miodrag@symbioticeda.com>
+ *
+ *  Permission to use, copy, modify, and/or distribute this software for any
+ *  purpose with or without fee is hereby granted, provided that the above
+ *  copyright notice and this permission notice appear in all copies.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ *  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ *  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ *  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ *  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ *  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ *  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ */
+
 #include <assert.h>
 #include <boost/program_options.hpp>
 #include <iostream>