HeteroCL v0.5

Overview

We are thrilled to announce the latest version of HeteroCL, which has undergone a complete migration from Halide IR to the MLIR ecosystem. The first release of HeteroCL-MLIR features a brand new Python frontend with HeteroCL AST, an IR system built around the newly designed HeteroCL dialect, an LLVM CPU backend, a Vivado HLS backend, and an Intel HLS backend.

The integration with MLIR allows HeteroCL to take advantage of the general, modular and powerful infrastructure provided by the MLIR ecosystem, making it easier to maintain and extend the system. We have also made numerous improvements to the system, including a systematic and extensible frontend design, more customization primitives, and performance enhancements. The functionality of the previous HalideIR-based system is well preserved in this new version, and we have ensured backward compatibility by passing all the unit tests.

We believe that these improvements will make HeteroCL an even more versatile and efficient tool for developing high-performance hardware designs. We invite all users to try out the new version and provide feedback on their experiences.

New Features

Frontend

HeteroCL Python program -> HeteroCL AST (Python) -> MLIR IR

• HeteroCL AST: an abstraction layer above MLIR IR, consisting of expressions and operations. AST simplifies the frontend design and IR building process and solves the MLIR operation scope issue.
• AST passes: transformation and legality checking passes on AST before IR generation.
• Extensible type system: including a type inference engine and an extensible set of type rules. Typing is performed on AST during tracing.
• IRBuilder: traverse HeteroCL AST and build corresponding MLIR IR operations.

IR System

The HeteroCL dialect covers all customization primitives available in the Halide-based IR system. The newly added primitives and utilities include:

• hcl.customization: defines a specification of parameterized customization
• hcl.apply: apply a customization spec on given inputs
• hcl.buffer_at: create a write buffer at given loop axis
• hcl.reverse: reverse input integer bits
• hcl.outline: outline operations to a function, supports unification
• hcl.reform: transform data layout format of a memref
• hcl.clone: clone functions
• File IO: read memref data from file, write memref data to file

API Changes

Front end API changes include:

• Scalar.v: the .v is now required to access the value of the scalar.
• Bit slicing behavior: the bit slicing behavior now matches Python convention, for example, v[3:5] returns a 2-bit unsigned integer containing the third and forth bit of v.
• Tag: hcl.Stage is no longer supported, we use tag to access imperative loop nests.

Deprecated APIs

• hcl.Stage: hcl.Stage is removed, using it will cause an error.
• @def: deprecated but still supported, using it will cause a warning.

Known Issues

• Data Placement
  • Host-xcel data placement after schedule customization is not supported, because dataflow graph partition is applied in the front-end.
  • Intra-kernel data placement is not implemented yet.
• Break and multiple return statements are not supported.
• Fixed-point divisions larger than 32-bits are not supported.
• Logical and, logical or does not support short-circuit evaluation.
• Invert is not implemented yet.
• Math operations including trigonometric, exponential, logarithmic functions are not implemented yet.
• Customizing functions defined by @def decorator is not supported yet.
• CSim, CSynth, HLS report are not yet supported in the HLS backend.
• Print operation limitations
  • Currenly only integer and float format printing in LLVM backend is supported.
  • Hexadecimal, binary, unsigned integer formats are not yet supported.
  • Printing in HLS is not yet supported.
• Limited support for simplifier: Only constant and binary op are supported for now.
• Source code information (e.g., file name, line number) support is thoroughly tested.

How to Upgrade

For users, you can directly run pip install . in the heterocl frontend folder. For developers, please follow the README in hcl-dialect repository for a step-by-step guide to compile the IR system and set up the end-to-end flow.

Feedback and Support

We encourage users to submit any issues they encounter, along with a minimal reproducible example to help us identify and solve the problem as quickly as possible.

HeteroCL v0.3

Release Note

We are happy to announce that v0.3 is released. Since Python 2 is deprecated, we will be supporting Python 3 from now on.

General API

