Get Started!

Prerequisites

We tested this workflow on Ubuntu 20.04, and it should basically work on other platforms. You need these packages to compile the whole framework.

We strongly recommend using the docker image we provided below to simplify the workflow.

$ sudo apt install cmake build-essential autoconf libtool zlib1g zlib1g-dev python3 python-is-python3 python3-pip
$ sudo pip install six

Set Up

These are the commands used to set up GemForge.

$ git clone --recurse-submodules [this repo]
$ cd [this repo]
# Make sure we are on the correct branch.
$ cd driver && git checkout main && cd ..
$ cd llvm && git checkout polyarch && cd ..
$ cd transform && git checkout main && cd ..
$ cd gem5 && git checkout gem-forge && cd ..
$ cd lib/affinity_alloc && git checkout main && cd ../..
# Set up some environment variables.
$ source envs.sh
# Build llvm.
$ cd llvm && bash ssp-setup.sh && cd ..
# Build everything.
$ make

In the future, you can rebuild by make $TARGET. For example, to rebuild gem5:

make gem5

Vector Add Example

In driver/gfm.sh, we provide the driver script to build and simulate a vector addition workload, with both baseline OOO core and stream floating. Just do this:

cd [this repo]
source envs.sh
cd driver
bash gfm.sh

Gap Graph Suite

In benchmarks/gapbs, we provide the Gap Graph Suite for testing. To use it, first we need to generate some synthesized graphs. You can also convert other real world graphs to the supported format. See their documentation for the details.

cd benchmarks/gapbs
CXX=clang++ make converter
LD_LIBRARY_PATH=$GEM_FORGE_TOP/lib/affinity_alloc/build:$GEM_FORGE_TOP/llvm/install-release/lib python synthesize_graph.py

This will generate synthesized graphs in benchmarks/gapbs/benchmark/graphs. Those with krn{V}-k{E}.sg format are power-law graphs with 2^V vertices and average degree E. Similarly those with uni prefix are uniform graphs. Weighted graphs have .wsg suffix. For BFS and SSSP workloads, we also specify the source vertex in .src.txt.

Now with the graph, this script will simulate gapbs on a small graph krn10-k4 and O3 cores.

cd driver
bash gapbs-o3.sh

Similarly, this script will simulate gapbs using near-stream computing.

cd driver
bash gapbs-nsc.sh

Infinity Stream

We also provide script to run the experiment for Infinity Stream.

cd driver
base ./RunningScripts/infinity-stream/gfm-pum.sh

This will simulate the stencil and Gaussian elimination using processing-use-memory (PUM). In the same folder there is another script driver/RunningScripts/infinity-stream/gfm-nsc.sh to run the same benchmarks with NSC as the baseline.

Docker

You can also try this docker file, or use this repo: Gem Forge Docker.

FROM ubuntu:20.04

ARG USER_ID
ARG GROUP_ID

RUN groupadd -g ${GROUP_ID} gf &&\
    useradd -l -u ${USER_ID} -g gf gf &&\
    usermod -aG sudo gf &&\
    install -d -m 0755 -o gf -g gf /home/gf &&\
    apt update &&\
    apt install -y \
    cmake \
    build-essential \
    autoconf \
    libtool \
    zlib1g \
    zlib1g-dev \
    python3 \
    python3-pip \
    python-is-python3 \
    scons \
    git \
    curl \
    wget \
    sudo \
    vim \
    bear \
    zsh &&\
    pip3 install six

RUN echo 'gf:gf' | chpasswd

USER gf

Save this into Dockerfile. Then build the image and start the container:

$ docker image build --network host --build-arg USER_ID=$(id -u $USER) --build-arg GROUP_ID=$(id -g $USER) -t gemforge:0.1 .
$ docker run --network host --detach -i --mount type=bind,src=[this repo],dst=[mounted path] --name gemforge gemforge:0.1
$ docker exec -it gemforge zsh

Then you can follow the commands above to build and run!