OTAWA  2.0
Framework to perform machine analysis and compute WCET.
Processor Layer

The OTAWA Properties System provides a flexible and easy way to store in the program representation the result of different analyses. Yet, the computation of the WCET may require a lot of different analyses, it becomes wuicly difficult to handle the chaining of different analyses according their requirement. More...

Classes

class  otawa::AbstractFeature
 
class  otawa::AbstractRegistration
 
class  otawa::BBProcessor
 
class  otawa::CFGProcessor
 
class  otawa::ConcurrentCFGProcessor
 
class  otawa::ContextualProcessor
 
class  otawa::p::declare
 
class  otawa::DelayedMaker
 
class  otawa::Feature< T, C >
 
class  otawa::FunProcessor
 
class  otawa::p::interfaced_feature< I >
 
class  otawa::cache::LBlockProcessor
 
class  otawa::NoProcessor
 
class  otawa::NoProcessorException
 
class  otawa::ProcessException
 
class  otawa::Processor
 
class  otawa::ProcessorException
 
class  otawa::Progress
 
class  otawa::Registry
 
class  otawa::StatCollector
 
class  otawa::StatInfo
 
class  otawa::UnavailableFeatureException
 

Functions

p::id< boolotawa::DUMP ("otawa::DUMP", false)
 Dump the results of all analyzes. More...
 
p::id< stringotawa::DUMP_FOR ("otawa::DUMP_FOR", "")
 Dump the result of the analysis which name is passed as argument. More...
 
p::id< elm::io::OutStream * > otawa::DUMP_STREAM ("otawa::DUMP_STREAM", nullptr)
 Dump the results to the given stream. More...
 
p::id< stringotawa::DUMP_TO ("otawa::DUMP_TO", "")
 Dump the result to the given file path. More...
 
AbstractFeatureotawa::p::find_feature (cstring name)
 Retrieve a feature by its name, possibly loading corresponding plug-in. More...
 
AbstractIdentifierotawa::p::find_id (cstring name)
 Find an identifierby its name. More...
 
template<class T >
p::id< T > & otawa::p::get_id (cstring name)
 
bool otawa::p::is_feature (const AbstractIdentifier *id)
 Test if the given identifier is a feature identifier. More...
 
p::id< elm::io::OutStream * > otawa::LOG ("otawa::LOG", &cerr.stream())
 This property identifier is used for setting the log stream used by the processor to write messages (information, warning, error). More...
 
p::id< stringotawa::LOG_FOR ("otawa::LOG_FOR")
 Display logs only for the named processor. More...
 
p::id< Monitor::log_level_totawa::LOG_LEVEL ("otawa::LOG_LEVEL", Monitor::LOG_NONE)
 Property passed in the configuration property list of a processor to select the log level between LOG_PROC, LOG_CFG or LOG_BB. More...
 
p::id< elm::io::OutStream * > otawa::OUTPUT ("otawa::OUTPUT", &cout.stream())
 This property identifier is used for setting the output stream used by the processor to write results. More...
 
p::id< boolotawa::VERBOSE ("otawa::VERBOSE", false)
 This property activates the verbose mode of the processor: information about the processor work will be displayed. More...
 

Variables

p::id< boolotawa::DUMP
 Dump the results of all analyzes. More...
 
p::id< stringotawa::DUMP_FOR
 Dump the result of the analysis which name is passed as argument. More...
 
p::id< elm::io::OutStream * > otawa::DUMP_STREAM
 Dump the results to the given stream. More...
 
p::id< stringotawa::DUMP_TO
 Dump the result to the given file path. More...
 
p::id< elm::io::OutStream * > otawa::LOG
 This property identifier is used for setting the log stream used by the processor to write messages (information, warning, error). More...
 
p::id< stringotawa::LOG_FOR
 Display logs only for the named processor. More...
 
p::id< Monitor::log_level_totawa::LOG_LEVEL
 Property passed in the configuration property list of a processor to select the log level between LOG_PROC, LOG_CFG or LOG_BB. More...
 
