Debug Server Scripting

From Texas Instruments Wiki
(Redirected from Automating CCS)
Jump to: navigation, search

Overview

Debug Server Scripting (DSS) is a set of cross platform Java APIs to the Debug Server which allow scripting through Java or 3rd Party tools such as JavaScript (via Rhino), Java, Python (via Jython), TCL (via Jacl/Tclblend), etc. JavaScript is the default (and preferred) scripting language supported by DSS.

The Debug Server is the base debug engine of Code Composer Studio (CCS). It can be accessed by both DSS and the CCS IDE.

DSS is available as part of CCS and can be downloaded from the CCS download page.

Note - DSS is truly independent of the CCS GUI (unlike CCScripting for CCSv3 and earlier) - the CCS release is simply the mechanism by which you obtain the DSS product.

If you are really anxious to get to down to business and try some scripts, have a look here.

Advantages over CCScripting

Unlike its predecessor, CCScripting, DSS interfaces directly with the Debug Server and has no GUI dependencies. This allows for DSS to be a more lightweight solution in both size and performance. Numerous other advantages of DSS over CCScripting in both features and performance make DSS the recommended solution for automating your debug environment. Some of these advantages are:

  • Interfaces directly with Debug Server (no debugger GUI)
  • Faster (No GUI overhead, runs in-process)
  • Standalone DSS install size much smaller than full CCS install
    • Light weight installs for lab machines for automation
  • More robust and detailed logging
  • Exception handling
    • Have script handle exceptions thrown by DSS APIs without script aborting
  • Run multiple scripting instances simultaneously
  • Interactive console support
  • More direct APIs supported (less reliance on GEL)

Migration from CCScripting to DSS

There is no migration tool for existing CCScripting scripts to DSS. The scripts will need to be rewritten. If the scripting language used with CCScripting is not supported by DSS, either a switch to a language that is supported (JavaScript, Perl, Java) or look for a solution yourself (look for a way to call Java APIs from your scripting language of choice). Beyond that, the other migration effort is to simply get familiar with the DSS APIs so that you can map the CCScripting APIs used in your script to an equivalent one. If the same language is being used in DSS as was used in CCScripting (i.e. Perl), then the only change to the script needed is how the scripting environment is initialized and the replacement of CCScripting API calls with equivalent DSS ones.

NOTE: Microsoft WSH JScript and JavaScript (which is supported by DSS) are different and NOT fully compatible.

Environment Setup and Running a JavaScript

The host environment must be properly configured before DSS can be run. This involves setting the system PATH, classpaths, other environment variables, etc.. When launching the Rhino JavaScript engine, various parameters must be passed. To simplify all these actions, DSS provides a batch/shell script which sets up the necessary environment and invokes the Rhino Javascript engine with the necessary parameters with the specified JavaScript to run. This file is stored in '<INSTALL DIR>\ccsv4\scripting\bin' (CCSv4), '<INSTALL DIR>\ccsv5\ccs_base\scripting\bin' (CCSv5) or '<INSTALL DIR>\ccsv6\ccs_base\scripting\bin (CCSv6)'. This file is 'dss.bat' on Windows and 'dss.sh' on Linux, with the first parameter being the JavaScript to run and subsequent optional parameters to be passed to the JavaScript.

Ex:

> dss myscript.js scriptParam1 scriptParam2

The above example has the path to batch/shell script in the system PATH so the dss schipt can be called from anywhere.

Debugging Your JavaScript

The Rhino Debugger is a GUI that allows debugging of interpreted JavaScript scripts run in Rhino. It comes bundled with the installation of Rhino which comes with DSS. You can step through your JavaScript , view contents of variables, set breakpoints, etc.

DSS Rhino Debugger.PNG

Launching the the Rhino Debugger

To use the Rhino Debugger with your DSS scripts:

For CCSv5.3 and greater (including CCSv6)

Pass in the -dss.debug parameter when calling the dss script via dss.bat

> dss.bat -dss.debug myScript.js

For CCSv5.2 and earlier

  • Windows: Open the 'dss.bat' file and edit the line where Rhino script engine is launched and replace %RHINO_SHELL% with %RHINO_DEBUGGER%

Change:

java.exe -Xms40m -Xmx256m -Dxpcom.bridge.executeOnDedicatedThread=yes -Dorg.eclipse.swt.browser.XULRunnerPath="%DEBUGSERVER%\win32" -DXPCOM.RUNTIME="%DEBUGSERVER%\win32" -cp %RHINO_JAR%;%SCRIPTING_JARS% %RHINO_SHELL% %1 %2 %3 %4 %5 %6 %7 %8 %9

