# Target Communication Framework Services - Stack Trace

- Commands
  - Get Context
  - Get Children
- Events
- API

# Stack Trace Service

The service implements thread stack back tracing. Command and event parameters are encoded as zero terminated JSON strings.

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

## Commands

### Get Context

    C • <token> • StackTrace • getContext • <array of context IDs> •

    <array of context IDs>
        Ø null
        Ø [ ]
        Ø [ <context ID list> ]

    <context ID list>
        Ø <string: context ID>
        Ø <context ID list> , <string: context ID>

The command retrieves context info for given context IDs. Command allows to query multiple contexts at once. Stack Trace context represents single stack frame. If target supports more then one stack per thread, each stack is also represented by a separate context.

Reply:

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

    <array of context data>
        Ø null
        Ø [ ]
        Ø [ <context data list> ]

    <context data list>
        Ø <context data>
        Ø <context data list> , <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. Cached context data should by flushed when parent thread is resumed.

Predefined stack trace context properties are:

- `"ID" : <string>` - ID of the context, same as getContext command argument.
- `"ParentID" : <string>` - ID of a parent context.
- `"ProcessID" : <string>` - process ID.
- `"Name" : <string>` - context name if context is a stack
- `"FP" : <number>` - frame pointer - memory address of stack frame
- `"PC" : <number>` - program counter - memory address of instruction that will be executed when thread returns from this stack frame.
- `"ArgsCnt" : <number>` - function arguments count
- `"ArgsAddr" : <number>` - memory address of function arguments
- `"Level" : <number>` - frame level. Bottom most (oldest) frame is level 0.

### Get Children

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

The command retrieves stack trace context list. Parent context usually corresponds to an execution thread. Some targets have more then one stack. In such case children of a thread are stacks, and stack frames are deeper in the hierarchy - they can be retrieved with additional getChildren commands.

The command will fail if parent thread is not suspended. Client can use Run Control service to suspend a thread.

Reply:

    R • <token> • <error report> • <array of context IDs> •

    <array of context IDs>
        Ø null
        Ø [ ]
        Ø [ <context ID list> ]

    <context ID list>
        Ø <string: context ID>
        Ø <context ID list> , <string: context ID>

## Events

No events are currently defined for Stack Trace service.

## API

    public interface IStackTrace extends IService {

        static final String NAME = "StackTrace";

        /**
         * Context property names.
         */
        static final String
            PROP_ID = "ID",
            PROP_PARENT_ID = "ParentID",
            PROP_PROCESS_ID = "ProcessID",
            PROP_NAME = "Name",
            PROP_FRAME_ADDRESS = "FP",
            PROP_PROGRAM_COUNTER = "PC",
            PROP_ARGUMENTS_COUNT = "ArgsCnt",
            PROP_ARGUMENTS_ADDRESS = "ArgsAddr",
            PROP_LEVEL = "Level";

        /**
         * Retrieve context info for given context IDs.
         *
         * The command will fail if parent thread is not suspended.
         * Client can use Run Control service to suspend a thread.
         *
         * @param id – array of context IDs.
         * @param done - call back interface called when operation is completed.
         */
        IToken getContext(String[] id, DoneGetContext done);

        /**
         * Client call back interface for getContext().
         */
        interface DoneGetContext {
            /**
             * Called when context data retrieval is done.
             * @param error – error description if operation failed, null if succeeded.
             * @param context – array of context data or null if error.
             */
            void doneGetContext(IToken token, Exception error, StackTraceContext[] context);
        }

        /**
         * Retrieve stack trace context list.
         * Parent context usually corresponds to an execution thread.
         * Some targets have more then one stack. In such case children of a thread
         * are stacks, and stack frames are deeper in the hierarchy - they can be
         * retrieved with additional getChildren commands.
         *
         * The command will fail if parent thread is not suspended.
         * Client can use Run Control service to suspend a thread.
         *
         * @param parent_context_id – parent context ID.
         * @param done - call back interface called when operation is completed.
         */
        IToken getChildren(String parent_context_id, DoneGetChildren done);

        /**
         * Client call back interface for getChildren().
         */
        interface DoneGetChildren {
            /**
             * Called when context list retrieval is done.
             * @param error – error description if operation failed, null if succeeded.
             * @param context_ids – array of available context IDs.
             * Stack frames are ordered from stack bottom to top.
             */
            void doneGetChildren(IToken token, Exception error, String[] context_ids);
        }

        /**
         * StackTraceContext represents stack trace objects - stacks and stack frames.
         */
        interface StackTraceContext {

            /**
             * Get Context ID.
             * @return context ID.
             */
            String getID();

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

            /**
             * Get context name - if context represents a stack.
             * @return context name or null.
             */
            String getName();

            /**
             * Get memory address of this frame.
             * @return address or null if not a stack frame.
             */
            Number getFrameAddress();

            /**
             * Get program counter saved in this stack frame -
             * it is address of instruction to be executed when the function returns.
             * @return program counter or null if not a stack frame.
             */
            Number getProgramCounter();

            /**
             * Get number of function arguments for this frame.
             * @return function arguments count.
             */
            int getArgumentsCount();

            /**
             * Get address of function arguments area in memory.
             * @return function arguments address or null if not available.
             */
            Number getArgumentsAddress();

            /**
             * Get stack frame level.
             * @return frame level or 0 if not a stack frame.
             */
            int getLevel();

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