8.8.1.1.1.2.6. DebuggerScripting¶

interface DebuggerScripting()¶

Encapsulates the debugger operations for the a given target. This interface is returned by openSession

If the debugger is de-configured, any current Session objects will automatically be invalidated and will refuse any further operations

simultaneous: Simultaneous¶

configure(ccxmlFile: string)¶

Initializes the debugger with the provided ccxml file.

This will not connect to any cores, but will prepare the debugger internally for debugging the configuration specified in the file.

Returns once the debugger is done being configured. This can take some time, especially the first time it is configured for a particular device.

Throws if the debugger is already initialized with a particular configuration. :js:meth:~DebuggerScripting.deconfigure must be called before configuring for a different configuration.

let { cores, nonDebugCores } = ds.configure("my_configuration.ccxml");

Parameters:

ccxmlFile (string) -- The ccxml file to be used

Returns:

The same value as DebuggerRootObject.listCores()

Return type:

CoreList

deconfigure()¶

Invalidates the current debugger configuration.

It is necessary to call this before switching to a different configuration can be used. The debugger will disconnect from all cores and invalidate any active debug session objects.

ds.deconfigure();

Returns:: once the debugger is done being deconfigured.
Return type:: void

listCores()¶

Get the names of the currently configured debuggable, and non-debuggable cores.

// Open a debug session to the first debuggable core
let { cores, nonDebugCores } = ds.listCores();
let session = ds.openSession(cores[0]);

Returns:: The device's cores, split into two lists, one for debuggable cores, and the other for non-debuggable cores.
Return type:: CoreList

setVariables(variables: Record<string, string>)¶

Provide a mapping of variable names and values to be substituted in string-valued settings, and select other contexts. Variables are specified in string-valued settings using the format ${...}.

session.settings.set(id, "abc${MY_VAR}xyz");
session.settings.get(id); // returns "abc${MY_VAR}xyz"

ds.setVariables({ MY_VAR: "123" });
session.settings.get(id); // returns "abc123xyz"

session.settings.set(id, "xyz${MY_VAR}");
session.settings.get(id); // returns "xyz123"

Parameters:

variables (Record) -- The mapping of variable names to values

Return type:

void

settingsVariableSubstitutions(variables: Record<string, string>)¶

Deprecated. Use :js:meth:~DebuggerRootObject.setVariables instead.

Parameters:

variables (Record) -- The mapping of variable names to values

Return type:

void

substituteVariables(text: string)¶

Substitute variables in a string using the variables set using :js:meth:~DebuggerRootObject.setVariables. Variables are specified in string setting values using the format ${...}. Variables which are not defined are not substituted.

ds.setVariables({ MY_VAR: "123" });
ds.substituteVariables("abc${MY_VAR}xyz"); // returns "abc123xyz"
ds.substituteVariables("abc${DOES_NOT_EXIST}xyz"); // returns "abc${DOES_NOT_EXIST}xyz"

Parameters:

text (string) -- The string in which variables should be substituted.

Returns:

The string with variables substituted.

Return type:

string

getVariable(variableName: string)¶

Query the value of a variable set using :js:meth:~DebuggerRootObject.setVariables.

ds.setVariables({ MY_VAR: "123" });
ds.getVariable("MY_VAR"); // returns "123"
ds.getVariable("DOES_NOT_EXIST"); // returns ""

Parameters:

variableName (string) -- The name of the variable to query.

Returns:

The value of the variable if it exists, or the empty string.

Return type:

string

openSession(corePattern="")¶

Open a debug session to the specified core on the device for which the debugger is configured.

The names of the cores of the current configuration can be obtained from {@link DebuggerRootObject.listCores}.

Throws if the debugger is not currently configured, or if no matching core is found.

// Specifying an exact name
const session = ds.openSession("Texas Instruments XDS110 USB Debug Probe_0/Cortex_M4_0");

// The first core with CortexM or CortexR anywhere in the name
const session = ds.openSession(/Cortex(M|R)/);
// equivalently
const session = ds.openSession("Cortex(M|R)");

// The first core
const session = ds.openSession();

Parameters:

corePattern (RegExp | string) -- Can be a string or a regular expression. A debug session will be opened to the first core that matches. Defaults to the first core.

Returns:

The DebugSession object

Return type:

DebugSession

openSymbolModule(processorId, isBigEndian=false)¶

Open a session with a new symbol module object. A :ts:class::~SymbolModule provides the ability to inspect symbol files without a hardwaretarget or debug session.

Symbol files loaded by a symbol module will remain in memory until it is closed or until the scripting session is shut down.

const symModule = ds.openSymbolModule(processorId);
// ... make use of the symbol module ...
symModule.close();  // gracefully close the module when no longer needed

Parameters:

processorId (int) -- Magic number that identifies the architecture.
isBigEndian (bool) -- Indicates if the symbol files are for a big endian architecture.

Return type:

SymbolModule

setScriptingTimeout(ms): void()¶

Configure a timeout duration for all future calls to scripting commands.

If a command takes longer to resolve than the timeout duration, a ScriptingTimeoutError will be thrown.

By default, the scripting timeout is disabled.

// Set a 1 second timeout duration
ds.setScriptingTimeout(1000);

// Disable scripting timeout
ds.setScriptingTimeout(0);

Parameters:

ms (number) -- New timeout duration in milliseconds. Positive values will enable the timeout, non-positive values will disable it.

Return type:

void

getScriptingTimeout(): void()¶

Get the current scripting timeout duration.

ds.setScriptingTimeout(10000);
tenSeconds = ds.getScriptingTimeout();  // returns 10000

ds.setScriptingTimeout(0);  // non-positive value, timeout will be disabled
zero = ds.getScriptingTimeout();  // returns 0

Returns:: The timeout duration in milliseconds, or 0 if the timeout is disabled.
Return type:: number

shutdown(): void()¶

Shutdown the scripting session.

This will close the connection to the debugger. If running standalone, the debugger will be shut down. No further commands will be allowed. This should be called at the end of a script to terminate the connection and allow the javascript process to end.

ds.shutdown();

launchCCS(mode = "waitUntilLaunch"): void()¶

Launch an instance of CCS side-by-side with this instance of the debugger. This allows CCS to display the current state of the target while it is controlled by a script, and/or provide a way of interacting with a scripting session.

This will not work with the Eclipse-based version of CCS.

// Launch CCS and wait until it has fully launched
ds.launchCCS();

// Launch CCS and wait until it exits (may be useful for inspecting the current state)
ds.launchCCS("waitUntilExit");

// Launch CCS such that it continues running after shutdown() is called
ds.launchCCS("detached");

Parameters:

mode (("waitUntilLaunch" | "waitUntilExit" | "detached")) -- One of "waitUntilLaunch", "waitUntilExit", or "detached". Defaults to "waitUntilLaunch".

If set to "waitUntilLaunch", launchCCS will wait until the CCS instance is launched, then continue. The CCS instance will be shutdown when the script exits. If set to "waitUntilExit", launchCCS will wait until the CCS instance exits. If set to "detached", launchCCS will wait until the CCS instance is launched, then continue. The CCS instance will not be shutdown when the script exits.