Target Communication Framework Services - Breakpoints

Breakpoints Service

Version History

Version Date Change
0.1 2008-01-10 Initial contribution
0.2 2008-04-25 Added getCapabilities
1.0 2008-05-06 Approved

Overview

A breakpoint is represented by a unique identifier and set of properties. A breakpoint identifier (String id) needs to be unique across all hosts and targets.

A breakpoint's property set is an extensible collection of named attributes, which define the breakpoint's location, the conditions that trigger the breakpoint, and the actions executed as a result. As such, breakpoint properties are separated into three broad categories:

The Location and Condition properties dictate how a breakpoint is installed and whether it should be triggered. The Action properties dictate the effect of the breakpoint if it is triggered.

The split of Location and Condition properties is subjective and is not meant to describe how it is implemented. Often, the Location properties dictate how a breakpoint is installed, and Condition properties dictate whether the breakpoint should be triggered. However, it is perfectly possible for an implementation to use Condition properties to control breakpoint installation and use Location properties each time the breakpoint is encountered to check if it should be triggered.

Unless stated otherwise, all Location and Condition properties have an implied "and" relationship. Conceptually, a breakpoint without any Location or Condition properties would be triggered by any state change in any of the attached contexts. Adding properties reduces the (sub)set of state changes that triggers the breakpoint.

The Location properties category contains the following properties:

Context defining properties specifying which context a breakpoint applies to are provided through the ContextIds, ContextNames or the ExecutablePaths properties.

The presence of certain properties defines what kind of breakpoint is installed.

The BreakpointType property configures whether the breakpoint should be installed as hardware or a software breakpoint.

Condition properties contain the Enabled property, the Condition and IgnoreCount properties.

Action properties contain the StopGroup and Temporary properties.

For each breakpoint a target agent maintains another extensible collection of named attributes: breakpoint status. While breakpoint properties are persistent and represent user input, breakpoint status reflects dynamic target agent reports about breakpoint current state, like actual addresses where breakpoint is installed or installation errors.

Every breakpoint is associated with a communication channel and when the channel is closed the target agent removes all corresponding breakpoints. Target agent should maintain separate breakpoint tables for each communication channel. It is allowed to set the same breakpoint (same ID) through multiple channels, target agent should treat it as single breakpoint with multiple references. Such a breakpoint is removed when all referring channels are closed.

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

Commands

Set


C • <token> • Breakpoints • set • <array of breakpoints> •

<array of breakpoints>
    ⇒ null
    ⇒ [ ]
    ⇒ [ <breakpoints list> ]

<breakpoints list>
    ⇒ <breakpoint data>
    ⇒ <breakpoints list>, <breakpoint data>

<breakpoint data>
    ⇒ <object>

The command downloads breakpoint data to a target agent. The command is intended to be used only to initialize the target's breakpoint table when communication channel is open. After that, host should notify the target about (incremental) changes in breakpoints data by sending Add, Change and Remove commands.

Breakpoint data consists of a list of breakpoint properties. All properties are optional, except ID. Tools and targets can define additional properties. All provided properties need to be true for a breakpoint to be installed/hit.
A breakpoint service implementation may not change the properties set by the client.

Predefined properties are:

Reply:


R • <token> • <error report> •

Examples:

The following properties install a hardware breakpoint at address 0x1000 for all attached contexts:

The following additional property limits the number of contexts for which the breakpoint by providing the ContextIDs property:

The following additional property stops the specified contexts when breakpoint 1 is hit:

The following properties set a watchpoint that stops core0 when variable fooVar is read from or written to by Core5:

The following additional properties further restrict the watchpoint to trigger only if an odd value is read from or written to the location.

The following properties set a temporal breakpoint that stops core0 at the specified absolute time.

Add


C • <token> • Breakpoints • add • <breakpoint data> •

The command adds a breakpoint to the target agent breakpoint table. The host should send this command when the user creates a new breakpoint

Reply:


R • <token> • <error report> •

Change


C • <token> • Breakpoints • change • <breakpoint data> •

The command updates the breakpoint data in the target agent breakpoint table. The host should send this command when the user modifies a breakpoint.

Reply:


R • <token> • <error report> •

