firrtl: A Scala repository from jsn1993

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/freechipsproject/firrtl/wiki

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

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 -i regress/RocketCore.fir --custom-transforms tutorial.lesson1.AnalyzeCircuit
./utils/bin/firrtl -td regress -i regress/RocketCore.fir --custom-transforms tutorial.lesson2.AnalyzeCircuit

Other Tools

Firrtl syntax highlighting for Vim users: https://github.com/azidar/firrtl-syntax
Firrtl syntax highlighting for Sublime Text 3 users: https://github.com/codelec/highlight-firrtl
Firrtl syntax highlighting for Atom users: https://atom.io/packages/language-firrtl
Firrtl mode for Emacs users: https://github.com/ibm/firrtl-mode
Chisel3, an embedded hardware DSL that generates Firrtl: https://github.com/freechipsproject/chisel3
Treadle, a Firrtl Interpreter: https://github.com/freechipsproject/treadle
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

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

Installation

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

sbt publishLocal

Useful sbt Tips

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

sbt
> compile
> test

Use scalafix to remove unused import and deprecated procedure syntax

Remove unused import:

sbt "firrtl/scalafix RemoveUnused"

Remove deprecated procedure syntax

sbt "firrtl/scalafix ProcedureSyntax"

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 ICCAD paper and technical report: https://ieeexplore.ieee.org/document/8203780

@INPROCEEDINGS{8203780, 
author={A. Izraelevitz and J. Koenig and P. Li and R. Lin and A. Wang and A. Magyar and D. Kim and C. Schmidt and C. Markley and J. Lawson and J. Bachrach}, 
booktitle={2017 IEEE/ACM International Conference on Computer-Aided Design (ICCAD)}, 
title={Reusability is FIRRTL ground: Hardware construction languages, compiler frameworks, and transformations}, 
year={2017}, 
volume={}, 
number={}, 
pages={209-216}, 
keywords={field programmable gate arrays;hardware description languages;program compilers;software reusability;hardware development practices;hardware libraries;open-source hardware intermediate representation;hardware compiler transformations;Hardware construction languages;retargetable compilers;software development;virtual Cambrian explosion;hardware compiler frameworks;parameterized libraries;FIRRTL;FPGA mappings;Chisel;Flexible Intermediate Representation for RTL;Reusability;Hardware;Libraries;Hardware design languages;Field programmable gate arrays;Tools;Open source software;RTL;Design;FPGA;ASIC;Hardware;Modeling;Reusability;Hardware Design Language;Hardware Construction Language;Intermediate Representation;Compiler;Transformations;Chisel;FIRRTL}, 
doi={10.1109/ICCAD.2017.8203780}, 
ISSN={1558-2434}, 
month={Nov},}

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}
}

jsn1993/firrtl