Chisel / FIRRTL Diagramming Project

This project can generate GraphViz dot files and from those svg files representing Chisel generated Firrtl circuits. It is also an example of a creating a Firrtl Transformation. This transformation can be applied through the use of annotations as demonstrated in the examples.GCD test. The graphs are mostly clickable, clicking a module will take you to a diagram for just that module. There is a TopLevel diagram that just shows the module hierarchy. Also, an individual arrow can be hovered over to make it turn red and become easier to follow.

Example

Top Level Example

Module Example

Using

Install

Installing this software should be pretty much the following.

git clone https://github.com/freechipsproject/diagrammer
cd diagrammer

Dependencies

You will need GraphViz (specifically a default path to the program dot) and sbt.

Note that this project currently depends on the master branches of all components of the Chisel ecosystem (chisel3 and firrtl), so you will need to clone and sbt publishLocal for each of these.

Creating Circuit Diagrams.

To create a set of graphs of a Firrtl Circuit all you need is this project and a Firrtl file (typically a file generated by Chisel with a .fir extension). Let's say you have a Firrtl file ~/projects/output/circuit.fir. From the command line you while in this directory for this project, you run

./diagram.sh -i ~/projects/output/circuit.fir

This will create a number of files in the same directory as the firrtl file that representing the firrtl graph. Each file will be a diagram for each module contained in the firrtl file, plus a file TopLevel.dot.svg file. It will also attempt to open the TopLevel.dot.svg file in a browser using the command open. Each Module in the TopLevel diagram is clickable and should take you into the diagram for that specific module. Because of the size of these files, the diagrams will include the internal logic of that module plus and IO only presentation of any sub-modules found.

Options

-i, --firrtl-source set the source firrtl to work on
-t, --targer-dir sets the output directory for the svg
-s, --start-module sets the module name where the graphs will start being generated. The default is at the top
-o, --open-program sets the open program, default is open, set to empty to tell it not to do open
-j, --just-top-level generates just the top level diagram

How Diagrammer Works

This program uses a number of firrtl transforms to create multiple graphviz dot file graph programs. The dot files are translated into .svg files. See GeneratorBootcamp Firrtl Chapters for a good introduction to writing Firrtl transforms

TODO

This used to work by annotating a circuit, consider re-adding that
Setting to allow the graphs to go deeper into sub-module logic
Provide links to the chisel source