7.9. Legacy Scripting (DSS)¶
Warning
DSS is being deprecated in favor of the new CCS Scripting solution.
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) Theia. It can be accessed by both DSS and the CCS Theia IDE.
The training video below contains a very thorough coverage of the fundamentals and operation of DSS. Note that while an older CCS version is referenced in the below, the DSS concepts are still relevant.
7.9.1. Prerequisites¶
A 64-bit Java Runtime Environment (JRE) are needed to run DSS scripts.
7.9.2. 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]\ccs\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.
Example:
> dss myscript.js scriptParam1 scriptParam2
The above example has the path to batch/shell script in the system PATH so the dss script can be called from anywhere.
7.9.3. Examples¶
DSS ships with several examples. These examples are located in:
[INSTALL DIR\]\ccs\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.
- Loadti (loadti) - a generic command-line loader which can load/run an executable .out file on TI targets.
- Test Server (TestServer) - demonstrates how to use DSS to set-up a debug test server and have remote clients send debug commands via TCP/IP socket connection.
Availability of examples vary per CCS version
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.
7.9.4. DSS API¶
References to the full DSS API documentation can be found in: [INSTALL DIR]\ccs\ccs_base\scripting\docs\GettingStarted.htm
7.9.5. Target Configuration¶
The Target Configuration File needs to be specified to DSS before attempting to start a debug session. This is done by passing in a target configuration (.ccxml) file to the setConfig() API. The CCS Target Setup tool can be used to create a new target configuration file.
7.9.6. 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).
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
}
7.9.7. Using GEL¶
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()");
7.9.8. 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!");
...
7.9.9. 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:
More information on XSLT (including information on how to create your own) can be found on this XSLT Tutorial site.
7.9.10. 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).
7.9.11. Download¶
DSS comes bundled with CCS Theia. It is not possible to get a standalone "DSS only" installer.
7.9.12. Training¶
- DSS Fundamentals Workshop: English | Chinese (中文).
Note
If you are using a proxy, you may need to set your proxy settings under General Settings.