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. These pages represent 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.
Reading this document
This document contains the automatic documentation of classes composing OTAWA, that is several tenth of classes. Hence, reading documentation of each class according to your needs is definitively the preferred way to use it. If your goal is to learn programming OTAWA, take first a look refer 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, go on here.
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 which 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 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.
Quick Links
Below is a list of most used modules that you may want to link to:
Contents
OTAWA is logically split in several modules 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 always reflected by the header files and the libraries, specially the kernel module of OTAWA. Notice that each class is member of a module and this documentation provides, just the class name, a straight link to the module documentation that may give more details or put in its context the concerned class.
OTAWA is logically split in several layers included in a module:
- Program Representation – the main module and the root of any work in OTAWA provides the abstract representation of the program to handle.
- Properties System – the property layer is built just above the program representation to link properties or annotations to the program representation.
- Processor Layer – this layer supports the chaining and dependency solving of analyzes.
- Platform Description – this layer provides the description of the host platform where the loaded program will run.
- Data Flow Analysis – module devoted to generic classes to perform static analyzes.
- IPET Method – module containing classes to implement the WCET computation by IPET (Implicit Path Enemeration Technique), currently the most successful method to compute WCET.
- Flow Facts – module providing support for flow fact information provided by user or external tools.
- Graph Structure – module providing classes to handle graphs.
- Graph Display – module providing facilities to display graphs.
- Application Writing – module helping to write command line applications.
In addition, some utilities are provided:
- dumpcfg Command – outputs CFG in different format (textual, .dot).
- odfa Command – performs and outputs data flow analysis.
- odisasm Command – disassembles of the program and provides information on instructions (semantic instructions, used register, branch targets, etc).
- opcg Command – outputs the Program Call Graph (PCG).
- ostat Command – computes some statistics about instructions of a program.
- owcet Command – computes the WCET based on the scripts.
- operform – launch the analyses and output the graph without to have to write a script.
Finally, some provide specific analyzes:
- ast (ast) – provide program representation as Abstract Syntactic Trees.
- bpred (bpred Plugin) – branch prediction based on state graphs.
- cat (Cat Plugin) – LRU instruction cache analysis by categorization.
- ccg (CCG Plugin) – direct-mapped instruction cache analysis based on state graphs.
- cfgio (CFG Input / Output) – input/output of CFGs.
- dcache (Data Cache) – basic LRU data cache analysis.
- etime (Event Time Module) – time determination by block based on parametric execution graph by time set split.
- ets (ets) – very basic implementation of Extended Timing Schema.
- display (Graph Display) – various display facilities for CFG.
- icat3 (@ef icat3) – new infrastructure to handle instruction cache analysis.
To get answers for developer questions, you can take a look to our Frequently Asked Questions.
How to read the API ?
Structure of OTAWA
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) based 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 to 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 provided by the analysis implementations. The implemented solution proposes to group logically annotations together in the so-called @i 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 @i code @i processor, extending the class otawa::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 processors but also generates new annotations that will be useful for the following analyzes. Projected to the domain of features, each code processor requires a set of features before its execution and provide a new set of features. Notice that most features are associated with a code processor and, hence, the requirement of a code processor may cause the automatic execution of the default code processor of the feature. This system ensures that all required information is provided when a code processor starts its analysis.
For example, the otawa::LOOP_INFO_FEATURE is implemented, as a default, by the otawa::LoopInfoBuilder. This one requires, before being 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, features and code processors have a specific documentation format described here.
Annotation Identifier Documentation
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:
Identifier otawa::ENCLOSING_LOOP_HEADER("otawa::ENCLOSING_LOOP_HEADER", 0)
Defined for any BasicBlock that is part of a loop.
Contains the header of the loop immediately containing the basicblock If the basicblock is a loop header, then, the property contains the header of the parent loop.
Hooks
Feature
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 as configurations for a code processor. In this last case, a @i Configuration replaces the @i Feature section.
Feature Documentation
A feature is a group of annotation identifiers tied together around a particular topic. It is documented as below:
SilentFeature otawa::dcache::MUST_ACS_FEATURE("otawa::dcache::MUST_ACS_FEATURE", _maker)
This feature ensures that the ACS (Abstract Cache State) for the MUST data cache analysis has been built.
Usually, the ACS are used to derivate the categories of each data cache access.
Processors
Properties
Configuration
After a declaration line containing mainly the name of the feature, several sections give:
- the code processors implementing the feature (and the default code processor),
- the set of properties belonging to the feature (with link to get quickly their documentation),
- the set of properties used as configuration for computing the feature.
Code Processor Documentation
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).
otawa::dcache::ACSBuilder Class Reference
...
This builder performs analysis of the L1 data cache and produces ACS for MUST and,
according to the configuration properties, persistence. As a result, it provides ACS.
Provided features
Required features
- LOOP_INFO_FEATURE
- DATA_BLOCK_FEATURE
Configuration
- DATA_FIRSTMISS_LEVEL
- DATA_PSEUDO_UNROLLING
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:
- the list of provided features,
- the list of required features,
- the list of configuration properties.
Developing with OTAWA
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) but it is important to be able to use otawa-config Command. Additionally, otawa-config Command helps to support the plugin management for the most currently used OS as Linux (Unix), Windows and MacOS.
Basic Options
See Application Writing for helper classes to write command line applications.
OTAWA provides an API in C++ and to compile a C++ source, just use the flags returned ny –cflags option:
To link your application, get the options with –libs:
To run the obtained program, ensure that the lib directory of OTAWA is found on the system paths. 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 and on MacOS, you may also use the –rpath option to get this directory linked in the executable
On Windows OSes, such facilities do not exist: one solution is to add the OTAWA bin directory to the @PATH @ system variable or to install your program in the bin executable directory of OTAWA (close to the OTAWA main library).
Whatever your compilation options, you may also obtain the installation directory of OTAWA with –prefix option:
Using a plugin
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):
otawa-config --libs path1/plugin1 path2/plugin2 ...
If the –rpath option is also given, the path of used plugins is appended to the RPATH list of directories. The paths of the plugin may be absolute or relative to the OTAWA plugin directory. This directory may be obtained by:
Plugin Writing
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 or from operform. To compile the plugin, the more portable solution consists in providing .eld file: these files contain information about a plugin in INI format. It is used by OTAWA at run-time to pre-load dependent plugins and libraries whatever the host system without any limitation imposed by the system.
Below is the .eld of the internal module called etime that computes the time of basic blocks:
This file gives the name of the module and provides a list of required plugins, deps: the plugin branch about branch prediction and the module dcache about data cache analysis. Notice that the paths of required plugins is relative to the OTAWA plugin directory. This directory may be obtained by:
Using the .eld file, the linking flags can be obtained with:
With PLUGNAME the name of the built plugin, the name of the .eld file without .eld.
Refer to the ELM documentation about plugins for more details on .eld files.
Installing new plugins
OTAWA v2 comes with a new installation tool named otawa-install.p. OTAWA may be installed using it but it allows also to automatically add new plugins that are not part of the basic installation.
To get the list of installed and available plugins, just type:
To install a particular plugin named PLUGIN, just type:
Depending of the availability of binary package for your OS, it will download it and attempt to built the attribute from sources.
OTAWA aims to be a very open and versatile framework encouraging third-party module. If you develop your own plugin and if you plan to make it freely available (what we advise), contact us at otawa.nosp@m.@iri.nosp@m.t.fr to add your module in the otawa-install.py module list.
