8.8.2. Migrating Legacy DSS Scripts

In general, scripting of the debugger is similar. However, legacy DSS scripts are not compatible with the new CCS Scripting solution.

This guide will highlight the major changes that we expect most scripts may need to consider. It is not a comprehensive list of all differences that advanced use cases will encounter, nor will it cover every detail of API changes. Please consult the API docs which can be found in <ccs root>/ccs/scripting/docs/.

8.8.2.1. Differences between the JavaScript environment

DSS ran in Rhino, a JavaScript environment implemented in Java. The new CCS Scripting solution runs in a Node.js environment. There are many differences between the two environments. Some minor, and some very significant. Major differences are highlighted below, consult Node.js documentation for more details.

• Node.js has support for many modern JavaScript features that Rhino did not support.

• Behavior related to assignment of undeclared variables and scope of global variables may be different.

• Rhino supported importing Java packages, Node.js does not.

• Importing other JavaScript files is different.

• In Rhino, large numbers values are returned as Java longs, whereas in the new scripting solution they are returned as BigInts.

• Printing to the console is done with console.log rather than print.

• Exiting the process is done with process.exit instead of java.lang.System.exit.

• File system access, in general, is different.

• Accessing command line arguments is done with process.argv instead of arguments.

8.8.2.2. Imports

DSS scripts had to import a few packages.

importPackage(Packages.com.ti.debug.engine.scripting)
importPackage(Packages.com.ti.ccstudio.scripting.environment)
importPackage(Packages.java.lang)

In the new CCS Scripting solution it is not necessary to import anything if using the run.bat or run.sh scripts provided with CCS. For more advanced use cases, the scripting node module in ccs/scripting/node_modules can be imported with

const { initScripting } = require("scripting");

When the scripting module is explicitly imported, it is possible to get assistance from static analysis tools in VS Code. Make sure the node_modules folder is in a location where VS Code can find it. The static analysis tools will pick up the module's type definitions and highlight any type issues. This will highlight most areas where changes are needed.

8.8.2.3. Launching a scripting session

DSS

importPackage(Packages.com.ti.debug.engine.scripting)
importPackage(Packages.com.ti.ccstudio.scripting.environment)
importPackage(Packages.java.lang)

var env = ScriptingEnvironment.instance()
var ds = script.getServer("DebugServer.1")
var session = ds.openSession(".*")

CCS Scripting

const ds = initScripting();
const session = ds.openSession(".*");

8.8.2.4. Command changes

env, ds and session will be used to denote the scripting environment object, the DebugServer object, and a debug session object respectively. Note that there is no scripting environment object in the new CCS Scripting solution. Many commands are identical, but some have changed. The table below highlights the major changes to the most used scripting commands. Anything that is not mentioned here is either unchanged or has no equivalent.

DSS	CCS Scripting
env.setScriptTimeout	ds.setScriptingTimeout
env.getScriptTimeout	ds.getScriptingTimeout
env.traceBegin	No equivalent
traceSetConsoleLevel	No equivalent
env.traceWrite	No equivalent
ds.setConfig	ds.configure
ds.getListOfCPUs	ds.listCores
ds.stop	ds.deconfigure
ds.simultaneous	Sessions are specified differently, see API documentation.
session.breakpoint	session.breakpoints (note the 's')
session.breakpoint.loadConfig	No equivalent
session.breakpoint.saveConfig	No equivalent
session.breakpoint.createProperties	Many changes, see API documentation
session.expression	session.expressions (note the 's')
session.flash	Largely identical, use performOperation for missing commands.
session.getCPUName	session.getName
session.memory.getSupportedTypes	session.memory.getSupportedFormats
session.memory.map	No equivalent
session.memory.readRegister	session.registers.read
session.memory.writeRegister	session.registers.write
session.memory.readData	session.memory.read*, session.memory.readOne*
session.memory.readWord	session.memory.read*, session.memory.readOne*
session.memory.writeData	session.memory.write*
session.memory.writeWord	session.memory.write*
session.memory.save	No equivalent
session.memory.load	No equivalent
session.memory.saveData	session.memory.saveData*
session.memory.saveData2	session.memory.saveData*
session.memory.loadData	session.memory.loadData*
session.memory.loadData2	session.memory.loadData*
session.memory.saveBinary	session.memory.saveBinary*
session.memory.saveRaw	session.memory.saveBinary*
session.memory.loadBinary	session.memory.loadBinary*
session.memory.loadRaw	session.memory.loadBinary*
session.options	Many changes, see API documentation
session.settings	Many changes, see API documentation
session.symbol	session.symbols (note the 's')
session.target.restart	No equivalent
session.target.runAsynch	session.target.run(false)
session.target.asmStep	session.target.stepInto
session.target.contextStep	session.target.stepOver
session.target.sourceStep	session.target.stepOut
session.terminate	session.close (optional, ds.deconfigure will close all sessions)

* Arguments have changed