TCF Docs: improved specifications of TCF services

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>