Target Communication Framework Services - Expressions

• Version History
• Overview
• Commands
  • Get Context
  • Get Children
  • Create
  • Create In Scope
  • Dispose
  • Evaluate
  • Assign
• API

Expressions Service

Version History

Overview

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.

After expression is created using either Create or Create In Scope 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 Assign command to change stored value. When expression is not needed anymore, it should be disposed using Dispose command.

Expressions syntax is extended C/C++ syntax. Extensions to regular C/C++ syntax are:

1. Special characters in identifiers: $"X", or just "X" if followed by ::, where X is object name that can contain any characters.
2. Symbol IDs in expressions: ${X}, where X is symbol ID as returned by the Symbols Service.
3. CPU registers: $X, where X is a register name, e.g. $ax
4. Debug print function: $printf(fmt, ...), see Debug Print Service.
5. Debug context ID: $thread, current context ID, same as returned by the Run Control Service.
6. OS loader breakpoint address: $loader_brk
7. OS loader state address: $loader_state

The service uses standard format for error reports, see Error Report Format.

Commands

Get Context

C • <token> • Expressions • getContext • <string: context ID> •

The command retrieves expression context info for given context ID

Reply:

R • <token> • <error report> • <context data> •

<context data>
    ⇒ null
    ⇒ <object>

Context data object should, at least, contain member "ID" : <string>. Context data is expected to be cached by clients.

Predefined expression context properties are:

• "ID" : <string> - ID of the context, same as getContext command argument.
• "ParentID" : <string> - ID of a parent context.
• "SymbolID" : <string> - symbol ID if expression designates a symbol. The symbol ID can be used with Symbols Service to get symbol data.
• "Expression" : <string> - text of the expression.
• "CanAssign" : <boolean> - true if expression designates a storage location, so new value can be assigned (stored) at the location.
• "HasFuncCall" : <boolean> - true if expression cantains a function call, which needs to be executed in the debug context. Evaluation of such expressions resumes and suspends target thread or CPU.
• "Class" : <number> - symbol class of the expression type. See Symbols Service for definition of symbol classes.
• "Type" : <string> - symbol ID of the expression type.
• "Size" : <number> - size (in bytes) of the expression value.

Get Children

C • <token> • Expressions • getChildren • <string: parent context ID> •

Retrieve children IDs for given parent ID. Meaning of the operation depends on parent kind:

1. parent is stack frame: children are function arguments and local variables
2. parent is thread: children are top stack frame function arguments and local variables
3. parent is expression with type of a struct, union, or class: children are symbol IDs of fields
4. parent is expression with type of an enumeration: children are symbol IDs of enumerators

Children list does not include IDs of expressions that were created by clients using "create" command.

Reply:

R • <token> • <error report> • <array: children IDs> •

Create

C • <token> • Expressions • create • <string: parent context ID> • <string: language> • <string: expression> •

Create an expression context. The context should be disposed after use.

"parent context ID" is a context ID that can be used to resolve symbol names. It can be process, thread or stack frame.

"language" - language of expression script, null means default language.

"expression" - the expression script.

Reply:

R • <token> • <error report> • <string: expression context ID> •

Create In Scope

C • <token> • Expressions • createInScope • <object: scope> • <string: expression> •

Create an expression context in a scope. The context should be disposed after use.

"scope" controls symbols resolution and and interpretation of the expression script.

Predefined properties of the expression scope are:

• "ContextID" : <string> - context ID that can be used to resolve symbol names. It can be process, thread or stack frame.
• "Address" : <string> - code instruction address in the parent context. The address identifies compilation unit, function and/or basic block to be used as expression evaluation environment.
• "Language" : <string> - language of expression script.

"expression" - the expression script.

Reply:

R • <token> • <error report> • <string: expression context ID> •

Dispose

C • <token> • Expressions • dispose • <string: expression ID> •

Dispose an expression context that was created by "create" or "createInScope" commands.

Reply:

R • <token> • <error report> •

Evaluate

C • <token> • Expressions • evaluate • <string: expression ID> •

Evaluate value of an expression.

Reply:

R • <token> • <array of bytes: value> • <error report> • <object: value properties> •

Predefined properties of the expression value are:

• "Class" : <number> - symbol class of the expression value type. See Symbols Service for definition of symbol classes.
• "Type" : <string> - symbol ID of the expression value type.
• "Symbol" : <string> - symbol ID if the expression designates a symbol.
• "BitStride" : <number> - if the value is an array, and if the amount of storage allocated to hold each element of the array is different from the amount of storage that is normally allocated to hold an individual object of the indicated element type, then BitStride is the size (in bits) of each element of the array.
• "BinaryScale" : <number> - if the value is a fixed point binary number, BinaryScale is the exponent of the base two scale factor to be applied to the value.
• "DecimalScale" : <number> - if the value is a fixed point decimal number, DecimalScale is the exponent of the base ten scale factor to be applied to the value.
• "ImplicitPointer" : <boolean> - true if the value is result of implicit pointer dereference.
• "Register" : <string> - register ID if the expression designates a register.
• "Address" : <number> - memory address if the expression designates a location in the parent context memory.
• "Pieces" : <array> - TBD
• "BigEndian" : <boolean> - true if the value is big endian.

Assign

C • <token> • Expressions • assign • <string: expression ID> • <array of bytes: value> •

Assign a value to memory location determined by an expression.

Reply:

R • <token> • <error report> •

API

/**
 * 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.
 */
public interface IExpressions extends IService {

    /**
     * This service name, as it appears on the wire - a TCF name of the service.
     */
    static final String NAME = "Expressions";

    /**
     * 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"
     */
    interface Expression {
        /**
         * Get context ID.
         * @return context ID.
         */
        String getID();

        /**
         * Get parent context ID.
         * @return parent context ID.
         */
        String getParentID();

        /**
         * Get expression script language ID.
         * @return language ID.
         */
        String getLanguage();

        /**
         * Return expression string - the script part of the context.
         * @return expression script string
         */
        String getExpression();

        /**
         * Return symbol ID if the expression represents a symbol (e.g. local variable).
         * @return symbol ID
         */
        String getSymbolID();

        /**
         * 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.
         */
        int getBits();

        /**
         * 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.
         */
        int getSize();

        /**
         * 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.
         */
        String getTypeID();

        /**
         * Get expression type class.
         * @return type class.
         */
        ISymbols.TypeClass getTypeClass();

        /**
         * Check if the expression can be assigned a new value.
         * @return true if can assign.
         */
        boolean canAssign();

        /**
         * Check if the expression contains target function call.
         * Such expression can resume the target when evaluated.
         * @return true if has a function call.
         */
        boolean hasFuncCall();

        /**
         * Get complete map of context properties.
         * @return map of context properties.
         */
        Map<String,Object> getProperties();
    }

    /**
     * Expression context property names.
     */
    static final 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_CLASS = "Class",
        PROP_CAN_ASSIGN = "CanAssign",
        PROP_HAS_FUNC_CALL = "HasFuncCall";

    /**
     * Expression scope attributes.
     * @since 1.2
     */
    static final String
        SCOPE_CONTEXT_ID = "ContextID",
        SCOPE_ADDRESS = "Address",
        SCOPE_LANGUAGE = "Language";

    /**
     * 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.
     */
    interface Value {

        /**
         * Get value type class.
         * @see ISymbols.TypeClass
         * @return
         */
        ISymbols.TypeClass getTypeClass();

        /**
         * Get value type ID. Symbols service can be used to get type properties.
         * @return type ID.
         */
        String getTypeID();

        /**
         * Check endianness of the values.
         * Big-endian means decreasing numeric significance with increasing byte number.
         * @return true if big-endian.
         */
        boolean isBigEndian();

        /**
         * 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
         */
        boolean isImplicitPointer();

        /**
         * Return register ID if the value represents register variable.
         * @return register ID or null.
         */
        String getRegisterID();

        /**
         * Return symbol ID if the value represents a symbol.
         * @return symbol ID or null.
         */
        String getSymbolID();

        /**
         * Return value memory address, if applicable.
         * @return address or null.
         */
        Number getAddress();

        /**
         * Get value as array of bytes.
         * @return value as array of bytes.
         */
        byte[] getValue();

        /**
         * Get complete map of value properties.
         * @return map of value properties.
         */
        Map<String,Object> getProperties();
    }

    /**
     * Expression value property names.
     */
    static final String
        VAL_CLASS = "Class",
        VAL_TYPE = "Type",
        VAL_BIG_ENDIAN = "BigEndian",
        VAL_REGISTER = "Register",
        VAL_SYMBOL = "Symbol",
        VAL_ADDRESS = "Address";
    /** @since 1.3 */
    static final String
        VAL_BINARY_SCALE = "BinaryScale",
        VAL_DECIMAL_SCALE = "DecimalScale",
        VAL_IMPLICIT_POINTER = "ImplicitPointer",
        VAL_PIECES = "Pieces";
    /** @since 1.4 */
    static final String
        VAL_BIT_STRIDE = "BitStride";

    /**
     * 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.
     */
    IToken getContext(String id, DoneGetContext done);

    /**
     * Client call back interface for getContext().
     */
    interface DoneGetContext {
        /**
         * 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.
         */
        void doneGetContext(IToken token, Exception error, Expression context);
    }

    /**
     * Retrieve children IDs for given parent ID.
     * Meaning of the operation depends on parent kind:
     * 1. stack frame - function arguments and local variables;
     * 2. thread - top stack frame function arguments and local variables;
     * 3. expression with type of a struct, union, or class - fields;
     * 4. expression with type of an enumeration - enumerators;
     *
     * @param parent_context_id - parent context ID.
     * @param done - call back interface called when operation is completed.
     * @return - pending command handle.
     */
    IToken getChildren(String parent_context_id, DoneGetChildren done);

    /**
     * Client call back interface for getChildren().
     */
    interface DoneGetChildren {
        /**
         * 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.
         */
        void doneGetChildren(IToken token, Exception error, String[] context_ids);
    }

    /**
     * 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.
     */
    IToken create(String parent_id, String language, String expression, DoneCreate done);

    /**
     * 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
     */
    IToken createInScope(Map<String,Object> scope, String expression, DoneCreate done);

    /**
     * Client call back interface for create() and createInScope().
     */
    interface DoneCreate {
        /**
         * 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.
         */
        void doneCreate(IToken token, Exception error, Expression context);
    }

    /**
     * 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.
     */
    IToken dispose(String id, DoneDispose done);

    /**
     * Client call back interface for dispose().
     */
    interface DoneDispose {
        /**
         * Called when context dispose command is done.
         * @param token - command handle
         * @param error - error description if operation failed, null if succeeded.
         */
        void doneDispose(IToken token, Exception error);
    }

    /**
     * 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.
     */
    IToken evaluate(String id, DoneEvaluate done);

    /**
     * Client call back interface for evaluate().
     */
    interface DoneEvaluate {
        /**
         * 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
         */
        void doneEvaluate(IToken token, Exception error, Value value);
    }

    /**
     * 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.
     */
    IToken assign(String id, byte[] value, DoneAssign done);

    /**
     * Client call back interface for assign().
     */
    interface DoneAssign {
        /**
         * Called when assign command is done.
         * @param token - command handle
         * @param error - error description if operation failed, null if succeeded.
         */
        void doneAssign(IToken token, Exception error);
    }

    /**
     * Add expressions service event listener.
     * @param listener - event listener implementation.
     */
    void addListener(ExpressionsListener listener);

    /**
     * Remove expressions service event listener.
     * @param listener - event listener implementation.
     */
    void removeListener(ExpressionsListener listener);

    /**
     * Registers event listener is notified when registers context hierarchy
     * changes, and when a register is modified by the service commands.
     */
    interface ExpressionsListener {

        /**
         * 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.
         */
        void valueChanged(String id);
    }
}