Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/freechipsproject/diagrammer

Provides dot visualizations of chisel/firrtl circuits
https://github.com/freechipsproject/diagrammer

chisel chisel3 firrtl visualization

Last synced: 2 months ago
JSON representation

Provides dot visualizations of chisel/firrtl circuits

Awesome Lists containing this project

README 

        
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

![Graph](https://raw.githubusercontent.com/freechipsproject/diagrammer/master/images/TopLevel.dot.svg?sanitize=true)



### Module Example



![Graph](https://raw.githubusercontent.com/freechipsproject/diagrammer/master/images/TopOfVisualizer.dot.svg?sanitize=true)



## Using

### Install

Installing this software should be pretty much the following.

```bash

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

cd diagrammer

```



### Dependencies

You will need [GraphViz](https://www.graphviz.org/) (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

```bash

./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](https://github.com/freechipsproject/chisel-bootcamp)

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