erki
7925b87f09
Some checks failed
continuous-integration/drone/push Build is failing
Fixed an outdated package reference.
125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
# clang Based Atomic Operations Parser & Analyzer
|
|
|
|
The source code attached for a master's thesis work carried out in 2021.
|
|
Contained within is the source code for an **Atomic Operations Parser** and
|
|
a **Performance Analyzer**.
|
|
|
|
## Atomic Operations Parser (Operatioon Finder)
|
|
|
|
The **Atomic Operations Parser** is a C++ program which is meant to parse C-code
|
|
source files, and extract atomic operations from them. The tool uses LLVM & clang.
|
|
So precompiling the development libraries of those two is required.
|
|
|
|
### Building LLVM & clang
|
|
|
|
A docker file which automatically compiles and installs the required dependencies
|
|
is included for convenience.
|
|
|
|
Otherwise, the steps to installing clang are as follows:
|
|
|
|
Install the required dependencies via apt:
|
|
```shell
|
|
apt update -y
|
|
apt install -y git build-essential cmake ninja-build python3 python3-pip
|
|
```
|
|
|
|
Clone LLVM from the repo. Depth 1 makes the process faster. Also set up the various
|
|
folders for building and installing.
|
|
```shell
|
|
cd ~
|
|
git clone --branch "release/11.x" --depth 1 https://github.com/llvm/llvm-project.git
|
|
mkdir ~/llvm-project/build
|
|
mkdir ~/llvm-install
|
|
cd ~/llvm-project/build
|
|
```
|
|
|
|
Run cmake to configure the project. Followed by ninja to install it.
|
|
Note that when installing, you can modify `-DCMAKE_INSTALL_PREFIX` to specify
|
|
where the libraries should be installed to. In this case, we'll put them into
|
|
`~/llvm-install`.
|
|
```shell
|
|
cmake ../llvm -G "Ninja" -DCMAKE_INSTALL_PREFIX=~/llvm-install -DLLVM_ENABLE_PROJECTS="clang" -DCMAKE_BUILD_TYPE=Release
|
|
ninja install
|
|
```
|
|
|
|
### Building the Tool
|
|
|
|
Using the conan package manager is recommended. Otherwise you have to provide `Catch2_ROOT`
|
|
and `nlohmann_json_ROOT` yourself.
|
|
|
|
The variables `Clang_ROOT` and `LLVM_ROOT` depend on the previous step. If you installed the libraries
|
|
into your system, then you don't need to specify them. Otherwise, assuming an installation directory of
|
|
`~/llvm_install`, they'd look as follows:
|
|
```
|
|
-DClang_ROOT=~/llvm_install/lib/cmake/clang/
|
|
-DLLVM_ROOT=~/llvm_install/lib/cmake/llvm/
|
|
```
|
|
|
|
Now clone this repo and `cd` inside of it. Make a build directory and build the project:
|
|
|
|
```shell
|
|
mkdir build
|
|
cd build
|
|
conan install .. --build=missing
|
|
export CLANG_ROOT=~/llvm_install/lib/cmake/clang/
|
|
export LLVM_ROOT=~/llvm_install/lib/cmake/llvm/
|
|
cmake .. -DWITH_TESTS=ON -DClang_ROOT=${CLANG_ROOT} -DLLVM_ROOT=${LLVM_ROOT} -GNinja
|
|
ninja
|
|
```
|
|
|
|
You are now left with `op-finder/op-finder` and `op-finder-tests/op-finder-tests` executables.
|
|
|
|
### Usage
|
|
|
|
Use `op-finder --help` for help.
|
|
|
|
The finder will process multiple source files and output them to a single JSON file. For example:
|
|
|
|
`op-finder ./source1.c ./source2.c -o=project_opfinder.json`
|
|
|
|
The above line will take the C-code source files of `source1.c` and `source2.c`, extract atomic operations
|
|
from them, and output the JSON to the `./project_opfinder.json` file. This file can then be given to the
|
|
analyzer along with a gcov report.
|
|
|
|
## Analyzer (Operation Summarizer)
|
|
|
|
The Analyzer is responsible for taking the Atomic Operations Finder report and a gcov code coverage report
|
|
and combining them into a singular analysis of the codebase. In the present implementation, it will
|
|
summarize all unique atomic operations. This can then be combined with a database of atomic operations
|
|
and turned into a performance estimation.
|
|
|
|
The Analyzer is written in Python and requires no tooling beyond having Python 3 installed. gcov is needed
|
|
to generate the simulation reports.
|
|
|
|
### Prerequisites
|
|
|
|
Install the prerequisites from your package manager:
|
|
```shell
|
|
apt update -y
|
|
apt install gcovr python3 python3-pip
|
|
pip3 install gcovr
|
|
```
|
|
|
|
### Usage
|
|
|
|
Assuming Atomic Operations Parser was used in the previous usage example. The first step is to compile
|
|
the C program with GCC and to acquire a code coverage report from it using gcovr. This is done as follows:
|
|
```shell
|
|
gcc -fprofile-arcs -ftest-coverage -fPIC -O0 ./source1.c ./source2.c -o project.out
|
|
./project.out
|
|
gcovr -r ./ --json-pretty -o project_gcov.json
|
|
```
|
|
|
|
This will output the coverage report in human-readable JSON into the `project_gcov.json` file.
|
|
|
|
Next, the Analyzer needs to be ran:
|
|
```shell
|
|
python3 op-summarizer/opsummarizer.py --gcov project_gcov.json --finder project_opfinder.json --output project_summarized.json source1.c source2.c
|
|
```
|
|
|
|
The list of files in the specifies which source files should be taken into consideration. If a file is not present, then
|
|
that file will not be evaluated during the summarization.
|
|
|
|
The summarizer will then generate an output report in JSON, along with printing a human-readable version out
|
|
on the screen.
|