• hcl.print (#178)
• hcl.struct (#157)

For hcl.struct, we only support CPU simulation and Xilinx toolchain (e.g. Vivado HLS). The Intel toolchain support will be introduced in the next release.

Data Streaming

• hcl.to (#140, #167)

With this new feature, users can specify data placement and data movement in a decoupled way. Currently, CPU simulation is still under development. We will release it in the next version.

Back-end Support

• Code generation for both Intel and Xilinx platforms (#140, #162)
• Integration with HLS IPs (#170)

We implemented several code generation passes for common FPGA back ends for different toolchains, including Xilinx Vitis and Intel AOCL. We also integrate HLS IPs with HeteroCL. Users can now use existing HLS IPs. We are working on integrating with RTL IPs, which will be introduced in the next version.

Front-end Support

• Integrate with Keras via Relay (#142)

We added a front-end pass that connects HeteroCL with Keras. We use Relay as a parser and graph builder. More front ends will be introduced in the later versions.

HeteroCL v0.2

Release Note

We are happy to announce that HeteroCL is now an open-source project. HeteroCL is currently both Python 2 and Python 3 compatible. Following we list the currently supported features and its related links (in tests and/or in the documentation).

General API

• hcl.init (initialize a HeteroCL environment)
• hcl.placeholder (create an input placeholder)
• hcl.create_schedule (create a schedule for hardware customization)
• hcl.lower (lower the program to IR for investigation)
• hcl.build (build the program)
• Related links: test, tutorial, doc

Data Type

• hcl.Int, hcl.UInt (can have arbitrary bitwidth up to 255 bits)
• hcl.Fixed, hcl.UFixed (can have arbitrary bitwidth up to 255 bits)
• hcl.Float (can be 32 or 64 bits)
• Related links: test, tutorial, doc

Imperative DSL

• hcl.and_, hcl.or_
• hcl.if_, hcl.elif_, hcl.else_
• hcl.for_, hcl.while_, hcl.break_
• bit operations (get bit, set bit, get slice, set slice)
• hcl.def_, hcl.return_ (a custom-defined HeteroCL module)
• Related links: general test, def test, tutorial, doc

Compute API

• hcl.compute (compute a new tensor according to the given formula)
• hcl.update (update an exsiting tensor according to the given formula)
• hcl.mutate (mutatively update an existing tensor)
• hcl.reduce_axis (create a reduce axis for reduction operation)
• hcl.sum (perform a summation on the given axis)
• hcl.pack, hcl.unpack (pack/unpack a tensor to larger/lower bitwidth)
• hcl.Stage (create a stage that contains user-defined operations)
• Related links: general test, reduction test, pack/unpck test, stage test, tutorial, doc

Compute Customization

• split, fuse, tile
• unroll, pipeline, parallel
• compute_at
• Related links: general test, imperative dsl test, tutorial, module tutorial, doc

Data Type API & Data Type Customization

• hcl.create_scheme (create a scheme for data type customization)
• hcl.create_schedule_from_scheme
• hcl.downsize (downsize integers to lower bit-width)
• hcl.quantize (quantize floating-points to fixed-points)
• Related links: test, tutorial, doc

Memory Customization

• partition, reshape
• reuse_at (create a reuse buffer provided the input tensor and stage)
• Related links: test, tutorial, doc

Back-end Target

• llvm (default target for CPU)
• vhls (generate Vivado HLS code)
• vhls_csim (generate an executable compiled from Vivado HLS code)
• ihls (generate Intel HLS code)
• merlinc (generate Merlin C code)
• soda (generate SODA DSL)
• soda_xhls (generate Vivado HLS code from SODA DSL)
• Related links: vhls test, ihls test, merlinc test, soda test, tutorial, SDOA tutorial

Stable Samples

• KNN-based digit recognition: code, tutorial
• CORDIC: code, tutorial
• K-means: code, tutorial
• GEMM: code, tutorial
• Smith-Waterman: code, tutorial
• LeNet Inference: code, tutorial