Examples

Examples

Now that you have FlipIt installed, let's walk though several examples to better understand FlipIt.

• Test Pass
• Sequential
  • Matmul
  • Countdown
• MPI
  • Jacobi

Test Pass

This simplistic example shows the minimum code that needs to be added to enable corruptions via FlipIt.

#include <stdio.h>
#include "/home/aperson40/Documents/FlipIt//src/corrupt/corrupt.h"
int main(int argc, char** argv)
{
	int a = 2, b=2;
	int rank = 0;
	int seed = 7;
	FLIPIT_Init(rank, argc, argv, seed);
 	printf("Should be corrupted: %d + %d = %d\n", a, b, work(a, b));
	FLIPIT_Finalize(NULL);
	return 0;
}

Walking though the code we see the inclusion of a header file corrupt.h. This header file defines all API functions in FlipIt. Inside the function main we see calls to FLIPIT_Init and FLIPIT_Finalize. Calls to these functions should bound all execution of code instrumented by FlipIt's compiler pass. Should this not be the case segfaults can occur!

FLIPIT_Init's first argument is the rank of the current process (uses MPI terminology). For all sequential applications this argument can be set as 0. The last argument is a seed number that seed FlipIt's internal random number generator. This value should differ between runs to generate differing sequence of random numbers.

FLIPIT_Finalize's lone argument is the name of the file that it should write the histogram of fault site traversal to.

The function work is corrupted during the compilation process. It is corrupted using the following terminal commands to replace a normal compilation step cc -c work.c -o final.o

clang  -g -emit-llvm work.c  -c -o work.bc 
llvm-link $FLIPIT_PATH/src/corrupt/corrupt.bc work.bc  -o crpt_work.bc
opt -load $LLVM_BUILD_PATH/Release+Asserts/lib/FlipIt.so -FlipIt -singleInj 1 -prob 0.95 -byte -1 -arith 1 -ctrl 0 -ptr 0 -funcList "" < crpt_work.bc > final.bc
clang  -g -c final.bc -o final.o

Command 1 compiles the C code to LLVM bitcode. Command 2 links the resulting bitcode to a bitcode header file declaring FlipIt's corruption functions. Command 3 runs the fault injection compiler pass over the bitcode. In this case we want a single injection (-singleInj 1), a fault probability of (-prob 0.95), the injection can be in any byte of the data type (-byte -1), we want only injections into arithmetic and not control or pointer type instructions (-arith 1 -ctrl 0 -ptr 0), corrupt all functions defined in this file (-funcList ""), bitcode file to transform, and finally the output file name. Command 4 compiled the instrumented bitcode into the object code we need for linking with other files.

In this case, the log file that is generated is displayed on the terminal prompt as command 3 is run. In practice this is written to a file on disk.

Finally, we must link to the corruption library -L$FLIPIT_PAHT/lib -lcorrupt when creating the executable.

Sequential

Matmul

This examples highlights FlipIt's compiler wrapper flipit-cc to make easy makefile modifications. The code structure modifications for this example are silimar to that of [Test Pass] (), but introduced a new API routine FLIPIT_SetInjector which turns on (FLIPIT_ON) and off(FLIPIT_OFF) FlipIt's ability to inject faults. We use this feature to calculate the correct result of the matrix matrix multiply for a verification phase at the end. Note with the selected seed this should only corrupt 1 entry when run.

Inside the Makefile shown below we see that we build this program in two different ways. The first was is the verbose way outlined in [Test Pass] (), and the second way uses the flipit-cc compiler script.

CC=gcc
CFLAGS = -g

FILIB= -L$(FLIPIT_PATH)/lib -lcorrupt
FIPASS= $(LLVM_BUILD_PATH)/Release+Asserts/lib/FlipIt.so
LFLAGS = $(FILIB)

long: matmul.o main.o
	$(CC) -o long matmul.o main.o $(LFLAGS)

matmul.o: matmul.c
	clang $(CFLAGS) -emit-llvm matmul.c  -c -o matmul.bc 
	llvm-link $(FLIPIT_PATH)/src/corrupt/corrupt.bc matmul.bc  -o crpt_matmul.bc
	opt -load $(FIPASS) -FlipIt -config FlipIt.config -singleInj 1 -prob 1e-8 -byte -1 -arith 1 -ctrl 1 -ptr 1 -funcList "" < crpt_matmul.bc > final.bc 2> matmul.LLVM.txt
	clang  -c final.bc -o matmul.o

main.o: main.c
	$(CC) $(CFLAGS) -o main.o -c main.c

###############################################################

short: _matmul.o _main.o
	$(CC) -o short _matmul.o _main.o $(LFLAGS)

_matmul.o: matmul.c
	$(FLIPIT_PATH)/scripts/flipit-cc $(CFLAGS) -o _matmul.o -c matmul.c

_main.o: main.c
	$(FLIPIT_PATH)/scripts/flipit-cc $(CFLAGS) -o _main.o -c main.c

Running both executables long and short produce the same results, but the amount of modification to the Makefile is much reduced by using flipit-cc. In fact, flipit-cc can be used to compile every file in the program as it uses two configuration files to determine what functions to inject into.

The configuration file matmul.config is used by the compiler pass itself to set instruction probabilities and function weights. In this configuration file the # character denotes a comment and that line will be ignored. Lines such as FLIPIT_Init=0 denote that these functions will not be instrumented for injection. By default all FlipIt routines and function main will not be instrumented.

The configuration file config.py is used by flipit-cc and sets all the compiler pass parameters and key variables required for successful compilation. These key variables include

• SHOW - series of libraries and paths that your particular compiler wraps, e.g. mpicc is a wrapper that includes several libraries including MPI (mpicc -show or mpicc -showme reveals the full command)
• notInject - is a python list of file names that contain no functions to instrument. This speeds up compilation by outright rejecting the file for instrumentation instead of testing every function contained inside.
• cc - the compiler that you would normally use to compile the program
• verbose - toggles the display of each of the 5 commands required to generate the object file (useful for debugging)

When matmul.c is compiled by either method, matmul.c.LLVM.txt is generated. This is a log file that is used by the analysis software to generate and visualize statistics based on fault injection runs. For more information about this see the Analysis wiki page.

Countdown

MPI

Jacobi