Debug Server Scripting

This page is no longer maintained and is kept here for reference only! Please go to this link for the most current version.

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.

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) or '<INSTALL DIR>\ccsv[x]\ccs_base\scripting\bin'. This file is 'dss.bat' on Windows and 'dss.sh' on Linux/Mac, 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.

Launching the the Rhino Debugger

To use the Rhino Debugger with your DSS scripts:

For CCSv5.3 and greater)

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
• CCSv7: <INSTALL DIR>\ccsv7\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.
• DVT basic examples (DVTExamples) - Sample script for collecting and exporting function profiling data
• Loadti (loadti) - a generic command-line loader which can load/run an executable *.out file on TI targets
• 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

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).

NOTE: The examples depend on specific targets. If device support for those targets were not installed (ex. MSP430), then the script will not be able to run "as-is". However, it is still very useful to look through the script, as mentioned above. The script can also be modified to support your target of choice.

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
• CCSv7: <INSTALL DIR>\ccsv7\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.

More information on target configurations can be found in the Debug Handbook for CCS.

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-throw-finally).

<syntaxhighlight lang='javascript'> try {

debugSession.memory.loadProgram(testProgFile);

} catch (ex) {

dssScriptEnv.traceWrite(testProgFile + " does not exist! Aborting script");
quit(); // call custom quit routine to do some cleanup to gracefully exit the script

} </syntaxhighlight>

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.

<syntaxhighlight lang='javascript'> // Call GEL function debugSession.expression.evaluate("myGEL_call()"); </syntaxhighlight>

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

<syntaxhighlight lang='javascript'> openSession("TCI6488EVM_XDS510USB/C64PLUS_F1A"); </syntaxhighlight>

• Passing in the board name and a CPU name to open a debug session for single configured CPU:

<syntaxhighlight lang='javascript'> openSession("TCI6488EVM_XDS510USB", "C64PLUS_F1A"); </syntaxhighlight>

• 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"

<syntaxhighlight lang='javascript'> openSession("TCI6488EVM_XDS510USB", "*"); </syntaxhighlight>

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

<syntaxhighlight lang='javascript'> ...

// 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!");

...

</syntaxhighlight>

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:

<syntaxhighlight lang='xml'> <?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>

... </syntaxhighlight>

Note the second line which references DefaultStylesheet.xsl:

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

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

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: <syntaxhighlight lang='javascript'>for (var i = 0; i < arguments.length; i++) {

  print(arguments[i]);

} </syntaxhighlight>

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: <syntaxhighlight lang='javascript'>options.printOptions(".*") </syntaxhighlight> 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: <syntaxhighlight lang='java'>long getNumeric(String id) String getString(String id) boolean getBoolean(String id) </syntaxhighlight> 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: <syntaxhighlight lang='java'>void setBoolean(String id, boolean value) void setNumeric(String id, long value) void setString(String id, String value) </syntaxhighlight> Example of setting a debugger property to enable real-time mode.

<syntaxhighlight lang='javascript'> ...

// 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);

... </syntaxhighlight>

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).

• Using Java
• Using Perl
• Using Python

Download

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

Training

• DSS Training Module