README.md 15.3 KB
Newer Older
1 2
The Task Parallel System Composer (TaPaSCo)
===========================================
Jaco Hofmann's avatar
Jaco Hofmann committed
3
![Tapasco logo](misc/icon/tapasco_icon.png)
4 5

Master Branch Status: [![pipeline status](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/badges/master/pipeline.svg)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/commits/master)
6
Dev Branch Status: [![pipeline status](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/badges/develop/pipeline.svg)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/commits/develop)
7

8 9 10 11 12
System Requirements
-------------------
TaPaSCo is known to work in this environment:

*   Intel x86_64 arch
13
*   Linux kernel 4.4+
14
*   Fedora 26+, Ubuntu 16.04+
15
*   Fedora 24/25 does not support debug mode due to GCC bug
16 17 18 19
*   Bash Shell 4.2.x+

Other setups likely work as well, but are untested.

20
Prerequisites for Toolflow
21 22 23
-------------
To use TaPaSCo, you'll need working installations of

24
*   Vivado Design Suite 2017.4 or newer
25
*   Java SDK 8 - 11
26
*   git
27
*   python
28
*   GCC newer than 5.x.x for C++11 support
29
*   *OPTIONAL:* libncurses for the tapasco-debug application
30
*   *OPTIONAL:* Local Installation of gradle 5.0+, if you do not want to use the included wrapper.
31 32

If you want to use the High-Level Synthesis flow for generating custom IP
Lukas Weber's avatar
Lukas Weber committed
33
cores, you will also need:
34

35
*   Vivado HLS 2017.4+
36 37 38

Check that at least the following are in your `$PATH`:

Lukas Weber's avatar
Lukas Weber committed
39
*   `vivado` - If not source `path/to/vivado/settings64.sh`
40 41
*   `git`
*   `bash`
42
*   \[`vivado_hls`\] - Since Vivado 2018.1 this is included in `vivado`
43

Lukas Weber's avatar
Lukas Weber committed
44 45 46 47 48 49 50 51 52
When using *Ubuntu*, ensure that the following packages are installed:

* unzip
* zip
* git
* findutils
* curl
* default-jdk

53 54 55 56
```
apt-get -y install unzip git zip findutils curl default-jdk
```

Lukas Weber's avatar
Lukas Weber committed
57 58 59 60 61 62
When using *Fedora*, ensure that the following packages are installed:

* which
* java-openjdk
* findutils

63 64 65
```
dnf -y install which java-openjdk findutils
```
Lukas Weber's avatar
Lukas Weber committed
66 67 68 69 70 71 72 73


TaPaSCo-Toolflow Setup
----------------------

Using the prebuilt packages, the setup of TaPaSCo is very easy:

1.  Create or open a folder, which you would like to use as your TaPaSCo workspace.
74
    Within this folder, run the TaPaSCo-Initialization-Script which is located in
Lukas Weber's avatar
Lukas Weber committed
75 76
    `/opt/tapasco/tapasco-init-toolflow.sh`. This will setup your current folder as `TAPASCO_WORK_DIR`.
    It will also create the file `tapasco-setup.sh` within your current directory. 
Lukas Weber's avatar
Lukas Weber committed
77
2.	Source `tapasco-setup.sh`.
Lukas Weber's avatar
Lukas Weber committed
78 79 80 81 82 83

If you want to use a specific (pre-release) version or branch, you can do the following:

1.  Clone TaPaSCo: `git clone https://github.com/esa-tu-darmstadt/tapasco.git`
2.  _Optionally_ Checkout a corresponding branch: `git checkout <BRANCH>`
3.  Create or open a folder, which you would like to use as your TaPaSCo workspace.
84
    Within this folder, run the TaPaSCo-Initialization-Script `tapasco-init.sh` which is located in the root-folder 
Lukas Weber's avatar
Lukas Weber committed
85 86 87 88
    of your cloned repo. This will setup your current folder as `TAPASCO_WORK_DIR`.
    It will also create the file `tapasco-setup.sh` within your workdir.
4.  Source `tapasco-setup.sh` to setup the TaPaSCo-Environment.
5.  Build the TaPaSCo-Toolflow using `tapasco-build-toolflow`.
89

Lukas Weber's avatar
Lukas Weber committed
90 91 92
Whenever you want to use TaPaSCo in the future, just source the corresponding workspace using the `tapasco-setup.sh`.
This also allows you to have multiple independent TaPaSCo-Workspaces.

93 94 95 96 97 98 99 100 101 102 103 104 105
Prerequisites for the Runtime
-------------

*Ubuntu*:
```
apt-get -y build-essential linux-headers-generic python cmake libelf-dev libncurses-dev git rpm
```

*Fedora*:
```
dnf -y install kernel-devel make gcc gcc-c++ elfutils-libelf-devel cmake ncurses-devel python libatomic git rpm-build
```

Lukas Weber's avatar
Lukas Weber committed
106 107 108 109 110 111 112 113
TaPaSCo-Runtime Setup
---------------------

If you want to use a specific (pre-release) version or branch, you can do the following:

1.  Clone TaPaSCo: `git clone https://github.com/esa-tu-darmstadt/tapasco.git`
2.  _Optionally_ Checkout a corresponding branch: `git checkout <BRANCH>`
3.  Create or open a folder, which you would like to use as your TaPaSCo workspace.
114
    Within this folder, run the TaPaSCo-Initialization-Script `tapasco-init.sh` which is located in the root-folder 
Lukas Weber's avatar
Lukas Weber committed
115 116 117 118 119
    of your cloned repo. This will setup your current folder as `TAPASCO_WORK_DIR`.
    It will also create the file `tapasco-setup.sh` within your workdir.
4.  Source `tapasco-setup.sh` to setup the TaPaSCo-Environment.
5.  Build the TaPaSCo-Toolflow using `tapasco-build-libs`.

Lukas Weber's avatar
Lukas Weber committed
120
All of this is not necessary when using the prebuilt packages. In that case, the corresponding libraries and files are installed as usual for your OS.
Lukas Weber's avatar
Lukas Weber committed
121

Lukas Weber's avatar
Lukas Weber committed
122 123
Getting Started - Build a TaPaSCo design
----------------------------------------
Carsten Heinz's avatar
Carsten Heinz committed
124
1.  Import your kernels
Lukas Weber's avatar
Lukas Weber committed
125 126
    *   HDL flow: `tapasco import path/to/ZIP as <ID> -p <PLATFORM>` will import the corresponding ZIP file as a new HDL-based core. The Kernel-ID is set from <ID> and the optional flag `-p <PLATFORM>` determines for which platform the kernel will be available. If it is omitted, it will be made available for all platforms which may take a lot of time.
    *   HLS flow: `tapasco hls <KERNEL> -p <PLATFORM>` will perform hls according to the `kernel.json`. The resulting HLS-based core will be made available for the platform given by `-p <PLATFORM>`. Again, `-p` can be omitted. HLS-Kernels are generally located in `$TAPASCO_WORKDIR/kernel`. If you want to add kernels you can create either symlink or copy them into the folder. Additionally, the folder can be temporarily changed using the optional `--kernelDir path/to/kernels` flag like this: `tapasco --kernelDir path/to/kernels hls <KERNEL> -p <PLATFORM>`
Carsten Heinz's avatar
Carsten Heinz committed
127 128 129 130 131 132
2.  Create a composition: `tapasco compose [<KERNEL> x <COUNT>] @ <NUM> MHz -p <PLATFORM>`
3.  Load the bitstream: `tapasco-load-bitstream <BITSTREAM>`
4.  Implement your host software
    *   C API
    *   C++ API

Lukas Weber's avatar
Lukas Weber committed
133
You can get more information about commands with `tapasco --help` and the corresponding subpages with `tapasco --help <TOPIC>`
Carsten Heinz's avatar
Carsten Heinz committed
134