Enable


C • <token> • Breakpoints • enable • <array of breakpoint IDs> •

<array of breakpoint IDs>
    ⇒ null
    ⇒ [ ]
    ⇒ [ <breakpoint IDs list> ]

<breakpoint IDs list>
    ⇒ <breakpoint ID>
    ⇒ <breakpoint IDs list>, <breakpoint ID>

<breakpoint ID>
    ⇒ <string>

The command enables a list of breakpoints - sets breakpoint property "Enabled" to true.

Reply:


R • <token> • <error report> •

Disable


C • <token> • Breakpoints • disable • <array of breakpoint IDs> •

The command disables a list of breakpoints - sets breakpoint property "Enabled" to false.

Reply:


R • <token> • <error report> •

Remove


C • <token> • Breakpoints • remove • <array of breakpoint IDs> •

The command removes a list of breakpoints. Host should send this command when user deletes breakpoints.

Reply:


R • <token> • <error report> •

Get IDs


C • <token> • Breakpoints • getIDs •

The command uploads IDs of breakpoints known to target agent, including breakpoints that are set through different communication channels. It is up to the client to keep track of which breakpoints it has set such that it can know which breakpoint are set by other channels.

Reply:


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

Get Properties


C • <token> • Breakpoints • getProperties • <string: breakpoint ID> •

The command uploads the properties of the given breakpoint from the target agent breakpoint table.

Reply:


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

Get Status


C • <token> • Breakpoints • getStatus • <string: breakpoint ID> •

The command uploads the status of given the breakpoint from the target agent.

Reply:


R • <token> • <error report> • <breakpoint status> •

<breakpoint status>
    ⇒ <object>

Breakpoint status consists of a list of status properties. All properties are optional. Tools and targets can define additional properties. Setting any properties that are not supported by or unknown to the service implementation will yield an error, which is reported in the Error property of the breakpoint status object.

Predefined properties are:

A breakpoint installation can lead to zero or more installed instances of the breakpoints. Properties associated with each of those installed instances (or error information in case there was a failure installing an instance) are provided in a list of instance status data objects 

<array of instance status data>
    ⇒ null
    ⇒ [ ]
    ⇒ [ <Instance status data list> ]

<Instance status data list>
    ⇒ <Instance status data>
    ⇒ <Instance staus data list>, <Instance status data>

<Instance status data>
    ⇒ <object>

Instance status data consists of a list of properties pertaining to each installed instance of the breakpoint.

Predefined properties are:

Get Capabilities


C • <token> • Breakpoints • getCapabilities • <string: context ID> •

The command reports breakpoint service capabilities to clients so they can adjust to different implementations of the service. When called with a null ("") context ID the global capabilities are returned, otherwise context specific capabilities are returned. A special capability property is used to indicate that all child contexts have the same capabilities.

Reply:


R • <token> • <error report> • <service capabilities> •

<service capabilities>
    ⇒ <object>

Service capabilities consist of a list of properties. All properties are optional. Tools and targets can define additional properties. Predefined properties are:

Events

Breakpoints service events are sent to notify clients about breakpoint properties and status changes. Note that contextAdded, contextChanged and contextRemoved events carry exactly same set of breakpoint properties that was sent by a client to a target. The purpose of these events is to let all clients know about breakpoints that were created by other clients.


E • Breakpoints • status • <string: breakpoint ID> • <breakpoint status> •
E • Breakpoints • contextAdded • <array of breakpoints> •
E • Breakpoints • contextChanged • <array of breakpoints> •
E • Breakpoints • contextRemoved • <array of breakpoint IDs> •
status
Is sent when breakpoint status changes.
contextAdded
Is sent when a new breakpoints are added.
contextChanged
Is sent when breakpoint properties change.
contextRemoved
Is sent when breakpoints are removed.

API