AbstractMakerotawa::no_maker = &no_inst
 Special maker for "no processor available". More...
 
AbstractMakerotawa::null_maker = &null_inst
 Special maker for a null processor. More...
 
p::id< elm::io::OutStream * > otawa::OUTPUT
 This property identifier is used for setting the output stream used by the processor to write results. More...
 
p::id< boolotawa::VERBOSE
 This property activates the verbose mode of the processor: information about the processor work will be displayed. More...
 

Detailed Description

The OTAWA Properties System provides a flexible and easy way to store in the program representation the result of different analyses. Yet, the computation of the WCET may require a lot of different analyses, it becomes wuicly difficult to handle the chaining of different analyses according their requirement.

Processor Concepts

Features

A feature represents a set of services that are available on the program representation. These services are provided either by the program loader, or by a previous analysis. These services are composed of:

  • properties linked to the program representation,
  • methods providing meaningful results in the object of the program representation.

The feature are an easier way to inform the framework that some services are provided and to group properties and methods in logical sets. A feature is mainly implemented by an otawa::AbstractFeature.It may be implemented using the command otawa::p::feature with a default code processor (see below) to satisfy the service if it is not provided. As the goal of feature is to share some data between analyzes, it is first declared in a header file, for example "my_feature.h" :

#include "MyDefaultProcessor.h"
extern p::feature MY_FEATURE;
Then, it must defined in a source file, for example, "my_feature.cpp", with a default builder, MyProcessor in this example:

#include "my_feature.h"
p::feature MY_FEATURE("MY_FEATURE", p::make<MyProcessor>());
Note that a feature must have a unique name: duplicate names in features names will be detected at system startup and will cause abortion of the application. Although it is not mandatory, it is advised (1) to give a name in upper case with underscores to separate names and (2) to give the full-qualified C++ name. This convention will help to retrieve features when dynamic module loading is used.Some features can come with a specific interface providing some special facilities that cannot be expressed using properties. This interface is typically an abstract class. To declare such a feature, one has to use "p::interfaced_feature" as:

p::interfaced_feature<MyInterface> MY_FEATURE;
To obtain this interface in a workspace wher the feature is provided, one has to use feature function, AbstractFeature::get() as below:

WorkSpace *ws;
ws->require(MY_FEATURE);
MyInterface *inter = MY_FEATURE.get(ws);
To implement, any code processor implementing the feature has to provide a function named Processor::interfaceFor() and to return the corresponding interface:

class MyProcessor: public Processor {
public:
...
void *interfaceFor(const AbstractFeature& f) override { return inter; }
...
private:
...
MyInterface *inter;
};
Code Processors

A code processor performs an analysis, that is, scans the program representation, extracts some properties and provide them to the remaining analyzes. To organize the properties, they are grouped logically in features. To organize this work, the code processors records itself to OTAWA in order to:

  • ensure that the required features are available,
  • inform that the processor computes some new features.

Consequently, in OTAWA, analyses are packaged inside code processors (otawa::Processor) that manages the features but also provides other facilities:

  • configuration of the processor work,
  • control of output streams,
  • statistics gathering,
  • details about the computation
  • several classes to make analysis writing easier (CFG processor, BB processor, contextual processor and so on),
  • resource cleanup.

This class provides also a common way to invoke analyzes. The configuration is perform in a property list structure:

PropList props;
CONFIGURATION_1(props) = value1;
CONFIGURATION_2(props) = value2;
...
Then, the processor object is simply created and invoked on a workspace:

WorkSpace *ws;
ws->run<MyProcessor>(props);
For example, to redirect the log output of the processor and to activate verbosity, and to compute the domination in a CFG, we may do:

