Open Data for Bankers example

LICENSE
This content has been generated via the EU H2020 RIA project COEMS - Continuous Observation of Embedded Multicore Systems
https://www.coems.eu

This work is licensed under a Creative Commons Attribution 4.0 International License, see https://creativecommons.org/licenses/by/4.0/.

The COEMS project is funded through the European Horizon 2020 program under grant agreement no. 732016.

OVERVIEW
This folder contains Open Data for the "bank_lock" case of study for the HAVELUND 65 paper.
The data is generated in the context of the COEMS EU H2020 project, which provides a novel platform for online monitoring of multicore systems.
For the case of study, we collect these data: the source code, the compiled instrumented binary file, the execution traces, the result of analyzing those execution traces using Tessla specifications [1], and the Tessla specifications.
The experiment consists of a 'default' version, that shows the ideal implementation and execution of a multicore code with no errors; and a 'race' version which include a potential data race error.
The evaluation of Tessla specifications over the execution traces should point out potential problems in the code.
The content of this folder is organised in several subfolders depending on the selected configuration (i.e., 'default' or 'race').
In particular, the folder hierarchy is:
Root:
|_> case_study_name:
    |_> src/
    |_> bin/
    |_> spec/
    |_> traces/
        |_> default
        |_> race
    |_> result/
        |_> default
        |_> race

The src/ folder contains a flattened version of the original C code, which is shrunk into a single file in the case of several source files.
The bin/ folder contains the compilation and instrumentation of the C file into an ARM binary executable. 
The spec/ folder contains the Tessla specifications.
The traces/ folder contains the result of processing the hw.tessla specification by the COEMS box.
The result/ folder contains the result of evaluating the sw.tessla specification on the COEMS box output traces with the Tessla interpreter.
The intermediate traces and Tessla reports are classified in several subfolders depending on the target configuration (i.e., 'default' or 'race').

[1] https://www.tessla.io/

SPECIFIC CONFIGURATION

This README file and the rest of the data in this folder have been automatically created.
The first part of the experiments (hw.tessla) are executed on the COEMS specific hardware in order to efficiently run the online monitoring and filtering.
The output of the COEMS box is saved into the traces/ folder.
In order to complete the analysis for race checking, a Personal Computer must run the second part of the Tessla specification (sw.tessla) over the output of the COEMS box.
Data race reports are precomputed in the result/ folder.

COMMAND LINE

Generated traces
-------------------------
The execution of the ARM binary will automatically emit the traces to the COEMS box, which will filter the first part of the events using the hw.tessla specification.
The COEMS box then emits preprocessed traces that can be analyzed by the Tessla interpreter using the sw.tessla specification.

COEMS box output traces (i.e., for the hw.tessla spec):
banker_lock/traces/default/coems_output_trace.log
banker_lock/traces/race/coems_output_trace.log

Tessla interpreter data race report (i.e., for the sw.tessla spec):
banker_lock/result/default/data_race_report.txt
banker_lock/result/race/data_race_report.txt

Analyze the traces using Tessla specs
-------------------------------------
The following software is required in order to analyze the traces obtained in the previous step:
1) The TeSSLa interpreter (tessla.jar), which will run the sw.tessla stage.

We use the next alias:

alias tessla="java -jar tessla.jar"

TeSSLa report for the HW trace
````
$ tessla banker_lock/spec/sw.tessla banker_lock/traces/default/coems_output_trace.log > banker_lock/result/default/data_race_report.txt
$ tessla banker_lock/spec/sw.tessla banker_lock/traces/race/coems_output_trace.log > banker_lock/result/race/data_race_report.txt
````

In the 'default' scenario, the TeSSLa interpreter should report potential issues in the default/data_race_report.txt.
Because of the eraser algorithm, it shows false positives (i.e., data races that happen after pthread_join).
E.g.,
105993503535: error_0_in_line = 96

In the 'race' scenario, the TeSSLa interpreter should report potential issues in the race/data_race_report.txt.
E.g.:
105847960743: error_0_in_line = 52.