Please see LICENSE for usage terms.
Sword is a data race detector for OpenMP programs.
Sword combines several techniques to identify data races in large OpenMP applications, maintaining low runtime and zero overheads, offering soundness and completeness of the data race detection process. It builds on open-source tools infrastructure such as LLVM, and OMPT to provide portability.
To compile Sword you need a host Clang/LLVM version >= 6.0, a CMake version >= 3.4.3, GLPK version >= 4.61, and Boost Libraries version >= 1.58.
Ninja build system is preferred. For more information how to obtain Ninja visit https://github.com/ninja-build/ninja. (Note that this is different than PRUNERS NINJA tool.)
Sword has been tested with the LLVM OpenMP Runtime version 6.0 (with OMPT support).
Sword has been developed under LLVM 6.0 (for more information visit http://llvm.org).
Sword comes as an LLVM tool, it can be compiled both as a stand-alone tool or within the Clang/LLVM infrastructure.
In order to obtain and build Sword, follow the instructions below for stand-alone or full Clang/LLVM with Sword support (instructions are based on bash shell, Clang/LLVM 6.0 version, Ninja build system, and the LLVM OpenMP Runtime with OMPT support).
Create a folder in which to download and build Sword:
export SWORD_BUILD=$PWD/SwordBuild
mkdir $SWORD_BUILD && cd $SWORD_BUILD
Obtain the LLVM OpenMP Runtime with OMPT support:
git clone https://github.com/llvm-mirror/openmp.git openmp
and build it with the following command:
export OPENMP_INSTALL=$HOME/usr # or any other install path
cd openmp/runtime
mkdir build && cd build
cmake -G Ninja \
-D CMAKE_C_COMPILER=clang \
-D CMAKE_CXX_COMPILER=clang++ \
-D CMAKE_BUILD_TYPE=Release \
-D CMAKE_INSTALL_PREFIX:PATH=$OPENMP_INSTALL \
..
ninja -j8 -l8 # or any number of available cores
ninja install
Obtain Sword:
cd $SWORD_BUILD
git clone https://github.com/PRUNERS/sword.git sword
and build it with the following commands:
export SWORD_INSTALL=$HOME/usr # or any other install path
cd sword
mkdir build && cd build
cmake -G Ninja \
-D CMAKE_C_COMPILER=clang \
-D CMAKE_CXX_COMPILER=clang++ \
-D CMAKE_BUILD_TYPE=Release
-D OMP_PREFIX:PATH=$OPENMP_INSTALL \
-D CMAKE_INSTALL_PREFIX:PATH=${SWORD_INSTALL} \
# -D GLPK_ROOT= \
# -D BOOST_ROOT= \
-D COMPRESSION=LZO .. \
ninja -j8 -l8 # or any number of available cores
ninja install
cd ../..
Sword provides a command to compile your programs with Clang/LLVM OpenMP and hide all the mechanisms necessary to detect data races.
The Sword compile command is called clang-sword, and this can be used as a drop-in replacement of your compiler command (e.g., clang, gcc, etc.).
The following are some of the examples of how one can integrate clang-sword into her build system.
clang-sword example.c -o example
In your Makefile, set the following variables:
CC=clang-sword
The command clang-sword works as a compiler wrapper, all the options available for clang are also available for clang-sword.
Runtime flags are passed via SWORD_OPTIONS environment variable, different flags are separated by spaces, e.g.:
SWORD_OPTIONS="traces_path=/path/to/traces/data" ./myprogram
| Flag Name | Default value | Description |
|---|---|---|
| traces_path | not set | Specify the path where to save the data gathered by Sword at runtime. |
Let us take the program below and follow the steps to compile and check the program for data races.
Suppose our program is called myprogram.c:
1 #include <stdio.h>
2
3 #define N 1000
4
5 int main (int argc, char **argv)
6 {
7 int a[N];
8
9 #pragma omp parallel for
10 for (int i = 0; i < N - 1; i++) {
11 a[i] = a[i + 1];
12 }
13 }
We compile the program as follow:
clang-sword myprogram.c -o myprogram
Now we can run the program with the following commands:
export OMP_NUM_THREADS=2
./myprogram
Sword will run the dynamic analysis and gather the data in the default folder sworddata in the current path. At the end of the execution Sword will print out the commands we have to execute to run the offline analysis, for this example it will print the following information:
################################################################
SWORD data gathering terminated.
To analyze the data and detect races, please execute:
sword-offline-analysis --analysis-tool /path/to/sword-race-analysis --executable /path/to/your/executable --traces-path /path/to/sword_data --report-path /path/to/sword_report
To print the results of theanalysis, please execute:
sword-print-report --executable /path/to/your/executable --report-path /path/to/sword_report
################################################################
Now we can execute the offline analysis with the tool:
sword-offline-analysis --analysis-tool sword-race-analysis --executable myprogram --traces-path sword_data --report-path sword_report
Then, print the result of the analysis with:
sword-print-report --executable myprogram --report-path sword_report
For our example, the result will be the following:
--------------------------------------------------
WARNING: SWORD: data race (program=myprogram)
Two different threads made the following accesses:
Write of size 4 in .omp_outlined._debug__ at /home/satzeni/work/compilers/sword/sword/build/myprogram.c:11:10
Read of size 4 in .omp_outlined._debug__ at /home/satzeni/work/compilers/sword/sword/build/myprogram.c:11:12
--------------------------------------------------
-
- For an invitation please write an email to Simone Atzeni with a reason why you want to be part of the PRUNERS Slack Team.
-
E-Mail Contacts:
