OTAWA (http://www.otawa.fr) is a C++ framework dedicated to static analysis of program in machine language form and more specifically oriented towards WCET (Worst Case Executime Time) computation.This pages represents the automatic documentation of the API of OTAWA (automatically extracted from sources) and is devoted to the OTAWA developer or to the command line user. If your goal is only to compute WCET from the Eclipse environment, refer instead to the OTAWA Eclipse plugin manual.
This document contains the automatic documentation of classes composing OTAWA, that is several tenth of classes. Hence, reading documentation of each in turn is definitively the preferred way to use it. If your goal is to learn programming OTAWA, take first a look to the OTAWA Manual available in OTAWA_HOME/share/Otawa/doc/manual/manual.html. If you aim to extend your knowledge of OTAWA classes or to look for an available facility, continue your reading.
This document is automatically generated from the automatic documentation of OTAWA classes by the Doxygen utility. This means that all classes, types, functions are documented and may be easily retrieved. For OTAWA concepts, like code processor, identifier and features, you have to fetch the module documentation whose the outline is given below.
If you look for an existing analysis, the good entry point should be the list of features, Available Features and Processors. For other facilities, consult the module list in the left sub-frame. In addition, below is a list of standard plugin of OTAWA. To get documentation of a specific class, we advise to use the alphabetic of classes from the menu Classes > Class Index.
OTAWA is logically split in different module representing different layers and usage of the framework. In the following, you will find a guide to explore theses modules. Notice that the OTAWA module splitting is not ever reflected by the header files and the libraries, specially the kernel module of OTAWA.
OTAWA is logically split in different layer matching module:
In addition, some utilities are provided:
To extend OTAWA facilities, some analyzes are packaged in plugins. Some plugins are devoted to load and to decode binaries:
Other plugins allows to plug ILP solver:
Finally, some provide specific analyzes:
Built over the C++ class abstraction, OTAWA proposes a layer taking into account the iterative process of analyzing the programs in machine code. Basically, the program is expressed in a form independent of the actual micro-architecture and ISA (Instruction Set Architecture) settled on the classes Process, File, Segment and Inst.
Each of these objects supports annotations. In OTAWA, an annotation is a piece of information referred and typed by an Identifier and linked to a so-called property list, that is, most of objects of the OTAWA program representation. For example, instructions receiving a label get a otawa::LABEL annotation that associates the string naming the label.
As long as static analyzes are performed on the program, more and more annotations are tied the program representation creating two issues: (a) how to chain the analyzes to maintain the soundness of the results and (b) how to cope with the chaos caused by availability of the different annotations in the analysis implementation. The implemented solution proposes to group logically annotations together in the so-called features. For example, the otawa::LOOP_INFO_FEATURE group together the annotations for identifying loop heads, the exiting edges and the parent loops in the CFG.
Finally, the analyzes are packaged in a so-called code processor (because they not only perform analyzes but they are able to also changes the program representation). Each code processor applies on the program representation using the annotations provided by other code processor but also generates new annotations that will be useful for the following analyzes. Projected to the domain features, each code processor requires a set of feature before its execution and provide a new set of feature. Notice that most feature are associated with a code processor and, hence, the requirement of a code processor may causes the automatic execution of the default code processor of the feature. This system ensures that all require information is provided when a code processor starts its analysis.
For example, the otawa::LOOP_INFO_FEATURE is implemnented, as a default, by the otawa::LoopInfoBuilder. This one requires, to be started, that the features otawa::DOMINANCE_FEATURE and otawa::INVOLVED_CFG_FEATURE to be available. If they are not, their own default code processor will be automatically called.
As a consequence, annotation identifiers, feature and code processor have a specific documentation format described here.
The identifier are used to type and name the annotation put in the property lists, that is, the object representing a program representation. Their documentation follows the example below:
The first line gives the C++ description of the identifier defining its name, the type of the tied data and its default value (0 here). The two following gives the meaning of the identifier. The
Hooks gives the list of classes that may support this identifier, otawa::BasicBlock in this case. Finally, the
Feature paragraph gives the list of feature this identifier belongs to. This last section is optional for identifiers used configurations for a code processor.
A feature is a group of annotation identifier tied together around a shared topic. It is documented is below:
After a declaration line containing mainly the name of the feature, several sections give:
The code processors performs the analysis using available annotations (whose feature are required by the processor) and provides new one (belonging to the provided features).
After the code processor class definition and the definition of its members, a small text describes the function and the algorithm of the code processor. Then several sections gives details about the code processor:
Whatever the type of program using OTAWA, the command otawa-config Command is the right entry point to obtain compilation flags, libraries to link with and installation information. OTAWA is not focused on a particular building (autotools, CMake, etc) while it provides the ability to call otawa-config Command.
See Application Writing for helper classes to write command line applications.
OTAWA provides an API in C++: to compile a C++ source, just use the
To link your application, get the options with
To run the obtained program, ensure that the
lib directory of OTAWA is found on the system. For Unixes, add this directory to the
$LD_LIBRARY_PATH, it may be obtained by using option
–prefix and appending
/lib. On Unixes supporting ELF format, you may also use the
–rpath option to get this directory linked in the executable (on Unixes only):
On Windows OSes, such facilities do not exist: one solution is to add the OTAWA
bin directory to the
@ system variable; another one is to copy your executable in the
bin directory of OTAWA.
Whatever your compilation option, you may also obtain the installation directory of OTAWA with
OTAWA framework is based on plugins. They are two ways to use identifier, features and processors provided by a plugin: (a) using the DynXXX classes (DynIdentifier, DynFeature or DynProcessor) or (b) by linking dynamically with a plugin binary. The latter form is preferred as soon as you have to use non-inlined method of classes provided by the plugin.
To perform the linkage, otawa-config Command may help also by adding to the command line the list of required plugins (do not forget to give the whole path with components separated by slashes):
–rpath option is also given, the path of used plugins is appended to the RPATH list of directories.
Maybe, the more easy way to extend OTAWA is to write new analyzes and to package them in a package and then to invoke analyzes from a script.
To link the plugin, otaw-config may help also either using the list of plugin, or using the plugin description file
.eld that contains a
deps entry as in the example below (file is named
To get the right option for linking the plugin, this file may be used with
-p option as below: