From 1e71621f6517faca01f1351ec60dd51288e14ec8 Mon Sep 17 00:00:00 2001
From: Clifford Wolf <clifford@clifford.at>
Date: Wed, 25 Jul 2018 13:06:21 +0200
Subject: Add bba README

Signed-off-by: Clifford Wolf <clifford@clifford.at>
---
 bba/README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 bba/main.cc   | 20 +++++++++++++++++
 2 files changed, 90 insertions(+)
 create mode 100644 bba/README.md

(limited to 'bba')

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>
-- 
cgit v1.2.3