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

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

7.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 will know to find it. The static analysis tools will pick up the module's type definitions and highlight any type issues. This should highlight most areas where changes are needed.

7.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(".*");

7.8.2.4. Command changes

I will use env, ds and session to denote the scripting environment object, the DebugServer object, and a debug session object. Note that there is no scripting environment object in the new 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.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