|
1 | | -# This project is in maintenance mode |
2 | | - |
3 | | -Pull Requests should only be made for bug fixes against versions 1.6 and below (Chisel 3.6 and below). |
| 1 | +# This project is archived |
4 | 2 |
|
5 | 3 | Please see [CIRCT](https://github.com/llvm/circt) for the next generation FIRRTL compiler. |
6 | | -Also see [Chisel](https://github.com/chipsalliance/chisel). |
7 | | - |
8 | | ---- |
9 | | - |
10 | | - |
| 4 | +Also see [the FIRRTL Spec](https://github.com/chipsalliance/firrtl-spec) and [Chisel](https://github.com/chipsalliance/chisel). |
11 | 5 |
|
12 | 6 | --- |
13 | 7 |
|
14 | | -[](https://gitter.im/freechipsproject/firrtl?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
15 | | - |
16 | | -[![Mergify Status][mergify-status]][mergify] |
17 | | - |
18 | | -[mergify]: https://mergify.io |
19 | | -[mergify-status]: https://img.shields.io/endpoint.svg?url=https://gh.mergify.io/badges/chipsalliance/firrtl&style=flat |
20 | | - |
21 | | -#### Flexible Internal Representation for RTL |
22 | | - |
23 | | - Firrtl is an intermediate representation (IR) for digital circuits designed as a platform for writing circuit-level transformations. |
24 | | - This repository consists of a collection of transformations (written in Scala) which simplify, verify, transform, or emit their input circuit. |
25 | | - |
26 | | - A Firrtl compiler is constructed by chaining together these transformations, then writing the final circuit to a file. |
27 | | - |
28 | | - For a detailed description of Firrtl's intermediate representation, see the [FIRRTL Language Specification](https://github.com/chipsalliance/firrtl-spec/releases/latest/download/spec.pdf) ([source](https://github.com/chipsalliance/firrtl-spec)). |
29 | | - |
30 | | -#### Wiki Pages and Tutorials |
31 | | - |
32 | | -Useful information is on our wiki, located here: |
33 | | -* https://github.com/freechipsproject/firrtl/wiki |
34 | | - |
35 | | -Some important pages to read, before writing your own transform: |
36 | | -* [Submitting Pull Requests](https://github.com/freechipsproject/firrtl/wiki/Submitting-a-Pull-Request) |
37 | | -* [Understanding Firrtl's IR](https://github.com/freechipsproject/firrtl/wiki/Understanding-Firrtl-Intermediate-Representation) |
38 | | -* [Traversing a Circuit](https://github.com/freechipsproject/firrtl/wiki/traversing-a-circuit) |
39 | | -* [Common Pass Idioms](https://github.com/freechipsproject/firrtl/wiki/Common-Pass-Idioms) |
40 | | - |
41 | | -To write a Firrtl transform, please start with the tutorial here: [src/main/scala/tutorial](https://github.com/freechipsproject/firrtl/blob/master/src/main/scala/tutorial). |
42 | | -To run these examples: |
43 | | -``` |
44 | | -sbt assembly |
45 | | -./utils/bin/firrtl -td regress -i regress/RocketCore.fir --custom-transforms tutorial.lesson1.AnalyzeCircuit |
46 | | -./utils/bin/firrtl -td regress -i regress/RocketCore.fir --custom-transforms tutorial.lesson2.AnalyzeCircuit |
47 | | -``` |
48 | | - |
49 | | -#### Other Tools |
50 | | -* Firrtl syntax highlighting for Vim users: https://github.com/azidar/firrtl-syntax |
51 | | -* Firrtl syntax highlighting for Sublime Text 3 users: https://github.com/codelec/highlight-firrtl |
52 | | -* Firrtl syntax highlighting for Atom users: https://atom.io/packages/language-firrtl |
53 | | -* Firrtl syntax highlighting, structure view, navigate to corresponding Chisel code for IntelliJ platform: [install](https://plugins.jetbrains.com/plugin/14183-easysoc-firrtl), [source](https://github.com/easysoc/easysoc-firrtl) |
54 | | -* Firrtl mode for Emacs users: https://github.com/ibm/firrtl-mode |
55 | | -* Chisel3, an embedded hardware DSL that generates Firrtl: https://github.com/freechipsproject/chisel3 |
56 | | -* Treadle, a Firrtl Interpreter: https://github.com/freechipsproject/treadle |
57 | | -* Yosys Verilog-to-Firrtl Front-end: https://github.com/cliffordwolf/yosys |
58 | | - |
59 | | -#### Installation Instructions |
60 | | -*Disclaimer*: The installation instructions should work for OSX/Linux machines. Other environments may not be tested. |
61 | | - |
62 | | -##### Prerequisites |
63 | | - 1. If not already installed, install [verilator](http://www.veripool.org/projects/verilator/wiki/Installing) (Requires at least v3.886) |
64 | | - 1. If not already installed, install [yosys](https://github.com/YosysHQ/yosys) (Requires at least v0.8) |
65 | | - 1. If not already installed, install [sbt](http://www.scala-sbt.org/) (Recommend v1.6.2) |
66 | | - |
67 | | -##### Installation |
68 | | - 1. Clone the repository: |
69 | | - ```git clone https://github.com/freechipsproject/firrtl.git && cd firrtl``` |
70 | | - 1. Compile firrtl: ```sbt compile``` |
71 | | - 1. Run tests: ```sbt test``` |
72 | | - 1. Build executable (`utils/bin/firrtl`): ```sbt assembly``` |
73 | | - * **Note:** You can add `utils/bin` to your path to call firrtl from other processes |
74 | | - 1. Publish this version locally in order to satisfy other tool chain library dependencies: |
75 | | -``` |
76 | | -sbt publishLocal |
77 | | -``` |
78 | | - |
79 | | -##### Useful sbt Tips |
80 | | - 1. Run a single test suite: |
81 | | - `sbt "testOnly firrtlTests.UnitTests"` |
82 | | - 2. Continually execute a command: |
83 | | - `sbt ~compile` |
84 | | - 3. Only invoke sbt once: |
85 | | -``` |
86 | | -sbt |
87 | | -> compile |
88 | | -> test |
89 | | -``` |
90 | | - |
91 | | -##### Use scalafix to remove unused import and deprecated procedure syntax |
92 | | - 1. Remove unused import: |
93 | | -``` |
94 | | -sbt "firrtl/scalafix RemoveUnused" |
95 | | -``` |
96 | | - 2. Remove deprecated procedure syntax |
97 | | -``` |
98 | | -sbt "firrtl/scalafix ProcedureSyntax" |
99 | | -``` |
100 | | - |
101 | | -##### Using Firrtl as a commandline tool |
102 | | -``` |
103 | | -utils/bin/firrtl -i regress/rocket.fir -o regress/rocket.v -X verilog // Compiles rocket-chip to Verilog |
104 | | -utils/bin/firrtl --help // Returns usage string |
105 | | -``` |
106 | | - |
107 | | -##### Using the JQF Fuzzer |
108 | | -The `build.sbt` defines the `fuzzer/jqfFuzz` and `fuzzer/jqfRepro` tasks. These |
109 | | -can be used to randomly generate and run test cases and reproduce failing test |
110 | | -cases respectively. These tasks are Scala implementations of the [FuzzGoal and |
111 | | -ReproGoal](https://github.com/rohanpadhye/JQF/tree/master/maven-plugin/src/main/java/edu/berkeley/cs/jqf/plugin) |
112 | | -of the JQF maven plugin and should be functionally identical. |
113 | | - |
114 | | -The format for the arguments to jqfFuzz are as follows: |
115 | | -``` |
116 | | -sbt> fuzzer/jqfFuzz <testClassName> <testMethodName> <otherArgs>... |
117 | | -``` |
118 | | - |
119 | | -The available options are: |
120 | | -``` |
121 | | - --classpath <value> the classpath to instrument and load the test class from |
122 | | - --outputDirectory <value> the directory to output test results |
123 | | - --testClassName <value> the full class path of the test class |
124 | | - --testMethod <value> the method of the test class to run |
125 | | - --excludes <value> comma-separated list of FQN prefixes to exclude from coverage instrumentation |
126 | | - --includes <value> comma-separated list of FQN prefixes to forcibly include, even if they match an exclude |
127 | | - --time <value> the duration of time for which to run fuzzing |
128 | | - --blind whether to generate inputs blindly without taking into account coverage feedback |
129 | | - --engine <value> the fuzzing engine, valid choices are zest|zeal |
130 | | - --disableCoverage disable code-coverage instrumentation |
131 | | - --inputDirectory <value> the name of the input directory containing seed files |
132 | | - --saveAll save ALL inputs generated during fuzzing, even the ones that do not have any unique code coverage |
133 | | - --libFuzzerCompatOutput use libFuzzer like output instead of AFL like stats screen |
134 | | - --quiet avoid printing fuzzing statistics progress in the console |
135 | | - --exitOnCrash stop fuzzing once a crash is found. |
136 | | - --runTimeout <value> the timeout for each individual trial, in milliseconds |
137 | | -``` |
138 | | - |
139 | | -The `fuzzer/jqfFuzz` sbt task is a thin wrapper around the `firrtl.jqf.jqfFuzz` |
140 | | -main method that provides the `--classpath` argument and a default |
141 | | -`--outputDirectory` and passes the rest of the arguments to the main method |
142 | | -verbatim. |
143 | | - |
144 | | -The results will be put in the `fuzzer/target/JQf/$testClassName/$testMethod` |
145 | | -directory. Input files in the |
146 | | -`fuzzer/target/JQf/$testClassName/$testMethod/corpus` and |
147 | | -`fuzzer/target/JQf/$testClassName/$testMethod/failures` directories can be |
148 | | -passed as inputs to the `fuzzer/jqfRepro` task. |
149 | | - |
150 | | - |
151 | | -The format for the arguments to jqfRepro are the same as `jqfFuzz` |
152 | | -``` |
153 | | -sbt> fuzzer/jqfRepro <testClassName> <testMethodName> <otherArgs>... |
154 | | -``` |
155 | | - |
156 | | -The available options are: |
157 | | - |
158 | | -``` |
159 | | - --classpath <value> the classpath to instrument and load the test class from |
160 | | - --testClassName <value> the full class path of the test class |
161 | | - --testMethod <value> the method of the test class to run |
162 | | - --input <value> input file or directory to reproduce test case(s) |
163 | | - --logCoverage <value> output file to dump coverage info |
164 | | - --excludes <value> comma-separated list of FQN prefixes to exclude from coverage instrumentation |
165 | | - --includes <value> comma-separated list of FQN prefixes to forcibly include, even if they match an exclude |
166 | | - --printArgs whether to print the args to each test case |
167 | | -``` |
168 | | - |
169 | | -Like `fuzzer/jqfFuzz`, the `fuzzer/jqfRepro` sbt task is a thin wrapper around |
170 | | -the `firrtl.jqf.jqfRepro` main method that provides the `--classpath` argument |
171 | | -and a default `--outputDirectory` and passes the rest of the arguments to the |
172 | | -main method verbatim. |
173 | | - |
174 | | -##### Citing Firrtl |
| 8 | +### Citing Firrtl |
175 | 9 |
|
176 | 10 | If you use Firrtl in a paper, please cite the following ICCAD paper and technical report: |
177 | 11 | https://ieeexplore.ieee.org/document/8203780 |
|
0 commit comments