PropList props;
Processor::VERBOSE(props) = true;
Processor::LOG(props) = System::newFile("my_log.txt");
ws->run<Domination>(props);
Notice that the configuration properties are passed to all processor invoked to provide features required by the invoked processor.Code processors are usually invoked directly by a user or indirectly to implement a specific feature. Whatever the case, the code processor follows this calling cycle:

  • Processor::prepare() – called before satisfying its required/used features,
  • Processor::setup() – to set up some common resources
  • Processor::processWorkSpace() – to perform the analysis itself
  • Processor::cleanup() – to clean the resources allocated in setup()
  • Processor::commit() – to install properties required its provided features,
  • Processor::destroy() – called at deletion/invalidation of its provided features to clean up properties installed in commit().
Processor Registration

Code processors or analyzers can be invoked explicitly from C++ code, implicitly by requiring a feature or from a script (see Script class or owcet command). In the latter case, the processor name is used to retrieve its code and to allow to create an instance.As C++ does not provide any reflexive information to find back the constructor of a class, the code processor need to record in the main registry of OTAWA. To achieve, it must declare a static object (1) that will record itself to the main registry and (2) that provides all details of the code processor to the OTAWA framework:

  • the name
  • the version
  • required and/or used features,
  • invalidated features,
  • provided features,
  • configuration properties,
  • the constructor,
  • possibly its base processor (as a default, all processor have for base otawa::Processor).

Although this registration can be achieved in different ways, the current preferred way requires to declare, as public members, a static attribute named reg and a constructor taking an AbstractRegistration with reg as default value. The constructor definition allows to pass the actual registration of the subclass (that is including the one of the current class) to the OTAWA framework.

class MyProcessor: public BBProcessor {
public:
static p::declare reg;
MyProcessor(AbstractRegistration& r = reg): BBProcessor(r) { ... }
};
In turn, the static attribute must be declared with the details of the code processor in the source file:

p::declare MyProcessor::reg =
p::init("MyProcessor", Version(1, 0, 0))
.base(BBProcessor::reg),
.require(CFG_COLLECTED_FEATURE)
.provide(MY_FEATURE)
.make<MyProcessor>();

Function Documentation

◆ DUMP()

p::id<bool> otawa::DUMP ( "otawa::DUMP"  ,
false   
)

Dump the results of all analyzes.

◆ DUMP_FOR()

p::id<string> otawa::DUMP_FOR ( "otawa::DUMP_FOR"  ,
""   
)

Dump the result of the analysis which name is passed as argument.

Several instances of this property can be given.

◆ DUMP_STREAM()

p::id<elm::io::OutStream *> otawa::DUMP_STREAM ( "otawa::DUMP_STREAM"  ,
nullptr   
)

Dump the results to the given stream.

◆ DUMP_TO()

p::id<string> otawa::DUMP_TO ( "otawa::DUMP_TO"  ,
""   
)

Dump the result to the given file path.

◆ find_feature()

AbstractFeature * otawa::p::find_feature ( cstring  name)

Retrieve a feature by its name, possibly loading corresponding plug-in.

Parameters
nameFull-qualified "::"-separated feature name.
Returns
Found feature or null.

References otawa::ProcessorPlugin::getFeature(), and name.

◆ find_id()

AbstractIdentifier * otawa::p::find_id ( cstring  name)

Find an identifierby its name.

Parameters
nameName of the looked identifier.
Returns
Found identifier or null.

References otawa::ProcessorPlugin::getIdentifier(), and name.

Referenced by otawa::p::get_id().

◆ get_id()

template<class T >
p::id< T > & otawa::p::get_id ( cstring  name)
inline

Find and return an identifier for the given and which value type corresponds to the given type T. If the identifier cannot be found, perform an assertion failure.

Parameters
TType of identifier values.
nameName of the identifier.
Returns
Corresponding identifier.

References otawa::p::find_id(), and name.

◆ is_feature()

bool otawa::p::is_feature ( const AbstractIdentifier id)

Test if the given identifier is a feature identifier.

Parameters
idIdentifier to test.
Returns
True if it is a feature, false else.

References otawa::IS_FEATURE.

Referenced by otawa::WorkSpace::provides().

