This repository hosts the specification for the FIRRTL language.

To build this, you need the following:

• pandoc
• pandoc-crossref
• A LaTeX distribution, e.g., TeX Live
• latexmk which may come with your LaTeX distribution
• Graphviz

For compatibility with continuous integration (CI) formatting, use the versions of pandoc and pandoc-crossref that are listed in the CI GitHub Action. If this release is not available in your package manager, you can download binaries from their GitHub releases pages:

• pandoc releases
• pandoc-crossref releases

To run tests, both firtool and Verilator must be available on your PATH. For compatibility with CI testing, use the version of firtool specified in include/circt.json and the Verilator version used by the version of the OSS CAD Suite in listed in the CI GitHub Action.

After resolving these dependencies, use the following build targets:

• make or make all will compile will compile spec.md and abi.md into build/spec.pdf and build/abi.pdf.
• make format will format all Markdown files by round-tripping them through pandoc. For this build step to be usable, use the exact versions of pandoc and pandoc-crossref that CI uses!
• make lint will rewrite all Markdown files in place to use the canonical terminology, e.g., subfield instead of sub-field. The rules are in scripts/lint-terminology.lua. CI runs this and fails if it produces any changes.
• make test will extract FIRRTL and Verilog snippets from the specification and ABI document and, respectively, run them through firtool -parse-only or verilator --lint-only to test that they are legal FIRRTL or Verilog.