Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat (limited to 'docs/TCF Service - Expressions.html')
-rw-r--r--docs/TCF Service - Expressions.html476
1 files changed, 476 insertions, 0 deletions
diff --git a/docs/TCF Service - Expressions.html b/docs/TCF Service - Expressions.html
index f8e919651..9a40bc01c 100644
--- a/docs/TCF Service - Expressions.html
+++ b/docs/TCF Service - Expressions.html
@@ -12,6 +12,15 @@
<li><a href='#VersionHistory'>Version History</a>
<li><a href='#Overview'>Overview</a>
<li><a href='#Cmds'>Commands</a>
+ <ul>
+ <li><a href='#CmdGetContext'>Get Context</a>
+ <li><a href='#CmdGetChildren'>Get Children</a>
+ <li><a href='#CmdCreate'>Create</a>
+ <li><a href='#CmdCreateInScope'>Create In Scope</a>
+ <li><a href='#CmdDispose'>Dispose</a>
+ <li><a href='#CmdEvaluate'>Evaluate</a>
+ <li><a href='#CmdAssign'>Assign</a>
+ </ul>
<li><a href='#API'>API</a>
</ul>
@@ -32,14 +41,481 @@
<h2><a name='Overview'>Overview</a></h2>
+<p>Expressions service allows TCF client to perform expression evaluation on remote target.
+The service can be used to retrieve or modify values of variables or any data structures in remote target memory.</p>
+
+<p>After expression is created using either <a href='#CmdCreate'>Create</a> or <a href='#CmdCreateInScope'>Create In Scope</a> command,
+it can be evaluated multiple times, for example, each time the target is suspended. If an expression denotes a storage location, it can be used in
+<a href='#CmdAssign'>Assign</a> command to change stored value. When expression is not needed anymore, it should be disposed using
+<a href='#CmdDispose'>Dispose</a> command.</p>
+
+<p>Expressions syntax is extended C/C++ syntax. Extensions to regular C/C++ syntax are:</p>
+<ol>
+ <li>Special characters in identifiers: <b>$"X"</b>, or just <b>"X"</b> if followed by ::, where X is object name that can contain any characters.
+ <li>Symbol IDs in expressions: <b>${X}</b>, where X is symbol ID as returned by the <a href='TCF Service - Symbols.html'>Symbols Service</a>.
+ <li>CPU registers: <b>$X</b>, where X is a register name, e.g. $ax
+ <li>Debug print function: <b>$printf(fmt, ...)</b>, see <a href='TCF Service - Debug Print.html'>Debug Print Service</a>.
+ <li>Debug context ID: <b>$thread</b>, current context ID, same as returned by the <a href='TCF Service - Run Control.html'>Run Control Service</a>.
+ <li>OS loader breakpoint address: <b>$loader_brk</b>
+ <li>OS loader state address: <b>$loader_state</b>
+</ol>
+
<p>The service uses standard format for error reports,
see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p>
<h2><a name='Cmds'>Commands</a></h2>
+<h3><a name='CmdGetContext'>Get Context</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C &bull; <i>&lt;token&gt;</i> &bull; Expressions &bull; getContext &bull; <i>&lt;string: context ID&gt;</i> &bull;
+</font></b></pre>
+
+<p>The command retrieves expression context info for given context ID</p>
+
+<p>Reply:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R &bull; <i>&lt;token&gt;</i> &bull; <i>&lt;error report&gt;</i> &bull; <i>&lt;context data&gt;</i> &bull;
+
+<i>&lt;context data&gt;</i>
+ &rArr; null
+ &rArr; <i>&lt;object&gt;</i>
+</font></b></pre>
+
+<p>Context data object should, at least, contain member
+<b><font face="Courier New" size=2 color=#333399>"ID" : <i>&lt;string&gt;.</i></font></b>
+Context data is expected to be cached by clients.</p>
+
+<p>Predefined expression context properties are:</p>
+<ul>
+ <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i>&lt;string&gt;</i></font></b></code>
+ - ID of the context, same as getContext command argument.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"ParentID" : <i>&lt;string&gt;</i></font></b></code>
+ - ID of a parent context.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"" : <i>&lt;&gt;</i></font></b></code>
+ - .
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"" : <i>&lt;&gt;</i></font></b></code>
+ - .
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"" : <i>&lt;&gt;</i></font></b></code>
+ - .
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"" : <i>&lt;&gt;</i></font></b></code>
+ - .
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"" : <i>&lt;&gt;</i></font></b></code>
+ - .
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"" : <i>&lt;&gt;</i></font></b></code>
+ - .
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"" : <i>&lt;&gt;</i></font></b></code>
+ - .
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"" : <i>&lt;&gt;</i></font></b></code>
+ - .
+
+</ul>
+
+<h3><a name='CmdGetChildren'>Get Children</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C &bull; <i>&lt;token&gt;</i> &bull; Expressions &bull; getChildren &bull; <i>&lt;string: parent context ID&gt;</i> &bull;
+</font></b></pre>
+
<h2><a name='API'>API</a></h2>
<pre>
+<font color=#3F5FBF>/**
+ * Expressions service allows TCF client to perform expression evaluation on remote target.
+ * The service can be used to retrieve or modify values of variables or any data structures in remote target memory.
+ *
+ * @noimplement This interface is not intended to be implemented by clients.
+ */</font>
+<font color=#7F0055>public interface</font> IExpressions <font color=#7F0055>extends</font> IService {
+
+ <font color=#3F5FBF>/**
+ * Service name.
+ */</font>
+ <font color=#7F0055>static final</font> String NAME = "Expressions";
+
+ <font color=#3F5FBF>/**
+ * Expression object represent an expression that can be evaluated by remote target.
+ * It has a unique ID and contains all information necessary to compute a value.
+ * The object data usually includes:
+ * 1. process, thread or stack frame ID that should be used to resolve symbol names;
+ * 2. a script that can compute a value, like "x.y + z"
+ */</font>
+ <font color=#7F0055>interface</font> Expression {
+ <font color=#3F5FBF>/**
+ * Get context ID.
+ * @return context ID.
+ */</font>
+ String getID();
+
+ <font color=#3F5FBF>/**
+ * Get parent context ID.
+ * @return parent context ID.
+ */</font>
+ String getParentID();
+
+ <font color=#3F5FBF>/**
+ * Get expression script language ID.
+ * @return language ID.
+ */</font>
+ String getLanguage();
+
+ <font color=#3F5FBF>/**
+ * Return expression string - the script part of the context.
+ * @return expression script string
+ */</font>
+ String getExpression();
+
+ <font color=#3F5FBF>/**
+ * Return symbol ID if the expression represents a symbol (e.g. local variable).
+ * @return symbol ID
+ */</font>
+ String getSymbolID();
+
+ <font color=#3F5FBF>/**
+ * Get size of expression value in bits.
+ * Can be 0 if value size is even number of bytes, use getSize() in such case.
+ * @return size in bits.
+ */</font>
+ <font color=#7F0055>int</font> getBits();
+
+ <font color=#3F5FBF>/**
+ * Get size in bytes. The size can include extra (unused) bits.
+ * This is "static" or "declared" size - as determined by expression type.
+ * @return size in bytes.
+ */</font>
+ <font color=#7F0055>int</font> getSize();
+
+ <font color=#3F5FBF>/**
+ * Get expression type ID. Symbols service can be used to get type properties.
+ * This is "static" or "declared" type ID, actual type of a value can be different -
+ * if expression language supports dynamic typing.
+ * @return type ID.
+ */</font>
+ String getTypeID();
+
+ <font color=#3F5FBF>/**
+ * Check if the expression can be assigned a new value.
+ * @return true if can assign.
+ */</font>
+ <font color=#7F0055>boolean</font> canAssign();
+
+ <font color=#3F5FBF>/**
+ * Check if the expression contains target function call.
+ * Such expression can resume the target when evaluated.
+ * @return true if has a function call.
+ */</font>
+ <font color=#7F0055>boolean</font> hasFuncCall();
+
+ <font color=#3F5FBF>/**
+ * Get complete map of context properties.
+ * @return map of context properties.
+ */</font>
+ Map&lt;String,Object&gt; getProperties();
+ }
+
+ <font color=#3F5FBF>/**
+ * Expression context property names.
+ */</font>
+ <font color=#7F0055>static final</font> String
+ PROP_ID = "ID",
+ PROP_PARENT_ID = "ParentID",
+ PROP_SYMBOL_ID = "SymbolID",
+ PROP_LANGUAGE = "Language",
+ PROP_EXPRESSION = "Expression",
+ PROP_BITS = "Bits",
+ PROP_SIZE = "Size",
+ PROP_TYPE = "Type",
+ PROP_CAN_ASSIGN = "CanAssign",
+ PROP_HAS_FUNC_CALL = "HasFuncCall";
+
+ <font color=#3F5FBF>/**
+ * Expression scope attributes.
+ * @since 1.2
+ */</font>
+ <font color=#7F0055>static final</font> String
+ SCOPE_CONTEXT_ID = "ContextID",
+ SCOPE_ADDRESS = "Address",
+ SCOPE_LANGUAGE = "Language";
+
+ <font color=#3F5FBF>/**
+ * Value represents result of expression evaluation.
+ * Note that same expression can be evaluated multiple times with different results.
+ * @noimplement This interface is not intended to be implemented by clients.
+ */</font>
+ <font color=#7F0055>interface</font> Value {
+
+ <font color=#3F5FBF>/**
+ * Get value type class.
+ * @see ISymbols.TypeClass
+ * @return
+ */</font>
+ ISymbols.TypeClass getTypeClass();
+
+ <font color=#3F5FBF>/**
+ * Get value type ID. Symbols service can be used to get type properties.
+ * @return type ID.
+ */</font>
+ String getTypeID();
+
+ <font color=#3F5FBF>/**
+ * Check endianness of the values.
+ * Big-endian means decreasing numeric significance with increasing byte number.
+ * @return true if big-endian.
+ */</font>
+ <font color=#7F0055>boolean</font> isBigEndian();
+
+ <font color=#3F5FBF>/**
+ * Implicit pointer means that the value represents a pointer,
+ * which value is unknown or optimized away,
+ * even though the value it would point to is known.
+ * @return true if the value is implicit pointer.
+ * @since 1.3
+ */</font>
+ <font color=#7F0055>boolean</font> isImplicitPointer();
+
+ <font color=#3F5FBF>/**
+ * Return register ID if the value represents register variable.
+ * @return register ID or null.
+ */</font>
+ String getRegisterID();
+
+ <font color=#3F5FBF>/**
+ * Return symbol ID if the value represents a symbol.
+ * @return symbol ID or null.
+ */</font>
+ String getSymbolID();
+
+ <font color=#3F5FBF>/**
+ * Return value memory address, if applicable.
+ * @return address or null.
+ */</font>
+ Number getAddress();
+
+ <font color=#3F5FBF>/**
+ * Get value as array of bytes.
+ * @return value as array of bytes.
+ */</font>
+ <font color=#7F0055>byte</font>[] getValue();
+
+ <font color=#3F5FBF>/**
+ * Get complete map of value properties.
+ * @return map of value properties.
+ */</font>
+ Map&lt;String,Object&gt; getProperties();
+ }
+
+ <font color=#3F5FBF>/**
+ * Expression value property names.
+ */</font>
+ <font color=#7F0055>static final</font> String
+ VAL_CLASS = "Class",
+ VAL_TYPE = "Type",
+ VAL_BIG_ENDIAN = "BigEndian",
+ VAL_REGISTER = "Register",
+ VAL_SYMBOL = "Symbol",
+ VAL_ADDRESS = "Address";
+ <font color=#3F5FBF>/** @since 1.3 */</font>
+ <font color=#7F0055>static final</font> String
+ VAL_BINARY_SCALE = "BinaryScale",
+ VAL_DECIMAL_SCALE = "DecimalScale",
+ VAL_IMPLICIT_POINTER = "ImplicitPointer",
+ VAL_PIECES = "Pieces";
+ <font color=#3F5FBF>/** @since 1.4 */</font>
+ <font color=#7F0055>static final</font> String
+ VAL_BIT_STRIDE = "BitStride";
+
+ <font color=#3F5FBF>/**
+ * Retrieve expression context info for given context ID.
+ * @see Expression
+ *
+ * @param id - context ID.
+ * @param done - call back interface called when operation is completed.
+ * @return - pending command handle.
+ */</font>
+ IToken getContext(String id, DoneGetContext done);
+
+ <font color=#3F5FBF>/**
+ * Client call back interface for getContext().
+ */</font>
+ <font color=#7F0055>interface</font> DoneGetContext {
+ <font color=#3F5FBF>/**
+ * Called when context data retrieval is done.
+ * @param token - command handle
+ * @param error - error description if operation failed, null if succeeded.
+ * @param context - context properties.
+ */</font>
+ <font color=#7F0055>void</font> doneGetContext(IToken token, Exception error, Expression context);
+ }
+
+ <font color=#3F5FBF>/**
+ * Retrieve children IDs for given parent ID.
+ * Meaning of the operation depends on parent kind:
+ * 1. expression with type of a struct, union, or class - fields;
+ * 2. expression with type of an enumeration - enumerators;
+ * 3. expression with type of an array - array elements;
+ * 4. stack frame - function arguments and local variables;
+ * 5. thread - top stack frame function arguments and local variables;
+ * 6. process - global variables;
+ *
+ * Children list does *not* include IDs of expressions that were created by clients
+ * using "create" command.
+ *
+ * @param parent_context_id - parent context ID.
+ * @param done - call back interface called when operation is completed.
+ * @return - pending command handle.
+ */</font>
+ IToken getChildren(String parent_context_id, DoneGetChildren done);
+
+ <font color=#3F5FBF>/**
+ * Client call back interface for getChildren().
+ */</font>
+ <font color=#7F0055>interface</font> DoneGetChildren {
+ <font color=#3F5FBF>/**
+ * Called when context list retrieval is done.
+ * @param token - command handle
+ * @param error - error description if operation failed, null if succeeded.
+ * @param context_ids - array of available context IDs.
+ */</font>
+ <font color=#7F0055>void</font> doneGetChildren(IToken token, Exception error, String[] context_ids);
+ }
+
+ <font color=#3F5FBF>/**
+ * Create an expression context.
+ * The context should be disposed after use.
+ * @param parent_id - a context ID that can be used to resolve symbol names.
+ * @param language - language of expression script, null means default language
+ * @param expression - expression script
+ * @param done - call back interface called when operation is completed.
+ * @return - pending command handle.
+ */</font>
+ IToken create(String parent_id, String language, String expression, DoneCreate done);
+
+ <font color=#3F5FBF>/**
+ * Create an expression context using given scope to resolve symbols.
+ * The context should be disposed after use.
+ * @param scope - see SCOPE_* attribute definitions.
+ * @param expression - expression script
+ * @param done - call back interface called when operation is completed.
+ * @return - pending command handle.
+ * @since 1.2
+ */</font>
+ IToken createInScope(Map&lt;String,Object&gt; scope, String expression, DoneCreate done);
+
+ <font color=#3F5FBF>/**
+ * Client call back interface for create() and createInScope().
+ */</font>
+ <font color=#7F0055>interface</font> DoneCreate {
+ <font color=#3F5FBF>/**
+ * Called when context create context command is done.
+ * @param token - command handle
+ * @param error - error description if operation failed, null if succeeded.
+ * @param context - context properties.
+ */</font>
+ <font color=#7F0055>void</font> doneCreate(IToken token, Exception error, Expression context);
+ }
+
+ <font color=#3F5FBF>/**
+ * Dispose an expression context that was created by create()
+ * @param id - the expression context ID
+ * @param done - call back interface called when operation is completed.
+ * @return - pending command handle.
+ */</font>
+ IToken dispose(String id, DoneDispose done);
+
+ <font color=#3F5FBF>/**
+ * Client call back interface for dispose().
+ */</font>
+ <font color=#7F0055>interface</font> DoneDispose {
+ <font color=#3F5FBF>/**
+ * Called when context dispose command is done.
+ * @param token - command handle
+ * @param error - error description if operation failed, null if succeeded.
+ */</font>
+ <font color=#7F0055>void</font> doneDispose(IToken token, Exception error);
+ }
+
+ <font color=#3F5FBF>/**
+ * Evaluate value of an expression context.
+ * @param id - the expression context ID
+ * @param done - call back interface called when operation is completed.
+ * @return - pending command handle.
+ */</font>
+ IToken evaluate(String id, DoneEvaluate done);
+
+ <font color=#3F5FBF>/**
+ * Client call back interface for evaluate().
+ */</font>
+ <font color=#7F0055>interface</font> DoneEvaluate {
+ <font color=#3F5FBF>/**
+ * Called when context dispose command is done.
+ * @param token - command handle
+ * @param error - error description if operation failed, null if succeeded.
+ * @param value - expression evaluation result
+ */</font>
+ <font color=#7F0055>void</font> doneEvaluate(IToken token, Exception error, Value value);
+ }
+
+ <font color=#3F5FBF>/**
+ * Assign a value to memory location determined by an expression.
+ * @param id - expression ID.
+ * @param value - value as an array of bytes.
+ * @param done - call back interface called when operation is completed.
+ * @return - pending command handle.
+ */</font>
+ IToken assign(String id, <font color=#7F0055>byte</font>[] value, DoneAssign done);
+
+ <font color=#3F5FBF>/**
+ * Client call back interface for assign().
+ */</font>
+ <font color=#7F0055>interface</font> DoneAssign {
+ <font color=#3F5FBF>/**
+ * Called when assign command is done.
+ * @param token - command handle
+ * @param error - error description if operation failed, null if succeeded.
+ */</font>
+ <font color=#7F0055>void</font> doneAssign(IToken token, Exception error);
+ }
+
+ <font color=#3F5FBF>/**
+ * Add expressions service event listener.
+ * @param listener - event listener implementation.
+ */</font>
+ <font color=#7F0055>void</font> addListener(ExpressionsListener listener);
+
+ <font color=#3F5FBF>/**
+ * Remove expressions service event listener.
+ * @param listener - event listener implementation.
+ */</font>
+ <font color=#7F0055>void</font> removeListener(ExpressionsListener listener);
+
+ <font color=#3F5FBF>/**
+ * Registers event listener is notified when registers context hierarchy
+ * changes, and when a register is modified by the service commands.
+ */</font>
+ <font color=#7F0055>interface</font> ExpressionsListener {
+
+ <font color=#3F5FBF>/**
+ * Called when expression value was changed and clients
+ * need to update themselves. Clients, at least, should invalidate
+ * corresponding cached expression data.
+ * Not every change is notified - it is not possible,
+ * only those, which are not caused by normal execution of the debuggee.
+ * At least, changes caused by "assign" command should be notified.
+ * @param id - expression context ID.
+ */</font>
+ <font color=#7F0055>void</font> valueChanged(String id);
+ }
+}
</pre>
</body>

Back to the top