◆ LOG()

p::id<elm::io::OutStream *> otawa::LOG ( "otawa::LOG"  ,
&cerr.  stream() 
)

This property identifier is used for setting the log stream used by the processor to write messages (information, warning, error).

Referenced by otawa::Monitor::configure().

◆ LOG_FOR()

p::id<string> otawa::LOG_FOR ( "otawa::LOG_FOR"  )

Display logs only for the named processor.

If no LOG_FOR is defined, all processors are logged. Several LOG_FOR can be recorded in the configuration.

Referenced by otawa::Monitor::configure().

◆ LOG_LEVEL()

p::id<Monitor::log_level_t> otawa::LOG_LEVEL ( "otawa::LOG_LEVEL"  ,
Monitor::LOG_NONE   
)

Property passed in the configuration property list of a processor to select the log level between LOG_PROC, LOG_CFG or LOG_BB.

Referenced by otawa::Monitor::configure().

◆ OUTPUT()

p::id<elm::io::OutStream *> otawa::OUTPUT ( "otawa::OUTPUT"  ,
&cout.  stream() 
)

This property identifier is used for setting the output stream used by the processor to write results.

Referenced by otawa::Monitor::configure().

◆ VERBOSE()

p::id<bool> otawa::VERBOSE ( "otawa::VERBOSE"  ,
false   
)

This property activates the verbose mode of the processor: information about the processor work will be displayed.

Referenced by otawa::Monitor::configure().

Variable Documentation

◆ DUMP

p::id<bool> otawa::DUMP("otawa::DUMP", false)

Dump the results of all analyzes.

Referenced by otawa::Processor::init(), and otawa::Application::run().

◆ DUMP_FOR

p::id<string> otawa::DUMP_FOR("otawa::DUMP_FOR", "")

Dump the result of the analysis which name is passed as argument.

Several instances of this property can be given.

Referenced by otawa::Processor::init(), and otawa::Application::run().

◆ DUMP_STREAM

p::id<elm::io::OutStream *> otawa::DUMP_STREAM("otawa::DUMP_STREAM", nullptr)

Dump the results to the given stream.

◆ DUMP_TO

p::id<string> otawa::DUMP_TO("otawa::DUMP_TO", "")

Dump the result to the given file path.

Referenced by otawa::Processor::init(), and otawa::Application::run().

◆ LOG

p::id<elm::io::OutStream *> otawa::LOG("otawa::LOG", &cerr.stream())

This property identifier is used for setting the log stream used by the processor to write messages (information, warning, error).

◆ LOG_FOR

p::id<string> otawa::LOG_FOR("otawa::LOG_FOR")

Display logs only for the named processor.

If no LOG_FOR is defined, all processors are logged. Several LOG_FOR can be recorded in the configuration.

◆ LOG_LEVEL

p::id<Monitor::log_level_t> otawa::LOG_LEVEL("otawa::LOG_LEVEL", Monitor::LOG_NONE)

Property passed in the configuration property list of a processor to select the log level between LOG_PROC, LOG_CFG or LOG_BB.

◆ no_maker

AbstractMaker * otawa::no_maker = &no_inst

Special maker for "no processor available".

Referenced by otawa::p::feature::~feature().

◆ null_maker

AbstractMaker * otawa::null_maker = &null_inst

Special maker for a null processor.

Referenced by otawa::p::feature::~feature().

◆ OUTPUT

p::id<elm::io::OutStream *> otawa::OUTPUT("otawa::OUTPUT", &cout.stream())

This property identifier is used for setting the output stream used by the processor to write results.

◆ VERBOSE

p::id<bool> otawa::VERBOSE("otawa::VERBOSE", false)

This property activates the verbose mode of the processor: information about the processor work will be displayed.

Feature.h
otawa::LOG
p::id< elm::io::OutStream * > LOG
This property identifier is used for setting the log stream used by the processor to write messages (...
otawa::clp::VERBOSE
Identifier< bool > VERBOSE