Download
Getting Started
Members
Projects
Community
Marketplace
Events
Planet Eclipse
Newsletter
Videos
Participate
Report a Bug
Forums
Mailing Lists
Wiki
IRC
How to Contribute
Working Groups
Automotive
Internet of Things
LocationTech
Long-Term Support
PolarSys
Science
OpenMDM
More
Community
Marketplace
Events
Planet Eclipse
Newsletter
Videos
Participate
Report a Bug
Forums
Mailing Lists
Wiki
IRC
How to Contribute
Working Groups
Automotive
Internet of Things
LocationTech
Long-Term Support
PolarSys
Science
OpenMDM
Toggle navigation
Bugzilla – Attachment 97212 Details for
Bug 228389
[tcf][api] Breakpoint data structure extensions
Home
|
New
|
Browse
|
Search
|
[?]
|
Reports
|
Requests
|
Help
|
Log In
[x]
|
Terms of Use
|
Copyright Agent
Amendment to the breakpoint data structures
TCF Service -V2 Breakpoints.html (text/html), 25.29 KB, created by
Sidharth Kodikal
on 2008-04-23 08:49:16 EDT
(
hide
)
Description:
Amendment to the breakpoint data structures
Filename:
MIME Type:
Creator:
Sidharth Kodikal
Created:
2008-04-23 08:49:16 EDT
Size:
25.29 KB
patch
obsolete
><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> ><html> ><head> > <title>Target Communication Framework Services - Breakpoints</title> ></head> > ><body lang='EN-US'> > ><h1>Target Communication Framework Services - Breakpoints</h1> > ><ul> > <li><a href='#Cmds'>Commands</a> > <ul> > <li><a href='#CmdSet'>Set</a> > <li><a href='#CmdAdd'>Add</a> > <li><a href='#CmdChange'>Change</a> > <li><a href='#CmdEnable'>Enable</a> > <li><a href='#CmdDisable'>Disable</a> > <li><a href='#CmdRemove'>Remove</a> > <li><a href='#CmdGetIDs'>Get IDs</a> > <li><a href='#CmdGetProperties'>Get Properties</a> > <li><a href='#CmdGetStatus'>Get Status</a> > </ul> > <li><a href='#Events'>Events</a> > <li><a href='#API'>API</a> ></ul> > ><h1>Breakpoints Service</h1> > ><p>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</p> > ><p>Breakpoint properties is an extendable collection of named attributes, >which define the breakpoint's location and behavior. The service defines some common >attribute names, host tools and target agents may support additional attributes.</p> > ><p>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 installed or installation errors.</p> > ><p>Every breakpoint is associated with a communication channel and when the channel is closed >the target agent must remove all corresponding breakpoints. >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 multiple references. Such a breakpoint >is removed when all refering channels are closed.</p> > ><p>The service uses standard format for error reports, >see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> > ><h2><a name='Cmds'>Commands</a></h2> > ><h3><a name='CmdSet'>Set</a></h3> > ><pre><b><font face="Courier New" size=2 color=#333399> >C <i><token></i> Breakpoints set <i><array of breakpoints></i> > ><i><array of breakpoints></i> > <font face=Wingdings>Ø</font> null > <font face=Wingdings>Ø</font> [ ] > <font face=Wingdings>Ø</font> [ <i><breakpoints list></i> ] > ><i><breakpoints list></i> > <font face=Wingdings>Ø</font> <i><breakpoint data></i> > <font face=Wingdings>Ø</font> <i><breakpoints list></i> , <i><breakpoint data></i> > ><i><breakpoint data></i> > <font face=Wingdings>Ø</font> <i><object></i> ></font></b></pre> > ><p> The command downloads breakpoints data to a 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.<p> > ><p>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.<br> >A breakpoint service implementation may not change the properties set by the client.<br> >Predefined properties are:</p> > ><ul> > <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b></code> > - breakpoint ID > > <li><code><b><font face="Courier New" size=2 color=#333399>"Enabled" : <i><boolean></i></font></b></code> > - if true breakpoint is enabled > <li><code><b><font face="Courier New" size=2 color=#333399>"Type" : <i><string></i></font></b></code> > - the breakpoint type > <dl> > <ul> > <li><dt><code><b>"Software"</b></code> <dd> Software breakpoint. > <li><dt><code><b>"Hardware"</b></code> <dd> Hardware breakpoint > <li><dt><code><b>"Auto"</b></code> <dd> Installed breakpoint type (software/hardware) deferred to agent's discretion. This is the default breakpoint type. > The actual type of each breakpoint instance consequently installed is received as a status event > </ul> > </dl> > <li><code><b><font face="Courier New" size=2 color=#333399>"ContextName" : <i><string></i></font></b></code> > - the context name for which the location expression should be evaluated. The location context could be a memory space name > or a register group name. If this property is not provided, the breakpoint will be installed for all > runcontrol/process context (these contexts may be limited by the Initiators property) > > <li><code><b><font face="Courier New" size=2 color=#333399>"Expression" : <i><string></i></font></b></code> > - if preset, defines location of the breakpoint. Location is an expression that evaluates either to a memory address > or a register location (with respect to the ContextName property). > Alternatively, breakpoint location can be given as File/Line/Column. > > <li><code><b><font face="Courier New" size=2 color=#333399>"AccessMode" : <i><int></i></font></b></code> > - the access mode that will trigger the breakpoint<br> > Access mode can be a bitwise OR of the values below: > <dl> > <ul> > <li><dt><code><b>READ = 0x01</b></code> <dd>triggered by a read from the breakpoint location > <li><dt><code><b>WRITE = 0x02</b></code> <dd>triggered by a write to the breakpoint location > <li><dt><code><b>EXECUTE = 0x04</b></code> <dd>triggered by an instruction fetch from the breakpoint location > <li><dt><code><b>CHANGE = 0x08</b></code> <dd>triggered by a data change (not an explicit write) at the breakpoint location > </ul> > </dl> > <li><code><b><font face="Courier New" size=2 color=#333399>"Size" : <i><int></i></font></b></code> > - The number of bytes starting at the location expression to which the AccessMode triggers apply > > <li><code><b><font face="Courier New" size=2 color=#333399>"File" : <i><string></i></font></b></code> > - source code file name of breakpoint location. > <li><code><b><font face="Courier New" size=2 color=#333399>"Line" : <i><int></i></font></b></code> > - source code line number of breakpoint location. > <li><code><b><font face="Courier New" size=2 color=#333399>"Column" : <i><int></i></font></b></code> > - source code column number of breakpoint location. > > <li><code><b><font face="Courier New" size=2 color=#333399>"Pattern" : <i><int></i></font></b></code> > - a breakpoint can be qualified by a data value or pattern. > <li><code><b><font face="Courier New" size=2 color=#333399>"Mask" : <i><int></i></font></b></code> > - a mask which is bitwise ANDed with the data value/pattern. > > <li><code><b><font face="Courier New" size=2 color=#333399>"Time" : <i><number></i></font></b></code> > - the time value in the execution of the program at which to set the breakpoint > <li><code><b><font face="Courier New" size=2 color=#333399>"TimeScale" : <i><string></i></font></b></code> > - the scale for the time value > <dl> > <ul> > <li><dt><code><b>"Relative"</b></code> <dd> Time value in the relative time scale. This is the default value for this property. > <li><dt><code><b>"Absolute"</b></code> <dd> Time value in the absolute time scale > </ul> > </dl> > <li><code><b><font face="Courier New" size=2 color=#333399>"TimeUnits" : <i><string></i></font></b></code> > - the units for the time value > <dl> > <ul> > <li><dt><code><b>"CycleCount"</b></code> <dd> Time value in cycles. This is the default type. > <li><dt><code><b>"NanoSeconds"</b></code> <dd> Time value in nano seconds > <li><dt><code><b>"InstructionCount"</b></code> <dd> Time value in instructions > </ul> > </dl> > > <li><code><b><font face="Courier New" size=2 color=#333399>"Initiators" : <i><string></i></font></b></code> > - an array of context identifiers or names for runcontrol/process contexts that can trigger the breakpoint. > <li><code><b><font face="Courier New" size=2 color=#333399>"StopGroup" : <i><string></i></font></b></code> > - an array context identifiers or names for runcontrol/process contexts to be stopped when this breakpoint is triggered. > > <li><code><b><font face="Courier New" size=2 color=#333399>"IgnoreCount" : <i><int></i></font></b></code> > - the number of times this breakpoint is to be ignored before it is triggered. The ignore count is tested after all other properties are validated. > > <li><code><b><font face="Courier New" size=2 color=#333399>"Condition" : <i><string></i></font></b></code> > - a conditional expression that is evaluted every time execution hits the breakpoint. If condition is evaluated to false, > the breakpoint is skipped and execution is resumed without sending notifications to a host. ></ul> ><p> ><p>Reply:</p> > ><pre><b><font face="Courier New" size=2 color=#333399> >R <i><token></i> <i><error report></i> ></font></b></pre> ><p><p> ><b>Examples:</b> ><p> >The following properties set a hardware breakpoint at address <code>0x1000</code> for all runcontrol/process contexts for which this breakpoint got successfully installed:<br> ><ul> > <li><code>ID = "1"</code> > <li><code>Type = "Hardware"</code> > <li><code>Expression = "0x1000"</code> ></ul> ><p> >The following additional property limits the number of contexts affected by the breakpoint by providing the Initiators property:<br> ><ul> > <li><code>Initiators = ["Core0", "Core1"]</code> ></ul> ><p> >The following additional property stop the specified contexts when the breakpoint set with the above properties is hit:<br> ><ul> > <li><code>StopGroup = ["Core0", "Core1", "Core5"]</code> ></ul> ><p> >The following properties set a watchpoint that stops <code>core0</code> when variable <code>fooVar</code> is read from or written to by <code>Core5</code>: ><ul> > <li><code>ID = "2"</code> > <li><code>Type = "Hardware"</code> > <li><code>Expression = "fooVar"</code> > <li><code>Size = 4</code> > <li><code>AccessMode = 0x01 | 0x02</code> > <li><code>Initiators = ["core5"]</code> > <li><code>StopGroup = ["core0"]</code> ></ul> ><p> >The following properties set a temporal breakpoint that stops if after executing 100 instructions, we are in function <code>bar()</code>:<br> ><ul> > <li><code>ID = "3"</code> > <li><code>Expression = "bar"</code> > <li><code>Time = 100</code> > <li><code>TimeUnits = "InstructionCount"</code> ></ul> ><p> ><p>Reply:</p> > ><pre><b><font face="Courier New" size=2 color=#333399> >R <i><token></i> <i><error report></i> ></font></b></pre> > ><h3><a name='CmdAdd'>Add</a></h3> > ><pre><b><font face="Courier New" size=2 color=#333399> >C <i><token></i> Breakpoints add <i><breakpoint data></i> ></font></b></pre> > ><p>The command adds breakpoint to target agent breakpoint table. Host should send this command when user creates new breakpoint</p> > ><h3><a name='CmdChange'>Change</a></h3> > ><pre><b><font face="Courier New" size=2 color=#333399> >C <i><token></i> Breakpoints change <i><breakpoint data></i> ></font></b></pre> > ><p>The command updates breakpoint data in target agent breakpoint table. Host should send this command when user modifies a breakpoint</p> > ><p>Reply:</p> > ><pre><b><font face="Courier New" size=2 color=#333399> >R <i><token></i> <i><error report></i> ></font></b></pre> > ><h3><a name='CmdEnable'>Enable</a></h3> > ><pre><b><font face="Courier New" size=2 color=#333399> >C <i><token></i> Breakpoints enable <i><array of breakpoint IDs></i> > ><i><array of breakpoint IDs></i> > <font face=Wingdings>Ø</font> null > <font face=Wingdings>Ø</font> [ ] > <font face=Wingdings>Ø</font> [ <i><breakpoint IDs list></i> ] > ><i><breakpoint IDs list></i> > <font face=Wingdings>Ø</font> <i><breakpoint ID></i> > <font face=Wingdings>Ø</font> <i><breakpoint IDs list></i> , <i><breakpoint ID></i> > ><i><breakpoint ID></i> > <font face=Wingdings>Ø</font> <i><string></i> ></font></b></pre> > ><p>The command enables a list of breakpoints - sets brekpoint property "Enabled" to true.</p> > ><p>Reply:</p> > ><pre><b><font face="Courier New" size=2 color=#333399> >R <i><token></i> <i><error report></i> ></font></b></pre> > ><h3><a name='CmdDisable'>Disable</a></h3> > ><pre><b><font face="Courier New" size=2 color=#333399> >C <i><token></i> Breakpoints disable <i><array of breakpoint IDs></i> ></font></b></pre> > ><p>The command disables a list of breakpoints - sets brekpoint property "Enabled" to false.</p> > ><p>Reply:</p> > ><pre><b><font face="Courier New" size=2 color=#333399> >R <i><token></i> <i><error report></i> ></font></b></pre> > ><h3><a name='CmdRemove'>Remove</a></h3> > ><pre><b><font face="Courier New" size=2 color=#333399> >C <i><token></i> Breakpoints remove <i><array of breakpoint IDs></i> ></font></b></pre> > ><p>The command removes a list of breakpoints. Host should send this command when user deletes breakpoints.</p> > ><p>Reply:</p> > ><pre><b><font face="Courier New" size=2 color=#333399> >R <i><token></i> <i><error report></i> ></font></b></pre> > ><h3><a name='CmdGetIDs'>Get IDs</a></h3> > ><pre><b><font face="Courier New" size=2 color=#333399> >C <i><token></i> Breakpoints getIDs ></font></b></pre> > ><p>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.</p> > ><p>Reply:</p> > ><pre><b><font face="Courier New" size=2 color=#333399> >R <i><token></i> <i><error report></i> <i><array of breakpoint IDs></i> ></font></b></pre> > ><h3><a name='CmdGetProperties'>Get Properties</a></h3> > ><pre><b><font face="Courier New" size=2 color=#333399> >C <i><token></i> Breakpoints getProperties <i><string: breakpoint ID></i> ></font></b></pre> > ><p>The command uploads properties of given breakpoint from target agent breakpoint table.</p> > ><p>Reply:</p> > ><pre><b><font face="Courier New" size=2 color=#333399> >R <i><token></i> <i><error report></i> <i><;breakpoint data></i> ></font></b></pre> > ><h3><a name='CmdGetStatus'>Get Status</a></h3> > ><pre><b><font face="Courier New" size=2 color=#333399> >C <i><token></i> Breakpoints getStatus <i><string: breakpoint ID></i> ></font></b></pre> > ><p>The command uploads status of given breakpoint from target agent.</p> > ><p>Reply:</p> > ><pre><b><font face="Courier New" size=2 color=#333399> >R <i><token></i> <i><error report></i> <i><;breakpoint status></i> > ><i><breakpoint status></i> > <font face=Wingdings>Ø</font> <i><object></i> ></font></b></pre> > ><p>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 provided in the Error property of the breakpoint status object.<br> > >Predefined properties are:</p> > ><ul> > <li><code><b><font face="Courier New" size=2 color=#333399>"Instances" : <i><array of status data></i></font></b></code> > <li><code><b><font face="Courier New" size=2 color=#333399>"Error" : <i><string></i></font></b></code> > <li><code><b><font face="Courier New" size=2 color=#333399>"File" : <i><string></i></font></b></code> > <li><code><b><font face="Courier New" size=2 color=#333399>"Line" : <i><int></i></font></b></code> > <li><code><b><font face="Courier New" size=2 color=#333399>"Column" : <i><int></i></font></b></code> ></ul> > >A breakpoint installation can lead to multiple 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 > ><pre><b><font face="Courier New" size=2 color=#333399> ><i><array of instance status data></i> > <font face=Wingdings>Ø</font> null > <font face=Wingdings>Ø</font> [ ] > <font face=Wingdings>Ø</font> [ <i><Instance status data list></i> ] > ><i><Instance status data list></i> > <font face=Wingdings>Ø</font> <i><Instance status data></i> > <font face=Wingdings>Ø</font> <i><Instance staus data list></i> , <i><Instance status data></i> > ><i><Instance status data></i> > <font face=Wingdings>Ø</font> <i><object></i> > ></font></b></pre> > ></font></b></pre> > ><p> Instance status data consists of a list of properties pertaining to each installed instance of the breakpoint.<br> >Predefined properties are:</p> ><ul> > <li><code><b><font face="Courier New" size=2 color=#333399>"Error" : <i><string></i></font></b></code> > <li><code><b><font face="Courier New" size=2 color=#333399>"BreakpointType" : <i><string></i></font></b></code> > <li><code><b><font face="Courier New" size=2 color=#333399>"LocationContext" : <i><string></i></font></b></code> > <li><code><b><font face="Courier New" size=2 color=#333399>"Address" : <i><string></i></font></b></code> ></ul> > ><h2><a name='Events'>Events</a></h2> > ><pre><b><font face="Courier New" size=2 color=#333399> >E Breakpoints status <i><string: breakpoint ID></i> <i><breakpoint status></i> ></font></b></pre> > ><dl> > <dt><b>status</b> > <dd>is sent when breakpoint status changes. ></dl> > ><h2><a name='API'>API</a></h2> > ><pre> ><font color=#3F5FBF>/** > * 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 extendable 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 extendable 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 installed or installation errors. > */</font> ><font color=#7F0055>public interface</font> IBreakpoints <font color=#7F0055>extends</font> IService { > > <font color=#3F5FBF>/** > * Service name. > */</font> > <font color=#7F0055>static final</font> String NAME = "Breakpoints"; > > <font color=#3F5FBF>/** > * Breakpoint property names. > */</font> > <font color=#7F0055>static final</font> String > PROP_ID = "ID", // String > PROP_ENABLED = "Enabled", // Boolean > PROP_TYPE = "BreakpointType", // String > PROP_LOCATIONCONTEXT = "LocationContext", // String > PROP_LOCATION = "LocationExpression", // String > PROP_SIZE = "Size", // Number > PROP_ACCESSMODE = "AccessMode", // Number > PROP_FILE = "File", // String > PROP_LINE = "Line", // Number > PROP_COLUMN = "Column", // Number > PROP_PATTERN = "Pattern", // Number > PROP_MASK = "Mask", // Number > PROP_INITIATOR_GROUP = "Initiators", // Array > 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 > > <font color=#3F5FBF>/** > * BreakpointType values > */</font> > <font color=#7F0055>static final</font> int > PROP_VAL_RELATIVE = "Software", > PROP_VAL_ABSOLUTE = "Hardware"; > > <font color=#3F5FBF>/** > * AccessMode values > */ </font> > <font color=#7F0055>final static</font> int > READ = 0x01, > WRITE = 0x02, > EXECUTE = 0x04, > CHANGE = 0x08; > > <font color=#3F5FBF>/** > * TimeScale values > */</font> > <font color=#7F0055>static final</font> int > PROP_VAL_RELATIVE = "Relative", > PROP_VAL_ABSOLUTE = "Absolute"; > > <font color=#3F5FBF>/** > * TimeUnits values > */</font> > <font color=#7F0055>static final</font> String > PROP_VAL_NSECS = "Nanoseconds", > PROP_VAL_CYCLE_COUNT = "CycleCount", > PROP_VAL_INSTRUCTION_COUNT = "InstructionCount"; > > <font color=#3F5FBF>/** > * Breakpoint status field names. > */</font> > <font color=#7F0055>static final</font> String > STATUS_INSTALLED = "Installed", // Array of addresses > STATUS_ERROR = "Error", // String > STATUS_FILE = "File", // String > STATUS_LINE = "Line", // Number > STATUS_COLUMN = "Column"; // Number > > <font color=#3F5FBF>/** > * Call back interface for breakpoint service commands. > */</font> > <font color=#7F0055>interface</font> DoneCommand { > <font color=#7F0055>void</font> doneCommand(IToken token, Exception error); > } > > <font color=#3F5FBF>/** > * 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. > */</font> > IToken set(Map<String,Object>[] properties, DoneCommand done); > > <font color=#3F5FBF>/** > * Called when breakpoint is added into breakpoints table. > * @param properties - breakpoint properties. > * @param done - command result call back object. > */</font> > IToken add(Map<String,Object> properties, DoneCommand done); > > <font color=#3F5FBF>/** > * Called when breakpoint properties are changed. > * @param properties - breakpoint properties. > * @param done - command result call back object. > */</font> > IToken change(Map<String,Object> properties, DoneCommand done); > > <font color=#3F5FBF>/** > * Tell target to change (only) PROP_ENABLED breakpoint property 'true'. > * @param ids - array of enabled breakpoint identifiers. > * @param done - command result call back object. > */</font> > IToken enable(String[] ids, DoneCommand done); > > <font color=#3F5FBF>/** > * 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. > */</font> > IToken disable(String[] ids, DoneCommand done); > > <font color=#3F5FBF>/** > * Tell target to remove breakpoint. > * @param id - unique breakpoint identifier. > * @param done - command result call back object. > */</font> > IToken remove(String[] ids, DoneCommand done); > > <font color=#3F5FBF>/** > * Upload IDs of breakpoints known to target agent. > * @param done - command result call back object. > */</font> > IToken getIDs(DoneGetIDs done); > > <font color=#7F0055>interface</font> DoneGetIDs { > <font color=#7F0055>void</font> doneGetIDs(IToken token, Exception error, String[] ids); > } > > <font color=#3F5FBF>/** > * Upload properties of given breakpoint from target agent breakpoint table. > * @param id - unique breakpoint identifier. > * @param done - command result call back object. > */</font> > IToken getProperties(String id, DoneGetProperties done); > > <font color=#7F0055>interface</font> DoneGetProperties { > <font color=#7F0055>void</font> doneGetProperties(IToken token, Exception error, Map<String,Object> properties); > } > > <font color=#3F5FBF>/** > * Upload status of given breakpoint from target agent. > * @param id - unique breakpoint identifier. > * @param done - command result call back object. > */</font> > IToken getStatus(String id, DoneGetStatus done); > > <font color=#7F0055>interface</font> DoneGetStatus { > <font color=#7F0055>void</font> doneGetStatus(IToken token, Exception error, Map<String,Object> status); > } > > <font color=#3F5FBF>/** > * Breakpoints service events listener. > */</font> > <font color=#7F0055>interface</font> BreakpointsListener { > > <font color=#3F5FBF>/** > * Called when breakpoint status changes. > * @param id - unique breakpoint identifier. > * @param status - breakpoint status. > */</font> > <font color=#7F0055>void</font> breakpointStatusChanged(String id, Map<String,Object> status); > } > > <font color=#7F0055>void</font> addListener(BreakpointsListener listener); > > <font color=#7F0055>void</font> removeListener(BreakpointsListener listener); >} ></pre> > ></body> ></html> > >
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head> <title>Target Communication Framework Services - Breakpoints</title> </head> <body lang='EN-US'> <h1>Target Communication Framework Services - Breakpoints</h1> <ul> <li><a href='#Cmds'>Commands</a> <ul> <li><a href='#CmdSet'>Set</a> <li><a href='#CmdAdd'>Add</a> <li><a href='#CmdChange'>Change</a> <li><a href='#CmdEnable'>Enable</a> <li><a href='#CmdDisable'>Disable</a> <li><a href='#CmdRemove'>Remove</a> <li><a href='#CmdGetIDs'>Get IDs</a> <li><a href='#CmdGetProperties'>Get Properties</a> <li><a href='#CmdGetStatus'>Get Status</a> </ul> <li><a href='#Events'>Events</a> <li><a href='#API'>API</a> </ul> <h1>Breakpoints Service</h1> <p>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</p> <p>Breakpoint properties is an extendable collection of named attributes, which define the breakpoint's location and behavior. The service defines some common attribute names, host tools and target agents may support additional attributes.</p> <p>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 installed or installation errors.</p> <p>Every breakpoint is associated with a communication channel and when the channel is closed the target agent must remove all corresponding breakpoints. 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 multiple references. Such a breakpoint is removed when all refering channels are closed.</p> <p>The service uses standard format for error reports, see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> <h2><a name='Cmds'>Commands</a></h2> <h3><a name='CmdSet'>Set</a></h3> <pre><b><font face="Courier New" size=2 color=#333399> C <i><token></i> Breakpoints set <i><array of breakpoints></i> <i><array of breakpoints></i> <font face=Wingdings>Ø</font> null <font face=Wingdings>Ø</font> [ ] <font face=Wingdings>Ø</font> [ <i><breakpoints list></i> ] <i><breakpoints list></i> <font face=Wingdings>Ø</font> <i><breakpoint data></i> <font face=Wingdings>Ø</font> <i><breakpoints list></i> , <i><breakpoint data></i> <i><breakpoint data></i> <font face=Wingdings>Ø</font> <i><object></i> </font></b></pre> <p> The command downloads breakpoints data to a 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.<p> <p>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.<br> A breakpoint service implementation may not change the properties set by the client.<br> Predefined properties are:</p> <ul> <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b></code> - breakpoint ID <li><code><b><font face="Courier New" size=2 color=#333399>"Enabled" : <i><boolean></i></font></b></code> - if true breakpoint is enabled <li><code><b><font face="Courier New" size=2 color=#333399>"Type" : <i><string></i></font></b></code> - the breakpoint type <dl> <ul> <li><dt><code><b>"Software"</b></code> <dd> Software breakpoint. <li><dt><code><b>"Hardware"</b></code> <dd> Hardware breakpoint <li><dt><code><b>"Auto"</b></code> <dd> Installed breakpoint type (software/hardware) deferred to agent's discretion. This is the default breakpoint type. The actual type of each breakpoint instance consequently installed is received as a status event </ul> </dl> <li><code><b><font face="Courier New" size=2 color=#333399>"ContextName" : <i><string></i></font></b></code> - the context name for which the location expression should be evaluated. The location context could be a memory space name or a register group name. If this property is not provided, the breakpoint will be installed for all runcontrol/process context (these contexts may be limited by the Initiators property) <li><code><b><font face="Courier New" size=2 color=#333399>"Expression" : <i><string></i></font></b></code> - if preset, defines location of the breakpoint. Location is an expression that evaluates either to a memory address or a register location (with respect to the ContextName property). Alternatively, breakpoint location can be given as File/Line/Column. <li><code><b><font face="Courier New" size=2 color=#333399>"AccessMode" : <i><int></i></font></b></code> - the access mode that will trigger the breakpoint<br> Access mode can be a bitwise OR of the values below: <dl> <ul> <li><dt><code><b>READ = 0x01</b></code> <dd>triggered by a read from the breakpoint location <li><dt><code><b>WRITE = 0x02</b></code> <dd>triggered by a write to the breakpoint location <li><dt><code><b>EXECUTE = 0x04</b></code> <dd>triggered by an instruction fetch from the breakpoint location <li><dt><code><b>CHANGE = 0x08</b></code> <dd>triggered by a data change (not an explicit write) at the breakpoint location </ul> </dl> <li><code><b><font face="Courier New" size=2 color=#333399>"Size" : <i><int></i></font></b></code> - The number of bytes starting at the location expression to which the AccessMode triggers apply <li><code><b><font face="Courier New" size=2 color=#333399>"File" : <i><string></i></font></b></code> - source code file name of breakpoint location. <li><code><b><font face="Courier New" size=2 color=#333399>"Line" : <i><int></i></font></b></code> - source code line number of breakpoint location. <li><code><b><font face="Courier New" size=2 color=#333399>"Column" : <i><int></i></font></b></code> - source code column number of breakpoint location. <li><code><b><font face="Courier New" size=2 color=#333399>"Pattern" : <i><int></i></font></b></code> - a breakpoint can be qualified by a data value or pattern. <li><code><b><font face="Courier New" size=2 color=#333399>"Mask" : <i><int></i></font></b></code> - a mask which is bitwise ANDed with the data value/pattern. <li><code><b><font face="Courier New" size=2 color=#333399>"Time" : <i><number></i></font></b></code> - the time value in the execution of the program at which to set the breakpoint <li><code><b><font face="Courier New" size=2 color=#333399>"TimeScale" : <i><string></i></font></b></code> - the scale for the time value <dl> <ul> <li><dt><code><b>"Relative"</b></code> <dd> Time value in the relative time scale. This is the default value for this property. <li><dt><code><b>"Absolute"</b></code> <dd> Time value in the absolute time scale </ul> </dl> <li><code><b><font face="Courier New" size=2 color=#333399>"TimeUnits" : <i><string></i></font></b></code> - the units for the time value <dl> <ul> <li><dt><code><b>"CycleCount"</b></code> <dd> Time value in cycles. This is the default type. <li><dt><code><b>"NanoSeconds"</b></code> <dd> Time value in nano seconds <li><dt><code><b>"InstructionCount"</b></code> <dd> Time value in instructions </ul> </dl> <li><code><b><font face="Courier New" size=2 color=#333399>"Initiators" : <i><string></i></font></b></code> - an array of context identifiers or names for runcontrol/process contexts that can trigger the breakpoint. <li><code><b><font face="Courier New" size=2 color=#333399>"StopGroup" : <i><string></i></font></b></code> - an array context identifiers or names for runcontrol/process contexts to be stopped when this breakpoint is triggered. <li><code><b><font face="Courier New" size=2 color=#333399>"IgnoreCount" : <i><int></i></font></b></code> - the number of times this breakpoint is to be ignored before it is triggered. The ignore count is tested after all other properties are validated. <li><code><b><font face="Courier New" size=2 color=#333399>"Condition" : <i><string></i></font></b></code> - a conditional expression that is evaluted every time execution hits the breakpoint. If condition is evaluated to false, the breakpoint is skipped and execution is resumed without sending notifications to a host. </ul> <p> <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> R <i><token></i> <i><error report></i> </font></b></pre> <p><p> <b>Examples:</b> <p> The following properties set a hardware breakpoint at address <code>0x1000</code> for all runcontrol/process contexts for which this breakpoint got successfully installed:<br> <ul> <li><code>ID = "1"</code> <li><code>Type = "Hardware"</code> <li><code>Expression = "0x1000"</code> </ul> <p> The following additional property limits the number of contexts affected by the breakpoint by providing the Initiators property:<br> <ul> <li><code>Initiators = ["Core0", "Core1"]</code> </ul> <p> The following additional property stop the specified contexts when the breakpoint set with the above properties is hit:<br> <ul> <li><code>StopGroup = ["Core0", "Core1", "Core5"]</code> </ul> <p> The following properties set a watchpoint that stops <code>core0</code> when variable <code>fooVar</code> is read from or written to by <code>Core5</code>: <ul> <li><code>ID = "2"</code> <li><code>Type = "Hardware"</code> <li><code>Expression = "fooVar"</code> <li><code>Size = 4</code> <li><code>AccessMode = 0x01 | 0x02</code> <li><code>Initiators = ["core5"]</code> <li><code>StopGroup = ["core0"]</code> </ul> <p> The following properties set a temporal breakpoint that stops if after executing 100 instructions, we are in function <code>bar()</code>:<br> <ul> <li><code>ID = "3"</code> <li><code>Expression = "bar"</code> <li><code>Time = 100</code> <li><code>TimeUnits = "InstructionCount"</code> </ul> <p> <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> R <i><token></i> <i><error report></i> </font></b></pre> <h3><a name='CmdAdd'>Add</a></h3> <pre><b><font face="Courier New" size=2 color=#333399> C <i><token></i> Breakpoints add <i><breakpoint data></i> </font></b></pre> <p>The command adds breakpoint to target agent breakpoint table. Host should send this command when user creates new breakpoint</p> <h3><a name='CmdChange'>Change</a></h3> <pre><b><font face="Courier New" size=2 color=#333399> C <i><token></i> Breakpoints change <i><breakpoint data></i> </font></b></pre> <p>The command updates breakpoint data in target agent breakpoint table. Host should send this command when user modifies a breakpoint</p> <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> R <i><token></i> <i><error report></i> </font></b></pre> <h3><a name='CmdEnable'>Enable</a></h3> <pre><b><font face="Courier New" size=2 color=#333399> C <i><token></i> Breakpoints enable <i><array of breakpoint IDs></i> <i><array of breakpoint IDs></i> <font face=Wingdings>Ø</font> null <font face=Wingdings>Ø</font> [ ] <font face=Wingdings>Ø</font> [ <i><breakpoint IDs list></i> ] <i><breakpoint IDs list></i> <font face=Wingdings>Ø</font> <i><breakpoint ID></i> <font face=Wingdings>Ø</font> <i><breakpoint IDs list></i> , <i><breakpoint ID></i> <i><breakpoint ID></i> <font face=Wingdings>Ø</font> <i><string></i> </font></b></pre> <p>The command enables a list of breakpoints - sets brekpoint property "Enabled" to true.</p> <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> R <i><token></i> <i><error report></i> </font></b></pre> <h3><a name='CmdDisable'>Disable</a></h3> <pre><b><font face="Courier New" size=2 color=#333399> C <i><token></i> Breakpoints disable <i><array of breakpoint IDs></i> </font></b></pre> <p>The command disables a list of breakpoints - sets brekpoint property "Enabled" to false.</p> <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> R <i><token></i> <i><error report></i> </font></b></pre> <h3><a name='CmdRemove'>Remove</a></h3> <pre><b><font face="Courier New" size=2 color=#333399> C <i><token></i> Breakpoints remove <i><array of breakpoint IDs></i> </font></b></pre> <p>The command removes a list of breakpoints. Host should send this command when user deletes breakpoints.</p> <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> R <i><token></i> <i><error report></i> </font></b></pre> <h3><a name='CmdGetIDs'>Get IDs</a></h3> <pre><b><font face="Courier New" size=2 color=#333399> C <i><token></i> Breakpoints getIDs </font></b></pre> <p>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.</p> <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> R <i><token></i> <i><error report></i> <i><array of breakpoint IDs></i> </font></b></pre> <h3><a name='CmdGetProperties'>Get Properties</a></h3> <pre><b><font face="Courier New" size=2 color=#333399> C <i><token></i> Breakpoints getProperties <i><string: breakpoint ID></i> </font></b></pre> <p>The command uploads properties of given breakpoint from target agent breakpoint table.</p> <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> R <i><token></i> <i><error report></i> <i><;breakpoint data></i> </font></b></pre> <h3><a name='CmdGetStatus'>Get Status</a></h3> <pre><b><font face="Courier New" size=2 color=#333399> C <i><token></i> Breakpoints getStatus <i><string: breakpoint ID></i> </font></b></pre> <p>The command uploads status of given breakpoint from target agent.</p> <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> R <i><token></i> <i><error report></i> <i><;breakpoint status></i> <i><breakpoint status></i> <font face=Wingdings>Ø</font> <i><object></i> </font></b></pre> <p>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 provided in the Error property of the breakpoint status object.<br> Predefined properties are:</p> <ul> <li><code><b><font face="Courier New" size=2 color=#333399>"Instances" : <i><array of status data></i></font></b></code> <li><code><b><font face="Courier New" size=2 color=#333399>"Error" : <i><string></i></font></b></code> <li><code><b><font face="Courier New" size=2 color=#333399>"File" : <i><string></i></font></b></code> <li><code><b><font face="Courier New" size=2 color=#333399>"Line" : <i><int></i></font></b></code> <li><code><b><font face="Courier New" size=2 color=#333399>"Column" : <i><int></i></font></b></code> </ul> A breakpoint installation can lead to multiple 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 <pre><b><font face="Courier New" size=2 color=#333399> <i><array of instance status data></i> <font face=Wingdings>Ø</font> null <font face=Wingdings>Ø</font> [ ] <font face=Wingdings>Ø</font> [ <i><Instance status data list></i> ] <i><Instance status data list></i> <font face=Wingdings>Ø</font> <i><Instance status data></i> <font face=Wingdings>Ø</font> <i><Instance staus data list></i> , <i><Instance status data></i> <i><Instance status data></i> <font face=Wingdings>Ø</font> <i><object></i> </font></b></pre> </font></b></pre> <p> Instance status data consists of a list of properties pertaining to each installed instance of the breakpoint.<br> Predefined properties are:</p> <ul> <li><code><b><font face="Courier New" size=2 color=#333399>"Error" : <i><string></i></font></b></code> <li><code><b><font face="Courier New" size=2 color=#333399>"BreakpointType" : <i><string></i></font></b></code> <li><code><b><font face="Courier New" size=2 color=#333399>"LocationContext" : <i><string></i></font></b></code> <li><code><b><font face="Courier New" size=2 color=#333399>"Address" : <i><string></i></font></b></code> </ul> <h2><a name='Events'>Events</a></h2> <pre><b><font face="Courier New" size=2 color=#333399> E Breakpoints status <i><string: breakpoint ID></i> <i><breakpoint status></i> </font></b></pre> <dl> <dt><b>status</b> <dd>is sent when breakpoint status changes. </dl> <h2><a name='API'>API</a></h2> <pre> <font color=#3F5FBF>/** * 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 extendable 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 extendable 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 installed or installation errors. */</font> <font color=#7F0055>public interface</font> IBreakpoints <font color=#7F0055>extends</font> IService { <font color=#3F5FBF>/** * Service name. */</font> <font color=#7F0055>static final</font> String NAME = "Breakpoints"; <font color=#3F5FBF>/** * Breakpoint property names. */</font> <font color=#7F0055>static final</font> String PROP_ID = "ID", // String PROP_ENABLED = "Enabled", // Boolean PROP_TYPE = "BreakpointType", // String PROP_LOCATIONCONTEXT = "LocationContext", // String PROP_LOCATION = "LocationExpression", // String PROP_SIZE = "Size", // Number PROP_ACCESSMODE = "AccessMode", // Number PROP_FILE = "File", // String PROP_LINE = "Line", // Number PROP_COLUMN = "Column", // Number PROP_PATTERN = "Pattern", // Number PROP_MASK = "Mask", // Number PROP_INITIATOR_GROUP = "Initiators", // Array 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 <font color=#3F5FBF>/** * BreakpointType values */</font> <font color=#7F0055>static final</font> int PROP_VAL_RELATIVE = "Software", PROP_VAL_ABSOLUTE = "Hardware"; <font color=#3F5FBF>/** * AccessMode values */ </font> <font color=#7F0055>final static</font> int READ = 0x01, WRITE = 0x02, EXECUTE = 0x04, CHANGE = 0x08; <font color=#3F5FBF>/** * TimeScale values */</font> <font color=#7F0055>static final</font> int PROP_VAL_RELATIVE = "Relative", PROP_VAL_ABSOLUTE = "Absolute"; <font color=#3F5FBF>/** * TimeUnits values */</font> <font color=#7F0055>static final</font> String PROP_VAL_NSECS = "Nanoseconds", PROP_VAL_CYCLE_COUNT = "CycleCount", PROP_VAL_INSTRUCTION_COUNT = "InstructionCount"; <font color=#3F5FBF>/** * Breakpoint status field names. */</font> <font color=#7F0055>static final</font> String STATUS_INSTALLED = "Installed", // Array of addresses STATUS_ERROR = "Error", // String STATUS_FILE = "File", // String STATUS_LINE = "Line", // Number STATUS_COLUMN = "Column"; // Number <font color=#3F5FBF>/** * Call back interface for breakpoint service commands. */</font> <font color=#7F0055>interface</font> DoneCommand { <font color=#7F0055>void</font> doneCommand(IToken token, Exception error); } <font color=#3F5FBF>/** * 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. */</font> IToken set(Map<String,Object>[] properties, DoneCommand done); <font color=#3F5FBF>/** * Called when breakpoint is added into breakpoints table. * @param properties - breakpoint properties. * @param done - command result call back object. */</font> IToken add(Map<String,Object> properties, DoneCommand done); <font color=#3F5FBF>/** * Called when breakpoint properties are changed. * @param properties - breakpoint properties. * @param done - command result call back object. */</font> IToken change(Map<String,Object> properties, DoneCommand done); <font color=#3F5FBF>/** * Tell target to change (only) PROP_ENABLED breakpoint property 'true'. * @param ids - array of enabled breakpoint identifiers. * @param done - command result call back object. */</font> IToken enable(String[] ids, DoneCommand done); <font color=#3F5FBF>/** * 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. */</font> IToken disable(String[] ids, DoneCommand done); <font color=#3F5FBF>/** * Tell target to remove breakpoint. * @param id - unique breakpoint identifier. * @param done - command result call back object. */</font> IToken remove(String[] ids, DoneCommand done); <font color=#3F5FBF>/** * Upload IDs of breakpoints known to target agent. * @param done - command result call back object. */</font> IToken getIDs(DoneGetIDs done); <font color=#7F0055>interface</font> DoneGetIDs { <font color=#7F0055>void</font> doneGetIDs(IToken token, Exception error, String[] ids); } <font color=#3F5FBF>/** * Upload properties of given breakpoint from target agent breakpoint table. * @param id - unique breakpoint identifier. * @param done - command result call back object. */</font> IToken getProperties(String id, DoneGetProperties done); <font color=#7F0055>interface</font> DoneGetProperties { <font color=#7F0055>void</font> doneGetProperties(IToken token, Exception error, Map<String,Object> properties); } <font color=#3F5FBF>/** * Upload status of given breakpoint from target agent. * @param id - unique breakpoint identifier. * @param done - command result call back object. */</font> IToken getStatus(String id, DoneGetStatus done); <font color=#7F0055>interface</font> DoneGetStatus { <font color=#7F0055>void</font> doneGetStatus(IToken token, Exception error, Map<String,Object> status); } <font color=#3F5FBF>/** * Breakpoints service events listener. */</font> <font color=#7F0055>interface</font> BreakpointsListener { <font color=#3F5FBF>/** * Called when breakpoint status changes. * @param id - unique breakpoint identifier. * @param status - breakpoint status. */</font> <font color=#7F0055>void</font> breakpointStatusChanged(String id, Map<String,Object> status); } <font color=#7F0055>void</font> addListener(BreakpointsListener listener); <font color=#7F0055>void</font> removeListener(BreakpointsListener listener); } </pre> </body> </html>
View Attachment As Raw
Actions:
View
Attachments on
bug 228389
:
97212
|
97246
|
98392
|
98686