This page provide documentation about the commands provided by OTAWA:
More...
This page provide documentation about the commands provided by OTAWA:
dumpcfg Command
This command is used to output the CFG of a binary program using different kind of output.
- SYNTAX
> dumpcfg options binary_file functions1 function2 ...
dumpcfg first loads the binary file then compute and display the CFG of the functions whose name is given. If there is no function, the main functions is dumped.
Currently, dumpcfg provides the following outputs:
- -S (simple output): the basic blocks are displayed, one by one, with their number, their address and the -1-ended list of their successors.
!icrc1
# Inlining icrc1
0 10000368 100003a4 1 -1
1 100003a8 100003b0 3 2 -1
2 100003b4 100003b4 4 -1
3 100003b8 100003c8 6 5 -1
4 1000040c 10000418 7 -1
5 100003cc 100003e8 8 -1
6 100003ec 100003f8 8 -1
7 1000041c 10000428 9 -1
8 100003fc 10000408 1 -1
- -L (listing output): each basic block is displayed starting by "BB", followed by its number, a colon and the list of its successors. Its successors may be T(number) for a taken edge, NT(number) for a not-taken edge and C(function) for a function call.
# Function main
# Inlining main
10000754 stwu r1,-32(r1)
10000758 mfspr r0,256
1000075c stw r31,28(r1)
10000760 stw r0,36(r1)
...
BB 2: C(icrc) NT(3)
1000079c or r0,r3,r3
100007a0 or r9,r0,r0
100007a4 sth r9,8(r31)
100007a8 addis r9,r0,4097
...
BB 3: T(4)
10000808 or r0,r3,r3
1000080c or r9,r0,r0
10000810 sth r9,10(r31)
10000814 addi r3,r0,0
10000818 b 1
BB 4:
1000081c lwz r11,0(r1)
10000820 lwz r0,4(r11)
10000824 mtspr 256,r0
10000828 lwz r31,-4(r11)
1000082c or r1,r11,r11
10000830 bclr 20,0
- -D (dot output): the CFG is output as a DOT graph description.
- -X or –xml (XML output): output a CFG as an XML file satisfying the DTD from $(OTAWA_HOME/share/Otawa/data/cfg.dtd .
dumpcfg accepts other options like:
- -a – dump all functions.
- -d – disassemble the machine code contained in each basic block,
- -i – inline the functions calls (recursive calls are reduced to loops),
- -v – verbose information about the work.
opcg Command
opcg is a simple OTAWA tool to display the Program Call Graph (PCG) of a binary program.
- Syntax
$ opcg [options] binary_file [entry function]
This program output in postscript the PCG of a binary program rooted by the given function or, as a default, by the "main" function.
The output file use the entry function name where the file type extension is appended. If you do not select a special file output and no entry function, the output file is named "main.ps".
The options includes:
-o|–output path – path of the file to output to.
-S|–statistics – display statistics about each subprogram.
-T|–out-type @i type – select the type of output (the @i type may be one of ps, pdf, png, gif, jpg, svg, dot, view).
ostat Command
OStat displays some statistics - average, maximum - about a binary file:
- basic block count,
- basic block sizes,
- memory access instructions count,
- branch instructions count.
- SYNTAX
$ ostat binary_file function1 function2 ...
OStat displays statistics about the given binary file for the requested functions. If no function is provided, the main() function is used.
Options consists of :
- -t: scan the full calling tree whose root is the processed function,
- -s: display statistics in short form (no more information labels),
- -o: display overall statistics including all processed functions.
- Example
$ ostat crc
instructions = 56, 14, 27, 100%
memory instructions = 20, 5, 9, 35.7143%
branch instructions = 4, 1, 1, 7.14286%
owcet Command
owcet command allows to compute WCET of an application using a script provided for a particular architecture implementation. It provide full power of OTAWA framework including selection of architecture-dependent plugin and fine-tuned computation scripts.
- Syntax
SYNTAX: owcet [options] EXECUTABLE_PATH [
TASK_ENTRY] -s SCRIPT_PATH
The @i EXECUTABLE_PATH must be the path of the executable file to compute WCET for. This executable file must be in a machine language understood by OTAWA (currently OTAWA supports PowerPC, ARM, Sparc, HCS12 and partly TriCore).
The optional @i TASK_ENTRY designs the function to compute the WCET for and usually matches a task in the real-time applications. If this parameter is not given, the @tt main function is used.
The @i SCRIPT_PATH is the path of the file containing the script. These file are usually found in $OTAWA_HOME/share/Otawa/scripts. When an architecture plugin is installed, it provides usually its own script.
Other options includes:
- –add-prop ID=VAL: add the property named ID with the value VAL to the configuration properties of the analysis,
- -f, –flowfacts PATH: OTAWA can not automatically found loops so this options is used to design the file containing loop bounds; supported formats includes .ff or .ffx (Flow Facts). Flowfacts allows also to pass specific configuration for the flow execution of a program.
- -i, –dump-ilp: dump the ILP system (if any) to the standard output.
- -l, –list: list the configuration items of the used script.
- –load-param ID=VAL: set the load parameter named ID to the value VAL.
- –log LEVEL: select the log level (one of proc, deps, cfg, bb or inst).
- -p, –param ID=VAL: several parameters with this form may be passed; these definition are used to pass parameters to the script and the supported @i ID depends on the launched script (see its documentation for more details).
- -s, –script PATH: use the given script to compute the WCET.
- -S, –display-stats: display statistics produced by the analysis.
- –stats: outputs available statistics in work directory.
- -t, –timed: display computation time.
- -v, –verbose: verbose display of the process (same as –log bb) *-W, –wcet-stat: outputs detailed statistics about WCET.
- –work-dir PATH: change the working directory to PATH.
- Hints
Real-time systems do not usually perform formatted output as @tt printf family of functions but such a function are often used in case of error. Usually formatting performed by @tt printf is big and complex piece of code that, in the case we take it into account in the WCET computation, would dominate the execution time and drive to a very overestimated WCET. To avoid this, you can command to OTAWA to ignore them without recompiling your application. Just create a file named YOU_EXECUTABLE.ff and write inside:
You can do the like with any function disturbing your computation. You can find in F4 : Flow Facts File Format more details about the commande @tt .ff files. You may also use XML format called @tt .ffx (see Flow Fact XML format).
mkff Command
This command is used to generate F4 file template file template (usually suffixed by a .ff) to pass flow facts to OTAWA. Currently, only constant loop bounds are supported as flow facts. Look the F4 : Flow Facts File Format documentation for more details.
- SYNTAX
$ mkff binary_file function1 function2 ...
mkff builds the .ff loop statements for each function calling sub-tree for the given binary file. If no function name is given, only the main() function is processed.
The loop statement are indented according their depth in the context tree and displayed with the current syntax:
loop loop1_address ?;
loop loop1_1_address ?;
loop loop_1_1_address ?;
loop loop2_address ?;
The "?" question marks must be replaced by the maximum loop bound in order to get valid .ff files. A good way to achieve this task is to use the dumpcfg Command command to get a graphical display of the CFG.
- Example
$ mkff fft1
loop 0x100006c0 ?;
loop 0x10000860 ?;
loop 0x10000920 ?;
loop 0x10000994 ?;
loop 0x10000a20 ?;
loop 0x10000bfc ?;
loop 0x10000d18 ?;
loop 0x10000dc0 ?;
loop 0x10000428 ?;
loop 0x1000045c ?;
loop 0x10000540 ?;
- Other information
mkff has the ability to produce automatically other commands to handle problematic or exotic flow fact structures:
- false control instruction (branching to the next instruction to get the PC values on some architecture),
- undirect branches (switch-like construction, function pointer calls),
- non-returning functions (like exit(), _exit()),
- problematic initialization (like __eabi on EABI based platforms, _main for tricore).
- Usage
- In very complex programs, it may be required to launch mkff several times.
As mkff may detect unsolved indirect branches (function pointer call or swicth-like statements, the first phase consist to fill this kind information and to relaunch mkff to scan unreachable parts of the program. Possibly, some parts may also be cut to tune the WCET computation.
As an example, we want to build the flow facts of the program xxx.
- generate a first version:
{$ mkff xxx > xxx.ff},
- if required, fix the non-loop directives and removes the loop directives,
- generate a new version:
{$ mkff xxx >> xxx.ff},
- while it remains unfixed non-loop, restart at step 2.
In the second phase, you must fix the loop directives, that is, to replace the question marks '?' by actual loop iteration bounds.
odisasm Command
ODisasm disassemble a binary program and display information provided by the instruction loader, that is,
- instruction kinds,
- branch target (for control instructions),
- read and written registers,
- semantic instructions (when available).
This command is particularly useful when a loader is written. It allows to examine the information provided by the loader from the OTAWA run-time point of view and to find back possible errors.
- SYNTAX
$ odisasm binary_file function1 function2 ...
The following are provided:
- -b, –bytes: display bytes of instructions,
- -c, –condition: display condition for conditional instructions,
- -k, –kind: display kind of instructions,
- -r, –regs: display register information,
- -p, –pipeline PROCESSOR_NAME: display execution pipeline of instructions for the given processor
- -s, –semantics: display translation of instruction into semantics language,
- -t, –target: display target of control instructions
- Example
$ odisasm -ktr loop1
01800248 lwz r0,12(r31)
written regs = r0
0180024c cmpi 7,0,r0,99
kind = INT ALU
written regs = cr0
01800250 bc 4,29,-9
kind = COND CONTROL
target =
written regs =
01800254 lwz r0,8(r31)
written regs = r0
01800258 or r3,r0,r0
written regs = r3
0180025c addi r11,r31,32
written regs = r11
01800260 lwz r0,4(r11)
written regs = r0
01800264 mtspr lr,r0
kind = INTERN
written regs = lr
01800268 lwz r31,-4(r11)
written regs = r31
odfa Command
ODFA allows to launch data flow analysis in a stand-alone way and to display the results. For the time being, only the CLP analysis is supported but more will be added later.
- SYNTAX
$ odfa binary_file function1 function2 ...
The following options are provided:
- -c, –clp – perform CLP analysis,
- –before – display the data values before the basic blocks,
- –after – display the data values after the basic blocks,
- -s, –sem – display semantic instructions,
- -F, –filter – display filters (for the CLP analysis),
- -S, –stats – display statistics of the analysis,
- -C, –cfg – dump the CFG in .dot format (including data values),
- -r, –reg REGISTER=VALUE – add an initialization register.
otawa-config Command
This command provides useful information to compile an OTAWA application or a plugin.
- Syntax
>
otawa-config [OPTIONS] MODULES...
The following options are available:
- –bindir - output the OTAWA binary path
- –cflags – output compilation C++ flags
- –datadir – output the OTAWA data path
- –docdir – output the OTAWA document path
- –help, -h – display this help message
- –ilp, –list-ilps – list ILP solver plugins available
- –install, -i – Output path to install the component
- –libdir – output the OTAWA library path
- –libs – output linkage C++ flags
- –list-loaders, –loader – list loader plugins available
- –list-path, –path – display path with plugins
- –list-plugins, –plug – list available plugins
- –list-scripts, –script – list available scripts
- –make-app, -a – information to make a third-party application
- –make-plug, -p PLUGIN_NAME – information to make a plugin
- –make-tool, -t – information to make a tool integrated in OTAWA
- –otawa-version – output the OTAWA version
- –plugdir – output the OTAWA plugin path
- –prefix – output the prefix directory of OTAWA
- –rpath, -r – output options to control RPATH
- –scriptdir – output the OTAWA script path
- –version, -v – display this application version
odec Command
This command is an helper to implement a new loader plugin. Program decoding is a complex and time-consuming task implemented by otawa::TextDecoder analyzer. It uses the decoding ability of the loader to follow execution paths of the program. Because of the complexity of this work, a lot of inconsistencies are silently ignored by the decoder but these issues could be good indications about something wrongly done by the implemented loader.
As it should to costly to support verbosity switch in the decoder, this command proceed as the decoder but provides as much information on the process impossible. This makes easier the understanding and the retrieval of an error from a loader.