| /******************************************************************************* |
| * Copyright (c) 2007-2021 Wind River Systems, Inc. and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License 2.0 |
| * which accompanies this distribution, and is available at |
| * https://www.eclipse.org/legal/epl-2.0/ |
| * |
| * Contributors: |
| * Wind River Systems - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.tcf.services; |
| |
| import java.util.Collection; |
| import java.util.Map; |
| |
| import org.eclipse.tcf.protocol.IService; |
| import org.eclipse.tcf.protocol.IToken; |
| |
| /** |
| * Run Control service provides basic run control operations for execution contexts on a target. |
| * |
| * @noimplement This interface is not intended to be implemented by clients. |
| */ |
| public interface IRunControl extends IService { |
| |
| /** |
| * This service name, as it appears on the wire - a TCF name of the service. |
| */ |
| static final String NAME = "RunControl"; |
| |
| /* Context property names ---------------------------------------------- */ |
| |
| static final String |
| /** Run control context ID */ |
| PROP_ID = "ID", |
| |
| /** Context parent (owner) ID, for a thread it is same as process ID */ |
| PROP_PARENT_ID = "ParentID", |
| |
| /** Context process (memory space) ID */ |
| PROP_PROCESS_ID = "ProcessID", |
| |
| /** ID of a context that created this context */ |
| PROP_CREATOR_ID = "CreatorID", |
| |
| /** Human readable context name */ |
| PROP_NAME = "Name", |
| |
| /** true if the context is a container. Container can propagate run control commands to his children */ |
| PROP_IS_CONTAINER = "IsContainer", |
| |
| /** true if context has execution state - can be suspended/resumed */ |
| PROP_HAS_STATE = "HasState", |
| |
| /** Bit-set of RM_ values that are supported by the context */ |
| PROP_CAN_RESUME = "CanResume", |
| |
| /** Bit-set of RM_ values that can be used with count > 1 */ |
| PROP_CAN_COUNT = "CanCount", |
| |
| /** true if suspend command is supported by the context */ |
| PROP_CAN_SUSPEND = "CanSuspend", |
| |
| /** true if terminate command is supported by the context */ |
| PROP_CAN_TERMINATE = "CanTerminate", |
| |
| /** true if detach command is supported by the context */ |
| PROP_CAN_DETACH = "CanDetach", |
| |
| /** Context ID of a run control group that contains the context. |
| * Members of same group are always suspended and resumed together: |
| * resuming/suspending a context resumes/suspends all members of the group */ |
| PROP_RC_GROUP = "RCGroup", |
| |
| /** Context ID of a breakpoints group that contains the context. |
| * Members of same group share same breakpoint instances: |
| * a breakpoint is planted once for the group, no need to plant |
| * the breakpoint for each member of the group */ |
| PROP_BP_GROUP = "BPGroup", |
| |
| /** Context ID of a symbols group that contains the context. |
| * Members of a symbols group share same symbol reader configuration settings, |
| * like user defined memory map entries and source lookup info */ |
| PROP_SYMBOLS_GROUP = "SymbolsGroup"; |
| |
| /** @since 1.3 */ |
| static final String |
| /** Array of String, the access types allowed for this context |
| * when accessing context registers. |
| */ |
| PROP_REG_ACCESS_TYPES = "RegAccessTypes"; |
| |
| /** |
| * Values of "RegAccessTypes". |
| * @since 1.3 |
| */ |
| static final String |
| REG_ACCESS_RD_RUNNING = "rd-running", /** Context supports reading registers while running */ |
| REG_ACCESS_WR_RUNNUNG = "wr-running"; /** Context supports writing registers while running */ |
| |
| /** |
| * Values of "RegAccessTypes". |
| * @since 1.4 |
| */ |
| static final String |
| REG_ACCESS_RD_STOP = "rd-stop", /** Debugger should stop the context to read registers */ |
| REG_ACCESS_WR_STOP = "wr-stop"; /** Debugger should stop the context to write registers */ |
| |
| /** |
| * Context resume modes. |
| */ |
| static final int |
| |
| RM_RESUME = 0, |
| |
| /** |
| * Step over a single instruction. |
| * If the instruction is a function call then don't stop until the function returns. |
| */ |
| RM_STEP_OVER = 1, |
| |
| /** |
| * Step a single instruction. |
| * If the instruction is a function call then stop at first instruction of the function. |
| */ |
| RM_STEP_INTO = 2, |
| |
| /** |
| * Step over a single source code line. |
| * If the line contains a function call then don't stop until the function returns. |
| */ |
| RM_STEP_OVER_LINE = 3, |
| |
| /** |
| * Step a single source code line. |
| * If the line contains a function call then stop at first line of the function. |
| */ |
| RM_STEP_INTO_LINE = 4, |
| |
| /** |
| * Run until control returns from current function. |
| */ |
| RM_STEP_OUT = 5, |
| |
| /** |
| * Start running backwards. |
| * Execution will continue until suspended by command or breakpoint. |
| */ |
| RM_REVERSE_RESUME = 6, |
| |
| /** |
| * Reverse of RM_STEP_OVER - run backwards over a single instruction. |
| * If the instruction is a function call then don't stop until get out of the function. |
| */ |
| RM_REVERSE_STEP_OVER = 7, |
| |
| /** |
| * Reverse of RM_STEP_INTO. |
| * This effectively "un-executes" the previous instruction |
| */ |
| RM_REVERSE_STEP_INTO = 8, |
| |
| /** |
| * Reverse of RM_STEP_OVER_LINE. |
| * Resume backward execution of given context until control reaches an instruction that belongs |
| * to a different source line. |
| * If the line contains a function call then don't stop until get out of the function. |
| * Error is returned if line number information not available. |
| */ |
| RM_REVERSE_STEP_OVER_LINE = 9, |
| |
| /** |
| * Reverse of RM_STEP_INTO_LINE, |
| * Resume backward execution of given context until control reaches an instruction that belongs |
| * to a different line of source code. |
| * If a function is called, stop at the beginning of the last line of the function code. |
| * Error is returned if line number information not available. |
| */ |
| RM_REVERSE_STEP_INTO_LINE = 10, |
| |
| /** |
| * Reverse of RM_STEP_OUT. |
| * Resume backward execution of the given context until control reaches the point where the current function was called. |
| */ |
| RM_REVERSE_STEP_OUT = 11, |
| |
| /** |
| * Step over instructions until PC is outside the specified range. |
| * Any function call within the range is considered to be in range. |
| */ |
| RM_STEP_OVER_RANGE = 12, |
| |
| /** |
| * Step instruction until PC is outside the specified range for any reason. |
| */ |
| RM_STEP_INTO_RANGE = 13, |
| |
| /** |
| * Reverse of RM_STEP_OVER_RANGE |
| */ |
| RM_REVERSE_STEP_OVER_RANGE = 14, |
| |
| /** |
| * Reverse of RM_STEP_INTO_RANGE |
| */ |
| RM_REVERSE_STEP_INTO_RANGE = 15, |
| |
| /** |
| * Run until the context becomes active - scheduled to run on a target CPU |
| */ |
| RM_UNTIL_ACTIVE = 16, |
| |
| /** |
| * Run reverse until the context becomes active |
| */ |
| RM_REVERSE_UNTIL_ACTIVE = 17; |
| |
| /** |
| * State change reason of a context. |
| * Reason can be any text, but if it is one of predefined strings, |
| * a generic client might be able to handle it better. |
| */ |
| static final String |
| /** Context suspended by suspend command */ |
| REASON_USER_REQUEST = "Suspended", |
| |
| /** Context suspended by step command */ |
| REASON_STEP = "Step", |
| |
| /** Context suspended by breakpoint */ |
| REASON_BREAKPOINT = "Breakpoint", |
| |
| /** Context suspended by exception */ |
| REASON_EXCEPTION = "Exception", |
| |
| /** Context suspended as part of container */ |
| REASON_CONTAINER = "Container", |
| |
| /** Context suspended by watchpoint (data breakpoint) */ |
| REASON_WATCHPOINT = "Watchpoint", |
| |
| /** Context suspended because it received a signal */ |
| REASON_SIGNAL = "Signal", |
| |
| /** Context suspended because a shared library is loaded or unloaded */ |
| REASON_SHAREDLIB = "Shared Library", |
| |
| /** Context suspended because of an error in execution environment */ |
| REASON_ERROR = "Error"; |
| |
| |
| /* Optional parameters of context state -------------------------------- */ |
| |
| /** |
| * Context state parameter: |
| * Integer - signal that caused the context to become suspended. |
| */ |
| static final String STATE_SIGNAL = "Signal"; |
| |
| /** |
| * Context state parameter: |
| * String - name of the signal that caused the context to become suspended. |
| */ |
| static final String STATE_SIGNAL_NAME = "SignalName"; |
| |
| /** |
| * Context state parameter: |
| * String - description of the signal that caused the context to become suspended. |
| */ |
| static final String STATE_SIGNAL_DESCRIPTION = "SignalDescription"; |
| |
| /** |
| * Context state parameter: |
| * Array of string - IDs of breakpoints that were triggered by the context. |
| */ |
| static final String STATE_BREAKPOINT_IDS = "BPs"; |
| |
| /** |
| * Context state parameter: |
| * Object - error report that describes a reason why program counter of the context is not available. |
| */ |
| static final String STATE_PC_ERROR = "PCError"; |
| |
| /** |
| * Context state parameter: |
| * Object - error report if last stepping operation failed to reach its destination. |
| * @since 1.2 |
| */ |
| static final String STATE_STEP_ERROR = "StepError"; |
| |
| /** |
| * Context state parameter: |
| * Boolean - true if the context is stopped by a function call injection. |
| * @since 1.2 |
| */ |
| static final String STATE_FUNC_CALL = "FuncCall"; |
| |
| /** |
| * Context state parameter: |
| * Boolean - true if the context is running in reverse. |
| */ |
| static final String STATE_REVERSING = "Reversing"; |
| |
| /** |
| * Context state parameter: |
| * String - name of a context that owns this context. |
| */ |
| static final String STATE_CONTEXT = "Context"; |
| |
| /** |
| * Context state parameter: |
| * String - name of CPU that is executing the context. |
| */ |
| static final String STATE_CPU = "CPU"; |
| |
| /** |
| * Context state parameter: |
| * String - name of current state if other than "Running", for example: "Sleeping", "Reset", "No Clock". |
| */ |
| static final String STATE_NAME = "StateName"; |
| |
| |
| /* Optional parameters of resume command ------------------------------- */ |
| |
| /** |
| * Resume command parameter: |
| * Integer - starting address of step range, inclusive. |
| */ |
| static final String RP_RANGE_START = "RangeStart"; |
| |
| /** |
| * Resume command parameter: |
| * Integer - ending address of step range, exclusive. |
| */ |
| static final String RP_RANGE_END = "RangeEnd"; |
| |
| /** |
| * Resume command parameter: |
| * Boolean - allow to stop in a hidden code during stepping. |
| * @since 1.4 |
| */ |
| static final String RP_STEP_INTO_HIDDEN = "StepIntoHidden"; |
| |
| |
| /* Commands ------------------------------------------------------------ */ |
| |
| /** |
| * Retrieve context properties for given context ID. |
| * |
| * @param id - context ID. |
| * @param done - callback interface called when operation is completed. |
| */ |
| IToken getContext(String id, DoneGetContext done); |
| |
| /** |
| * Client callback interface for getContext(). |
| */ |
| interface DoneGetContext { |
| /** |
| * Called when context data retrieval is done. |
| * @param error - error description if operation failed, null if succeeded. |
| * @param context - context data. |
| */ |
| void doneGetContext(IToken token, Exception error, RunControlContext context); |
| } |
| |
| /** |
| * Retrieve children of given context. |
| * |
| * @param parent_context_id - parent context ID. Can be null - |
| * to retrieve top level of the hierarchy, or one of context IDs retrieved |
| * by previous getContext or getChildren commands. |
| * @param done - callback interface called when operation is completed. |
| */ |
| IToken getChildren(String parent_context_id, DoneGetChildren done); |
| |
| /** |
| * Client callback 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. |
| */ |
| void doneGetChildren(IToken token, Exception error, String[] context_ids); |
| } |
| |
| /** |
| * A context corresponds to an execution thread, process, address space, etc. |
| * A context can belong to a parent context. Contexts hierarchy can be simple |
| * plain list or it can form a tree. It is up to target agent developers to choose |
| * layout that is most descriptive for a given target. Context IDs are valid across |
| * all services. In other words, all services access same hierarchy of contexts, |
| * with same IDs, however, each service accesses its own subset of context's |
| * attributes and functionality, which is relevant to that service. |
| * @noimplement This interface is not intended to be implemented by clients. |
| */ |
| interface RunControlContext { |
| |
| /** |
| * Get context properties. See PROP_* definitions for property names. |
| * Context properties are read only, clients should not try to modify them. |
| * @return Map of context properties. |
| */ |
| Map<String,Object> getProperties(); |
| |
| /** |
| * Retrieve context ID. |
| * Same as getProperties().get("ID") |
| */ |
| String getID(); |
| |
| /** |
| * Retrieve parent context ID. |
| * Same as getProperties().get("ParentID") |
| */ |
| String getParentID(); |
| |
| /** |
| * Retrieve context process ID. |
| * Same as getProperties().get("ProcessID") |
| */ |
| String getProcessID(); |
| |
| /** |
| * Retrieve context creator ID. |
| * Same as getProperties().get("CreatorID") |
| */ |
| String getCreatorID(); |
| |
| /** |
| * Retrieve human readable context name. |
| * Same as getProperties().get("Name") |
| */ |
| String getName(); |
| |
| /** |
| * Utility method to read context property PROP_IS_CONTAINER. |
| * Executing resume or suspend command on a container causes all its children to resume or suspend. |
| * @return value of PROP_IS_CONTAINER. |
| */ |
| boolean isContainer(); |
| |
| /** |
| * Utility method to read context property PROP_HAS_STATE. |
| * Only context that has a state can be resumed or suspended. |
| * @return value of PROP_HAS_STATE. |
| */ |
| boolean hasState(); |
| |
| /** |
| * Utility method to read context property PROP_CAN_SUSPEND. |
| * Value 'true' means suspend command is supported by the context, |
| * however the method does not check that the command can be executed successfully in |
| * the current state of the context. For example, the command still can fail if context is |
| * already suspended. |
| * @return value of PROP_CAN_SUSPEND. |
| */ |
| boolean canSuspend(); |
| |
| /** |
| * Utility method to read a 'mode' bit in context property PROP_CAN_RESUME. |
| * Value 'true' means resume command is supported by the context, |
| * however the method does not check that the command can be executed successfully in |
| * the current state of the context. For example, the command still can fail if context is |
| * already resumed. |
| * @param mode - resume mode, see RM_*. |
| * @return value of requested bit of PROP_CAN_RESUME. |
| */ |
| boolean canResume(int mode); |
| |
| /** |
| * Utility method to read a 'mode' bit in context property PROP_CAN_COUNT. |
| * Value 'true' means resume command with count other then 1 is supported by the context, |
| * however the method does not check that the command can be executed successfully in |
| * the current state of the context. For example, the command still can fail if context is |
| * already resumed. |
| * @param mode - resume mode, see RM_*. |
| * @return value of requested bit of PROP_CAN_COUNT. |
| */ |
| boolean canCount(int mode); |
| |
| /** |
| * Utility method to read context property PROP_CAN_TERMINATE. |
| * Value 'true' means terminate command is supported by the context, |
| * however the method does not check that the command can be executed successfully in |
| * the current state of the context. For example, the command still can fail if the context |
| * already has exited. |
| * @return value of PROP_CAN_TERMINATE. |
| */ |
| boolean canTerminate(); |
| |
| /** |
| * Utility method to read context property PROP_CAN_DETACH. |
| * Value 'true' means detach command is supported by the context, |
| * however the method does not check that the command can be executed successfully in |
| * the current state of the context. For example, the command still can fail if the context |
| * already has exited. |
| * @return value of PROP_CAN_DETACH. |
| */ |
| boolean canDetach(); |
| |
| /** |
| * Utility method to read context property PROP_RC_GROUP - |
| * context ID of a run control group that contains the context. |
| * Members of same group are always suspended and resumed together: |
| * resuming/suspending a context resumes/suspends all members of the group. |
| * @return value of PROP_RC_GROUP. |
| */ |
| String getRCGroup(); |
| |
| /** |
| * Utility method to read context property PROP_BP_GROUP - |
| * context ID of a breakpoints group that contains the context. |
| * Members of same group share same breakpoint instances: |
| * a breakpoint is planted once for the group, no need to plant |
| * the breakpoint for each member of the group |
| * @return value of PROP_BP_GROUP or null if the context does not support breakpoints. |
| */ |
| String getBPGroup(); |
| |
| /** |
| * Utility method to read context property PROP_SYMBOLS_GROUP - |
| * context ID of a symbols group that contains the context. |
| * Members of a symbols group share same symbol reader configuration settings, |
| * like user defined memory map entries and source lookup info. |
| * @return value of PROP_SYMBOLS_GROUP or null if the context is not a member of a symbols group. |
| */ |
| String getSymbolsGroup(); |
| |
| /** |
| * Get the register access types allowed for this context. |
| * @return collection of access type names. |
| * @since 1.3 |
| */ |
| Collection<String> getRegAccessTypes(); |
| |
| /** |
| * Send a command to retrieve current state of a context. |
| * @param done - command result call back object. |
| * @return pending command handle, can be used to cancel the command. |
| */ |
| IToken getState(DoneGetState done); |
| |
| /** |
| * Send a command to retrieve current state of a context. |
| * Similar to getState, but does not retrieve PC. |
| * With some targets, it can be substantially faster. |
| * @param done - command result call back object. |
| * @return pending command handle, can be used to cancel the command. |
| */ |
| IToken getMinState(DoneGetMinState done); |
| |
| /** |
| * Send a command to suspend a context. |
| * Also suspends children if context is a container. |
| * @param done - command result call back object. |
| * @return pending command handle, can be used to cancel the command. |
| */ |
| IToken suspend(DoneCommand done); |
| |
| /** |
| * Send a command to resume a context. |
| * Also resumes children if context is a container. |
| * @param mode - defines how to resume the context, see RM_*. |
| * @param count - if mode implies stepping, defines how many steps to perform. |
| * @param done - command result call back object. |
| * @return pending command handle, can be used to cancel the command. |
| */ |
| IToken resume(int mode, int count, DoneCommand done); |
| |
| /** |
| * Send a command to resume a context. |
| * Also resumes children if context is a container. |
| * @param mode - defines how to resume the context, see RM_*. |
| * @param count - if mode implies stepping, defines how many steps to perform. |
| * @param params - resume parameters, for example, step range definition, see RP_*. |
| * @param done - command result call back object. |
| * @return pending command handle, can be used to cancel the command. |
| */ |
| IToken resume(int mode, int count, Map<String,Object> params, DoneCommand done); |
| |
| /** |
| * Send a command to terminate a context. |
| * @param done - command result call back object. |
| * @return pending command handle, can be used to cancel the command. |
| */ |
| IToken terminate(DoneCommand done); |
| |
| /** |
| * Send a command to detach a context. |
| * @param done - command result call back object. |
| * @return pending command handle, can be used to cancel the command. |
| */ |
| IToken detach(DoneCommand done); |
| } |
| |
| interface DoneGetState { |
| /** |
| * Called when getState command execution is complete. |
| * @param token - pending command handle. |
| * @param error - command execution error or null. |
| * @param suspended - true if the context is suspended |
| * @param pc - program counter of the context (if suspended). |
| * @param reason - suspend reason (if suspended), see REASON_*. |
| * @param params - additional target specific data about context state, see STATE_*. |
| */ |
| void doneGetState(IToken token, Exception error, boolean suspended, String pc, |
| String reason, Map<String,Object> params); |
| } |
| |
| interface DoneGetMinState { |
| /** |
| * Called when getMinState command execution is complete. |
| * @param token - pending command handle. |
| * @param error - command execution error or null. |
| * @param suspended - true if the context is suspended |
| * @param reason - suspend reason (if suspended), see REASON_*. |
| * @param params - additional target specific data about context state, see STATE_*. |
| */ |
| void doneGetMinState(IToken token, Exception error, boolean suspended, |
| String reason, Map<String,Object> params); |
| } |
| |
| interface DoneCommand { |
| /** |
| * Called when run control command execution is complete. |
| * @param token - pending command handle. |
| * @param error - command execution error or null. |
| */ |
| void doneCommand(IToken token, Exception error); |
| } |
| |
| /** |
| * Add run control event listener. |
| * @param listener - run control event listener to add. |
| */ |
| void addListener(RunControlListener listener); |
| |
| /** |
| * Remove run control event listener. |
| * @param listener - run control event listener to remove. |
| */ |
| void removeListener(RunControlListener listener); |
| |
| /** |
| * Service events listener interface. |
| */ |
| interface RunControlListener { |
| |
| /** |
| * Called when new contexts are created. |
| * @param contexts - array of new context properties. |
| */ |
| void contextAdded(RunControlContext contexts[]); |
| |
| /** |
| * Called when a context properties changed. |
| * @param contexts - array of new context properties. |
| */ |
| void contextChanged(RunControlContext contexts[]); |
| |
| /** |
| * Called when contexts are removed. |
| * @param context_ids - array of removed context IDs. |
| */ |
| void contextRemoved(String context_ids[]); |
| |
| /** |
| * Called when a thread is suspended. |
| * @param context - ID of a context that was suspended. |
| * @param pc - program counter of the context, can be null. |
| * @param reason - human readable description of suspend reason. |
| * @param params - additional, target specific data about suspended context. |
| */ |
| void contextSuspended(String context, String pc, |
| String reason, Map<String,Object> params); |
| |
| /** |
| * Called when a thread is resumed. |
| * @param context - ID of a context that was resumed. |
| */ |
| void contextResumed(String context); |
| |
| /** |
| * Called when target simultaneously suspends multiple threads in a container |
| * (process, core, etc.). |
| * |
| * @param context - ID of a context responsible for the event. It can be container ID or |
| * any one of container children, for example, it can be thread that hit "suspend all" breakpoint. |
| * Client expected to move focus (selection) to this context. |
| * @param pc - program counter of the context. |
| * @param reason - suspend reason, see REASON_*. |
| * @param params - additional target specific data about context state, see STATE_*. |
| * @param suspended_ids - full list of all contexts that were suspended. |
| */ |
| void containerSuspended(String context, String pc, |
| String reason, Map<String,Object> params, String[] suspended_ids); |
| |
| /** |
| * Called when target simultaneously resumes multiple threads in a container (process, |
| * core, etc.). |
| * |
| * @param context_ids - full list of all contexts that were resumed. |
| */ |
| void containerResumed(String[] context_ids); |
| |
| /** |
| * Called when an exception is detected in a target thread. |
| * @param context - ID of a context that caused an exception. |
| * @param msg - human readable description of the exception. |
| */ |
| void contextException(String context, String msg); |
| } |
| |
| /** |
| * Service events listener interface - extended. |
| */ |
| interface RunControlListenerV1 extends RunControlListener { |
| |
| /** |
| * Called when context state changes and the context is not and was not in suspended state. |
| * Changes to and from suspended state should be reported by other events: |
| * contextSuspended, contextResumed, containerSuspended, containerResumed. |
| * @param context - ID of a context that changed state. |
| */ |
| void contextStateChanged(String context); |
| } |
| } |
