From d4d98c8c307d0de24acbe31b22c037d56f6b98f2 Mon Sep 17 00:00:00 2001 From: fburton Date: Wed, 7 May 2008 06:09:46 +0000 Subject: [Bug 228389] [tcf][api] Breakpoint data structure extensions --- docs/TCF Service - Breakpoints.html | 386 +++++++++++++++++++++++++++++------- 1 file changed, 318 insertions(+), 68 deletions(-) diff --git a/docs/TCF Service - Breakpoints.html b/docs/TCF Service - Breakpoints.html index 4bf8ea0be..4ee8ff31f 100644 --- a/docs/TCF Service - Breakpoints.html +++ b/docs/TCF Service - Breakpoints.html @@ -28,23 +28,70 @@

Breakpoints Service

-

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

+

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.

-

Breakpoint properties is extendable collection of named attributes, -which define breakpoint location and behavior. The service defines some common -attribute names, host tools and target agents may support additional attributes.

+

A breakpoint's property set is an extendable 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 planted, and Condition +properties dictate whether the breakpoint should be triggered. +However, it is perfectly possible for an implementation to use +Condition properties to control planting of a breakpoint 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 planted. +

+ +

The Type 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 extendable 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 planted or planting errors.

+like actual addresses where breakpoint is installed or installation errors. -

Breakpoints are associated with communication channel and traget agent must remove them -when the channel is closed. Target agent should maintain separate breakpoint table -for each communication channel. It is allowed to set same breakpoint (same ID) through multiple -channels, target agent should treat it as single breakpoint with maltiple references. Such breakpoint -is removed when all refering channels are closed.

+

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.

@@ -63,38 +110,115 @@ C <breakpoints list> Ø <breakpoint data> - Ø <breakpoint data> , <breakpoint data> + Ø <breakpoints list>, <breakpoint data> <breakpoint data> Ø <object> -

The command downloads breakpoints data to a target agent. -The command is intended to be used only to initialize target breakpoints table +

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 target about (incremental) changes in breakpoint data by sending +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. Predefined properties are:

+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:

@@ -102,18 +226,63 @@ Tools and targets can define additional properties. Predefined properties are:<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 breakpoint to target agent breakpoint table. Host should send this command when user creates new breakpoint

+

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> •
+R • <token> • <error report> •

Change

@@ -122,7 +291,7 @@ R C • <token> • Breakpoints • change • <breakpoint data> • -

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

+

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:

@@ -142,13 +311,13 @@ C <breakpoint IDs list> Ø <breakpoint ID> - Ø <breakpoint ID> , <breakpoint ID> + Ø <breakpoint IDs list>, <breakpoint ID> <breakpoint ID> Ø <string> -

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

+

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

Reply:

@@ -162,7 +331,7 @@ R C • <token> • Breakpoints • disable • <array of breakpoint IDs> • -

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

+

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

Reply:

@@ -190,9 +359,11 @@ R C • <token> • Breakpoints • getIDs • -

The command uploads IDs of breakpoints known to target agent. Only breakpoints what are set through -this communication channel are reported. Target agent should maintain separate breakpoint table -for each communication channel.

+

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:

@@ -206,12 +377,12 @@ R C • <token> • Breakpoints • getProperties • <string: breakpoint ID> • -

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

+

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

Reply:


-R • <token> • <error report> • <;breakpoint data> •
+R • <token> • <error report> • <breakpoint data> •

Get Status

@@ -220,28 +391,61 @@ R C • <token> • Breakpoints • getStatus • <string: breakpoint ID> • -

The command uploads status of given breakpoint from target agent.

+

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

Reply:


-R • <token> • <error report> • <;breakpoint status> •
+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. Predefined properties are:

+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


@@ -253,12 +457,12 @@ 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..

+capabilities.

 
 
Reply:

 
 

-R • <token> • <error report> • <;service capabilities> •
+R • <token> • <error report> • <service capabilities> •
 
 <service capabilities>
     Ø <object>
@@ -282,7 +486,7 @@ Tools and targets can define additional properties. Predefined properties are:Events
 
-
Breakpoints service events are user to notify clients about breakpoint properties and status changes.
+
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.

@@ -296,13 +500,13 @@ E 
 
 

     
status
-        
is sent when breakpoint status changes.
+        
Is sent when breakpoint status changes.
     
contextAdded
-        
is sent when a new breakpoints are added.
+        
Is sent when a new breakpoints are added.
     
contextChanged
-        
is sent when breakpoint properties change.
+        
Is sent when breakpoint properties change.
     
contextRemoved
-        
is sent when breakpoints are removed.
+        
Is sent when breakpoints are removed.
 

 
 
API

@@ -312,14 +516,14 @@ E 
  * 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,
+ * Breakpoint properties (Map<String,Object>) is extensible 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:
+ * For each breakpoint a target agent maintains another extensible 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.
+ * about breakpoint current state, like actual addresses where breakpoint is installed or installation errors.
  */
 public interface IBreakpoints extends IService {
 
@@ -331,20 +535,66 @@ E 
     /**
      * Breakpoint property names.
      */
-    static final String   
-        PROP_ID = "ID",                 // String
-        PROP_ENABLED = "Enabled",       // Boolean
-        PROP_ADDRESS = "Address",       // String
-        PROP_CONDITION = "Condition",   // String
-        PROP_FILE = "File",             // String
-        PROP_LINE = "Line",             // Number
-        PROP_COLUMN = "Column";         // Number
+    static final String
+        PROP_ID = "ID",                           // String
+        PROP_ENABLED = "Enabled",                 // Boolean
+        PROP_TYPE = "BreakpointType",             // String
+        PROP_CONTEXTNAMES = "ContextNames",       // Array
+        PROP_CONTEXTIDS = "ContextIds",           // Array
+        PROP_EXECUTABLEPATHS = "ExecPaths",       // Array
+        PROP_LOCATION = "Location",               // String
+        PROP_SIZE = "Size",                       // Number
+        PROP_ACCESSMODE = "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_IGNORECOUNT = "IgnoreCount",         // Number
+        PROP_TIME = "Time",                       // Number
+        PROP_SCALE = "TimeScale",                 // String
+        PROP_UNITS = "TimeUnits",                 // String
+        PROP_CONDITION = "Condition",             // String
+        PROP_TEMPORARY = "Temporary";             // Boolean
+
+    /**
+     * BreakpointType values 
+     */
+    static final String
+        TYPE_RELATIVE = "Software",
+        TYPE_ABSOLUTE = "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_PLANTED = "Planted",     // Array of addresses
+        STATUS_INSTALLED = "Installed", // Array of addresses
         STATUS_ERROR = "Error",         // String
         STATUS_FILE = "File",           // String
         STATUS_LINE = "Line",           // Number
@@ -394,7 +644,7 @@ E 
     IToken change(Map<String,Object> properties, DoneCommand done);
 
     /**
-     * Tell target to change (only) PROP_ENABLED breakpoint property to 'true'.
+     * Tell target to change (only) PROP_ENABLED breakpoint property 'true'.
      * @param ids - array of enabled breakpoint identifiers.
      * @param done - command result call back object.
      */
@@ -408,7 +658,7 @@ E 
     IToken disable(String[] ids, DoneCommand done);
 
     /**
-     * Tell target to remove breakpoints.
+     * Tell target to remove breakpoint.
      * @param id - unique breakpoint identifier.
      * @param done - command result call back object.
      */
-- 
cgit v1.2.3