Analysis Examples
=================
The ``samples`` directory of ScEpTIC repository contains various working examples for running an analysis with ScEpTIC.

Continuous Execution
####################
In the ``samples/continuous/`` directory there is an example containing the configuration and source code for executing a program sequentially.

This example sequentially executes the following program::

    int a __attribute__((section(".NVM"))) = 5;

    int main() {
        for(int i = 0; i < 10; i++) {
            a++;
            printf("%d -> %d\n", i, a);
            checkpoint();
        }
        return a;
    }

We can execute the example with the command ``python3 run.py``.
During its execution, we can see the output of the ``printf()`` functions, which is normally not available on embedded devices.

Once ScEpTIC terminates the sequential execution, it creates a ``analysis_results`` directory that contains the results of our analysis.
Here we can see two sub-directories:

- ``code``: contains a txt file for each function. Each file contains the modified LLVM IR of a function of the program, which ScEpTIC uses for emulating the program execution
- ``states``: contains a txt file that contains a textual representation of the states of register file, memory, input, and outputs at the end of the simulation execution

Custom Intermittent Execution
#############################
In the ``samples/profiling/`` directory there is an example containing the configuration and source code for simulating and debugging a specific intermittent execution of the program.

This example simulates an intermittent execution of the following program::

    int i __attribute__((section(".NVM")));
    int res[100] __attribute__((section(".NVM")));

    void main() {
        i = 0;
        checkpoint();
        for(; i < 100; i++) {
            sceptic_log("i", i);
            sceptic_reset("conditional", i == 3);
            res[i] = i;
            sceptic_log("res_i", res[i]);
            sceptic_reset("conditional", i == 2);
            sceptic_reset("clock", 2);
        }
    }


We can execute the example with the command ``python3 run.py``.
During the program execution, ScEpTIC simulates a sequence of power failures, as we describe in :ref:`profiling-label`.

Once ScEpTIC terminates the sequential execution, it creates a ``analysis_results`` directory that contains the results of our analysis.
Here we can see two sub-directories:

- ``code``: contains a txt file for each function. Each file contains the modified LLVM IR of a function of the program, which ScEpTIC uses for emulating the program execution
- ``states``: contains a txt file that contains a textual representation of the states of register file, memory, input, and outputs at the end of the simulation execution

There is also a ``profiling.txt`` file that contains the program execution trace, which includes the output of ``sceptic_log()`` function calls and a signal for the execution of ``sceptic_resets()``.

Memory Anomalies
################
In the ``samples/memory/`` directory there is an example containing the configuration and source code for both locating intermittence anomalies and evaluating their effects.

This example analyzes the following program::

    int a __attribute__((section(".NVM"))) = 5;


    int main() {
        for(int i = 0; i < 10; i++) {
            a++;
            checkpoint();
        }
        return a;
    }

We can execute the example with the command ``python3 run.py``.
ScEpTIC executes two different analysis and saves their results inside the ``analysis_results`` directory.

Here we can see two sub-directories:

- ``code``: contains a txt file for each function. Each file contains the modified LLVM IR of a function of the program, which ScEpTIC uses for emulating the program execution
- ``states``: contains a txt file that contains a textual representation of the states of register file, memory, input, and outputs at the end of the simulation execution

There are also two files:

- ``memory_evaluate_anomalies.txt`` contains the textual representation of the anomalies that ScEpTIC identified while running its analysis for evaluating the effects of intermittence anomalies
- ``memory_locate_anomalies.txt`` contains the textual representation of the anomalies that ScEpTIC identified while running its analysis for locating the presence of intermittence anomalies

Input Accesses
##############
In the ``samples/input/`` directory there is an example containing the configuration and source code for analyzing input accesses. 

This example analyzes the following program::

    int i;
    int val;
    int sum = 0;
    int critical = 10000;

    int main() {
            for(i = 0; i < 50; i++) {
                    val = input();
                    checkpoint();
                    sum = sum + val;

                    if(sum > critical) {
                            out('Error: critical value exceeded!');
                    }
            }

            out(sum);
    }


We can execute the example with the command ``python3 run.py``.
ScEpTIC executes the analysis and saves its result inside the ``analysis_results`` directory.

Here we can see two sub-directories:

- ``code``: contains a txt file for each function. Each file contains the modified LLVM IR of a function of the program, which ScEpTIC uses for emulating the program execution
- ``states``: contains a txt file that contains a textual representation of the states of register file, memory, input, and outputs at the end of the simulation execution

There is also a ``input_anomalies.txt`` file that contains the input access anomalies that ScEpTIC found while executing the analysis.

Output Accesses
###############
In the ``samples/output/`` directory there is an example containing the configuration and source code for analyzing output accesses. 

This example analyzes the following program::

    int i;
    int val;
    int sum = 0;

    int main() {
            for(i = 0; i < 50; i++) {
                    val = input();
                    checkpoint();
                    sum = sum + val;
                    out1(1);
                    out2(sum);
            }
    }

We can execute the example with the command ``python3 run.py``.
ScEpTIC executes the analysis and saves its result inside the ``analysis_results`` directory.

Here we can see two sub-directories:

- ``code``: contains a txt file for each function. Each file contains the modified LLVM IR of a function of the program, which ScEpTIC uses for emulating the program execution
- ``states``: contains a txt file that contains a textual representation of the states of register file, memory, input, and outputs at the end of the simulation execution

There are also two files:

- ``output_anomalies.txt`` contains the output access anomalies that ScEpTIC found during the analysis execution
- ``output_profiling.txt`` contains the execution trace of the program, where we can analyze the occurrence of output-related events. This allows us to identify the reason of unexpected output access idempotency models

Multithreads
############
The analysis for evaluating the effects of intermittence anomalies may take several hours.
Hence, to monitor ScEpTIC analysis execution we made an overwatch thread that enables us to access ScEpTIC internal state, so to verify the analysis advancement.
``samples/multithread/`` contains such code.
To use it, you just need to copy the two python files inside the directory that contains your ScEpTIC configuration and your source program.
Then, simply run ``python3 run_thread.py`` to start the analysis.

During the analysis execution, you can run the following commands:

- ``p`` prints the current program counter, which corresponds to the instruction that ScEpTIC is currently executing
- ``i`` prints the current analysis result (note: it may be incomplete)
- ``c`` prints the current clock id
- ``s`` prints the current environment state (i.e. register file, memory, input, and output)
- ``t`` prints the elapsed time
- ``stop`` stops the current analysis