falktx/stoat

STatic (LLVM) Object file Analysis Tool

Stoat - Realtime Function Static Analysis

Stoat is a tool to assert properties about the callgraph of programs/libraries. The primary usage of this tool is to analyze programs which need to perform hard realtime operations in a portion of a mixed codebase. This is done by identifying all functions which can transitively be called from some known root function which must be realtime. If any unsafe function which could block for an arbitrary amount of time is found in this transitive closure, then an error is emitted to indicate where the improper behavior can be found and what backtrace is responsible for it getting called.

Why?

Maintaining a large codebase in C/C++ can make it very difficult to know what code ends up calling what other routines. This is further complicated when there is some segregation within one codebase which may not be at all clear in implementation. This is further complicated by the opaqueness of some C++ techniques, such as virtual overloading, operator overloading, multiple inheritance, and implicit conversions.

Requires

• LLVM 3.3+

• Clang 3.3+

• c++filt

• ruby

• graphviz gem (OPTIONAL) for callgraph renderings

• colorize gem (OPTIONAL) for colored output

How To Build

git clone https://github.com/fundamental/stoat && cd stoat
mkdir build && cd build
cmake .. && make && make test
make install #or just run in place

Features

• Inline safety markers __attribute__((annotate("realtime")))

• Inline hazard markers __attribute__((annotate("non-realtime")))

• Out-of-line whitelists/blacklists

• Out-of-line suppression files

• Graph capabilities for safe or contradicting graph

• Support for dispatch tree analysis within librtosc

How To Use

1. Annotate a root realtime function with __attribute__((annotate("realtime")))

2. Compile all files with CC=stoat-compile CXX=stoat-compile++ or just compile files with clang’s -emit-llvm flag

3. Run the stoat on the resulting llvm IR files using the --recursive option

4. View the contradictions

5. Optionally redo the analysis using the -G option to graphically view the contradictions

6. Update your code, a whitelist, or suppression list

7. Enjoy the safer code

For a more explicit guide please see the tutorial at http://log.fundamental-code.com/2014/08/15/stoat-tutorial-example.html

License

Stoat is available under the GPLv3 license