adding BNIL overview

3 files changed, 59 insertions, 6 deletions

diff --git a/docs/dev/bnil-llil.md b/docs/dev/bnil-llil.md
index 60beb3db..608c5e82 100644
--- a/docs/dev/bnil-llil.md
+++ b/docs/dev/bnil-llil.md
@@ -1,6 +1,8 @@
 # Binary Ninja Intermediate Language Series, Part 1: Low Level IL
 
-The Binary Ninja Intermediate Language (BNIL) is a semantic representation of the assembly language instructions for a native architecture in Binary Ninja.  BNIL is actually a family of intermediate languages that work together to provide functionality at different abstraction layers. This developer guide is intended to cover some of the mechanics of the LLIL to distinguish it from the other ILs in the BNIL family. 
+Make sure to checkout the [BNIL overview](bnil-overview.md) first if you haven't already. Or feel free to skip to [part 2](bnil-mlil.md) which covers MLIL. This developer guide is intended to cover some of the mechanics of the LLIL to distinguish it from the other ILs in the BNIL family. 
+
+If you've already read the introduction, let's get right into the details of LLIL!
 
 ![BNIL-LLIL Selected](../img/BNIL-llil.png)
 
@@ -131,7 +133,7 @@ For the above instruction, we have a few operations we can perform:
 'rsp'
 ```
 
-* **size** - returns the size of the operation in bytes (in this case we have an 8 byte assigment)
+* **size** - returns the size of the operation in bytes (in this case we have an 8 byte assignment)
 
 ```
 >>> instr.size
@@ -182,7 +184,7 @@ Reading and writing memory is accomplished through the following instructions.
 
 ### Control Flow & Conditionals
 
-Control flow transfering- and comparison instructions are straightforward enough, but one instruction that deserves more attention is the `if` instruction. To understand the `if` instruction we need to first understand the concept of labels.
+Control flow transferring- and comparison instructions are straightforward enough, but one instruction that deserves more attention is the `if` instruction. To understand the `if` instruction we need to first understand the concept of labels.
 
 Labels function much like they do in C code. They can be put anywhere in the emitted IL and serve as a destination for the `if` and `goto` instructions.  Labels are required because one assembly language instruction can translate to multiple IL instructions, and you need to be able to branch to any of the emitted IL instructions. Let's consider the following x86 instruction `cmove` (Conditional move if equal flag is set):
 
@@ -199,7 +201,7 @@ To translate this instruction to IL we have to first create true and false label
 2 @ 00000002 goto 3
 ``` 
 
-As you can see from the above code, labels are really just used internaly and aren't explicitly marked. In addition to `if` and `goto`, the `jump_to` IL instruction is the only other instruction that operates on labels.  The rest of the IL control flow instructions operate on addresses rather than labels, much like actual assembly language instructions. Note that an architecture plugin author should not be emitting `jump_to` IL instructions as those are generated by the analysis automatically. 
+As you can see from the above code, labels are really just used internally and aren't explicitly marked. In addition to `if` and `goto`, the `jump_to` IL instruction is the only other instruction that operates on labels.  The rest of the IL control flow instructions operate on addresses rather than labels, much like actual assembly language instructions. Note that an architecture plugin author should not be emitting `jump_to` IL instructions as those are generated by the analysis automatically. 
 
 * **`LLIL_JUMP`** - Branch execution to the result of the IL operation.
 * **`LLIL_JUMP_TO`** - Jump table construct, contains an expression and list of possible targets.
diff --git a/docs/dev/bnil-mlil.md b/docs/dev/bnil-mlil.md
index 305c836d..545d72df 100644
--- a/docs/dev/bnil-mlil.md
+++ b/docs/dev/bnil-mlil.md
@@ -282,9 +282,9 @@ The parameter list can be accessed through the ``params`` property:
 * ``MLIL_RET`` - Return to the calling function.
 * ``MLIL_RET_HINT`` - Indirect jump to ``dest`` expression (only used in internal analysis passes.)
 * ``MLIL_NORET`` - This instruction will never be executed, the instruction before it is a call that doesn't return
-* ``MLIL_IF`` - Branch to the ``true``/``false`` mlil instruction identifier depending on the result of the ``condition`` expression
+* ``MLIL_IF`` - Branch to the ``true``/``false`` MLIL instruction identifier depending on the result of the ``condition`` expression
 * ``MLIL_GOTO`` - Branch to the ``dest`` expression id
-* ``MLIL_TAILCALL`` - This instruction calls an the expression ``dest`` using ``params`` as input and ``output`` for return values
+* ``MLIL_TAILCALL`` - This instruction calls the expression ``dest`` using ``params`` as input and ``output`` for return values
 * ``MLIL_SYSCALL`` - Make a system/service call with parameters ``params`` and output ``output``
 * ``MLIL_SYSCALL_UNTYPED`` - Makes a system/service call, but an exact set of parameters couldn't be determined.
 
diff --git a/docs/dev/bnil-overview.md b/docs/dev/bnil-overview.md
new file mode 100644
index 00000000..acf3c241
--- /dev/null
+++ b/docs/dev/bnil-overview.md
@@ -0,0 +1,51 @@
+# Binary Ninja Intermediate Language Series, Part 0: Overview
+
+The Binary Ninja Intermediate Language (BNIL) is a semantic representation of the assembly language instructions for a native architecture in Binary Ninja.  BNIL is actually a family of intermediate languages that work together to provide functionality at different abstraction layers. 
+
+BNIL is a [tree-based](https://raw.githubusercontent.com/withzombies/bnil-graph/master/images/graph.png), architecture-independent intermediate representation of machine code used throughout Binary Ninja.
+
+![BNIL-Overview](../img/BNIL-overview.png)
+
+During each step a number of optimizations and analysis passes occur, resulting in a higher and higher level of abstraction the further through the analysis binaries are processed.
+
+Except that overview isn't telling the whole story! The real stack of BNIL _actually_ looks like this:
+
+![BNIL-Stack](../img/BNIL.png)
+
+This short introduction is a very brief guide to BNIL with much more details in [Part 1: LLIL](bnil-llil.md) and [Part 2: MLIL](bnil-mlil.md).
+
+## Reading IL
+
+All of the various ILs (with the exception of the SSA forms) are intended to be easily human-readable and look much like pseudo-code. There is some shorthand notation that is used throughout the ILs, though, explained below:
+
+### Comparisons
+
+First, all comparisons are either signed `s<=` or unsigned `u>=`.
+
+
+### Bitwise operations
+
+Besides the typical `&&` bitwise operators, BNIL makes use of `sx` and `zx` to indicate `sign-extended` and `zero-extended` operations.
+
+### Size Specifiers
+
+Expressions in BNIL can have one of the following suffixes to indicate a size:
+
+```
+.q -- Qword (64 bits)
+.d -- Dword (32 bits)
+.w -- Word (16 bits)
+.b -- Byte (8 bits)
+```
+
+### Variable Offsets
+
+Offsets into variables are specified with a `:$offset` syntax indicating how many bits from the bottom of the variable the expression is referencing.
+
+### Example
+
+So putting all that together, if you were to see the following in an IL expression:
+
+```sx.q(rax_2:0.d)```
+
+It represents the lower 32-bits of variable `rax_2`, sign-extended into a 64-bit variable.