README.md 5.21 KB
Newer Older
EGLOFF Valentin's avatar
EGLOFF Valentin committed
1
# Comet
2

3
[![pipeline status](https://gitlab.inria.fr/srokicki/Comet/badges/master/pipeline.svg)](https://gitlab.inria.fr/srokicki/Comet/commits/master)
4 5


PATUREL Joseph's avatar
PATUREL Joseph committed
6 7
A RISC-V 32-bit processor written in C++ for High Level Synthesis (HLS).
Support for the RV32I base ISA only, support for the M extension can be found on [another branch](https://gitlab.inria.fr/srokicki/Comet/tree/rv32im). There is [branch dedicated to the support of the F extension](https://gitlab.inria.fr/srokicki/Comet/tree/rv32imf) but it is not stable yet and may not be in a functional state.
EGLOFF Valentin's avatar
EGLOFF Valentin committed
8

PATUREL Joseph's avatar
PATUREL Joseph committed
9
## Dependencies
PATUREL Joseph's avatar
PATUREL Joseph committed
10
The only dependency to satisfy in order to build the simulator is `cmake`.
EGLOFF Valentin's avatar
EGLOFF Valentin committed
11

PATUREL Joseph's avatar
PATUREL Joseph committed
12
To compile the tests, a RISC-V toolchain and libraries are needed:
13
  - [RISC-V GNU toolchain](https://github.com/riscv/riscv-gnu-toolchain)
EGLOFF Valentin's avatar
EGLOFF Valentin committed
14

PATUREL Joseph's avatar
PATUREL Joseph committed
15
## Building the simulator
EGLOFF Valentin's avatar
EGLOFF Valentin committed
16

PATUREL Joseph's avatar
PATUREL Joseph committed
17
Make sure that the dependencies are met by installing `cmake` using your package manager or directly from the sources.
PATUREL Joseph's avatar
PATUREL Joseph committed
18

PATUREL Joseph's avatar
PATUREL Joseph committed
19
For exemple on a debian based system, run `sudo apt install cmake`.
EGLOFF Valentin's avatar
EGLOFF Valentin committed
20

PATUREL Joseph's avatar
PATUREL Joseph committed
21
Once the repository cloned, `cd` into it.
EGLOFF Valentin's avatar
EGLOFF Valentin committed
22
```
PATUREL Joseph's avatar
PATUREL Joseph committed
23 24
mkdir build && cd build
cmake ..
EGLOFF Valentin's avatar
EGLOFF Valentin committed
25 26
make
```
EGLOFF Valentin's avatar
EGLOFF Valentin committed
27

PATUREL Joseph's avatar
PATUREL Joseph committed
28 29 30
The simulator binary is located in `<repo_root>/build/bin` under the name `comet.sim`

#### Building the GNU RISC-V toolchain
EGLOFF Valentin's avatar
EGLOFF Valentin committed
31

PATUREL Joseph's avatar
PATUREL Joseph committed
32 33 34
To produce binaries that can be executed by Comet, a working 32bit RISC-V toolchain and libraries are needed.
To build a such a set of tools, these steps can be followed :

EGLOFF Valentin's avatar
EGLOFF Valentin committed
35
```
PATUREL Joseph's avatar
PATUREL Joseph committed
36 37 38
git clone --recursive https://github.com/riscv/riscv-gnu-toolchain
export RISCV=/path/to/install/riscv/toolchain
cd riscv-gnu-toolchain
EGLOFF Valentin's avatar
EGLOFF Valentin committed
39 40
```

PATUREL Joseph's avatar
PATUREL Joseph committed
41
The toolchain is dependant on a few packages that can be installed using :
EGLOFF Valentin's avatar
EGLOFF Valentin committed
42 43

```
PATUREL Joseph's avatar
PATUREL Joseph committed
44 45
sudo apt-get install autoconf automake autotools-dev curl libmpc-dev libmpfr-dev libgmp-dev gawk\
 build-essential bison flex texinfo gperf libtool patchutils bc zlib1g-dev libexpat-dev
PATUREL Joseph's avatar
PATUREL Joseph committed
46 47
```
on a Debian based system.
PATUREL Joseph's avatar
PATUREL Joseph committed
48
Or using :
EGLOFF Valentin's avatar
EGLOFF Valentin committed
49
```
PATUREL Joseph's avatar
PATUREL Joseph committed
50 51
sudo yum install autoconf automake libmpc-devel mpfr-devel gmp-devel gawk  bison flex texinfo patchutils\
 gcc gcc-c++ zlib-devel expat-devel
PATUREL Joseph's avatar
PATUREL Joseph committed
52 53 54
```
on Fedora/CentOS/RHEL OS systems

PATUREL Joseph's avatar
PATUREL Joseph committed
55
The build process needs to be configured function of which extension is supported by the core. In our case, we enable support for the base ISA only:
EGLOFF Valentin's avatar
EGLOFF Valentin committed
56 57

```
PATUREL Joseph's avatar
PATUREL Joseph committed
58
./configure --prefix=$RISCV --with-arch=rv32i --with-abi=ilp32
PATUREL Joseph's avatar
PATUREL Joseph committed
59
make
EGLOFF Valentin's avatar
EGLOFF Valentin committed
60 61
```

PATUREL Joseph's avatar
PATUREL Joseph committed
62
Once the toolchain compiled it is a good idea to add it's installation directory to the your PATH :
PATUREL Joseph's avatar
PATUREL Joseph committed
63
```
ROKICKI Simon's avatar
ROKICKI Simon committed
64
export PATH = $PATH:$RISCV/bin
PATUREL Joseph's avatar
PATUREL Joseph committed
65 66
```

PATUREL Joseph's avatar
PATUREL Joseph committed
67 68 69 70 71
> You may want to add that command to your shell startup file

#### Building the tests

This repository includes a basic set of benchmarks (`dijkstra`, `matmul`, `qsort` and `dct`) working on different datatypes.
PATUREL Joseph's avatar
PATUREL Joseph committed
72 73

```
PATUREL Joseph's avatar
PATUREL Joseph committed
74
cd <repo_root>/tests
PATUREL Joseph's avatar
PATUREL Joseph committed
75 76
make
```
PATUREL Joseph's avatar
PATUREL Joseph committed
77
The `make` command will compile the tests for a RISC-V target and for your system and will collect their expected output.
PATUREL Joseph's avatar
PATUREL Joseph committed
78 79 80 81
This will allow the `runTests.sh` script to check the behavior of Comet against a verified CPU (your system's).

##### Adding a test

PATUREL Joseph's avatar
PATUREL Joseph committed
82
To add a test to the test pool, add a folder in the `tests` directory at the root of the repository. This folder needs to be named like the binary it will contain.
PATUREL Joseph's avatar
PATUREL Joseph committed
83 84 85 86

> Exemple : the `qsort` folder contains the `qsort.riscv32` binary

The folder must contain the sources of the program and a makefile.
PATUREL Joseph's avatar
PATUREL Joseph committed
87
The binary produced by the makefile must be named like the folder it's contained in and bear the `.riscv32` extension.
PATUREL Joseph's avatar
PATUREL Joseph committed
88 89 90 91 92 93 94 95 96 97

For the test to be valid, a file named `expectedOutput` needs to be created. It must contain the standard output that the test is supposed to produce.

> You can reuse the makefile of the existing tests as a starting point.
> This makefile compiles the sources for the RISC-V target as well as for the host system, runs the native binary and creates the `expectedOutput` file automatically

All the tests **must** be reproducible output-wise, no random or system dependent data should be used.

The `runTests.sh` script executes all the tests present in the `tests` subfolders with a timeout (set in the script).
Please make sure that the tests you add all execute within the bounds of this timeout with a reasonable margin.
PATUREL Joseph's avatar
PATUREL Joseph committed
98 99

## Simulator
PATUREL Joseph's avatar
PATUREL Joseph committed
100
To run the simulator execute the `comet.sim` located in `<repo_root>/build/bin`.
PATUREL Joseph's avatar
PATUREL Joseph committed
101
You can provide a specific binary to be run by the simulator using the `-f <path_to_the_binary>` switch.
PATUREL Joseph's avatar
PATUREL Joseph committed
102 103 104

The `-i` and `-o` switches are used to specify the benchmark's standard input and output respectively.

PATUREL Joseph's avatar
PATUREL Joseph committed
105
The `-a` switch allows to pass arguments to the benchmark that is being run by the simulator.
106

PATUREL Joseph's avatar
PATUREL Joseph committed
107
For further information about the arguments of the simulator, run `comet.sim -h`.
108

109 110 111 112 113
## Logic Synthesis

Using HLS tools, the Comet core can be synthesized and implemented on FPGA targets or mapped to standard cells using a design kit.
RTL synthesis is tested using [Mentor Catapult HLS](https://www.mentor.com/hls-lp/catapult-high-level-synthesis/). If you wish to have the RTL output, please send an email to simon.rokicki@irisa.fr.

ROKICKI Simon's avatar
ROKICKI Simon committed
114 115 116 117 118
## Publication

- "<a href="https://hal.archives-ouvertes.fr/hal-02303453v1">What You Simulate Is What You Synthesize: Designing a Processor Core from C++ Specifications</a>", in 38th IEEE/ACM International Conference on Computer-Aided Design


119 120 121 122 123 124 125 126
## Contributors

The following persons contributed to the Comet project:

- Simon Rokicki
- Davide Pala
- Joseph Paturel
- Valentin Egloff
PATUREL Joseph's avatar
PATUREL Joseph committed
127
- Edwin Mascarenhas
128
- Gurav Datta
PATUREL Joseph's avatar
PATUREL Joseph committed
129 130
- Lauric Desauw
- Olivier Sentieys