Debug Server Scripting

From Texas Instruments Embedded Processors Wiki

(Redirected from DSS)
Jump to: navigation, search

Contents

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), Perl (via Inline::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 that has been extracted out of the Code Composer Studio (CCS) v4 product and made available independent of the CCSv4 GUI. It has been wrapped in a Java interface and is used by both DSS and the CCSv4 IDE.

Fig. 1: Debug Server Overview

DSS is currently available as part of the CCSv4 beta release and can be downloaded from the CCSv4 main page.

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

Check out the DSS FAQs for more information on DSS.


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'. On DSS for Windows, this file is 'dss.bat' 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 '<INSTALL DIR>\ccsv4\scripting\bin' in the system PATH so the batch file 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.

Fig. 2: Rhino JavaScript Debugger

To use the Rhino Debugger with your DSS scripts:

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

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 CCSv4 to a running debug session created by DSS.

Examples

DSS ships with several examples. These examples are located in '<INSTALL DIR>\ccsv4\scripting\examples'

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

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 '<INSTALL DIR>\ccsv4\scripting\docs\GettingStarted.htm'

Scripting Console

Interactive scripting support is available though the CCSv4 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 (*.ccs) are not compatible with DSS.

The CCSv4 Target Setup tool can be used to create a new target configuration (*.ccxml) file. Information on how to use the new setup tool is available on the CCSv4 quick tips training section of the CCSv4 page.

The default location of *.ccxml files is in (for Windows XP): C:\Documents and Settings\<user>\user\CCSTargetConfigurations. These files can be copied and relocated anywhere.

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();
}

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...");
debugServer.simultaneous.run(debugSessionF1A, debugSessionF1B); // 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:

Fig. 3: DSS XML log referencing the default XSLT file opened in a web browser

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 CCSv4 to create, build and import a CCSv4 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 top-level script object has access to a number of predefined properties. One of these is called "argmuments". An example of printing out the arguments passed to a DSS script is: 

for (var i = 0; i < 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. Other than Java, 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

  • Latest versions are installed with CCSv4. A custom installation can also be done to only install the components needed for DSS (No GUI IDE).

For technical support please post your questions at http://e2e.ti.com. Please post only comments about the article Debug Server Scripting here.
Retrieved from "http://tiexpressdsp.com/index.php/Debug_Server_Scripting"
Leave a Comment
Personal tools