Running FITIn
FITIn is controlled by a Lua script. It is a callback-driven script that also allows the user to maintain states between callbacks. Specify your Lua script path by adding the --control-script= as command line argument . For a complete documentation of all callbacks, please consult the example script.
In general, you can consider the script workflow as follows:
| before_start | Executed after the initialization of FITIn, you can use this callback e.g. to initialize your states. |
| treat_superblock | Your program is segmented into superblocks. Think of different subroutines or library calls. Use this callback to decide on which specific superblocks you want FITIn to monitor. Less superblocks result in faster execution performance. |
| next_block | You can use this callback to eventually stop FITIn from working (return 1) or even to terminate the process (return 2). You can skip this callback if you don't need it. |
| monitor_address | Every time FITIn encounters a load operation from memory inside of one of your monitored superblocks, this callbacks asks you whether it is an interesting address. If yes, FITIn will call flip_value every time before the value of this address is read. If you use annotations in your source code, check the second argument of this function for being an annotated address. |
| flip_value | On each read to a monitored address, FITIn calls this method. You have to return an array of integers, representing the bit pattern of bits to flip. {0} means do nothing. From inside of this method, call persist_flip to copy the flips back to the originating memory. |
| after_end | Executed at the very end, while shutting down FITIn. Use this callback to do clean up work. |
Please note that some functions are limited unless the compiler adds debug information to the binary. Compile the elevator example as shown:
gcc -g -O0 -Iinclude/valgrind main.c -o elevator
Let us create a minimal Lua control script elevator.lua that is performing a golden run. A golden run does not touch any of the bits:
In treat_superblock, we decide to only look at superblocks belonging to main. As we just want to use our annotations, monitor_address only tests for annotated. In flip_value, we currently do nothing by simply returning {0}. Replacing zero by any other number makes the value flip at the according bits.
Now, we are ready to run:
bin/valgrind --tool=fitin --control-script=elevator.lua ./elevator