![BLADE](https://raw.githubusercontent.com/bluwireless/blade/master/documentation/source/_static/images/BLADE.png)

---

BLADE is a tool for generating hierarchical hardware designs from a YAML based input syntax. It allows front-end designers to work like IP integrators from day one, with the ability to describe blocks, interconnections, register and address maps and more with strict type checking and high-level design rule checks.

When BLADE executes, it produces a DesignFormat blob describing the hardware - this interchange format, which is based on JSON, can drive templating engines, GUIs, CLIs and more. The whole process is agnostic of the design implementation language used, so templates can be easily crafted to work with development flows in SystemC, Verilog, VHDL, and more.

# Simple Example
The example below demonstrates how a module can be declared with ports and children, and how an explicit connection can be described between two child nodes. Further details on using BLADE can be found in the documentation and example designs.

```yaml
#include "axi4_lite.yaml"
#include "wire.yaml"

#include "watchdog_ctrl.yaml"
#include "watchdog_tmr.yaml"

- !Mod
  name       : watchdog
  ld         : A four channel watchdog timer
  ports      :
  - !HisRef [cfg, axi4_lite, "Configuration port", 1, slave ]
  - !HisRef [irq, wire,      "Interrupt outputs",  4, master]
  modules    :
  - !ModInst [ctrl,  watchdog_ctrl, "Control block for the timers", 1]
  - !ModInst [timer, watchdog_tmr,  "Timer modules",                4]
  connections:
  - !Connect
    points:
    - !Point [timer_enable, ctrl ]
    - !Point [enable,       timer]
  ...
```

# Getting Started with BLADE

## System Requirements
BLADE is a Python based tool, and has a few system dependencies:
 * Python 3.6 or greater
 * [PyYAML](https://pypi.org/project/PyYAML/) - Used to power the YAML parser
 * [Mako](https://pypi.org/project/Mako/) - Templating engine used for generating reports, also used by the BLADE Templating Engine
 * [TQDM](https://pypi.org/project/tqdm/) - CLI compatible progress bars
 * [DesignFormat](https://github.com/bluwireless/designformat) - The interchange format used by BLADE

```bash
$> pip install pyyaml mako tqdm
$> pip install git+https://github.com/bluwireless/designformat#subdirectory=python
```

As BLADE designs can get quite big, we recommend using PyYAML's CLoader which uses LibYAML to accelerate the parsing process - it can result in some quite substantial speed ups when generating large designs. [More details can be found here](https://pyyaml.org/wiki/PyYAMLDocumentation).

The following dependencies are not mandatory, but are required for building the documentation:
 * [Sphinx](https://pypi.org/project/Sphinx/) - Powerful documentation generation tool
 * [Recommonmark](https://pypi.org/project/recommonmark/) - Markdown convertor for Sphinx
 * [Sphinx Markdown Tables](https://pypi.org/project/sphinx-markdown-tables/) - Markdown table convertor for Sphinx
 * [Sphinx RTD Theme](https://pypi.org/project/sphinx-rtd-theme/) - Read The Docs theme for Sphinx HTML

```bash
$> pip install sphinx recommonmark sphinx-markdown-tables sphinx-rtd-theme
```

## Building Your First Design
The best way to test your installation is to clone a copy of the [BLADE Examples](https://github.com/bluwireless/blade-examples) which demonstrate how to use the tool in a flow that generates RTL. Perhaps start with the [basic timer](https://github.com/bluwireless/blade-examples/tree/master/designs/basic_timer) tutorial and see how the hierarchy, registers, and wiring have been put together.

## Next Steps
Take a look at the [BLADE](https://github.com/bluwireless/blade/releases) and [DesignFormat](https://github.com/bluwireless/designformat/releases) documentation which is included with every release. It covers the architecture of the tool, the input syntax, and the API for interacting with the DesignFormat blob generated by BLADE.

In the coming months we hope to put together some tutorials on how to build a design from scratch, taking you step-by-step from writing BLADE YAML to simulating the design. Watch this space!

# Future Development
BLADE has been an internal Blu Wireless tool for close to ten years (in one form or another). It represents a substantial investment of effort from many members of the company, and it is a tool we are proud of. We use BLADE on a daily basis and continue to invest significant time and resources in developing new features to aid our design flow.

This release to GitHub takes BLADE in a new and exciting direction, hopefully providing the opensource community with a valuable tool. We're very much looking forward to engaging with other developers to make this a springboard platform for hardware development.

It is worth noting that the code currently released is not the wavefront of development - in fact the code in this initial release has been taken from the tape-out branch of our last SoC, about 6 months ago. Since the tape-out we've been trialing new features for BLADE, and we plan to introduce these into the GitHub repository over time.

**However** this is not to say that we won't be continuing development on the opensourced code base. We have a shopping list of tasks (see below) that will be addresses over the coming months. We also welcome bug reports, questions, feature requests, and pull requests from the community.

## To-Do List
The following tasks will be addressed over the next few months:

 * Unit testing suite - tests for the preprocessor and parser are already written and will be integrated into this project, tests for the elaborator and checker will need to be developed.
 * Tutorials and examples - while [some designs and guides](http://github.com/bluwireless/blade-examples) are already available, we plan to create more to demonstrate some of the other features of BLADE.
