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.lograther thanprint. - Exiting the process is done with
process.exitinstead ofjava.lang.System.exit. - File system access, in general, is different
- Accessing command line arguments is done with
process.argvinstead ofarguments.
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