// write a compelling introduction here
[TOC]
hlstool is a tool for driving various CIRCT-based HLS flows. The tool works by defining pass pipelines that string together various MLIR and CIRCT passes to realize an HLS flow.
For new users to MLIR, it is important to recognize the different between such compiler driver tools, and the MLIR opt tools (optimization drivers), such as mlir-opt and circt-opt.
For instance, in hlstool we may specify a pass pipeline such as:
// Memref legalization.
pm.addPass(circt::createFlattenMemRefPass());
pm.nest<func::FuncOp>().addPass(
circt::handshake::createHandshakeLegalizeMemrefsPass());
pm.addPass(mlir::createConvertSCFToCFPass());
pm.nest<handshake::FuncOp>().addPass(createSimpleCanonicalizerPass());For the compiler developer, however, we often don't want to run the entire HLS pass pipeline on our IR, but instead work on a specific level of IR and run a specific pass. Thus, every pass that is nested within hlstool can also be driven by an opt tool, e.g. circt::createFlattenMemRefPass is registered in circt-opt as circt-opt --flatten-memref.
CIRCT homes multiple actively developed HLS flows, each with their own approach to HLS. This section aims to provide a brief overview of the different flows, and how to use them.
Note: we do mean 'active development'(!) - most of these flows are the combined efforts of various student, phd and research projects, and should not be considered production-ready. You will encounter bugs, but you will also have a group of people are happy to help you fix them, and improve the flows. Feel free to reach out to the codeowner of the dialect/pass that you're working on, or ask a question in the LLVM discord which has a dedicated circt channel.
How flow documentation is structured:
- Description: A brief description/rationale of the flow, what it is and why it is how it is.
- Relevant dialects: A listing of the dialects used in the flow (preferably in order), as well as links to the dialect rationales. We encourage the user to read the dialect rationales to understand the design decisions behind the dialects.
- Example usage/relevant tests: A vast majority of CIRCTs flow-specific knowledge is (unfortunately) institutional. However, users are often referred to the CIRCT tests to understand what different passes do, and how to drive the various CIRCT tools to achieve their goals. This section thus lists some relevant tests that may serve as important references of how to use the flow.
- handshake integration tests is a collection of cocotb-based tests that use
hlstoolto convertcf-level code to verilog. - handshake-runner tests show how to use the
handshake-runnerto interprethandshake-level IR
The following is a list of work that has used or contributed to the DHLS flow in CIRCT: