Scripting Console

From Texas Instruments Embedded Processors Wiki

Overview

The Scripting Console is a window in CCStudio v4 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 CCStudio v4. These console commands are JavaScript functions contained in JavaScript files (provided with CCStudio v4) 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

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. These are:

• env: Scripting Environment
• ds: Debug Server
• gss_0: GUI Scripting Server
• ps: Profile Server (deprecated, do not use)
• hotmenu: add and remove GEL and JavaScript hotmenu items

Using the 'services' command will echo the list of services to the console.

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();

If you have already started a debug session manually, there is another service available called 'activeDS'. This service is only available if in an active debug session and it indeed represents the active debug session. Thus there is no need to use the API to open another debug session.

Leverage the existing active debug session (activeDS) in addition to 'env' and 'ds':

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

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

js:> activeDS.target.run();

Note how I not only removed the command to open a debug session ( openSession() ), but I also removed the command to configure it ( setConfig() ). I already have a configured debug session up and running so there is no need to do either.

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

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:

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;
}

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

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

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