to:

java.exe -Xms40m -Xmx256m -Dxpcom.bridge.executeOnDedicatedThread=yes -Dorg.eclipse.swt.browser.XULRunnerPath="%DEBUGSERVER%\win32" -DXPCOM.RUNTIME="%DEBUGSERVER%\win32" -cp %RHINO_JAR%;%SCRIPTING_JARS% %RHINO_DEBUGGER% %1 %2 %3 %4 %5 %6 %7 %8 %9

This will run the JavaScript using the Rhino Debugger instead of the shell.

If you plan on debugging your scripts with the Rhino Debugger often, it is a good idea to create a copy of the dss.bat file and have that copy configured to use the Rhino Debugger so you have on batch file that will run your script with the shell (dss.bat) and one with the debugger (dss_debug.bat).

CCS GUI Visibility

Sometimes it is not enough to simply use the Rhino Debugger to debug automation errors, but target debug visibility is also needed to properly diagnose the cause of the errors. In such cases, it is possible to attach CCS to a running debug session created by DSS.

Examples

DSS ships with several examples. These examples are located in:

  • CCSv4: <INSTALL DIR>\ccsv4\scripting\examples
  • CCSv5: <INSTALL DIR>\ccsv5\ccs_base\scripting\examples
  • CCSv6: <INSTALL DIR>\ccsv6\ccs_base\scripting\examples

The examples are meant to demonstrate and highlight some of the capabilities of DSS. Some of the examples available are:

  • DSS basic examples (DebugServerExamples) - These sample scripts which perform basic memory and breakpoint operations on a C64x+ simulator. These examples can be run by running 'go.bat' in the '.\DebugServerExamples' directory
  • DVT basic examples (DVTExamples) - Sample script for collecting and exporting function profiling data. This example can be run by running 'go.bat' in the '.\DVTExamples' directory
  • Loadti (loadti) - a generic command-line loader which can load/run an executable *.out file on TI targets (simulator and hardware platforms)
  • Test Server (TestServer) - DSS example that demonstrates how to use DSS to set-up remote debug session by sending debug commands to remote DSS session via TCP/IP

NOTE: Many of the examples are dependent on C6000 components. If the C6000 components were not installed with your CCS installation, you will not be able to run the example scripts unless the scripts are modified to run with another target.

It is strongly encouraged for new users to open up the DSS basic examples and slowly walk through them to get an understanding of how DSS works. The examples are well commented and should give you an understanding of the basic steps needed to create the scripting environment and start a debug session for a specified target, in addition to highlighting some of the DSS APIs available. It is also useful to use the example scripts as a baseline for creating your own scripts (by referencing it or simply copying and then "gutting" it to use as a template).

DSS API

References to the full DSS API documentation can be found in:

  • CCSv4: <INSTALL DIR>\ccsv4\scripting\docs\GettingStarted.htm
  • CCSv5: <INSTALL DIR>\ccsv5\ccs_base\scripting\docs\GettingStarted.htm
  • CCSv6: <INSTALL DIR>\ccsv6\ccs_base\scripting\docs\GettingStarted.htm

Scripting Console

Interactive scripting support is available though the CCS Scripting Console. DSS APIs can be called from the console. Full standalone DSS JavaScript files can be run from the Scripting Console.

Target Configuration

The target configuration needs to be specified to DSS before attempting to start a debug session. This is done by passing in a target configuration file to the setConfig() API. DSS uses new xml based target configuration files (*.ccxml). Existing target configuration file from CCSv3 and earlier (*.ccs) are not compatible with DSS.

The CCS Target Setup tool can be used to create a new target configuration (*.ccxml) file.

Exception Handling

All DSS APIs throw a Java exception when encountering errors. These exceptions can be caught and handled within the script (ex. JavaScript try-catch).

try {
 debugSession.memory.loadProgram(testProgFile);
} catch (ex) {
 dssScriptEnv.traceWrite(testProgFile + " does not exist! Aborting script");
 quit();
}

Using GEL

Like with CCScripting, you can call GEL functions from DSS. The expression.evaluate() API can be used to call any GEL function/expression.

// Call GEL function
debugSession.expression.evaluate("myGEL_call()");

Multiple Debug Sessions for Multi-core Debug

It is possible to open and control a debug session for each CPU on a multi-core target. Simply use the openSession() API and specify the board name and CPU name to open a session to a specific CPU.

Lets take a look at an example of opening debug sessions to a TCI6488 EVM with 6 C64x+ DSPs. First, it is important to know the exact board name and CPU names used by the target configuration ccxml file. the names can be found by looking inside the ccxml file used or opening the ccxml file in the new Target Configuration GUI tool. For our example, the names are:

  • Board Name: TCI6488EVM_XDS510USB
  • CPU Name(s): C64PLUS_F1A, C64PLUS_F1B, C64PLUS_F1C, C64PLUS_F2A, C64PLUS_F2B, C64PLUS_F2C

Once you know the names, the openSession() API can be called in a variety of ways:

  • Passing in a unique name. In the system configuration, each debuggable object (CPU) has a unique name that is constructed as: boardname/CPUName
openSession("TCI6488EVM_XDS510USB/C64PLUS_F1A");
  • Passing in the board name and a CPU name to open a debug session for single configured CPU:
openSession("TCI6488EVM_XDS510USB", "C64PLUS_F1A");
  • This method also allows the passing of wildcards "*" to sBoardName and sCPUName. A wildcard will match the first found target. In this case, the a wildcard to open a connection to the first CPU of the board named "TCI6488EVM_XDS510USB"
openSession("TCI6488EVM_XDS510USB", "*");

Lets take a look at what a real JavaScript code would look like using the first option (passing in a unique name):

...
 
// Get the Debug Server and start a Debug Session
debugServer = script.getServer("DebugServer.1");
 
// Configure target for a TCI6488 EVM with SD XDS510 USB emulator
script.traceWrite("Configuring debug server for TCI6488 EVM...");
debugServer.setConfig("TCI6488EVM_SD510USB.ccxml");
script.traceWrite("Done!");
 
// Open a debug session for each TCI6488 CPU
script.traceWrite("Opening a debug session for all TCI6488 cores...");
debugSessionF1A = debugServer.openSession("TCI6488EVM_XDS510USB/C64PLUS_F1A");
debugSessionF1B = debugServer.openSession("TCI6488EVM_XDS510USB/C64PLUS_F1B");
debugSessionF1C = debugServer.openSession("TCI6488EVM_XDS510USB/C64PLUS_F1C");
debugSessionF2A = debugServer.openSession("TCI6488EVM_XDS510USB/C64PLUS_F2A");
debugSessionF2B = debugServer.openSession("TCI6488EVM_XDS510USB/C64PLUS_F2B");
debugSessionF2C = debugServer.openSession("TCI6488EVM_XDS510USB/C64PLUS_F2C");
script.traceWrite("Done!");
 
// Connect to each TCI6488 CPU
script.traceWrite("Connecting to all TCI6488 CPUs...");
debugSessionF1A.target.connect();
debugSessionF1B.target.connect();
debugSessionF1C.target.connect();
debugSessionF2A.target.connect();
debugSessionF2B.target.connect();
debugSessionF2C.target.connect();
script.traceWrite("Done!");
 
// Load a program for just the first TCI6488 CPU
script.traceWrite("Loading program to first TCI6488 CPU...");
debugSessionF1A.memory.loadProgram("HelloTCI6488.out");
script.traceWrite("Done!");
 
// Load a program for just the second TCI6488 CPU
script.traceWrite("Loading program to second TCI6488 CPU...");
debugSessionF1B.memory.loadProgram("HelloTCI6488.out");
script.traceWrite("Done!");
 
// Run the program for just the first TCI6488 CPU
script.traceWrite("Executing program on first TCI6488 CPU...");
debugSessionF1A.target.run();
script.traceWrite("Execution complete!");
 
// Reload program for just the first TCI6488 CPU
script.traceWrite("Loading program to first TCI6488 CPU...");
debugSessionF1A.memory.loadProgram("HelloTCI6488.out");
script.traceWrite("Done!");
 
// Run the program for the first and second TCI6488 CPU simultaneously
script.traceWrite("Executing program on first and second TCI6488 CPU...");
 
var dsArray = new Array();
dsArray[0] = debugSessionF1A;
dsArray[1] = debugSessionF1B;
 
debugServer.simultaneous.run(dsArray); // Run CPUs 1 and 2
script.traceWrite("Done!");
 
...


Logging

DSS logging can be enabled using the traceBegin() API. The logs can contain various information such as timestamps, sequence ID, time deltas and status for each log entry. The amount of logging (entries) can be set to the desired verbosity level with the traceSetFileLevel() API. At the higher verbosity levels, many internal diagnostic and status messages will be logged, which can be very useful in trying to determine what/where exactly was the cause of a script failure. However this can lead to very large log files for long automation sessions so it is recommended to use the higher verbosity settings only when needed.

