Repository files navigation

Welcome to the StreamBlocks Platforms repository. This repository contains thecode generators for the StreamBlocks dataflow compiler. If you are usingStreamBlocks for the first time, this is the readme you need to follow to get asense of the overall workflow and the different tools used within StreamBlocks.

StreamBlocks compiler provides a unified compilation framework for CPU-FPGAplatforms. The figure below shows the compiler flow in full.

StreamBlock transpiles dataflow programs written in CAL to C++ formulticore + FPGA platforms. Tycho is the frontend that takes CAL and producesand internal representation called the Actor Machine IR. Tycho's code is foundin thestreamblocks-tychorepositry.

The two hardware and software backends generate heterogeneous C++ code forexecution. The code generators along with the runtime are part of thestreamblocks-platformrepository (i.e., this one!).

The partitioning tool is yet another repository, not surprisingly calledstreamblocks-partitioning.

The first two repositories are essential for code generation and execution. Thelast one is for design space exploration.streamblocks-partitioninguses profiling information obtained from either simulation or real executionto suggest pseudo-optimal hardware-software partitions.

This readme only walk you through setting up the first two repositories. Atutorial on setting up the partitioning is found in the correspondingstreamblocks-partitioningrepository. There is a 4thstreamblocks-examplesrepository with a good number CAL programs.

The rest of this guide is organized as follows:

1. The compiler basics
2. Basic setup and dependencies
3. Compiling a simple example

The StreamBlocks dataflow compiler offers code-generation for multicore genericplatforms and FPGAs through High-level synthesis. This repository contains thebackends of the StreamBlocks-tycho dataflow frontend compiler.

To use the StreamBlocks platforms first you need to compile and installStreamBlocks-Tycho compilerstreamblocks-tycho.We will go through installation in the next step.

The Tycho frontend does not get too far, it can generate some basic C code thatis then compiled down to single-thread binaries for software execution but wenever use that. Rather, we use Tycho's internal representation of an Actornetwork to generateheterogeneous C++ code.

This is where the current repository comes into play. Since we are targetingheterogeneous execution, we need to generate code for both software and hardwareexecution. We do this throughplatforms or basically different code generatorsor backends.You can find a brief description of each platform below:

We basically just need to understand whatplatform-vivadohls andplatform-multicore do. Each take a (part of) dataflow program and generate HLSor software C++ respectively. They could whileplatform-multicore can be usedcompletely independently butplatform-vivadohls is not standalone. This isbecause any HLS code needs some software code that feeds it data and interceptsits output.

• StreamBlocks platforms are written with Java 8, you will need a compatible Java SE Development Kit 8 (or later), Apache Maven and Git.

• The generated C multithreaded source code of StreamBlocks has the following dependencies: CMake, libxml2 and (optionaly) libsdl2.

• The generated C++ for Vivado HLS source code of StreamBlocks, needs theXilinx Vivado Design Suite. You also need xilinx run time orXRTinstalled with the FPGA platforms you want to use.

Once you have all the dependencies set up. Create a directory calledstreamblocks somewhere in your system and go to that directory.

> mkdir streamblocks>cd streamblocks

Clonestreamblocks-tychoand install it using maven (this will install some jar files somewhere in yourhome directory which is picked up bystreamblocks-platforms).

> git clone https://github.com/streamblocks/streamblocks-tycho>cd streamblocks-tycho&&  mvn install -DskipTests&&cd ..

Maven should succeed, then clonethis repository and install it using maven.

> git clone https://github.com/streamblocks/streamblocks-platforms>cd streamblocks-platforms&&  mvn install

In thestreamblocks-platforms directory runningstreamblocks --help shouldwelcome you with some basic command line options. We will first go through thesoftware execution flow and then we will give you a tour of how you can compilecode for heterogeneous platforms (slightly more complicated). This guide doesnot cover our partitioning methodology though, for that refer to thestreamblocks-partitioningrepository.

To actually execute something, let's write a simple CAL program:

>echo'namespace hetero.simple:  actor Source(int payload_size) ==> int Out:    int counter := 0;    transmit: action ==> Out:[t]    guard counter < payload_size    var t = counter    do      println("Tx: " + t);      counter := counter + 1;    end  end  actor Sink() int In ==>:    action In:[t] ==>    do        println("Rx: " + t);    end  end  actor Pass() int In ==> int Out:    action In:[t] ==> Out:[t]    end  end  network PassThrough() ==> :  entities    source = Source(payload_size = 20);    pass  = Pass() { partition = "hw"; };    sink = Sink();  structure    source.Out --> pass.In { bufferSize = 1; };    pass.Out --> sink.In { bufferSize = 1; } ;  endend'> simple.cal

You can compile this program program using:

> ./streamblocks multicore --source-path simple.cal --target-path myproject hetero.simple.PassThrough

Note that we have to specify the source files, an output directory, and the nameof the top network (which does not have any inputs or outputs) to the compiler.Oncestreamblocks finishes successfully, you see a new directorymyproject with thefollowing structure:

myproject├── bin│   ├── configuration.xcf│   ├── PassThrough.py│   ├── PassThrough.script│   └── streamblocks.py├── build├── CMakeLists.txt├── code-gen│   ├── auxiliary│   ├── CMakeLists.txt│   ├── include│   └── src└── lib    ├── art-genomic    ├── art-native    ├── art-node    ├── art-runtime    ├── cmake    └── CMakeLists.txt

