cmtrs_macros 0.1.2

The macros for cmtrs.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

# Cement: The Next-gen Language & Compiler Powering Efficient Hardware Design

[<img alt="Static Badge" src="https://img.shields.io/badge/-pku--liang%2Fcmt2-blue?style=for-the-badge&logo=github">](https://github.com/pku-liang/Cement/tree/cmt2)
[<img alt="Static Badge" src="https://img.shields.io/badge/crates-cmtc-orange?style=for-the-badge&logo=rust">](https://crates.io/crates/cmtc)
[<img alt="Static Badge" src="https://img.shields.io/badge/crates-cmtrs-orange?style=for-the-badge&logo=rust">](https://crates.io/crates/cmtrs)
[<img alt="Static Badge" src="https://img.shields.io/badge/doc-cmtc-green?style=for-the-badge&logo=docs.rs">](https://docs.rs/cmtc)
[<img alt="Static Badge" src="https://img.shields.io/badge/doc-cmtrs-green?style=for-the-badge&logo=docs.rs">](https://docs.rs/cmtrs)


## Introduction

Cement (now referred to as `cmt2`!) represents an innovative framework that endows users with a wealth of language capabilities and compiler functionalities, all geared towards facilitating efficient hardware design. 

Since the release of its predecessor, the now-outdated [`cmt1` at FPGA'24](https://dl.acm.org/doi/10.1145/3626202.3637561), Cement has undergone a significant and comprehensive redesign. Building upon `cmt1`'s remarkable **event-based procedural specification** attribute, which empowered designers to delineate hardware control logic (e.g., generate FSMs) at an abstraction level that resembled software yet maintained cycle-determinism, `cmt2` takes a leap forward. It adopts a **rule-based** hardware description methodology, much like [Bluespec SystemVerilog (BSV)](https://github.com/B-Lang-org/bsc), thereby proffering straightforward and precise semantics for characterizing hardware behavior. This seamless integration of features equips `cmt2` to offer a hardware design journey that is not only more adaptable, modular, and responsive but also shields designers from the intricate web of connecting Register Transfer Level (RTL) hardware components. 

Moreover, `cmt2` presents a revamped Rust-based **embedded HDL** frontend, enhancing user experience with its enhanced intuitiveness. `cmt2` is engineered to generate top-notch SystemVerilog code by leveraging the [FIRRTL](https://bar.eecs.berkeley.edu/projects/firrtl.html) Intermediate Representation (IR) and the [firtool](https://github.com/llvm/circt/releases) compiler, and it extends its compatibility to multiple simulator backends, notably [Verilator](https://www.veripool.org/verilator/) and [Khronos](https://github.com/pku-liang/ksim).

### Terminology

In this project, different terms are used to refer to specific components:
- `Cement`: This term represents the entire framework, which includes the language and compiler tools. It provides the foundation and overall structure where other elements function.
  - `cmt1`: The [FPGA'24](https://dl.acm.org/doi/10.1145/3626202.3637561)-published version (archived at [`cmt1` branch](https://github.com/pku-liang/Cement/tree/cmt1))
  - `cmt2`: The current, **rule-based** version.

Within the `cmt2` framework in particular:
  - `cmtrs`: Signifies the front-end language. It is a Rust-based embedded HDL!
  - `cmtir`: Represents the intermediate representation (IR) at the central position of the whole framework. It enables diverse optimization and transformation activities.
  - `cmtc`: Stands for the compiler. It is based on `cmtir` and generates diverse backends, including FIRRTL, SystemVerilog, and simulator workspaces.


### Overview

```mermaid
graph LR;
    A[cmtrs eHDL
    in Rust] --> B[cmtir]
    B --> C[cmtc] --> B
    C --> D[FIRRTL] --> F[SystemVerilog] 
    C --> E[simulator backends
    verilator/ksim]
```

## Usage


### VERY IMPORTANT!!!

`cmtrs` use nightly features for span support. You need add a file `.cargo/config.toml` with the following content:
```toml
[build]
rustflags = "--cfg procmacro2_semver_exempt"
```
as well as a `rust-toolchain.toml` file with the following content:
```toml
[toolchain]
channel = "nightly-2024-12-25"
```

### Setup


`cmt2` itself is a Rust crate. You can build it by:
```bash
git clone -b cmt2 git@github.com:pku-liang/Cement.git cmt2
cd cmt2
git submodule update --init --recursive
cargo build
```

`cmt2` depends on `firtool` for SV generation. `firtool-1.86.0` is tested. You can download it by:
```bash
wget https://github.com/llvm/circt/releases/download/firtool-1.86.0/firrtl-bin-linux-x64.tar.gz
tar -xvf firrtl-bin-linux-x64.tar.gz
cp -rf ./firtool-1.86.0/* <INSTALL_DIR>
```
Make sure `<INSTALL_DIR>/bin` is in your PATH.

If you want to simulate `cmt2` designs, you need to install [Verilator](https://www.veripool.org/verilator/) or [Khronos](https://github.com/pku-liang/ksim/tree/aspdac24-tutorial), depending on your preference.

> [!NOTE]
> For `ksim`, you need to rename the built `firtool` to `firtool-ksim`, `llc` to `llc-ksim`, and put them as well as `ksim` in your PATH.



### Example

Look at `crates/cmtc/examples/`.


For `GEMM`, you can run `cargo run --example gemm` to see the generated SV code `gemm.sv` and the simulator workspace `tb/gemm_ksim`.


## Components

### Crates

- `cmtrs`: The Rust-based embedded HDL frontend for `cmt2`.
- `cmtrs_macros`: The macros for `cmtrs`.
- `cmtir`: The Intermediate Representation (IR) for `cmt2`. **RULE-BASED!**
- `cmtc`: The compiler for `cmtir`, generating FIRRTL and simulators.
- `kir`: Parse, print, and def/use support for `cmtir`.


### File structure

```
cmt2/
├── crates/
│   ├── cmtrs/
│   ├── cmtrs_macros/
│   ├── cmtir/
│   ├── cmtc/
│   ├── kir/
├── README.md
├── LICENSE
```

## Publications


If you find this project useful in your research, please cite our paper that has been recently accepted to FPGA 2024:

```plain
@inproceedings{xiao2024cement,
  title={Cement: Streamlining FPGA Hardware Design with Cycle-Deterministic eHDL and Synthesis},
  author={Xiao, Youwei and Luo, Zizhang and Zhou, Kexing and Liang, Yun},
  booktitle={Proceedings of the 2024 ACM/SIGDA International Symposium on Field Programmable Gate Arrays (FPGA '24)},
  year={2024},
  address={Monterey, CA, USA},
  url = {https://doi.org/10.1145/3626202.3637561},
  doi = {10.1145/3626202.3637561},
}
```

> [!NOTE]
> `cmt2` has undergone a significant redesign since the publication of the FPGA'24 paper. The current version is **rule-based**!


## For Chisel Experts/Fans

If you enjoy Chisel's mature ecosystem and community, feel free to try our archieved Chisel-based version [`Handle`](https://github.com/arch-of-shadow/Handle).