Automating The Process

Once the XTA has been used interactively to create the timing critical routes, the tool can be automated to ensure that new versions of an application still meet the timing requirements.

Creating a Script

The first step to automating the process is creating a timing script. The script can either be generated by the tool or written by hand.

Generating A Script

Once the timing critical sections of code have been timed, refined and their timing requirements set, a script can be generated. The script will re-create the current set of routes.

Tool Creating A Script

In the GUI press the Generate Script button on the toolbar. This brings up a dialog showing the endpoints, labels and calls which will be used to create the script. The tool attempts to make all references portable. In order to do this it inserts the necessary pragmas into the source.

The names of the pragmas and whether or not they are used can be configured through this dialog. The name of the script to be created is also configured through this dialog.

If creating a script within an existing project then the script is automatically run on future compilations.

If the script creation process has modified the source (e.g. by inserting pragmas), then the relevant binary must be rebuilt before the script can be successfully executed.

Writing A Script

It is also possible to write a script by hand. In this case the user must insert pragmas into the source code where required to make the script portable.

The script file is a sequence of XTA console commands. Each one on a separate line. Any line starting with the # symbol is considered a comment.

It is recommended not to put a load or exit command in the script. These commands should be done at the time of calling the script.

XTA scripts must use the .xta extension in order to be used by the compiler and understood correctly by xTIMEcomposer Studio.

Running a Script

Scripts can be run in a number of different ways, either in xTIMEcomposer Studio or on the command-line.

During Compilation

In xTIMEcomposer Studio .xta scripts are automatically added to the compiler flags for compilation. On the command line the .xta scripts must be passed to the compiler manually. By default, timing failures are treated as warnings and syntax errors in the script as errors.

To treat timing failures as errors, add the following to the compiler arguments:

-Werror=timing

In order to treat script syntax errors as warnings, add the following to the compiler arguments:

-Wno-error=timing-syntax

Running From Within xTIMEcomposer Studio

There are two ways in which an .xta script can be executed from within xTIMEcomposer Studio.

If the binary was loaded into the XTA via a Time Configuration, then an XTA script can be specified in the configuration. This has the effect of running the specified script on the loaded binary whenever a new timing session is started. Note: This will also rebuild the binary if required, thus ensuring that the script is run on the most up to date version of the binary.

Alternatively scripts can be sourced from within the xTIMEcomposer Timing Perspective by clicking on the Run Script icon in the toolbar. This will run the script command on the binary that is currently loaded in the XTA.

Batch Mode

The XTA tool can be run in batch mode. It takes command-line arguments and interprets them as XTA commands. For example, to run an XTA script (script.xta) on a binary (test.xe) use:

xta -load test.xe -source script.xta -exit

Note: the ‘-‘ character is used as a separator between commands.

Embedding Commands Into Source

The tool supports the ability to embed commands into source code. A command is embedded into the source using a command pragma. For example,

#pragma xta command "print summary"

All commands embedded into the source are run every time the binary is loaded into the XTA. Commands are executed in the order they occur in the file, but the order between commands in different source files is not defined.

Pragmas are only supported in XC code. See Pragmas for further information.

Advanced Scripting Via the Jython Interface

The XTA supports the writing of scripts using the Jython language (an implementation of Python running on the Java virtual machine). XTA Jython scripts must have the extension .py. They can be executed in the same way as command based XTA scripts. From within Jython, XTA features are made available though the globally accessible xta object. See Example of an XTA Jython script. for an example script. This scripts loads the binary test.xe into the XTA and analyzes the function functionName. It then sets a loop count on each of the resulting routes and finally, prints the best and worst case times for each.

Example of an XTA Jython script.
import sys
import java

try :
    xta . load (" test .xe");

except java . lang . Exception , e:
    print e. getMessage ()

try :
    ids = xta . analyzeFunction (" functionName ");

    for id in ids :
        xta . setLoop (id , " loopReference ", 10)

    for id in ids :
        print xta . getRouteDescription (id),
        print xta . getWorstCase (id , "ns"),
        print xta . getBestCase (id , "ns")

except java . lang . Exception , e:
    print e. getMessage ()

The interface to the global xta object is as follows:

Load Methods

  • void load(String fileName) throws Exception

Route Creation/Deletion Methods

  • List<Integer> analyzeFunction(String functionName) throws Exception

    List<Integer> analyzeEndpoints(String fromRef, String toRef) throws Exception

    List<Integer> analyzeLoop(String loopRef) throws Exception

    void removeRoute(int routeId) throws Exception

Add/Remove Methods

  • void addTile(String tileReference) throws Exception

    void removeTile(String tileReference) throws Exception

    Collection<String> getTiles() throws Exception

  • void addExclusion(String ref) throws Exception

    void removeExclusion(String ref) throws Exception

    Collection<String> getExclusions() throws Exception

  • void addBranch(String fromRefString, Collection<String> toRefStrings)

    throws Exception

    void removeBranch(String fromRefString, Collection<String> toRefStrings)

    throws Exception

    Collection<String> getBranches() throws Exception

    Collection<String> getBranchTargets(String branch) throws Exception

  • void addLoop(String ref, long iterations) throws Exception

    void removeLoop(String ref) throws Exception

    Collection<String> getLoops() throws Exception

  • void addLoopPath(String ref, long iterations) throws Exception

    void removeLoopPath(String ref) throws Exception

    Collection<String> getLoopPaths() throws Exception

  • void addLoopScope(String ref, boolean absolute) throws Exception

    void removeLoopScope(String ref) throws Exception

    Collection<String> getLoopScopes() throws Exception

  • void addInstructionTime(String ref, double value, String units)

    throws Exception

    void removeInstructionTime(String ref) throws Exception

    Collection<String> getInstructionTimes() throws Exception

  • void addFunctionTime(String ref, double value, String units)

    throws Exception

    void removeFunctionTime(String ref) throws Exception

    Collection<String> getFunctionTimes() throws Exception

  • void addPathTime(String fromRef, String toRef, double value, String units)

    throws Exception

    void removePathTime(String fromRef, String toRef) throws Exception

    Collection<String> getPathTimes() throws Exception

Set Methods

  • void setRequired(int routeId, double value, String units) throws Exception

    void setFunctionTime(int routeId, String refString, double value,

    String units) throws Exception

    void setPathTime(int routeId, String fromRef, String toRef, double value,

    String units) throws Exception

    void setInstructionTime(int routeId, String refString, double value,

    String units) throws Exception

    void setLoop(int routeId, String refString, long iterations)

    throws Exception

    void setLoopPath(int routeId, String refString, long iterations)

    throws Exception

    void setLoopScope(int routeId, String refString, boolean absolute)

    throws Exception

    void setExclusion(int routeId, String refString) throws Exception

Get Methods

  • double getRequired(int routeId, String units) throws Exception

    double getWorstCase(int routeId, String units) throws Exception

    double getBestCase(int routeId, String units) throws Exception

    List<String> getWarnings(int routeId) throws Exception

    List<String> getErrors(int routeId) throws Exception

    List<Integer> getRouteIds() String getRouteDescription(int routeId)

    throws Exception

Config Methods

  • void configCores(String tileReference, int numCores) throws Exception

    void configFreq(String nodeId, double tileFrequency) throws Exception

See Also