Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

Python Scripting with DSS

From Texas Instruments Wiki
Jump to: navigation, search

Overview

JavaScript is the default scripting language supported by DSS. But because DSS is implemented as a set of Java APIs, any language that supports importing and using Java classes can be used with DSS. Jython is an implementation of Python scripting language written in Java, and hence falls into this category.

Prerequisites

  • CCSv5 (or greater)
  • A installation of Jython (tested with jython 2.5.3 and 2.5.4rc1)
  • Compatible Java Runtime Environment (JRE), depending on the CCS version used (CCS ships with a compatible JRE)
    • Windows (all CCS versions) and Linux (up to CCSv6.1.3) users: Compatible 32-bit JRE
    • MacOS and Linux (CCSv6.2.0 and greater) users: Compatible 64-bit JRE

Setting up the Environment

Before a jython DSS script can be run, the following JAR files need to be added to the CLASSPATH:

  • <CCS BASE DIR>/DebugServer/packages/ti/dss/java/dss.jar
  • <CCS BASE DIR>/DebugServer/packages/ti/dss/java/com.ti.ccstudio.scripting.environment_3.1.0.jar
  • <CCS BASE DIR>/DebugServer/packages/ti/dss/java/com.ti.debug.engine_1.0.0.jar
  • <CCS BASE DIR>/dvt/scripting/dvt_scripting.jar

NOTE: <CCS BASE DIR> refers to the 'ccs_base' directory in the CCS installation:

  • CCSv5: <CCS INSTALL DIR>\ccsv5\ccs_base
  • CCSv6: <CCS INSTALL DIR>\ccsv6\ccs_base
  • CCSv7: <CCS INSTALL DIR>\ccsv7\ccs_base

TIP: This can be done in a batch/shell script to setup the environment before running jython. You can even have the same batch/shell script also run the jython script afterwards to automate everything with the execution of one script

Importing the DSS Java Classes

The DSS Java classes need to be imported by the jython script

from com.ti.debug.engine.scripting import *
from com.ti.ccstudio.scripting.environment import *

Now you can call the DSS APIs in your jython script

Example

Below is an example jython script. It is a port of the Breakpoints.js example javascript that comes with CCS:

from java.lang import *
from java.util import *
from com.ti.debug.engine.scripting import *
from com.ti.ccstudio.scripting.environment import *
 
# Create our scripting environment object - which is the main entry point into any script and
# the factory for creating other Scriptable Servers and Sessions
script = ScriptingEnvironment.instance()
 
# Create a log file in the current directory to log script execution
script.traceBegin("dss_py.xml", "DefaultStylesheet.xsl")
 
# Set our TimeOut
script.setScriptTimeout(15000)
 
# Log everything
script.traceSetConsoleLevel(TraceLevel.ALL)
script.traceSetFileLevel(TraceLevel.ALL)
 
# Get the Debug Server and start a Debug Session
debugServer = script.getServer("DebugServer.1")
debugServer.setConfig("tisim_c64xple.ccxml");
 
debugSession = debugServer.openSession()
 
# Connect to the target
debugSession.target.connect()
 
# Load program
debugSession.memory.loadProgram("modem.out")
 
# 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)
 
# Restart our Target
debugSession.target.restart()
 
# Run if already not automatically halted at main.  Should halt at first BP
if debugSession.expression.evaluate("PC") != main:
	debugSession.target.run()
 
# Using an expression - get the current value of the PC
nPC = debugSession.expression.evaluate("PC")
 
# Verify we halted at the correct address.  Use hex() to convert the
# result to a hex string when logging messages
if nPC == main:
	script.traceWrite("SUCCESS: Halted at correct location")
else:
	script.traceWrite("FAIL: Expected halt at " + hex(address) + ", actually halted at " + hex(nPC))
	script.traceSetConsoleLevel(TraceLevel.INFO)
	script.traceWrite("TEST FAILED!")
	script.traceEnd()
	System.exit(1);
 
# Run again.  Should halt at our breakpoint
debugSession.target.run()
 
#  Using an expression - get the current value of the PC
nPC = debugSession.expression.evaluate("PC")
 
# Verify we halted at the correct address.
if nPC == address:
	script.traceWrite("SUCCESS: Halted at correct location")
else:
	script.traceWrite("FAIL: Expected halt at " + hex(address) + ", actually halted at " + hex(nPC))
	script.traceSetConsoleLevel(TraceLevel.INFO)
	script.traceWrite("TEST FAILED!")
	script.traceEnd()
	System.exit(1);
 
# All done
debugSession.terminate()
debugServer.stop()

Running your Jython Script

You can run your DSS jython script as you would run any jython script.

Example for Jython 2.5.x (Command may differ depending on Jython version)

<JYTHON ROOT>\jython.bat <script name>.py

References