diff --git a/README.md b/README.md index c24730fd53..ef60816ab0 100644 --- a/README.md +++ b/README.md @@ -1,177 +1,11 @@ -# This project is in maintenance mode - -Pull Requests should only be made for bug fixes against versions 1.6 and below (Chisel 3.6 and below). +# This project is archived Please see [CIRCT](https://github.com/llvm/circt) for the next generation FIRRTL compiler. -Also see [Chisel](https://github.com/chipsalliance/chisel). - ---- - -![FIRRTL](https://raw.githubusercontent.com/freechipsproject/firrtl/master/doc/images/firrtl_logo.svg?sanitize=true) +Also see [the FIRRTL Spec](https://github.com/chipsalliance/firrtl-spec) and [Chisel](https://github.com/chipsalliance/chisel). --- -[![Join the chat at https://gitter.im/freechipsproject/firrtl](https://badges.gitter.im/freechipsproject/firrtl.svg)](https://gitter.im/freechipsproject/firrtl?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -![Build Status](https://github.com/chipsalliance/firrtl/workflows/Continuous%20Integration/badge.svg) -[![Mergify Status][mergify-status]][mergify] - -[mergify]: https://mergify.io -[mergify-status]: https://img.shields.io/endpoint.svg?url=https://gh.mergify.io/badges/chipsalliance/firrtl&style=flat - -#### 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 [FIRRTL Language Specification](https://github.com/chipsalliance/firrtl-spec/releases/latest/download/spec.pdf) ([source](https://github.com/chipsalliance/firrtl-spec)). - -#### 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: -* [Submitting Pull Requests](https://github.com/freechipsproject/firrtl/wiki/Submitting-a-Pull-Request) -* [Understanding Firrtl's IR](https://github.com/freechipsproject/firrtl/wiki/Understanding-Firrtl-Intermediate-Representation) -* [Traversing a Circuit](https://github.com/freechipsproject/firrtl/wiki/traversing-a-circuit) -* [Common Pass Idioms](https://github.com/freechipsproject/firrtl/wiki/Common-Pass-Idioms) - -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). -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 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) -* 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 - 1. If not already installed, install [verilator](http://www.veripool.org/projects/verilator/wiki/Installing) (Requires at least v3.886) - 1. If not already installed, install [yosys](https://github.com/YosysHQ/yosys) (Requires at least v0.8) - 1. If not already installed, install [sbt](http://www.scala-sbt.org/) (Recommend v1.6.2) - -##### Installation - 1. Clone the repository: - ```git clone https://github.com/freechipsproject/firrtl.git && cd firrtl``` - 1. Compile firrtl: ```sbt compile``` - 1. Run tests: ```sbt test``` - 1. Build executable (`utils/bin/firrtl`): ```sbt assembly``` - * **Note:** You can add `utils/bin` to your path to call firrtl from other processes - 1. Publish this version locally in order to satisfy other tool chain library dependencies: -``` -sbt publishLocal -``` - -##### 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 -``` - -##### Use scalafix to remove unused import and deprecated procedure syntax - 1. Remove unused import: -``` -sbt "firrtl/scalafix RemoveUnused" -``` - 2. 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 -``` - -##### Using the JQF Fuzzer -The `build.sbt` defines the `fuzzer/jqfFuzz` and `fuzzer/jqfRepro` tasks. These -can be used to randomly generate and run test cases and reproduce failing test -cases respectively. These tasks are Scala implementations of the [FuzzGoal and -ReproGoal](https://github.com/rohanpadhye/JQF/tree/master/maven-plugin/src/main/java/edu/berkeley/cs/jqf/plugin) -of the JQF maven plugin and should be functionally identical. - -The format for the arguments to jqfFuzz are as follows: -``` -sbt> fuzzer/jqfFuzz ... -``` - -The available options are: -``` - --classpath the classpath to instrument and load the test class from - --outputDirectory the directory to output test results - --testClassName the full class path of the test class - --testMethod the method of the test class to run - --excludes comma-separated list of FQN prefixes to exclude from coverage instrumentation - --includes comma-separated list of FQN prefixes to forcibly include, even if they match an exclude - --time the duration of time for which to run fuzzing - --blind whether to generate inputs blindly without taking into account coverage feedback - --engine the fuzzing engine, valid choices are zest|zeal - --disableCoverage disable code-coverage instrumentation - --inputDirectory the name of the input directory containing seed files - --saveAll save ALL inputs generated during fuzzing, even the ones that do not have any unique code coverage - --libFuzzerCompatOutput use libFuzzer like output instead of AFL like stats screen - --quiet avoid printing fuzzing statistics progress in the console - --exitOnCrash stop fuzzing once a crash is found. - --runTimeout the timeout for each individual trial, in milliseconds -``` - -The `fuzzer/jqfFuzz` sbt task is a thin wrapper around the `firrtl.jqf.jqfFuzz` -main method that provides the `--classpath` argument and a default -`--outputDirectory` and passes the rest of the arguments to the main method -verbatim. - -The results will be put in the `fuzzer/target/JQf/$testClassName/$testMethod` -directory. Input files in the -`fuzzer/target/JQf/$testClassName/$testMethod/corpus` and -`fuzzer/target/JQf/$testClassName/$testMethod/failures` directories can be -passed as inputs to the `fuzzer/jqfRepro` task. - - -The format for the arguments to jqfRepro are the same as `jqfFuzz` -``` -sbt> fuzzer/jqfRepro ... -``` - -The available options are: - -``` - --classpath the classpath to instrument and load the test class from - --testClassName the full class path of the test class - --testMethod the method of the test class to run - --input input file or directory to reproduce test case(s) - --logCoverage output file to dump coverage info - --excludes comma-separated list of FQN prefixes to exclude from coverage instrumentation - --includes comma-separated list of FQN prefixes to forcibly include, even if they match an exclude - --printArgs whether to print the args to each test case -``` - -Like `fuzzer/jqfFuzz`, the `fuzzer/jqfRepro` sbt task is a thin wrapper around -the `firrtl.jqf.jqfRepro` main method that provides the `--classpath` argument -and a default `--outputDirectory` and passes the rest of the arguments to the -main method verbatim. - -##### Citing Firrtl +### Citing Firrtl If you use Firrtl in a paper, please cite the following ICCAD paper and technical report: https://ieeexplore.ieee.org/document/8203780