hassansalehe / embedsanitizer

EmbedSantizer is a runtime race detection tool which extends ThreadSanitizer to detect data races in 32-bit ARM applications.

EmbedSanitizer: A Runtime Race Detection Tool for 32-bit Embedded ARM

This tool extends ThreadSanitizer to do race detection for 32-bit ARM applications. Due to the complexity of the ThreadSanitizer's race detection runtime, EmbedSanitizer implements its own runtime by applying FastTrack (see: link) which is an efficient and precise race detection algorithm relying on happens-before concepts.

Please consult relevant tool paper for further information here.

Usage Summary

EmbedSanitizer can be installed as part of LLVM/Clang infrastructure in a development machine; presumably an x86_64 platform. Then it can be launched in similar manner to ThreadSanitizer; using a compiler flag -fsanitize=thread. Once the compiler produces your program's final executable with EmbedSanitizer instrumentation, you can run on a target ARM 32-bit platform.

# Use the installed EmbedSanitizer in your development machine as part of Clang compiler
# to build your 32-bit ARM applications.
>$ ./clang++ my_program.cpp -o my_program.exe -fsanitize=thread -static <other_compiler_flags>

>$ file my_program.exe # this shows the type of the produced binary.
my_program.exe: ELF 32-bit LSB executable, ARM, EABI5 version 1 (GNU/Linux), statically linked, for GNU/Linux 3.2.0

Then take your executable to a target platform and run it there.

>$  ./my_program.exe # running on a target hardware

Then races will be reported, if any, when the program runs. Alternatively, you can use QEMU emulator in your development machine to run your program but it may be very slow.

>$ qemu-arm ./my _program.exe

Building and Installation

(a) Prerequisites

This tool has been tested on x86_64 machine with Ubuntu 16.04. Moreover, make sure that the following are installed in your platform.

• LLVM/Clang, more information on how to install: http://llvm.org/docs/GettingStarted.html
• The cross-compilers utilities. Use the commands below to install them:

>$ apt-get install -y gcc-multilib g++-multilib
>$ apt-get install -y libc6-armel-cross libc6-dev-armel-cross binutils-arm-linux-gnueabi
>$ apt-get install -y libncurses5-dev gcc-arm-linux-gnueabi g++-arm-linux-gnueabi

(b) Installation

To build and install, there is Bash script install.sh at the main directory of the project.

>$  ./install.sh

Running

(a) Compiling your program

The install.sh script builds LLVM/Clang with EmbedSanitizer in it and installs it in arm directory. Then you can compile your program from the main directory of the project using the command format below:

>$  ./arm/bin/clang++ -o <executable_name> <your_program_name.cpp> -fsanitize=thread

The compiler produces an ARM-compatible executable.

Note:

Sometimes your program may not compile due to 'missing' library headers like iostream, cstdlib and bits/config.h. Therefore, you need to add appropriate include paths as in the example below.

>$  ./arm/bin/clang++ -o <executable_name> <your_program_name.cpp> -fsanitize=thread -I$(shell find /usr/arm-linux-gnueabi -name iostream | sed 's/\/iostream//g') -I$(shell find /usr/arm-linux-gnueabi/include -type d -name arm-linux-gnueabi) -I/usr/arm-linux-gnueabi/include

(b) Running your program

Once your program is instrumented and compiled by LLVM/Clang, you can run it in a 32-bit ARM platform. Alternatively, you can launch your program with the Qemu emulator:

>$ qemu-arm <executable_name>

Experimental Results from the Benchmarks

please refer to tests/parsec_benchmarks/README.md for more information on how to run the benchmarks and get results.

License

Our license derives from that of LLVM/Clang project as we use its source codes. For more information, please read the file LICENSE.md.
Moreover, the benchmarks that we used for evaluation in tests/parsec_benchmarks have their own license from the PARSEC Benchmark suite.

Contact

For any inquiries, suggestions or collaborations please contact hassansalehe<at>gmail.com

embedsanitizer's Issues

Create README

The readme file should discuss:

1. Prerequisites
2. How to build and install
3. How to run

Alternative access of the tool

An Ubuntu OS virtualization instance with the tool installed can be
downloaded through the link: https://www.dropbox.com/s/i38qm3i0oto6wuo/etsanOS.ova?dl=1

Create Wiki of the tool

The wiki page should

1. Introduce the tool.
2. Introduce the methods used
3. Explain how to compile
4. Explain how to run a sample program
5. Explain how to run the tests and get results

Handle the atomic and unaligned operations

In particular, EmbedSanitizer should implement the following:
* __tsan_atomic8_load
* __tsan_unaligned_read8
* __tsan_unaligned_write8

Create unit tests for raceReport.h

This code needs a number of improvements. As a first step, create unit tests to cover the existing functionality. This will help to guard the current behavior during refactoring.