Thebin does not contain the final executable at this point. The python filesare not currently used but generated nonetheless and you should just ignorethem. To get an executable, you should compile the generated C++ files down tobinary, this is done quite simply:

> mkdir -p myproject/build> cd myproject/build> cmake ..> cmake --build .

This will create an executablebin/PassThrough:

> cd ../bin> ./PassThroughTx: 0Tx: 1Rx: 0Tx: 2Rx: 1Tx: 3Rx: 2Tx: 4Rx: 3Tx: 5Rx: 4Tx: 6Rx: 5Tx: 7...

Note that here we used a single thread to execute the three actors in software.Using multiple threads is quite simple, you need a configuration file to specifythe actor to thread mapping. ThePassThrough executable can generate this file,and you can then simply modify it:

> ./PassThrough --generate=threads.xml

Or you can write it yourself (e.g., use one thread per actor):

<?xml version="1.0" encoding="UTF-8"?><configuration><partitioning><partitionid="0"scheduling="ROUND_ROBIN"><instanceid="source"/>        </partition>        <partitionid="1"scheduling="ROUND_ROBIN"><instanceid="pass"/>        </partition>        <partitionid="2"scheduling="ROUND_ROBIN"><instanceid="sink"/></partition></partitioning></configuration>

And use for multi-thread execution:

> ./PassThrough --cfile=threads.xml

For heterogeneous code we have to call the compiler twice with an extra--set partitioning=on argument:

> ./streamblocks multicore --source-path simple.cal --target-path myproject --set partitioning=on hetero.simple.PassThrough> ./streamblocks vivado-hls --source-path simple.cal --target-path myproject --set partitioning=on hetero.simple.PassThrough

Note that the two commands above merely generate C++ code for hardware andsoftware. Like the software-only flow, we have to further build the FPGA andhost binaries usingcmake.

Here is an example of generated directories:

myproject├── CMakeLists.txt├── multicore│   ├── bin│   ├── build│   ├── CMakeLists.txt│   ├── code-gen│   │   ├── auxiliary│   │   ├── CMakeLists.txt│   │   ├── include│   │   └── src│   └── lib│       ├── art-genomic│       ├── art-native│       ├── art-node│       ├── art-plink│       ├── art-runtime│       ├── cmake│       └── CMakeLists.txt└── vivado-hls    ├── bin    │   ├── xclbin    │   └── xrt.ini    ├── build    ├── cmake    │   ├── FindSDAccel.cmake    │   ├── FindVitis.cmake    │   ├── FindVitisHLS.cmake    │   ├── FindVivado.cmake    │   ├── FindVivadoHLS.cmake    │   ├── FindXRT.cmake    │   └── Helper.cmake    ├── CMakeLists.txt    ├── code-gen    │   ├── auxiliary    │   ├── host    │   ├── include    │   ├── include-tb    │   ├── rtl    │   ├── rtl-tb    │   ├── src    │   ├── src-tb    │   ├── tcl    │   ├── wcfg    │   └── xdc    ├── output    │   ├── fifo-traces    │   └── kernel    ├── scripts    └── systemc        ├── include        └── src

In these rather large directory of files, what matters is the top-levelCMakeLists.txt files which can be used to build a heterogeneous executable.

To build hardware targets, you need to have a working Vitis and Vivaod HLSinstallation. Ideally use the 2019.2 versions (newer versions may work but havenot been really tested). Vitits is installed in${VITIS_DIR} you can make itavailable in the${PATH} by:

source ${VITIS_DIR}/settings64.sh

You also need to have${XILINX_XRT} set to whereXRT. Assuming youhaveXRT installed in/opt/xilinx/xrt:

export XILINX_XRT=/opt/xilinx/xrt

With these environment variables set, you can proceed to building an FPGA binary

> mkdir -p myproject/build>cd myproject/build> cmake .. -DHLS_CLOCK_PERIOD=3.3 -DFPGA_NAME=xcu200-fsgd2104-2-e -DPLATFORM=xilinx_u200_xdma_201830_2 -DUSE_VITIS=on -DCMAKE_BUILD_TYPE=Debug> cmake --build. --target PassThrough_kernel_xclbin -- -j 4

This can take several hours. To get a simulation binary instead you can use-DTARGET=hw_emu to use the hardware emulation mode in which the hardwareexecution is simulated in software (see hardware emulation mode in Vitis). Thisresults in a faster compilation time but orders of magnitude slower executiontime.

Likewise, you can build the software binary by

> cmake --build . --target PassThrough -- -j 4

Once both targets are ready, you can execute the program:

> cd ../bin> ./PassThrough

Note that there is nocmake dependency between the software and hardwarebinary. Therefore, if you don't build the hardware binary you will end up with aruntime error regarding a missing file. The hardware binary is be placedinbin/xclbin/ and is supposed to be present when you call./PassThrough.

This rather tedious flow can easily be scripted. We plan to streamlinecompilation in the future by integrating all the steps in one place. But for nowconsider writing your own scripts. You can checkout thestreamblocks-examplerepository to ge inspired by how you can usecmake to fully automate theprocess.