/**
 * Breakpoint is represented by unique identifier and set of properties.
 * Breakpoint identifier (String id) needs to be unique across all hosts and targets.
 *
 * Breakpoint properties (Map<String,Object>) is extendible collection of named attributes,
 * which define breakpoint location and behavior. This module defines some common
 * attribute names (see PROP_*), host tools and target agents may support additional attributes.
 *
 * For each breakpoint a target agent maintains another extendible collection of named attributes:
 * breakpoint status (Map<String,Object>, see STATUS_*). While breakpoint properties are
 * persistent and represent user input, breakpoint status reflects dynamic target agent reports
 * about breakpoint current state, like actual addresses where breakpoint is planted or planting errors.
 *
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IBreakpoints extends IService {

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

    /**
     * Breakpoint property names.
     */
    static final String
        PROP_ID = "ID",                           // String
        PROP_ENABLED = "Enabled",                 // Boolean
        PROP_TYPE = "BreakpointType",             // String
        PROP_CONTEXT_NAMES = "ContextNames",      // Array
        PROP_CONTEXT_IDS = "ContextIds",          // Array
        PROP_EXECUTABLE_PATHS = "ExecPaths",      // Array
        PROP_CONTEXT_QUERY = "ContextQuery",      // String, see IContextQuery
        PROP_LOCATION = "Location",               // String
        PROP_SIZE = "Size",                       // Number
        PROP_ACCESS_MODE = "AccessMode",          // Number
        PROP_FILE = "File",                       // String
        PROP_LINE = "Line",                       // Number
        PROP_COLUMN = "Column",                   // Number
        PROP_PATTERN = "MaskValue",               // Number
        PROP_MASK = "Mask",                       // Number
        PROP_STOP_GROUP = "StopGroup",            // Array
        PROP_IGNORE_COUNT = "IgnoreCount",        // Number
        PROP_TIME = "Time",                       // Number
        PROP_SCALE = "TimeScale",                 // String
        PROP_UNITS = "TimeUnits",                 // String
        PROP_CONDITION = "Condition",             // String
        PROP_TEMPORARY = "Temporary",             // Boolean
        PROP_EVENT_TYPE = "EventType",            // String
        PROP_EVENT_ARGS = "EventArgs",            // String or Object
        PROP_CLIENT_DATA = "ClientData",          // Object
        PROP_ACTION = "Action";                   // String - expression or script
    /** @since 1.3 */
    static final String
        PROP_SKIP_PROLOGUE = "SkipPrologue";      // Boolean
    /** @since 1.4 */
    static final String
        PROP_LINE_OFFSET = "LineOffset";          // Number - max number of lines breakpoint is allowed
                                                  // to be moved in case of inexact line info match
    /** @since 1.5 */
    static final String
        PROP_SERVICE = "Service";                 // String - name of a service that owns the breakpoint.
                                                  // User breakpoints don't have this attribute.

    /**
     * Breakpoints service can control cross trigger matrix - if the target hardware has one.
     * If a breakpoint has cross trigger attributes, planting of the breakpoint enables routing of
     * CrossTriggerInp signals to CrossTriggerOut signals. If CrossTriggerOut array includes
     * CPU stop request, any CrossTriggerInp signal also stops software execution. In such case,
     * breakpoint attributes like Condition or StopGroup have same meaning as for regular breakpoint.
     * Values of cross trigger attributes are arrays of signal IDs. Signal ID can be either Number or String.
     * Mapping of signal IDs to hardware depends on the target.
     * @since 1.5
     */
    static final String
        PROP_CT_INP = "CrossTriggerInp",          // Array - Cross trigger inputs
        PROP_CT_OUT = "CrossTriggerOut";          // Array - Cross trigger outputs

    /**
     * @deprecated
     */
    static final String
        PROP_CONTEXTNAMES = "ContextNames",       // Array
        PROP_CONTEXTIDS = "ContextIds",           // Array
        PROP_EXECUTABLEPATHS = "ExecPaths",       // Array
        PROP_ACCESSMODE = "AccessMode",           // Number
        PROP_IGNORECOUNT = "IgnoreCount";         // Number

    /**
     * BreakpointType values
     */
    static final String
        TYPE_SOFTWARE = "Software",
        TYPE_HARDWARE = "Hardware",
        TYPE_AUTO = "Auto";

    /**
     * AccessMode values
     */
    static final int
        ACCESSMODE_READ    = 0x01,
        ACCESSMODE_WRITE   = 0x02,
        ACCESSMODE_EXECUTE = 0x04,
        ACCESSMODE_CHANGE  = 0x08;

    /**
     * TimeScale values
     */
    static final String
        TIMESCALE_RELATIVE = "Relative",
        TIMESCALE_ABSOLUTE = "Absolute";

    /**
     * TimeUnits values
     */
    static final String
        TIMEUNIT_NSECS = "Nanoseconds",
        TIMEUNIT_CYCLE_COUNT = "CycleCount",
        TIMEUNIT_INSTRUCTION_COUNT = "InstructionCount";

    /**
     * Breakpoint status field names.
     */
    static final String
        STATUS_INSTANCES = "Instances",         // Array of Map<String,Object>
        STATUS_ERROR = "Error",                 // String
        STATUS_FILE = "File",                   // String
        STATUS_LINE = "Line",                   // Number
        STATUS_COLUMN = "Column";               // Number

    /**
     * Breakpoint instance field names.
     */
    static final String
        INSTANCE_ERROR = "Error",               // String
        INSTANCE_CONTEXT = "LocationContext",   // String
        INSTANCE_ADDRESS = "Address",           // Number
        INSTANCE_SIZE = "Size",                 // Number
        INSTANCE_TYPE = "BreakpointType",       // String
        INSTANCE_MEMORY_CONTEXT = "MemoryContext",// String
        INSTANCE_HIT_COUNT = "HitCount";         // Number
    /** @since 1.3 */
    static final String
        INSTANCE_CONDITION_ERROR = "ConditionError"; // String

    /**
     * Breakpoint service capabilities.
     */
    static final String
        CAPABILITY_CONTEXT_ID = "ID",                   // String
        CAPABILITY_HAS_CHILDREN = "HasChildren",        // Boolean
        CAPABILITY_BREAKPOINT_TYPE = "BreakpointType",  // Boolean
        CAPABILITY_LOCATION = "Location",               // Boolean
        CAPABILITY_CONDITION = "Condition",             // Boolean
        CAPABILITY_FILE_LINE = "FileLine",              // Boolean
        CAPABILITY_FILE_MAPPING = "FileMapping",        // Boolean
        CAPABILITY_CONTEXT_IDS = "ContextIds",          // Boolean
        CAPABILITY_CONTEXT_NAMES = "ContextNames",      // Boolean
        CAPABILITY_CONTEXT_QUERY = "ContextQuery",      // Boolean
        CAPABILITY_STOP_GROUP = "StopGroup",            // Boolean
        CAPABILITY_TEMPORARY = "Temporary",             // Boolean
        CAPABILITY_IGNORE_COUNT = "IgnoreCount",        // Boolean
        CAPABILITY_ACCESS_MODE = "AccessMode",          // Number
        CAPABILITY_CLIENT_DATA = "ClientData";          // Boolean
    /** @since 1.3 */
    static final String
        CAPABILITY_SKIP_PROLOGUE = "SkipPrologue";      // Boolean
    /** @since 1.5 */
    static final String
        CAPABILITY_CROSS_TRIGGER = "CrossTrigger";      // Boolean

    /**
     * @deprecated
     */
    static final String
        CAPABILITY_CONTEXTNAMES = "ContextNames",
        CAPABILITY_CONTEXTIDS = "ContextIds",
        CAPABILITY_IGNORECOUNT = "IgnoreCount",
        CAPABILITY_ACCESSMODE = "AccessMode";

    /**
     * Call back interface for breakpoint service commands.
     */
    interface DoneCommand {
        /**
         * Called when command is done.
         * @param token - command handle.
         * @param error - error object or null.
         */
        void doneCommand(IToken token, Exception error);
    }

    /**
     * Download breakpoints data to target agent.
     * The command is intended to be used only to initialize target breakpoints table
     * when communication channel is open. After that, host should
     * notify target about (incremental) changes in breakpoint data by sending
     * add, change and remove commands.
     *
     * @param properties - array of breakpoints.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken set(Map<String,Object>[] properties, DoneCommand done);

    /**
     * Called when breakpoint is added into breakpoints table.
     * @param properties - breakpoint properties.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken add(Map<String,Object> properties, DoneCommand done);

    /**
     * Called when breakpoint properties are changed.
     * @param properties - breakpoint properties.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken change(Map<String,Object> properties, DoneCommand done);

    /**
     * Tell target to change (only) PROP_ENABLED breakpoint property to 'true'.
     * @param ids - array of enabled breakpoint identifiers.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken enable(String[] ids, DoneCommand done);

    /**
     * Tell target to change (only) PROP_ENABLED breakpoint property to 'false'.
     * @param ids - array of disabled breakpoint identifiers.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken disable(String[] ids, DoneCommand done);

    /**
     * Tell target to remove breakpoints.
     * @param ids - array of breakpoint identifiers.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken remove(String[] ids, DoneCommand done);

    /**
     * Upload IDs of breakpoints known to target agent.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken getIDs(DoneGetIDs done);

    /**
     * Call back interface for 'getIDs' command.
     */
    interface DoneGetIDs {
        /**
         * Called when 'getIDs' command is done.
         * @param token - command handle.
         * @param error - error object or null.
         * @param ids - IDs of breakpoints known to target agent.
         */
        void doneGetIDs(IToken token, Exception error, String[] ids);
    }

    /**
     * Upload properties of given breakpoint from target agent breakpoint table.
     * @param id - unique breakpoint identifier.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken getProperties(String id, DoneGetProperties done);

    /**
     * Call back interface for 'getProperties' command.
     */
    interface DoneGetProperties {
        /**
         * Called when 'getProperties' command is done.
         * @param token - command handle.
         * @param error - error object or null.
         * @param properties - properties of the breakpoint.
         */
        void doneGetProperties(IToken token, Exception error, Map<String,Object> properties);
    }

    /**
     * Upload status of given breakpoint from target agent.
     * @param id - unique breakpoint identifier.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken getStatus(String id, DoneGetStatus done);

    /**
     * Call back interface for 'getStatus' command.
     */
    interface DoneGetStatus {
        /**
         * Called when 'getStatus' command is done.
         * @param token - command handle.
         * @param error - error object or null.
         * @param status - status of the breakpoint.
         */
        void doneGetStatus(IToken token, Exception error, Map<String,Object> status);
    }

    /**
     * Report breakpoint service capabilities to clients so they
     * can adjust to different implementations of the service.
     * When called with a null ("") context ID the global capabilities are returned,
     * otherwise context specific capabilities are returned.  A special capability
     * property is used to indicate that all child contexts have the same
     * capabilities.
     * @param id - a context ID or null.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken getCapabilities(String id, DoneGetCapabilities done);

    /**
     * Call back interface for 'getCapabilities' command.
     */
    interface DoneGetCapabilities {
        /**
         * Called when 'getCapabilities' command is done.
         * @param token - command handle.
         * @param error - error object or null.
         * @param capabilities - breakpoints service capabilities description.
         */
        void doneGetCapabilities(IToken token, Exception error, Map<String,Object> capabilities);
    }

    /**
     * Breakpoints service events listener.
     * Note that contextAdded, contextChanged and contextRemoved events carry exactly same set
     * of breakpoint properties that was sent by a client to a target. The purpose of these events is to
     * let all clients know about breakpoints that were created by other clients.
     */
    interface BreakpointsListener {

        /**
         * Called when breakpoint status changes.
         * @param id - unique breakpoint identifier.
         * @param status - breakpoint status.
         */
        void breakpointStatusChanged(String id, Map<String,Object> status);

        /**
         * Called when a new breakpoints are added.
         * @param bps - array of breakpoints.
         */
        void contextAdded(Map<String,Object>[] bps);

        /**
         * Called when breakpoint properties change.
         * @param bps - array of breakpoints.
         */
        void contextChanged(Map<String,Object>[] bps);

        /**
         * Called when breakpoints are removed.
         * @param ids - array of breakpoint IDs.
         */
        void contextRemoved(String[] ids);
    }

    /**
     * Add breakpoints service event listener.
     * @param listener - object that implements BreakpointsListener interface.
     */
    void addListener(BreakpointsListener listener);

    /**
     * Remove breakpoints service event listener.
     * @param listener - object that implements BreakpointsListener interface.
     */
    void removeListener(BreakpointsListener listener);
}