Customizing a Debug Session

Overview

This is a placeholder for customizing a Debug Session.

• Add the Export Settings method of saving existing configurations
• Add the loadJSFile method to add a Scripts menu entry
  • https://e2e.ti.com/support/development_tools/code_composer_studio/f/81/t/547383
• Add George's video about launching the PRU automatically.
• Reference the GEL Sliders and Input Boxes (perhaps not)
  • http://processors.wiki.ti.com/index.php/GEL#GEL_Hotmenus.2FMenuitems

The Scripting Console is a window, in Eclipse based CCS version, which allows users to specify commands to the IDE through a console. It is a JavaScript shell which will create a DSS scripting environment instance when it is opened. This allows users to call DSS APIs from the console. Full DSS scripts can also be run straight from the console.

The Scripting Console also supports a set of built-in console commands for more commonly used functionality within CCS. These console commands are JavaScript functions contained in JavaScript files (provided with CCS) automatically loaded by the Scripting Console when opened. Most of these JavaScript functions simply wrap DSS/GSS calls underneath to make it easier to automate actions with a single short command (very much like a GEL hotmenu).

Basics

The Scripting Console can be opened using the 'View->Scripting Console' menu option. From the console, a full list of the loaded console commands can be displayed by pressing the 'TAB' button. The 'TAB' button can also be used for partially typed commands in the console for the auto-complete feature. Documentation for each command can be displayed using the 'help' command (js:> help <command>).

Fig. 1: Scripting Console

Examples

Load/save to/from memory

Memory and program load operations such as loadRaw, loadData, loadProg have the basic syntax below.

loadRaw(0x80000000,PAGE_PROGRAM,"C:\\temp\\myFile.bin",32,false)

loadRaw(0x80000000,0,"/temp/myFile.bin",32,true)

• Do not insert spaces between the commas and the parameters inside the parenthesis
• When passing a reference to a file, use double quotes and use C-syntax parameters, including escaping special characters:
• Boolean values must be passed with the constants false and true - these must be in lowercase.
• The constants that designate the memory page of the target are optional: PAGE_PROGRAM, PAGE_DATA and PAGE_IO can be replaced with 0, 1 and 2 respectively.

Memory save operations differ slightly from the above

saveRaw(PAGE_PROGRAM,0x80000000,"C:\\temp\\myFile.bin",0x400,32,false)

• The forward slash syntax for the filename designator does not work in this case.
• The length parameter (0x400 in this example) specifies the total number of elements to be read, which is dependent on the target device. For MSP430, F28x and C55x each element consists of 16 bits or two bytes (in the example above 0x800 bytes will be read). For all other architectures it is 32 bits or four bytes (0x1000 bytes for the example above).

Project Build

For a project build, the project must exist in the workspace.

buildProject("myProject")

buildProject "myProject"

• The return value is always true, regardless of the success of the build.
• When using version control, projects with changes must be preceded with the ">" signal:

buildProject "> myProject"

NOTE: There is a console command called 'eval'. This command differs from the standard JavaScript 'eval' function. Any JavaScript being executed from the Scripting Console using the JavaScript 'eval' will be impacted since the console 'eval' function will override the standard JavaScript function.

Custom Console Commands

In addition to the built-in console commands, custom console commands can be easily created. Simply create a new JavaScript file with a function for the new console command. The body of the function can contain whatever actions you wish the new console command to execute. Once the file is competed and saved, use the 'loadJSFile' console command to load the new JavaScript file. This will allow the function to be called from the Scripting Console and the new custom command will appear in the list of console commands until the Scripting Console is restarted. To have the new JavaScript file automatically loaded by the Scripting Console every time it is opened, set the second argument for loadJSFile to 'true'. When creating custom console commands, it is suggested to reuse the services available from the Scripting Console (see below).

Services

Within the Scripting Console, several services are available to be used from the console. Using the 'services' command will echo the list of services to the console. Many are just used internally and not meant for public use. However, there are some that can be used publicly, such as:

• env: Scripting Environment (this is similar to the scripting environment object that gets returned by the DSS ScriptingEnvironment.instance() call)
• ds: Debug Server (this is similar to the debug server object that gets returned by the ScriptingEnvironment getServer( "DebugServer.1" ) call)
• hotmenu: add and remove GEL and JavaScript hotmenu items (see "Script execution from a menu" section below)

These services can be used with DSS APIs from the console.

For example, instead of calling the APIs to create a Scripting Environment and Debug Server (entry #1 and #3):

js:> script = ScriptingEnvironment.instance();

js:> script.traceBegin("dssLog.xml");

js:> debugServer = script.getServer("DebugServer.1");

js:> debugServer.setConfig("c6416_le_sim.ccxml");

js:> debugSession = debugServer.openSession(".*");

js:> debugSession.memory.loadProgram("myApp.out");

js:> debugSession.target.run();

Leverage the existing services for the Scripting Environment (env) and Debug Server (ds):

js:> env.traceBegin("dssLog.xml");

js:> ds.setConfig("c6416_le_sim.ccxml");

js:> debugSession = ds.openSession(".*");

js:> debugSession.memory.loadProgram("myApp.out");

js:> debugSession.target.run();

These services can also be reused in DSS JavaScript files that are meant to be run from the Scripting Console (such as custom console commands).

Note that these services will not be recognized when running the script outside the Scripting Console.

Running DSS JavaScript Files

The same 'loadJSFile' console command can be used to load and run standalone DSS JavaScript files from the Scripting Console "as-is". The call in the standalone DSS JavaScript to create the scripting environment will attach to the existing scripting environment created by the Scripting Console. If desired, the script can be modified so that it can check to see if it is running from within the Scripting Console or standalone with a condition to leverage the existing services such as 'env', 'ds', and so forth if it is the former:

<syntaxhighlight lang='javascript'>

var ds;

// Check to see if running from within CCSv4 Scripting Console var withinCCS = (ds !== undefined);

// Create scripting environment and get debug server if running standalone if (!withinCCS) {

   // Import the DSS packages into our namespace to save on typing
   importPackage(Packages.com.ti.debug.engine.scripting);
   importPackage(Packages.com.ti.ccstudio.scripting.environment);
   importPackage(Packages.java.lang);

   // Create our scripting environment object - which is the main entry point into any script and
   // the factory for creating other Scriptable ervers and Sessions
   var script = ScriptingEnvironment.instance();

   // Get the Debug Server and start a Debug Session
   debugServer = script.getServer("DebugServer.1");

} else // otherwise leverage existing scripting environment and debug server {

   var debugServer = ds;
   var script = env;

} </syntaxhighlight>

Script execution from a menu

Scripts may contain a command that will create a menu item under "Scripts" menu that will allow execution of that function when menu is pressed. Scripting Console allows to automatically reload scripts when CCS is restarted. This may be accomplished by passing "true" parameter to loadJSFile command. Combining these two features may be used to create scripts that perform complex sequence of tasks with a single user action.

example.js <syntaxhighlight lang='javascript'> function load_out() {

  // Change timeout from the default (infinite) to 15 seconds
  script.setScriptTimeout(30000);
  // Create a log file in the current directory to log script execution
  script.traceBegin("autoRunLog.xml", "DefaultStylesheet.xsl");
  ... //rest of script

}

hotmenu.addJSFunction("Load", "load_out()"); </syntaxhighlight>

Example above will create a 'Load' menu under Scripts that will call load_out function when pressed.

Another example of using the scripts menu to execute a JavaScript function is shown in the quicktip video below: