Firrtl

Flexible Internal Representation for RTL

Firrtl is an intermediate representation (IR) for digital circuits designed as a platform for writing circuit-level transformations. This repository consists of a collection of transformations (written in Scala) which simplify, verify, transform, or emit their input circuit.

A Firrtl compiler is constructed by chaining together these transformations, then writing the final circuit to a file.

For a detailed description of Firrtl's intermediate representation, see the document "Specification of the Firrtl Language" located in spec/spec.pdf.

Wiki Pages and Tutorials

Useful information is on our wiki, located here:

• https://github.com/ucb-bar/firrtl/wiki

Some important pages to read, before writing your own transform:

• Submitting Pull Requests
• Understanding Firrtl's IR
• Traversing a Circuit
• Common Pass Idioms

To write a Firrtl transform, please start with the tutorial here: src/main/scala/tutorial. To run these examples:

sbt assembly
./utils/bin/firrtl -td regress -tn rocket --custom-transforms tutorial.lesson1.AnalyzeCircuit
./utils/bin/firrtl -td regress -tn rocket --custom-transforms tutorial.lesson2.AnalyzeCircuit

Other Tools

• Firrtl syntax highlighting for Vim users: https://github.com/azidar/firrtl-syntax
• Firrtl mode for Emacs users: https://github.com/ibm/firrtl-mode
• Chisel3, an embedded hardware DSL that generates Firrtl: https://github.com/ucb-bar/chisel3
• Firrtl Interpreter: https://github.com/ucb-bar/firrtl-interpreter
• Yosys Verilog-to-Firrtl Front-end: https://github.com/cliffordwolf/yosys

Installation Instructions

Disclaimer: The installation instructions should work for OSX/Linux machines. Other environments may not be tested.

Prerequisites

1. If not already installed, install verilator (Requires at least v3.886)
2. If not already installed, install sbt (Requires at least v0.13.6)

Installation

1. Clone the repository: git clone https://github.com/ucb-bar/firrtl.git && cd firrtl
2. Compile firrtl: sbt compile
3. Run tests: sbt test
4. Build executable (utils/bin/firrtl): sbt assembly
   • Note: You can add utils/bin to your path to call firrtl from other processes
5. Publish this version locally in order to satisfy other tool chain library dependencies:

sbt publish-local

Useful sbt Tips

1. Run a single test suite: sbt "testOnly firrtlTests.UnitTests"
2. Continually execute a command: sbt ~compile
3. Only invoke sbt once:

sbt
> compile
> test

Using Firrtl as a commandline tool

utils/bin/firrtl -i regress/rocket.fir -o regress/rocket.v -X verilog // Compiles rocket-chip to Verilog
utils/bin/firrtl --help // Returns usage string

Citing Firrtl

If you use Firrtl in a paper, please cite the following technical report: https://www2.eecs.berkeley.edu/Pubs/TechRpts/2016/EECS-2016-9.html

@techreport{Li:EECS-2016-9,
    Author = {Li, Patrick S. and Izraelevitz, Adam M. and Bachrach, Jonathan},
    Title = {Specification for the FIRRTL Language},
    Institution = {EECS Department, University of California, Berkeley},
    Year = {2016},
    Month = {Feb},
    URL = {http://www2.eecs.berkeley.edu/Pubs/TechRpts/2016/EECS-2016-9.html},
    Number = {UCB/EECS-2016-9}
}