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.
Reading this Document
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.
Content
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:
- Program Representation – the main module and the root 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 annotation to the program representation.
- Processor Layer – this layer allows to make automatic the chaining and dependency solving of analyses.
- 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 analyses.
- IPET Method – module containing class to implements the WCET computation by IPET.
- Flow Facts – module providing support for flow fact information provided by user or external tool.
- graph – module providing classes to handle graphs.
- ODisplay Library – 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 with different format (textual, .dot).
- odfa Command – performs and outputs data flow analysis.
- odisasm Command – disassembling of the program in machine code and in semantic instructions.
- oipet Command – computes WCET according to different alternativs of the IPET approach.
- 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.
To extend OTAWA facilities, some analyzes are packaged in plugins. Some plugins are devoted to load and to decode binaries:
- arm2 – loader for ARM v5 (+ thumb) instruction set.
- ppc2 – loader for PowerPC (including VLE extension) instruction set.
Other plugins allows to plug ILP solver:
- lp_solve5 – lp_solve library.
Finally, some provide specific analyzes:
- ast (AST Plugin) – provide program representation as Abstract Syntactic Trees.
- bpred (bpred Plugin) – branch prediction based on state graphs.
- cat (Cat Plugin) – LRU instuction cache analysis by categorisation.
- 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 (Extended Timing Schema) – very basic implementation of Extended Timing Schema.
- display (ODisplay Library) – various display facilities for CFG.
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) 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.
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 configurations for a code processor.
Feature Documentation
A feature is a group of annotation identifier tied together around a shared topic. It is documented is 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 comuting 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 (i.e. annotations).
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) while it provides the ability to call otawa-config Command.
Basic Options
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 –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. 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 bin directory of OTAWA.
Whatever your compilation option, 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.
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.
To link the plugin, otaw-config may help also either using the list of plugin, or using the plugin description file deps entry as in the example below (file is named myplugin.elf ):
[elm-plugin]
deps=path1/plugin1;path2/plugin2;...
To get the right option for linking the plugin, this file may be used with -p option as below:
otawa-
config --libs -p myplugin.eld
1.8.7