Lukas Weber's avatar
Lukas Weber committed
135 136 137 138 139 140 141 142 143 144

Getting Started - Build a Software-Interface
--------------------------------------------
1.  Design your Accelerator using HLS/HDL according to the previous section.
2.  Load your bitstream: `tapasco-load-bitstream my-design.bit --reload-driver`. To do this, you have to source `vivado` and `tapasco-setup.sh`.
3.  Write a C/C++ executable that interfaces with your design accordingly. To get a better understanding of this, you might want to refer to the collection of examples and the corresponding README which is located in `$TAPASCO_HOME/runtime/examples`
4.  Build and Compile your Software.



145 146 147 148 149 150 151 152 153 154 155 156 157
Acknowledgements
----------------
TaPaSCo is based on [ThreadPoolComposer][1], which was developed by us as part
of the [REPARA project][2], a _Framework Seven (FP7) funded project by the
European Union_.

We would also like to thank [Bluespec, Inc.][3] for making their _Bluespec
SystemVerilog (BSV)_ tools available to us and their permission to distribute
the Verilog code generated by the _Bluespec Compiler (bsc)_.

[1]: https://git.esa.informatik.tu-darmstadt.de/REPARA/threadpoolcomposer.git
[2]: http://repara-project.eu/
[3]: http://bluespec.com/
Jaco Hofmann's avatar
Jaco Hofmann committed
158

159 160 161 162 163 164 165 166 167 168 169 170
Publications
------------

A List of publications about TaPaSCo or TaPaSCo-related research can be found [here](https://github.com/esa-tu-darmstadt/tapasco/wiki/Publications).

If you want to cite TaPaSCo, please use the following information:

[Korinth2019] Korinth, Jens, Jaco Hofmann, Carsten Heinz, and Andreas Koch. 2019. **The
Tapasco Open-Source Toolflow for the Automated Composition of Task-Based
Parallel Reconfigurable Computing Systems.** In *International Symposium
on Applied Reconfigurable Computing (Arc)*.

Jaco Hofmann's avatar
Jaco Hofmann committed
171 172 173 174 175 176
Releases
----------------

We provided pre-compiled packages for many popular Linux distributions. All packages are build for the x86_64 variant.

### Ubuntu 16.04
177 178
[Kernel Driver](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_ubuntu_16_04)
[Kernel Driver Debug](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_ubuntu_16_04_debug)
179 180
[Runtime (DEB)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.deb?job=build_tapasco_ubuntu_16_04)
[Runtime Debug (DEB)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.deb?job=build_tapasco_ubuntu_16_04_debug)
Lukas Weber's avatar
Lukas Weber committed
181
[Toolflow](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/toolflow/scala/build/distributions/tapasco_2019-10_amd64.deb?job=build_scala_tapasco_ubuntu_16_04)
Jaco Hofmann's avatar
Jaco Hofmann committed
182 183

### Ubuntu 18.04
184 185
[Kernel Driver](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_ubuntu_18_04)
[Kernel Driver Debug](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_ubuntu_18_04_debug)
186 187
[Runtime (DEB)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.deb?job=build_tapasco_ubuntu_18_04)
[Runtime Debug (DEB)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.deb?job=build_tapasco_ubuntu_18_04_debug)
Lukas Weber's avatar
Lukas Weber committed
188
[Toolflow](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/toolflow/scala/build/distributions/tapasco_2019-10_amd64.deb?job=build_scala_tapasco_ubuntu_18_04)
Jaco Hofmann's avatar
Jaco Hofmann committed
189

190 191 192
### Ubuntu 18.10
[Kernel Driver](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_ubuntu_18_10)
[Kernel Driver Debug](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_ubuntu_18_10_debug)
193 194
[Runtime (DEB)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.deb?job=build_tapasco_ubuntu_18_10)
[Runtime Debug (DEB)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.deb?job=build_tapasco_ubuntu_18_10_debug)
Lukas Weber's avatar
Lukas Weber committed
195
[Toolflow](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/toolflow/scala/build/distributions/tapasco_2019-10_amd64.deb?job=build_scala_tapasco_ubuntu_18_10)
196 197 198 199

### Ubuntu 19.04
[Kernel Driver](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_ubuntu_19_04)
[Kernel Driver Debug](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_ubuntu_19_04_debug)
200 201
[Runtime (DEB)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.deb?job=build_tapasco_ubuntu_19_04)
[Runtime Debug (DEB)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.deb?job=build_tapasco_ubuntu_19_04_debug)
Lukas Weber's avatar
Lukas Weber committed
202
[Toolflow](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/toolflow/scala/build/distributions/tapasco_2019-10_amd64.deb?job=build_scala_tapasco_ubuntu_19_04)
203

204
### Fedora 27
205 206
[Kernel Driver](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_fedora_27)
[Kernel Driver Debug](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_fedora_27_debug)
207 208
[Runtime (RPM)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.rpm?job=build_tapasco_fedora_27)
[Runtime Debug (RPM)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.rpm?job=build_tapasco_fedora_27_debug)
Lukas Weber's avatar
Lukas Weber committed
209
[Toolflow](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/toolflow/scala/build/distributions/tapasco-2019-10.x86_64.rpm?job=build_scala_tapasco_fedora_27)
Jaco Hofmann's avatar
Jaco Hofmann committed
210

211
### Fedora 28
212 213
[Kernel Driver](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_fedora_28)
[Kernel Driver Debug](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_fedora_28_debug)
214 215
[Runtime (RPM)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.rpm?job=build_tapasco_fedora_28)
[Runtime Debug (RPM)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.rpm?job=build_tapasco_fedora_28_debug)
Lukas Weber's avatar
Lukas Weber committed
216
[Toolflow](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/toolflow/scala/build/distributions/tapasco-2019-10.x86_64.rpm?job=build_scala_tapasco_fedora_28)
Jaco Hofmann's avatar
Jaco Hofmann committed
217

218
### Fedora 29
219 220
[Kernel Driver](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_fedora_29)
[Kernel Driver Debug](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_fedora_29_debug)
221 222
[Runtime (RPM)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.rpm?job=build_tapasco_fedora_29)
[Runtime Debug (RPM)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.rpm?job=build_tapasco_fedora_29_debug)
Lukas Weber's avatar
Lukas Weber committed
223
[Toolflow](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/toolflow/scala/build/distributions/tapasco-2019-10.x86_64.rpm?job=build_scala_tapasco_fedora_29)
224 225 226 227

### Fedora 30
[Kernel Driver](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_fedora_30)
[Kernel Driver Debug](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_fedora_30_debug)
228 229
[Runtime (RPM)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.rpm?job=build_tapasco_fedora_30)
[Runtime Debug (RPM)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.rpm?job=build_tapasco_fedora_30_debug)
Lukas Weber's avatar
Lukas Weber committed
230
[Toolflow](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/toolflow/scala/build/distributions/tapasco-2019-10.x86_64.rpm?job=build_scala_tapasco_fedora_30)
231 232 233 234

### Fedora 31
[Kernel Driver](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_fedora_31)
[Kernel Driver Debug](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/runtime/kernel/tlkm.ko?job=build_kernel_fedora_31_debug)
235 236
[Runtime (RPM)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.rpm?job=build_tapasco_fedora_31)
[Runtime Debug (RPM)](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/build/tapasco-2019.10.0-Linux.rpm?job=build_tapasco_fedora_31_debug)
Lukas Weber's avatar
Lukas Weber committed
237
[Toolflow](https://git.esa.informatik.tu-darmstadt.de/tapasco/tapasco/-/jobs/artifacts/master/raw/toolflow/scala/build/distributions/tapasco-2019-10.x86_64.rpm?job=build_scala_tapasco_fedora_31)