fundamental / Stoat

image::stoat-logo.png[align="center"]

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

[source,shell]
-----------------------------------------------------------
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