Java Scripting with DSS

Overview

JavaScript is the default scripting language supported by DSS. But because DSS is implemented as a set of Java APIs, it works quite nicely out of the box with Java. While the provided DSS examples are mostly for JavaScript, the DSS Java API documentation shows examples of API calls with Java code.

Prerequisites

At minimum, a Java compiler (javac) and a Java Runtime Environment (JRE) are needed to build and run the DSS Java application. While CCS comes with a JRE, it does not come with a JDK (which provides a Java compiler). The JDK can be downloaded from the Sun Java SE download site. If a Java IDE (such as Eclipse) will be used to develop the DSS Java application, then a java compiler will already be available.

Creating DSS Java Source

To create a new DSS Java source file, simply create a new Java source file in an editor. If a Java IDE is being used, create a new Java project and add your new Java source file to the project. Refer to the documentation for the available APIs.

Example

Let's take a look at some example code snippets. They are from a straight Java port of the 'Breakpoints.js' JavaScript example that ships with DSS.

First thing that is needed is to import all the necessary DSS packages. the 'Breakpoints' example uses APIs for the Debug Server and the below will import all the necessary packages:

<syntaxhighlight lang='java'> // Import all DSS packages for the Debug Server import com.ti.ccstudio.scripting.environment.*; import com.ti.debug.engine.scripting.*; </syntaxhighlight>

The first action done my the main() method is to create a scripting instance:

<syntaxhighlight lang='java'> ...

public class DssBreakpointsExample {

   public static void main(String[] args)
   {

// Create our scripting environment object - which is the main entry point into any script and

       // the factory for creating other Scriptable ervers and Sessions
       ScriptingEnvironment env = ScriptingEnvironment.instance();

       ...

</syntaxhighlight>

Let's look at how the a debug server instance is created and a debug session is started. Since most DSS APIs can throw exceptions, note how the calls are in a 'try-catch' block;

<syntaxhighlight lang='java'>

       ...

       DebugServer debugServer = null;

DebugSession debugSession = null;

try { // Get the Debug Server and start a Debug Session debugServer = (DebugServer) env.getServer("DebugServer.1"); debugServer.setConfig("C:/ti/ccsv6/ccs_base/scripting/examples/C64/tisim_c64xple.ccxml"); debugSession = debugServer.openSession(".*");

           // Load a program

debugSession.memory.loadProgram("C:/ti/ccsv6/ccs_base/scripting/examples/C64/modem/Debug/modem.out"); } catch (Exception e) {

           ...

</syntaxhighlight>

Let's look at one more snippet, somewhere in the middle, of breakpoints being set:

<syntaxhighlight lang='java'>

       ...

try {

           // Set a breakpoint at "main"
           main = debugSession.symbol.getAddress("main");
           bp1 = debugSession.breakpoint.add(main);

           // Set another breakpoint
           address = debugSession.symbol.getAddress("ReadNextData");
           bp2 = debugSession.breakpoint.add(address);

           ...

</syntaxhighlight>

And so forth. To see what the rest of the functionality of the example is, refer to the 'Breakpoints.js' JavaScript example that ships with DSS. As an exercise, try to do a complete port of it yourself! The file should be saved as 'DssBreakpointsExample.java'.

Compiling

Once all the code has been written, next is to build it. When calling the java compiler, the following JAR files must be passed in with the '-classpath' (or '-cp') option:

• com.ti.ccstudio.scripting.environment_3.1.0.jar
• com.ti.debug.engine_1.0.0.jar
• dss.jar

The JAR files can be found in:

• CCSv4: '<INSTALL DIR>\ccsv4\DebugServer\packages\ti\dss\java'
• CCSv5 and greater: '<INSTALL DIR>\ccsv[x]\ccs_base\DebugServer\packages\ti\dss\java'

If building from a JAVA IDE, add the above JAR files to the list of external JAR in the project settings.

Below is an example of building the 'DssBreakpointsExample.java' file from the command line (with CCSv6):

> javac -cp "C:\ti\ccsv6\ccs_base\DebugServer\packages\ti\dss\java\com.ti.ccstudio.scripting.environment_3.1.0.jar";C:\ti\ccsv6\ccs_base\DebugServer\packages\ti\dss\java\com.ti.debug.engine_1.0.0.jar";"C:\ti\ccsv6\ccs_base\DebugServer\packages\ti\dss\java\dss.jar" DssBreakpointsExample.java

This will generate the 'DssBreakpointsExample.class' file. Note that the above example has '<JDK INSTALL>\bin' added to the system PATH so 'javac.exe' can be called from anywhere.

Running

Once the *.class file has been generated, the application can be run. Before running, two paths must be added to the system PATH:

• CCSv4:
  • <INSTALL DIR>\ccsv4\common\bin
  • <INSTALL DIR>\ccsv4\common\uscif

• CCSv5 and greater:
  • <INSTALL DIR>\ccsv[x]\ccs_base\common\bin
  • <INSTALL DIR>\ccsv[x]\ccs_base\common\uscif

Ex (with CCSv6):

> set PATH=%PATH%;"C:\ti\ccsv6\ccs_base\common\bin;"C:\ti\ccsv6\ccs_base\common\uscif

Now the application can be run. When calling 'java.exe':

• CCSv4 ONLY: set the 'XPCOM.RUNTIME' system property needs to '<INSTALL DIR>\ccsv4\DebugServer\win32' with the '-D' option
• ALL: Set the classpath to include:
  • Path to the 'dss.jar' file
  • Path to 'com.ti.ccstudio.scripting.environment.*.jar' (<INSTALL DIR>\ccsv6\ccs_base\DebugServer\packages\ti\dss\java)
  • Path to the *.class file being run

The following will run the example DSS Java 'DssBreakpointsExample' application (with CCSv6):

> java -cp ".";"C:\ti\ccsv6\ccs_base\DebugServer\packages\ti\dss\java\dss.jar";"C:\ti\ccsv6\ccs_base\DebugServer\packages\ti\dss\java" DssBreakpointsExample

Using DVT APIs

When using DVT API calls:

• Add an additional line to the list of imported packages in your code:

<syntaxhighlight lang='java'> import com.ti.dvt.engine.scripting.*; </syntaxhighlight>

• Add the following DVT JAR files to the classpath (along with the other JAR files) that is passed to the Java compiler:
  • dvt_scripting.jar

The DVT JAR file can be found in:

• CCSv4: '<INSTALL DIR>\ccsv4\dvt\scripting'
• CCSv5 and CCSv6: '<INSTALL DIR>\ccsv[x]\ccs_base\dvt\scripting'
• CCSv7 and greater: DVT scripting is not supported

• When running the application, add the 'dvt.jar' file to the classpath that is passed to 'java.exe'.

Ex (with CCSv6):

<syntaxhighlight lang='dos'> > java -cp ".";"C:\ti\ccsv6\ccs_base\DebugServer\packages\ti\dss\java\dss.jar";"C:\ti\ccsv6\ccs_base\DebugServer\packages\ti\dss\java";"C:\ti\ccsv6\ccs_base\dvt\scripting\dvt.jar" DssDvtExample </syntaxhighlight>