README.adoc

:source-highlighter:

++++
++++

image::blarney-logo.svg#gh-light-mode-only[Blarney logo, width=275] image::blarney-logo-dark.svg#gh-dark-mode-only[Blarney logo, width=275]

++++
++++

Blarney is a Haskell library for hardware description that builds a range of HDL abstractions on top of a small set of pure functional circuit primitives. It is a modern variant of http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.110.5587&rep=rep1&type=pdf[Lava] using many of the latest features of GHC. Some aspects of the library are also inspired by https://github.com/B-Lang-org/bsc[Bluespec], such as first-class actions and method-based interfaces.

== Prerequisites

We'll need Verilator and GHC 9.2.1 or later.

On Ubuntu 20.04, we can do:

[source, shell]

$ sudo apt install verilator libgmp-dev

For GHC 9.2.1 or later, https://www.haskell.org/ghcup/[ghcup] can be used.

== Quick start

To clone the repo:

[source, shell]

$ git clone --recursive https://github.com/blarney-lang/blarney

To simulate the https://github.com/blarney-lang/blarney/tree/master/Examples/Sorter/Sorter.hs[Sorter] example from Blarney's https://github.com/blarney-lang/blarney/tree/master/Examples[Examples] directory:

[source, shell]

$cd blarney/Examples/Sorter$ make # Build the example using GHC ./Sorter # Generate Verilog for the example cd Sorter-Verilog # Go to the generated Verilog make # Compile the generated Verilog using Verilator ./Sorter # Simulate the generated Verilog

You should see the output:

---

sort [3,4,1,0,2] = [0,1,2,3,4]

To run the regression test suite:

[source, shell]

$cd blarney/Test$ ./test.sh --run-all

To start development of your own Blarney application or library, take a look at the https://github.com/blarney-lang/template-project/[Blarney template project].

== Documentation

See https://www.repository.cam.ac.uk/handle/1810/385421[Abstracting the Classic Five-Stage Pipeline], a tutorial paper that introduces Blarney and applies it to the development of a simple processor pipeline. Also see https://github.com/blarney-lang/blarney/blob/master/Doc/ByExample.adoc[Blarney by Example], a more general introduction to Blarney, which supplements the http://blarney-lang.github.io/blarney/index.html[Haddock docs].

== Applications

Our current list of applications developed using Blarney:

• https://github.com/blarney-lang/actora/[Actora]: A 3-stage stack processor that runs code written a subset of Erlang. It has higher performance density than Intel's register-based NIOS-II core for compiled Erlang code.

• https://github.com/CTSRD-CHERI/SIMTight/[SIMTight]: A https://cheri-cpu.org[CHERI]-enabled RISC-V GPGPU with dynamic scalarisation features and high performance density on Intel's Stratix 10 FPGA.

• https://github.com/blarney-lang/five/[Five]: A formally verified implementation of the classic 5-stage RISC pipeline as an abstract component, largely independent of any specific instruction set.

• https://github.com/blarney-lang/five-alive/[FiveAlive]: A proof-of-concept instantiation of the https://github.com/blarney-lang/five/[Five] pipeline with the RISC-V instruction set to give a simple 32-bit microcontroller.