The generated log files are XML format. Everyone will have slightly different logging needs and by producing standardized XML log files it is easy to transform XML using XSLT (XML StyLesheet Transforms) into any custom format (comma-delimited text, HTML, etc.). The traceBegin() API can take a second parameter (the first being the log file name) to specify an XSLT file to be referenced when opening the XML file in your web browser. An example XSLT file (DefaultStylesheet.xsl) is provided in the scripting examples folder with DSS.

An example of raw XML output of a DSS log in a text editor:

<?xml version="1.0" encoding="windows-1252" standalone="no"?>
<?xml-stylesheet type="text/xsl" href="DefaultStylesheet.xsl"?>
<log>
<record>
 <date>2008-10-30T17:16:53</date>
 <millis>1225401413228</millis>
 <sequence>6</sequence>
 <logger>com.ti</logger>
 <level>FINER</level>
 <class>com.ti.ccstudio.scripting.environment.ScriptingEnvironment</class>
 <method>traceSetFileLevel</method>
 <thread>10</thread>
 <message>RETURN</message>
</record>
<record>
 <date>2008-10-30T17:16:53</date>
 <millis>1225401413238</millis>
 <sequence>7</sequence>
 <logger>com.ti</logger>
 <level>FINER</level>
 <class>com.ti.ccstudio.scripting.environment.ScriptingEnvironment</class>
 <method>getServer</method>
 <thread>10</thread>
 <message>ENTRY sServerName: DebugServer.1</message>
</record>
 
...

Note the second line which references DefaultStylesheet.xsl:

<?xml-stylesheet type="text/xsl" href="DefaultStylesheet.xsl"?>

Opening the same log file in a web browser will look something along the lines of:

DSS xml log.PNG

More information on XSLT (including information on how to create your own) can be found on this XSLT Tutorial site.

Profiling

See the mediawiki topic: Profiling with DSS

Project Management

DSS does not have any APIs for project management (project create, project build, etc) since DSS is for scripting the debugger (and not the project manager). However there are command-line utilities that come with CCS to create, build and import a CCS project that can be called from a script, effectively automating such actions. More information on these commands are available in the mediawiki topic: Projects - Command Line Build/Create

Breakpoints

Information for setting breakpoints with DSS is covered in the Breakpoint mediawiki topic.

Passing Arguments to a Script

The method for passing arguments to a script will vary depending on the scripting language used, so it is best to check the documentation for that language.

If using JavaScript, the top-level script object has access to a number of predefined properties. One of these is called "arguments". An example of printing out the arguments passed to a DSS script is:

for (var i = 0; i &lt; arguments.length; i++) {
   print(arguments[i]);
}

Debugger Properties

There are DSS APIs to get and set various debugger options ('Tools->Debugger Options').

Some options that are supported are:

  • auto-run to 'main' on program load/restart/reset
  • enable real-time mode
  • ...

Use the following API to print the full list of supported options in DSS:

options.printOptions(".*")

This will generate a list of supported options. A single entry will look like:

Boolean Option:
    id: AllowInterruptsWhenHalted
    name: Generic.Realtime options.Enable silicon real-time mode (service critical interrupts when halted, allow debugger accesses while running)
    value: false
  • The first line indicates that this option is a 'boolean' option. Option types will be either 'numeric', 'String' or 'boolean'.
    • Note that drop-downs (as well as radio buttons) are considered to be a 'String' type
  • The second line is the 'id' of the option
  • The third line is a description of the option

The APIs to get the value of a specific option are:

long getNumeric(String id)
String getString(String id)
boolean getBoolean(String id)

Pass in the option 'id' as described above. Depending on the option type, use the applicable API (ex: use 'getBoolean()' for 'boolean' options)

The APIs to set the value of specific options are:

void setBoolean(String id, boolean value)
void setNumeric(String id, long value)
void setString(String id, String value)

Example of setting a debugger property to enable real-time mode.

...
 
// Get Debug Server
debugServer = script.getServer("DebugServer.1");
 
// Configure for F2812 target
debugServer.setConfig("F2812.ccxml");
 
// Open a debug session
debugSession = debugServer.openSession(".*");
 
// connect to the target
debugSession.target.connect();
 
// Load a program
debugSession.memory.loadProgram("modem.out");
 
// enable real-time mode
debugSession.options.setBoolean("AllowInterruptsWhenHalted",true);
 
...

Other Supported Languages

The underlying Debug Server Scripting package is implemented as a set of Java APIs. Using readily available packages (many of them open source) it is possible to access these APIs using other scripting languages. JavaScript (via Rhino) is the preferred language and will be officially supported by DSS. However there are many third-party solutions available to interface Java with TCL (tclblend), Python (Jython) and Perl (Inline::Java).

Download

DSS comes bundled with CCS. It is not possible to get a standalone "DSS only" installer.

Training