diff options
| author | eutarass | 2009-09-02 20:30:27 +0000 |
|---|---|---|
| committer | eutarass | 2009-09-02 20:30:27 +0000 |
| commit | 63c23ca255c52bd0ca6c29fd4f3758cdef1da49a (patch) | |
| tree | 383f60e29ff169e42ee13c6dcc402c077fbb4bde /docs | |
| parent | d1598d1e38275606cade2dbcfed327bf9593ff5f (diff) | |
| download | org.eclipse.tcf-63c23ca255c52bd0ca6c29fd4f3758cdef1da49a.tar.gz org.eclipse.tcf-63c23ca255c52bd0ca6c29fd4f3758cdef1da49a.tar.xz org.eclipse.tcf-63c23ca255c52bd0ca6c29fd4f3758cdef1da49a.zip | |
Code cleanup: trailing spaces are removed from the source line
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/TCF Agent Porting Guide.html | 10 | ||||
| -rw-r--r-- | docs/TCF Context Identifier Explanation.html | 2 | ||||
| -rw-r--r-- | docs/TCF Getting Started.html | 12 | ||||
| -rw-r--r-- | docs/TCF Project.html | 128 | ||||
| -rw-r--r-- | docs/TCF Service - Breakpoints.html | 82 | ||||
| -rw-r--r-- | docs/TCF Service - File System.html | 166 | ||||
| -rw-r--r-- | docs/TCF Service - Memory.html | 172 | ||||
| -rw-r--r-- | docs/TCF Service - Processes.html | 170 | ||||
| -rw-r--r-- | docs/TCF Service - Registers.html | 154 | ||||
| -rw-r--r-- | docs/TCF Service - Run Control.html | 116 | ||||
| -rw-r--r-- | docs/TCF Service - Stack Trace.html | 62 | ||||
| -rw-r--r-- | docs/TCF Service - Streams.html | 78 | ||||
| -rw-r--r-- | docs/TCF Service - System Monitor.html | 290 | ||||
| -rw-r--r-- | docs/TCF Services.html | 28 | ||||
| -rw-r--r-- | docs/TCF Specification.html | 530 |
15 files changed, 1000 insertions, 1000 deletions
diff --git a/docs/TCF Agent Porting Guide.html b/docs/TCF Agent Porting Guide.html index 57da3c6fd..216afa01a 100644 --- a/docs/TCF Agent Porting Guide.html +++ b/docs/TCF Agent Porting Guide.html @@ -61,7 +61,7 @@ Single threaded event driven design provides good level of concurrency (equivalent to cooperative multithreading), while greatly reduces need for synchronization - each event dispatch cycle can be viewed as fully synchronized atomic operation. </p> - + <p> Event driven code should avoid long running or potentially blocking operations in event handlers since they can stop all event processing for indefinite time. Such operations should use asynchronous APIs (like POSIX Asynchronous I/O), or should be performed by background threads. @@ -69,7 +69,7 @@ Background thread scope should be limited to a single module and it should not call agent public APIs. Instead they should communicate with the rest of the code by posting events. </p> - + <p> An event is essentially a function pointer (a call-back) that points to event handler, plus a data pointer. Call-backs are also used throughout the agent code to subscribe listeners for various state change notifications. @@ -91,7 +91,7 @@ Also, macro values can be overwritten by using -D option in C compiler command line. Agent <a href='http://dev.eclipse.org/svnroot/dsdp/org.eclipse.tm.tcf/trunk/agent/Makefile'>Makefile</a> contains additional logic that makes it even more convenient to build different agent configurations. </p> - + <p> It should be much easier to port the agent if you don't need all TCF services. For example, for RSE integration you only need File System, System Monitor and Processes services, @@ -130,7 +130,7 @@ When it is not possible or not feasible to use portable POSIX APIs, the agent code contains conditional compilation statements that use well known macros like WIN32, __CYGWIN__, __MINGW32__, etc. Such places might require editing when porting to a new OS. </p> - + <h2> <a name='NewCPU'>Porting TCF Agent to a New CPU Type</a> </h2> @@ -138,7 +138,7 @@ <p> Searching TCF agent source code for __i386__ is a good way to find all places where the source code depends on CPU type. </p> - + <p> There are several files in the code that might need changes in order to support a new CPU type: </p> diff --git a/docs/TCF Context Identifier Explanation.html b/docs/TCF Context Identifier Explanation.html index 956c56cf2..fa76450ac 100644 --- a/docs/TCF Context Identifier Explanation.html +++ b/docs/TCF Context Identifier Explanation.html @@ -108,7 +108,7 @@ be relatively simple; the information is categorized as follows:</P> <P CLASS="western">2. Slow changing properties per service, a.k.a. properties</P> <P CLASS="western">3. Fast changing properties per service, a.k.a. -state or status +state or status </P> <P CLASS="western">Category 1 provides a simple way to express unbounded lists of related contextIds. If such a list becomes too diff --git a/docs/TCF Getting Started.html b/docs/TCF Getting Started.html index 6ed3b19a6..ba030da47 100644 --- a/docs/TCF Getting Started.html +++ b/docs/TCF Getting Started.html @@ -5,9 +5,9 @@ </head> <body lang='EN-US'> - + <h1>Target Communication Framework: Getting Started</h1> - + <p>Copyright (c) 2007, 2008 Wind River Systems, Inc. Made available under the EPL v1.0 <p>Direct comments, questions to the <a href="mailto:dsdp-tcf-dev@eclipse.org">dsdp-tcf-dev@eclipse.org</a> mailing list @@ -24,7 +24,7 @@ <h2><a name='Workspace'>Creating Eclipse Workspace</a></h2> -<p>Eclipse can be used for developing clients for TCF in Java. +<p>Eclipse can be used for developing clients for TCF in Java. TCF host side code is organized into several Eclipse plug-in projects, below are steps to create and populate Eclipse workspace with TCF projects:</p> @@ -98,7 +98,7 @@ below are steps to create and populate Eclipse workspace with TCF projects:</p> <dt><b>org.eclipse.tm.tcf</b> <dd>This is the main TCF plugin. It contains Eclipse integration code for the framework. It is the only TCF plugin, which (together with its fragments) should be required by a TCF client. The rest of TCF plugins are - clients developed as a reference implementation or for demonstration purposes. + clients developed as a reference implementation or for demonstration purposes. <p> <dt><b>org.eclipse.tm.tcf.core</b> <dd>This is a fragment of <b>org.eclipse.tm.tcf</b> plugin. It contains the framework itself and interfaces for standard services. @@ -160,7 +160,7 @@ following changes in settings may be necessary:<ul> add <tt>_CRT_SECURE_NO_DEPRECATE</tt></li> <li>Project > Properties > Linker > Input > Additional Dependencies : add <tt>shell32.lib</tt></li> -</ul></li> +</ul></li> </ul></p> <p>On <b>VxWorks</b>, line number mapping and the SysMonitor service (needed for RSE Processes @@ -322,7 +322,7 @@ The integration has only been tested on Linux at this point. <p><code>cd <<i>luadir</i>> <br>curl -O http://www.lua.org/ftp/lua-5.1.4.tar.gz -<br>tar zxf lua-5.1.4.tar.gz +<br>tar zxf lua-5.1.4.tar.gz <br>cd lua-5.1.4 <br>make linux <br>make local diff --git a/docs/TCF Project.html b/docs/TCF Project.html index 3feb27f88..373ad50e6 100644 --- a/docs/TCF Project.html +++ b/docs/TCF Project.html @@ -12,9 +12,9 @@ <H2><A name='Index'></A>Index</H2> <UL> - <LI><A href="#Summary">Summary</A> - <LI><A href="#Goals">Goals</A> - <LI><A href="#Features">Features</A> + <LI><A href="#Summary">Summary</A> + <LI><A href="#Goals">Goals</A> + <LI><A href="#Features">Features</A> <LI><A href="#Agent">Reference implementation of a target agent</A> <LI><A href="#Debugger">Prototype of a debugger based on Eclipse Debug Framework and TCF</A> <LI><A href="#RSE">Prototype of a system monitor and remote file access based on Remote System Explorer and TCF</A> @@ -23,46 +23,46 @@ <P> <H2><A name='Summary'></A>Summary </H2> -<P>Today almost every device software development tool on the market has its own -method of communication with target system. Communication methods often conflict -with each other, require individual setup, configuration and maintenance, impose -all kinds of unnecessary limitations. Target Communication Framework is designed -to establish common ground in the area of communication protocols between -development tools and embedded devices. +<P>Today almost every device software development tool on the market has its own +method of communication with target system. Communication methods often conflict +with each other, require individual setup, configuration and maintenance, impose +all kinds of unnecessary limitations. Target Communication Framework is designed +to establish common ground in the area of communication protocols between +development tools and embedded devices. <P> <H2><A name='Goals'></A>Goals </H2> <P> <UL> - <LI>Universal, extensible, simple, lightweight, vendor agnostic framework for - tools and targets to communicate for purpose of debugging, profiling, code - patching and other device software development needs. - <LI>Single configuration per target (not per tool per target as today in most - cases), or no configuration when possible. + <LI>Universal, extensible, simple, lightweight, vendor agnostic framework for + tools and targets to communicate for purpose of debugging, profiling, code + patching and other device software development needs. + <LI>Single configuration per target (not per tool per target as today in most + cases), or no configuration when possible. <LI>Small overhead and footprint on target side. </LI></UL> <P> <H2><A name='Features'></A>Features </H2> -<P><A href="TCF Specification.html">Target Communication Framework Specification</A> is a document -describing design goals, requirements and format of TCF communication protocol, -as well as framework API and software design considerations. -<P>TCF communication model is based on the idea of services. A service is a group -of related commands, events and semantics. A service can be discovered, -added or removed as a group at communication endpoint. Service definitions are -not part of the framework specification, and new services are expected to be -defined by developers of tools and target agents. However, standardization of -common services is needed to achieve certain level of compatibility of +<P><A href="TCF Specification.html">Target Communication Framework Specification</A> is a document +describing design goals, requirements and format of TCF communication protocol, +as well as framework API and software design considerations. +<P>TCF communication model is based on the idea of services. A service is a group +of related commands, events and semantics. A service can be discovered, +added or removed as a group at communication endpoint. Service definitions are +not part of the framework specification, and new services are expected to be +defined by developers of tools and target agents. However, standardization of +common services is needed to achieve certain level of compatibility of tools/targets, see <A href="TCF Services.html">TCF Services Specification</A> -as starting point of this work. +as starting point of this work. <H2><A name='Agent'></A>Reference implementation of a target agent</H2> -<P>Current reference implementation of TCF target agents is fully functional, -can run on Windows, Linux and VxWorks. On Linux it is implemented -using PTRACE, on VxWorks is uses vxdbgLib, on Windows it uses Debug API and dbghelp.dll. -The agent provides the following services: +<P>Current reference implementation of TCF target agents is fully functional, +can run on Windows, Linux and VxWorks. On Linux it is implemented +using PTRACE, on VxWorks is uses vxdbgLib, on Windows it uses Debug API and dbghelp.dll. +The agent provides the following services: <UL> - <LI>Run Control - provides threads and processes run control functionality + <LI>Run Control - provides threads and processes run control functionality sufficient for debugging of user space programs. <LI>Breakpoints - provides basic breakpoints support. @@ -72,7 +72,7 @@ The agent provides the following services: <LI>Memory - program memory access. - <LI>Processes - provides access to the target OS's process + <LI>Processes - provides access to the target OS's process information, allows starting new and terminating existing processes, and allows attaching and detaching processes for debugging. @@ -80,56 +80,56 @@ The agent provides the following services: and corresponding machine instruction addresses in the executable object. Implemented for Linux and Windows, not supported on VxWorks. - <LI>Sys Monitor - provides list of processes, process attributes and - CPU/memory utilization data. On Linux it is implemented using /proc file - system, on Windows and VxWorks it is not currently supported. + <LI>Sys Monitor - provides list of processes, process attributes and + CPU/memory utilization data. On Linux it is implemented using /proc file + system, on Windows and VxWorks it is not currently supported. <LI>File System - provides access to remote file system. - + <LI>Streams - a generic service to support streaming of data between host and target. - <LI>Diagnostics - allows testing of communication channel and agent + <LI>Diagnostics - allows testing of communication channel and agent functionality. </UL> -<P>The agent code is designed to be easily extensible by adding new command -handler implementations. The code separates machine dependences, common TCF -logic and service implementations, which allows easy porting to a new OS or a -target and reconfiguring of the agent for specific needs. The code is written in +<P>The agent code is designed to be easily extensible by adding new command +handler implementations. The code separates machine dependences, common TCF +logic and service implementations, which allows easy porting to a new OS or a +target and reconfiguring of the agent for specific needs. The code is written in ANSI C. See <A href="TCF Linux Agent Prototype.html">TCF Linux Agent Prototype</A> -for more details about the agent code. +for more details about the agent code. <H2><A name='Debugger'></A>Prototype of a debugger based on Eclipse Debug Framework and TCF</H2> -<P>The prototype code connects Eclipse Debug Framework and Target Communication -Framework. It allows to launch Eclipse debug session by connecting to a target -running TCF agent, and then perform basic debugging tasks, like resuming, +<P>The prototype code connects Eclipse Debug Framework and Target Communication +Framework. It allows to launch Eclipse debug session by connecting to a target +running TCF agent, and then perform basic debugging tasks, like resuming, suspending, single-stepping, setting/removing breakpoints, etc. -<P>The prototype launch configuration autodetects TCF targets on a local network -and allows a user to connect to a target by simply selecting it from a list -without a need for any further configuration or setup. TCF launch configuration -dialog also offers controls to run a built-in diagnostics on a selecting target, -which perform stress testing of communication channel, agent and target itself: -<P><IMG alt="TCF launch configuration dialog" src="TCF_Launch_Dialog.jpg"> - -<P>The prototype makes use of flexible debug model element hierarchy support, -which is available in Eclipse debug framework since Eclipse 3.2. The flexible -hierarchy allows debugger views to be "data driven" or, in other words, dynamically -adapt to a given targets capabilities and structure, without a need to modify +<P>The prototype launch configuration autodetects TCF targets on a local network +and allows a user to connect to a target by simply selecting it from a list +without a need for any further configuration or setup. TCF launch configuration +dialog also offers controls to run a built-in diagnostics on a selecting target, +which perform stress testing of communication channel, agent and target itself: +<P><IMG alt="TCF launch configuration dialog" src="TCF_Launch_Dialog.jpg"> + +<P>The prototype makes use of flexible debug model element hierarchy support, +which is available in Eclipse debug framework since Eclipse 3.2. The flexible +hierarchy allows debugger views to be "data driven" or, in other words, dynamically +adapt to a given targets capabilities and structure, without a need to modify debugger code to support a new target. - + <H2><A name='RSE'></A>Prototype of a system monitor and remote file access based on Remote System Explorer and TCF</H2> -<P>Remote System Explorer is an Eclipse based component that allows users to -create connections to remote machines and explore their file systems, see list -of processes and access some other resources, like remote shells. Remote System -Explorer has been designed as a flexible, extensible framework to which Eclipse -plug-in developers can contribute their own system definitions, actions, etc. -<P>The prototype enables use of Processes and Files subsystems of Remote System -Explorer over TCF. It also extends Processes subsystem to include CPU +<P>Remote System Explorer is an Eclipse based component that allows users to +create connections to remote machines and explore their file systems, see list +of processes and access some other resources, like remote shells. Remote System +Explorer has been designed as a flexible, extensible framework to which Eclipse +plug-in developers can contribute their own system definitions, actions, etc. +<P>The prototype enables use of Processes and Files subsystems of Remote System +Explorer over TCF. It also extends Processes subsystem to include CPU utilization data and some other process attributes in RSE views: -<P><IMG alt="Remote System Explorer: Files subsystem over TCF" src="TCF_RSE_Files.jpg"> -<P><IMG alt="Remote System Explorer: Processes subsystem over TCF" src="TCF_RSE_Processes.jpg"> +<P><IMG alt="Remote System Explorer: Files subsystem over TCF" src="TCF_RSE_Files.jpg"> +<P><IMG alt="Remote System Explorer: Processes subsystem over TCF" src="TCF_RSE_Processes.jpg"> </BODY> </HTML>
\ No newline at end of file diff --git a/docs/TCF Service - Breakpoints.html b/docs/TCF Service - Breakpoints.html index d58617ff7..0bf6ce047 100644 --- a/docs/TCF Service - Breakpoints.html +++ b/docs/TCF Service - Breakpoints.html @@ -5,9 +5,9 @@ </head> <body lang='EN-US'> - + <h1>Target Communication Framework Services - Breakpoints</h1> - + <ul> <li><a href='#VersionHistory'>Version History</a> <li><a href='#Overview'>Overview</a> @@ -55,16 +55,16 @@ <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>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 +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: <ul><b> <li>Location properties <li>Condition properties <li>Action properties </b></ul> -<p>The Location and Condition properties dictate how a breakpoint is installed and whether it should be triggered. +<p>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. <p>The split of Location and Condition properties is subjective and is @@ -83,19 +83,19 @@ change in any of the attached contexts. Adding properties reduces the (sub)set of state changes that triggers the breakpoint. <p>The <b>Location properties category</b> contains the following properties: -<p>Context defining properties specifying which context a breakpoint applies to are provided through the <a href='#propContextIds'>ContextIds</a>, -<a href='#propContextNames'>ContextNames </a> or the <a href='#propExecPaths'>ExecutablePaths</a> properties. +<p>Context defining properties specifying which context a breakpoint applies to are provided through the <a href='#propContextIds'>ContextIds</a>, +<a href='#propContextNames'>ContextNames </a> or the <a href='#propExecPaths'>ExecutablePaths</a> properties. <p>The presence of certain properties defines what kind of breakpoint is installed. <ul> -<li>Line Breakpoints, which are configured using the <a href='#propFile'>File</a>, +<li>Line Breakpoints, which are configured using the <a href='#propFile'>File</a>, <a href='#propLine'>Line</a> and <a href='#propColumn'>Column</a> properties -<li>Address breakpoints and watchpoints are configured using the <a href='#propLocation'>Location</a>, -<a href='#propAccessMode'>AccessMode</a>, <a href='#propSize'>Size</a>, +<li>Address breakpoints and watchpoints are configured using the <a href='#propLocation'>Location</a>, +<a href='#propAccessMode'>AccessMode</a>, <a href='#propSize'>Size</a>, <a href='#propMaskValue'>MaskValue </a>and <a href='#propMask'>Mask</a> properties. -<li>Temporal breakpoints which are located on a time scale are configured using the <a href='#propTime'>Time</a>, +<li>Temporal breakpoints which are located on a time scale are configured using the <a href='#propTime'>Time</a>, <a href='#propTimeScale'>TimeScale</a>, and <a href='#propTimeUnits'> TimeUnits</a> properties. </ul> @@ -112,14 +112,14 @@ like actual addresses where breakpoint is installed or installation errors. <p>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. +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. <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> @@ -141,8 +141,8 @@ C • <i><token></i> • Breakpoints • set • <i><array </font></b></pre> <p> 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 +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.<p> @@ -157,7 +157,7 @@ A breakpoint service implementation may not change the properties set by the cli <dd>Breakpoint ID. This is the only required property. <li><dt><code><b><font face="Courier New" size=2 color=#333399><a name='propeEnabled'>"Enabled"</a> : <i><boolean></i></font></b></code> - <dd>If true, the breakpoint is enabled. + <dd>If true, the breakpoint is enabled. <li><dt><code><b><font face="Courier New" size=2 color=#333399><a name='propType'>"Type"</a> : <i><string></i></font></b></code> <dd>The breakpoint type @@ -177,10 +177,10 @@ A breakpoint service implementation may not change the properties set by the cli <dd>This property contains an array of contexts names (such as a process/thread name) for which this breakpoint should be installed. <li><dt><code><b><font face="Courier New" size=2 color=#333399><a name='propExecPaths'>"ExecutablePaths"</a> : <i><string></i></font></b></code> - <dd>This property contains all the target executable paths for which this breakpoint should be installed. + <dd>This property contains all the target executable paths for which this breakpoint should be installed. <li><dt><code><b><font face="Courier New" size=2 color=#333399><a name='propLocation'> "Location" </a> : <i><string></i></font></b></code> - <dd>If preset, defines location of the breakpoint. The expression evaluates either to a memory address + <dd>If preset, defines location of the breakpoint. The expression evaluates either to a memory address or a register location. <li><dt><code><b><font face="Courier New" size=2 color=#333399><a name='propAccessMode'>"AccessMode"</a> : <i><int></i></font></b></code> @@ -195,7 +195,7 @@ A breakpoint service implementation may not change the properties set by the cli </dl> <li><dt><code><b><font face="Courier New" size=2 color=#333399><a name='propSize'>"Size"</a> : <i><int></i></font></b></code> <dd>The number of bytes starting at the location expression to which the AccessMode triggers applies - + <li><dt><code><b><font face="Courier New" size=2 color=#333399><a name='propFile'>"File"</a> : <i><string></i></font></b></code> <dd>Source code file name of breakpoint location. <li><dt><code><b><font face="Courier New" size=2 color=#333399><a name='propLine'>"Line"</a> : <i><int></i></font></b></code> @@ -204,7 +204,7 @@ A breakpoint service implementation may not change the properties set by the cli <dd>Source code column number of breakpoint location. <li><dt><code><b><font face="Courier New" size=2 color=#333399><a name='propMaskValue'>"MaskValue"</a> : <i><int></i></font></b></code> - <dd>A breakpoint can be qualified with a mask value which may be further refined with a mask. + <dd>A breakpoint can be qualified with a mask value which may be further refined with a mask. <li><dt><code><b><font face="Courier New" size=2 color=#333399><a name='propMask'>"Mask"</a> : <i><int></i></font></b></code> <dd>A mask which is bitwise ANDed with the value accessed. @@ -234,7 +234,7 @@ A breakpoint service implementation may not change the properties set by the cli <li><dt><code><b><font face="Courier New" size=2 color=#333399><a name='propIgnoreCount'>"IgnoreCount"</a>: <i><int></i></font></b></code> <dd>The number of times this breakpoint is to be ignored before it is triggered. The ignore count is tested after all other Location and Condition properties are validated. - + <li><dt><code><b><font face="Courier New" size=2 color=#333399><a name = 'propStopGroup'>"StopGroup"</a> : <i><string></i></font></b></code> <dd>An array of TCF Context identifiers representing contexts to be stopped when this breakpoint is triggered. This is an "Action" property that is used to stop contexts in addition to the one that triggered the breakpoint. @@ -427,8 +427,8 @@ R • <i><token></i> • <i><error report></i> • <i><b </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, +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.</p> <p>Predefined properties are:</p> @@ -455,7 +455,7 @@ in a list of instance status data objects <i><Instance status data list></i> ⇒ <i><Instance status data></i> ⇒ <i><Instance staus data list></i>, <i><Instance status data></i> - + <i><Instance status data></i> ⇒ <i><object></i> </font></b></pre> @@ -534,16 +534,16 @@ E • Breakpoints • contextRemoved • <i><array of breakpoint IDs </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 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 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 @@ -583,31 +583,31 @@ E • Breakpoints • contextRemoved • <i><array of breakpoint IDs PROP_TEMPORARY = "Temporary"; // Boolean <font color=#3F5FBF>/** - * BreakpointType values + * BreakpointType values */</font> <font color=#7F0055>static final</font> String TYPE_RELATIVE = "Software", TYPE_ABSOLUTE = "Hardware", TYPE_AUTO = "Auto"; - <font color=#3F5FBF>/** - * AccessMode values + <font color=#3F5FBF>/** + * AccessMode values */ </font> - <font color=#7F0055>static final</font> int + <font color=#7F0055>static final</font> int ACCESSMODE_READ = 0x01, - ACCESSMODE_WRITE = 0x02, + ACCESSMODE_WRITE = 0x02, ACCESSMODE_EXECUTE = 0x04, ACCESSMODE_CHANGE = 0x08; <font color=#3F5FBF>/** - * TimeScale values + * TimeScale values */</font> - <font color=#7F0055>static final</font> String + <font color=#7F0055>static final</font> String TIMESCALE_RELATIVE = "Relative", TIMESCALE_ABSOLUTE = "Absolute"; - + <font color=#3F5FBF>/** - * TimeUnits values + * TimeUnits values */</font> <font color=#7F0055>static final</font> String TIMEUNIT_NSECS = "Nanoseconds", @@ -623,7 +623,7 @@ E • Breakpoints • contextRemoved • <i><array of breakpoint IDs STATUS_FILE = "File", // String STATUS_LINE = "Line", // Number STATUS_COLUMN = "Column"; // Number - + <font color=#3F5FBF>/** * Breakpoint service capabilities. */</font> @@ -643,11 +643,11 @@ E • Breakpoints • contextRemoved • <i><array of breakpoint IDs <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 + * 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> @@ -687,7 +687,7 @@ E • Breakpoints • contextRemoved • <i><array of breakpoint IDs * @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. diff --git a/docs/TCF Service - File System.html b/docs/TCF Service - File System.html index 51666f56e..cd467db8e 100644 --- a/docs/TCF Service - File System.html +++ b/docs/TCF Service - File System.html @@ -5,9 +5,9 @@ </head> <body lang='EN-US'> - + <h1>Target Communication Framework Services - File System</h1> - + <ul> <li><a href='#VersionHistory'>Version History</a> <li><a href='#Overview'>Overview</a> @@ -63,7 +63,7 @@ <p>File System service provides file transfer (and more generally file system access) functionality in TCF. The service design is derived from SSH File Transfer Protocol specifications.</p> - + <h2><a name='ReqSync'>Request Synchronization and Reordering</a></h2> <p>The protocol and implementations MUST process requests relating to @@ -142,7 +142,7 @@ using a slash ('/') as the separator, and that will work as expected.</p> <dd>Forces an existing file with the same name to be truncated to zero length when creating a file by specifying TCF_O_CREAT. TCF_O_CREAT MUST also be specified if this flag is used. - + <dt><code>TCF_O_EXCL = 0x00000020</code> <dd>Causes the request to fail if the named file already exists. TCF_O_CREAT MUST also be specified if this flag is used. @@ -403,7 +403,7 @@ R • <i><token></i> • <i><array of directory entries></i> & ⇒ null ⇒ [ ] ⇒ [ <i><directory entry list></i> ] - + <i><directory entry list></i> ⇒ <i><directory entry></i> ⇒ <i><directory entry list></i> , <i><directory entry></i> @@ -468,7 +468,7 @@ C • <i><token></i> • FileSystem • roots • UNIX file system can report just one root with path "/". Other types of systems can have more the one root. For example, Windows server can return multiple roots: one per disc (e.g. "/C:/", "/D:/", etc.). Note: even Windows implementation of -the service must use forward slash as directory separator, and must start +the service must use forward slash as directory separator, and must start absolute path with "/". Server should implement proper translation of protocol file names to OS native names and back.</p> @@ -583,7 +583,7 @@ R • <i><token></i> • <i><error report></i> • C • <i><token></i> • FileSystem • user • </font></b></pre> -<p>The command retrieves information about user account, which is used by server +<p>The command retrieves information about user account, which is used by server to access file system on behalf of the client.</p> <p>Reply:</p> @@ -594,7 +594,7 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< </font></b></pre> <h2><a name='API'>API</a></h2> - + <pre> <font color=#3F5FBF>/** * File System service provides file transfer (and more generally file @@ -602,7 +602,7 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< * derived from SSH File Transfer Protocol specifications. */</font> <font color=#7F0055>public interface</font> IFileSystem <font color=#7F0055>extends</font> IService { - + <font color=#3F5FBF>/** * Service name. */</font> @@ -612,7 +612,7 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< * Flags to be used with open() method. */</font> <font color=#7F0055>static final int</font> - + <font color=#3F5FBF>/** * Open the file for reading. */</font> @@ -627,7 +627,7 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< <font color=#3F5FBF>/** * Force all writes to append data at the end of the file. */</font> - TCF_O_APPEND = 0x00000004, + TCF_O_APPEND = 0x00000004, <font color=#3F5FBF>/** * If this flag is specified, then a new file will be created if one @@ -672,30 +672,30 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< * server normally returns all attributes it knows about. */</font> <font color=#7F0055>final static class</font> FileAttrs { - + <font color=#3F5FBF>/** * The `flags' specify which of the fields are present. */</font> <font color=#7F0055>public final int</font> flags; - + <font color=#3F5FBF>/** * The `size' field specifies the size of the file in bytes. */</font> <font color=#7F0055>public final long</font> size; - + <font color=#3F5FBF>/** * The `uid' and `gid' fields contain numeric Unix-like user and group * identifiers, respectively. */</font> <font color=#7F0055>public final int</font> uid; <font color=#7F0055>public final int</font> gid; - + <font color=#3F5FBF>/** * The `permissions' field contains a bit mask of file permissions as * defined by posix [1]. */</font> <font color=#7F0055>public final int</font> permissions; - + <font color=#3F5FBF>/** * The `atime' and `mtime' contain the access and modification times of * the files, respectively. They are represented as milliseconds from @@ -708,13 +708,13 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< * Additional (non-standard) attributes. */</font> <font color=#7F0055>public final</font> Map<String,Object> attributes; - + <font color=#7F0055>public</font> FileAttrs(<font color=#7F0055>int</font> flags, <font color=#7F0055>long</font> size, <font color=#7F0055>int</font> uid, <font color=#7F0055>int</font> gid, <font color=#7F0055>int</font> permissions, <font color=#7F0055>long</font> atime, <font color=#7F0055>long</font> mtime, Map<String,Object> attributes); - + <font color=#3F5FBF>/** * Determines if the file system object is a file on the remote file system. - * + * * @return true if and only if the object on the remote system can be considered to have "contents" that * have the potential to be read and written as a byte stream. */</font> @@ -722,13 +722,13 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< <font color=#3F5FBF>/** * Determines if the file system object is a directory on the remote file system. - * + * * @return true if and only if the object on the remote system is a directory. * That is, it contains entries that can be interpreted as other files. */</font> <font color=#7F0055>public boolean</font> isDirectory(); } - + <font color=#3F5FBF>/** * The following flags are defined for the 'permissions' field: */</font> @@ -756,14 +756,14 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< S_IROTH = 00004, // others have read permission S_IWOTH = 00002, // others have write permisson S_IXOTH = 00001; // others have execute permission - + <font color=#7F0055>final static class</font> DirEntry { <font color=#3F5FBF>/** * `filename' is a file name being returned. It is a relative name within * the directory, without any path components; */</font> <font color=#7F0055>public final</font> String filename; - + <font color=#3F5FBF>/** * `longname' is an expanded format for the file name, similar to what * is returned by "ls -l" on Unix systems. @@ -775,29 +775,29 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< * use the attrs field instead. */</font> <font color=#7F0055>public final</font> String longname; - + <font color=#3F5FBF>/** * `attrs' is the attributes of the file. */</font> <font color=#7F0055>public final</font> FileAttrs attrs; - + <font color=#7F0055>public</font> DirEntry(String filename, String longname, FileAttrs attrs); } - + <font color=#3F5FBF>/** * Opaque representation of open file handle. - * Note: open file handle can be used only with service instance that + * Note: open file handle can be used only with service instance that * created the handle. */</font> <font color=#7F0055>interface</font> IFileHandle { IFileSystem getService(); } - + <font color=#3F5FBF>/** * Service specific error codes. */</font> <font color=#7F0055>static final int</font> - + <font color=#3F5FBF>/** * Indicates end-of-file condition; for read() it means that no * more data is available in the file, and for readdir() it @@ -817,19 +817,19 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< */</font> STATUS_PERMISSION_DENIED = 0x10003; - + <font color=#3F5FBF>/** - * The class to represent File System error reports. + * The class to represent File System error reports. */</font> <font color=#7F0055>abstract static class</font> FileSystemException extends IOException { - + <font color=#7F0055>protected</font> FileSystemException(String message); - + <font color=#7F0055>protected</font> FileSystemException(Exception x) - + <font color=#3F5FBF>/** * Get error code. The code can be standard TCF error code or - * one of service specific codes, see STATUS_*. + * one of service specific codes, see STATUS_*. * @return error code. */</font> <font color=#7F0055>public abstract int</font> getStatus(); @@ -837,7 +837,7 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< <font color=#3F5FBF>/** * Open or create a file on a remote system. - * + * * @param file_name specifies the file name. See 'File Names' for more information. * @param flags is a bit mask of TCF_O_* flags. * @param attrs specifies the initial attributes for the file. @@ -846,25 +846,25 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< * @return pending command handle. */</font> IToken open(String file_name, <font color=#7F0055>int</font> flags, FileAttrs attrs, DoneOpen done); - + <font color=#7F0055>interface</font> DoneOpen { <font color=#7F0055>void</font> doneOpen(IToken token, FileSystemException error, IFileHandle handle); } - + <font color=#3F5FBF>/** * Close a file on a remote system. - * + * * @param handle is a handle previously returned in the response to * open() or opendir(). * @param done is call back object. * @return pending command handle. */</font> IToken close(IFileHandle handle, DoneClose done); - + <font color=#7F0055>interface</font> DoneClose { <font color=#7F0055>void</font> doneClose(IToken token, FileSystemException error); } - + <font color=#3F5FBF>/** * Read bytes from an open file. * In response to this request, the server will read as many bytes as it @@ -875,7 +875,7 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< * true in case of EOF. For normal disk files, it is guaranteed * that this will read the specified number of bytes, or up to end of file * or error. For e.g. device files this may return fewer bytes than requested. - * + * * @param handle is an open file handle returned by open(). * @param offset is the offset (in bytes) relative * to the beginning of the file from where to start reading. @@ -884,7 +884,7 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< * @return pending command handle. */</font> IToken read(IFileHandle handle, long offset, <font color=#7F0055>int</font> len, DoneRead done); - + <font color=#7F0055>interface</font> DoneRead { <font color=#7F0055>void</font> doneRead(IToken token, FileSystemException error, byte[] data, boolean eof); } @@ -895,7 +895,7 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< * It is legal to write way beyond the end of the file; the semantics * are to write zeroes from the end of the file to the specified offset * and then the data. - * + * * @param handle is an open file handle returned by open(). * @param offset is the offset (in bytes) relative * to the beginning of the file from where to start writing. @@ -911,10 +911,10 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< <font color=#7F0055>interface</font> DoneWrite { <font color=#7F0055>void</font> doneWrite(IToken token, FileSystemException error); } - + <font color=#3F5FBF>/** * Retrieve file attributes. - * + * * @param path - specifies the file system object for which * status is to be returned. * @param done is call back object. @@ -925,27 +925,27 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< <font color=#3F5FBF>/** * Retrieve file attributes. * Unlike 'stat()', 'lstat()' does not follow symbolic links. - * + * * @param path - specifies the file system object for which * status is to be returned. * @param done is call back object. * @return pending command handle. */</font> IToken lstat(String path, DoneStat done); - + <font color=#3F5FBF>/** * Retrieve file attributes for an open file (identified by the file handle). - * + * * @param handle is a file handle returned by 'open()'. * @param done is call back object. * @return pending command handle. */</font> IToken fstat(IFileHandle handle, DoneStat done); - + <font color=#7F0055>interface</font> DoneStat { <font color=#7F0055>void</font> doneStat(IToken token, FileSystemException error, FileAttrs attrs); } - + <font color=#3F5FBF>/** * Set file attributes. * This request is used for operations such as changing the ownership, @@ -953,7 +953,7 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< * An error will be returned if the specified file system object does * not exist or the user does not have sufficient rights to modify the * specified attributes. - * + * * @param path specifies the file system object (e.g. file or directory) * whose attributes are to be modified. * @param attrs specifies the modifications to be made to file attributes. @@ -961,23 +961,23 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< * @return pending command handle. */</font> IToken setstat(String path, FileAttrs attrs, DoneSetStat done); - + <font color=#3F5FBF>/** * Set file attributes for an open file (identified by the file handle). * This request is used for operations such as changing the ownership, * permissions or access times, as well as for truncating a file. - * + * * @param handle is a file handle returned by 'open()'. * @param attrs specifies the modifications to be made to file attributes. * @param done is call back object. * @return pending command handle. */</font> IToken fsetstat(IFileHandle handle, FileAttrs attrs, DoneSetStat done); - + <font color=#7F0055>interface</font> DoneSetStat { <font color=#7F0055>void</font> doneSetStat(IToken token, FileSystemException error); } - + <font color=#3F5FBF>/** * The opendir() command opens a directory for reading. * Once the directory has been successfully opened, files (and @@ -991,7 +991,7 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< * @return pending command handle. */</font> IToken opendir(String path, DoneOpen done); - + <font color=#3F5FBF>/** * The files in a directory can be listed using the opendir() and * readdir() requests. Each readdir() request returns one @@ -1007,21 +1007,21 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< * @return pending command handle. */</font> IToken readdir(IFileHandle handle, DoneReadDir done); - + <font color=#7F0055>interface</font> DoneReadDir { <font color=#7F0055>void</font> doneReadDir(IToken token, FileSystemException error, DirEntry[] entries, boolean eof); } - + <font color=#3F5FBF>/** * Create a directory on the server. - * + * * @param path - specifies the directory to be created. * @param attrs - new directory attributes. * @param done - result call back object. * @return pending command handle. */</font> IToken mkdir(String path, FileAttrs attrs, DoneMkDir done); - + <font color=#7F0055>interface</font> DoneMkDir { <font color=#7F0055>void</font> doneMkDir(IToken token, FileSystemException error); } @@ -1032,13 +1032,13 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< * with the specified path exists, or if the specified directory is not * empty, or if the path specified a file system object other than a * directory. - * + * * @param path - specifies the directory to be removed. * @param done - result call back object. * @return pending command handle. */</font> IToken rmdir(String path, DoneRemove done); - + <font color=#7F0055>interface</font> DoneRemove { <font color=#7F0055>void</font> doneRemove(IToken token, FileSystemException error); } @@ -1048,15 +1048,15 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< * UNIX file system can report just one root with path "/". Other types of systems * can have more the one root. For example, Windows server can return multiple roots: * one per disc (e.g. "/C:/", "/D:/", etc.). Note: even Windows implementation of - * the service must use forward slash as directory separator, and must start + * the service must use forward slash as directory separator, and must start * absolute path with "/". Server should implement proper translation of - * protocol file names to OS native names and back. - * + * protocol file names to OS native names and back. + * * @param done - result call back object. * @return pending command handle. */</font> IToken roots(DoneRoots done); - + <font color=#7F0055>interface</font> DoneRoots { <font color=#7F0055>void</font> doneRoots(IToken token, FileSystemException error, DirEntry[] entries); } @@ -1064,24 +1064,24 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< <font color=#3F5FBF>/** * Remove a file or symbolic link. * This request cannot be used to remove directories. - * + * * @param file_name is the name of the file to be removed. * @param done - result call back object. * @return pending command handle. */</font> IToken remove(String file_name, DoneRemove done); - + <font color=#3F5FBF>/** * Canonicalize any given path name to an absolute path. * This is useful for converting path names containing ".." components or * relative pathnames without a leading slash into absolute paths. - * + * * @param path specifies the path name to be canonicalized. * @param done - result call back object. * @return pending command handle. */</font> IToken realpath(String path, DoneRealPath done); - + <font color=#7F0055>interface</font> DoneRealPath { <font color=#7F0055>void</font> doneRealPath(IToken token, FileSystemException error, String path); } @@ -1092,48 +1092,48 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< * with the name specified by 'new_path'. The server may also fail rename * requests in other situations, for example if `old_path' and `new_path' * point to different file systems on the server. - * + * * @param old_path is the name of an existing file or directory. * @param new_path is the new name for the file or directory. * @param done - result call back object. * @return pending command handle. */</font> IToken rename(String old_path, String new_path, DoneRename done); - + <font color=#7F0055>interface</font> DoneRename { <font color=#7F0055>void</font> doneRename(IToken token, FileSystemException error); } <font color=#3F5FBF>/** * Read the target of a symbolic link. - * + * * @param path specifies the path name of the symbolic link to be read. * @param done - result call back object. * @return pending command handle. */</font> IToken readlink(String path, DoneReadLink done); - + <font color=#7F0055>interface</font> DoneReadLink { <font color=#7F0055>void</font> doneReadLink(IToken token, FileSystemException error, String path); } <font color=#3F5FBF>/** * Create a symbolic link on the server. - * + * * @param link_path specifies the path name of the symbolic link to be created. * @param target_path specifies the target of the symbolic link. * @param done - result call back object. * @return pending command handle. */</font> IToken symlink(String link_path, String target_path, DoneSymLink done); - + <font color=#7F0055>interface</font> DoneSymLink { <font color=#7F0055>void</font> doneSymLink(IToken token, FileSystemException error); } <font color=#3F5FBF>/** * Copy a file on remote system. - * + * * @param src_path specifies the path name of the file to be copied. * @param dst_path specifies destination file name. * @param copy_permissions - if true then copy source file permissions. @@ -1143,20 +1143,20 @@ R • <i><token></i> • <i><int: real UID></i> • <i>< */</font> IToken copy(String src_path, String dst_path, boolean copy_permissions, boolean copy_ownership, DoneCopy done); - + <font color=#7F0055>interface</font> DoneCopy { <font color=#7F0055>void</font> doneCopy(IToken token, FileSystemException error); } - + <font color=#3F5FBF>/** - * Retrieve information about user account, which is used by server + * Retrieve information about user account, which is used by server * to access file system on behalf of the client. - * + * * @param done - result call back object. * @return pending command handle. */</font> IToken user(DoneUser done); - + <font color=#7F0055>interface</font> DoneUser { <font color=#7F0055>void</font> doneUser(IToken token, FileSystemException error, <font color=#7F0055>int</font> real_uid, <font color=#7F0055>int</font> effective_uid, <font color=#7F0055>int</font> real_gid, <font color=#7F0055>int</font> effective_gid, diff --git a/docs/TCF Service - Memory.html b/docs/TCF Service - Memory.html index 559ddcbe2..2079567fd 100644 --- a/docs/TCF Service - Memory.html +++ b/docs/TCF Service - Memory.html @@ -5,9 +5,9 @@ </head> <body lang='EN-US'> - + <h1>Target Communication Framework Services - Memory</h1> - + <ul> <li><a href='#VersionHistory'>Version History</a> <li><a href='#Overview'>Overview</a> @@ -53,20 +53,20 @@ and event parameters are encoded as zero terminated <a href='TCF Specification.h <p>The service uses standard format for error reports, see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> - + <p>A single memory access can succeed for some addresses and fail for others. In such situation result message can contain partially valid data. Array of error addresses, in addition to error report, describes data validity on per byte basis:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> <i><array of error addresses></i> ⇒ null ⇒ [ <i><error address list></i> ] - + <i><error address list></i> ⇒ <i><error address></i> ⇒ <i><error address list></i> , <i><error address></i> - + <i><error address></i> ⇒ { "addr" : <i><int: range starting address></i> , "size" : <i><int: range length in bytes></i> , "stat" : <i><int: status code></i> , "msg" : <i><object: error description></i> } </font></b></pre> @@ -86,7 +86,7 @@ byte is defined by main error report.</p> <h2><a name='Cmds'>Commands</a></h2> <h3><a name='CmdGetContext'>Get Context</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Memory • getContext • <i><string: context ID></i> • </font></b></pre> @@ -95,20 +95,20 @@ C • <i><token></i> • Memory • getContext • <i><stri execution thread, process, address space, etc. Exact meaning of a context depends on the target. Target agent should define contexts hierarchy that is:</p> - + <ul type='disc'> <li>Sufficient to resolve possible ambiguity of a memory address; - + <li>Adequately reflects target memory management strategy; - + <li>Intuitive to a user. </ul> - + <p>For traditional OS, like UNIX, memory access context can be one of:</p> - + <ul type='disc'> <li>Kernel address space; - + <li>A process. </ul> @@ -197,20 +197,20 @@ Service sends contextChanged event to notify changes in context data.</p> </ul> <h3><a name='CmdGetChildren'>Get Children</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Memory • getChildren • <i><string: parent context ID></i> • </font></b></pre> <p>The command requests a list of contexts available for memory access commands.</p> - + <p>Parent context ID can be null – to retrieve top level of the hierarchy, can be one of context IDs retrieved by previous getChildren commands, or it can be obtained from another service. 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.</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 context IDs></i> •<i></i> @@ -218,7 +218,7 @@ R • <i><token></i> • <i><error report></i> • <i><a ⇒ null ⇒ [ ] ⇒ [ <i><context ID list></i> ] - + <i><context ID list></i> ⇒ <i><string: context ID></i> ⇒ <i><context ID list></i> , <i><string: context ID></i> @@ -226,9 +226,9 @@ R • <i><token></i> • <i><error report></i> • <i><a </font></b></pre> <h3><a name='CmdSetMemory'>Set Memory</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> -C • <token> • Memory • set • +C • <token> • Memory • set • <i><string: context ID></i> • <i><int: address></i> • <i><int: word size></i> • <i><int: byte count></i> • <i><int: mode></i> • <i><string: BASE64 encoded byte array></i> • </font></b></pre> @@ -236,15 +236,15 @@ C • <token> • Memory • set • <p>Writes data bytes at given address in memory, "word size" bytes at a time. Address should be aligned by "word size". Context ID must be one returned by getContexts. Mode is logical OR of any combination of:</p> - + <ul type='disc'> <li>0x1 – continue on error (like bus error or page fault) - + <li>0x2 – verify data after writing by reading back and compare </ul> - + <p>Result message:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> R • <i><token></i> • <i><error report></i> • <i><array of error addresses></i> • </font></b></pre> @@ -254,7 +254,7 @@ of error. Error addresses, when present, let client know which bytes of data fai to be written into memory.</p> <h3><a name='CmdGetMemory'>Get Memory</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <token> • Memory • get • <i><string: context ID></i> • <i><int: address></i> • <i><int: word size></i> • @@ -264,15 +264,15 @@ C • <token> • Memory • get • <p>Reads data bytes at given address in memory, "word size" bytes at a time. Address should be aligned by "word size". Context ID must be one returned by getContexts. Mode is logical OR of any combination of:</p> - + <ul type='disc'> <li>0x1 – continue on error (like bus error or page fault) - + <li>0x2 – verify data after reading by re-reading and compare </ul> - + <p>Result message:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> R • <i><token></i> • <i><string: BASE64 encoded byte array></i> • <i><error report></i> • <i><array of error addresses></i> • </font></b></pre> @@ -282,9 +282,9 @@ of error. Error addresses, when present, let client know which bytes of data fai to be retrieved from memory.</p> <h3><a name='CmdFillMemory'>Fill Memory</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> -C • <token> • Memory • fill • +C • <token> • Memory • fill • <i><string: context ID></i> • <i><int: address></i> • <i><int: word size></i> • <int: byte count> • <i><int: mode></i> • <i><array: array of pattern bytes></i> • </font></b></pre> @@ -293,15 +293,15 @@ C • <token> • Memory • fill • should be aligned by "word size". If "byte count" is bigger then pattern size, then pattern is repeated necessary number of times. Context ID must be one returned by getContexts. Mode is logical OR of any combination of:</p> - + <ul type='disc'> <li>0x1 – continue on error (like bus error or page fault) - + <li>0x2 – verify data after writing by reading back and compare </ul> - + <p>Result message:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> R • <i><token></i> • <i><error report></i> • <i><array of error addresses></i> • </font></b></pre> @@ -311,29 +311,29 @@ of error. Error addresses, when present, let client know which bytes of data fai to be written into memory.</p> <h2><a name='Events'>Events</a></h2> - + <p>Memory service broadcasts notification events when memory contexts are added, removed or changed, and when memory content is altered by "set" or "fill" commands.</p> - + <pre><b><font face="Courier New" size=2 color=#333399> E • Memory • contextAdded • <i><array of context data></i> • E • Memory • contextChanged • <i><array of context data></i> • E • Memory • contextRemoved • <i><array of context IDs></i> • E • Memory • memoryChanged • <i><string: context ID></i> • <i><array of address ranges></i> • - + <i><array of context data></i> <font face="Times New Roman" size=3>- see Get Contexts command.</font> - + <i><array of context IDs></i> ⇒ [ <i><context ID list></i> ] - + <i><context ID list></i> ⇒ <i><string: context ID></i> ⇒ <i><context ID list></i> , <i><string: context ID></i> - + <i><array of address ranges></i> ⇒ null ⇒ [ <i><address ranges list></i> ] - + <i><address ranges list></i> ⇒ <i><address range></i> ⇒ <i><address ranges list></i> , <i><address range></i> @@ -343,13 +343,13 @@ E • Memory • memoryChanged • <i><string: context ID></i> &b </font></b></pre> <h2><a name='API'>API</a></h2> - + <pre> <font color=#3F5FBF>/** * IMemory service provides basic operations to read/write memory on a target. */</font> <font color=#7F0055>public interface</font> Memory <font color=#7F0055>extends</font> Service { - + <font color=#7F0055>static final</font> String NAME = "Memory"; <font color=#3F5FBF>/** @@ -365,7 +365,7 @@ E • Memory • memoryChanged • <i><string: context ID></i> &b PROP_START_BOUND = "StartBound", <font color=#3F5FBF>/** Number, lowest address (inclusive) which is valid for the context */</font> PROP_END_BOUND = "EndBound", <font color=#3F5FBF>/** Number, highest address (inclusive) which is valid for the context */</font> PROP_ACCESS_TYPES = "AccessTypes"; <font color=#3F5FBF>/** Array of String, the access types allowed for this context */</font> - + <font color=#3F5FBF>/** * Values of "AccessTypes". * Target system can support multiple different memory access types, like instruction and data access. @@ -386,11 +386,11 @@ E • Memory • memoryChanged • <i><string: context ID></i> &b ACCESS_PHYSICAL = "physical", <font color=#3F5FBF>/** Context uses physical addresses */</font> ACCESS_CACHE = "cache", <font color=#3F5FBF>/** Context is a cache */</font> ACCESS_TLB = "tlb"; <font color=#3F5FBF>/** Context is a TLB memory */</font> - + <font color=#3F5FBF>/** * Retrieve context info for given context ID. - * - * <font color=#7F9FBF>@param</font> id – context ID. + * + * <font color=#7F9FBF>@param</font> id – context ID. * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed. */</font> IToken getContext(String id, DoneGetContext done); @@ -416,7 +416,7 @@ E • Memory • memoryChanged • <i><string: context ID></i> &b * 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. - * + * * <font color=#7F9FBF>@param</font> parent_context_id – parent context ID. Can be null – * to retrieve top level of the hierarchy, or one of context IDs retrieved * by previous getContexts commands. @@ -443,89 +443,89 @@ E • Memory • memoryChanged • <i><string: context ID></i> &b * were not processed correctly. */</font> <font color=#7F0055>final static int</font> MODE_CONTINUEONERROR = 0x1; - + <font color=#3F5FBF>/** * Memory access mode: * Verify result of memory operations (by reading and comparing). */</font> <font color=#7F0055>final static int</font> MODE_VERIFY = 0x2; - + <font color=#7F0055>interface</font> MemoryContext { - - <font color=#3F5FBF>/** + + <font color=#3F5FBF>/** * Get context ID. * <font color=#7F9FBF>@return</font> context ID. */</font> String getID(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get parent context ID. * <font color=#7F9FBF>@return</font> parent ID. */</font> String getParentID(); - - <font color=#3F5FBF>/** + + <font color=#3F5FBF>/** * Get process ID, if applicable. * <font color=#7F9FBF>@return</font> process ID. */</font> String getProcessID(); - - <font color=#3F5FBF>/** + + <font color=#3F5FBF>/** * Get memory endianess. * <font color=#7F9FBF>@return</font> true if memory id big-endian. */</font> boolean isBigEndian(); - - <font color=#3F5FBF>/** + + <font color=#3F5FBF>/** * Get memory address size. * <font color=#7F9FBF>@return</font> number of bytes used to store memory address value. */</font> <font color=#7F0055>int</font> getAddressSize(); - - <font color=#3F5FBF>/** + + <font color=#3F5FBF>/** * Get memory context name. * The name can be used for UI purposes. * <font color=#7F9FBF>@return</font> context name. */</font> String getName(); - - <font color=#3F5FBF>/** + + <font color=#3F5FBF>/** * Get lowest address (inclusive) which is valid for the context. * <font color=#7F9FBF>@return</font> lowest address. */</font> Number getStartBound(); - - <font color=#3F5FBF>/** + + <font color=#3F5FBF>/** * Get highest address (inclusive) which is valid for the context. * <font color=#7F9FBF>@return</font> highest address. */</font> Number getEndBound(); - - <font color=#3F5FBF>/** + + <font color=#3F5FBF>/** * Get the access types allowed for this context. * <font color=#7F9FBF>@return</font> collection of access type names. */</font> Collection<String> getAccessTypes(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get context properties. * <font color=#7F9FBF>@return</font> all available context properties. */</font> Map<String,Object> getProperties(); - + <font color=#3F5FBF>/** * Set target memory. * If 'word_size' is 0 it means client does not care about word size. */</font> <font color=#7F0055>void</font> set(long addr, <font color=#7F0055>int</font> word_size, byte[] buf, <font color=#7F0055>int</font> offs, <font color=#7F0055>int</font> size, <font color=#7F0055>int</font> mode, DoneMemory done); - + <font color=#3F5FBF>/** * Read target memory. */</font> <font color=#7F0055>void</font> get(long addr, <font color=#7F0055>int</font> word_size, byte[] buf, <font color=#7F0055>int</font> offs, <font color=#7F0055>int</font> size, <font color=#7F0055>int</font> mode, DoneMemory done); - + <font color=#3F5FBF>/** * Fill target memory with given pattern. * 'size' is number of bytes to fill. @@ -533,7 +533,7 @@ E • Memory • memoryChanged • <i><string: context ID></i> &b <font color=#7F0055>void</font> fill(long addr, <font color=#7F0055>int</font> word_size, byte[] value, <font color=#7F0055>int</font> size, <font color=#7F0055>int</font> mode, DoneMemory done); } - + <font color=#3F5FBF>/** * Client callback interface for set(), get() and fill(). */</font> @@ -543,7 +543,7 @@ E • Memory • memoryChanged • <i><string: context ID></i> &b <font color=#7F0055>class</font> MemoryError <font color=#7F0055>extends</font> Exception { } - + <font color=#3F5FBF>/** * ErrorOffset interface can be implemented by MemoryError object, * which is returned by get, set and fill commands. @@ -556,26 +556,26 @@ E • Memory • memoryChanged • <i><string: context ID></i> &b * possible reasons of partial memory operation. */</font> <font color=#7F0055>interface</font> ErrorOffset { - + // Error may have per byte information - <font color=#7F0055>final static int</font> + <font color=#7F0055>final static int</font> BYTE_VALID = 0x00, BYTE_UNKNOWN = 0x01, // e.g. out of range BYTE_INVALID = 0x02, BYTE_CANNOT_READ = 0x04, BYTE_CANNOT_WRITE = 0x08; - + <font color=#7F0055>int</font> getStatus(<font color=#7F0055>int</font> offset); - + <font color=#3F5FBF>/** * Returns the detail message string about the * byte associated with specified location. * <font color=#7F9FBF>@return</font> the detail error message string. */</font> String getMessage(<font color=#7F0055>int</font> offset); - + } - + <font color=#3F5FBF>/** * Add memory service event listener. * <font color=#7F9FBF>@param</font> listener - event listener implementation. @@ -590,27 +590,27 @@ E • Memory • memoryChanged • <i><string: context ID></i> &b <font color=#3F5FBF>/** * Memory event listener is notified when memory context hierarchy - * changes, and when memory is modified by memory service commands. + * changes, and when memory is modified by memory service commands. */</font> <font color=#7F0055>interface</font> MemoryListener { - + <font color=#3F5FBF>/** * Called when a new memory access context(s) is created. */</font> <font color=#7F0055>void</font> contextAdded(Context[] contexts); - + <font color=#3F5FBF>/** * Called when a new memory access context(s) properties changed. */</font> <font color=#7F0055>void</font> contextChanged(Context[] contexts); - + <font color=#3F5FBF>/** * Called when memory access context(s) is removed. */</font> <font color=#7F0055>void</font> contextRemoved(String[] context_ids); - + <font color=#3F5FBF>/** - * Called when target memory content was changed and clients + * Called when target memory content was changed and clients * need to update themselves. Clients, at least, should invalidate * corresponding cached memory data. * Not every change is notified - it is not possible, diff --git a/docs/TCF Service - Processes.html b/docs/TCF Service - Processes.html index 1c0bfa5db..ec4a3d20e 100644 --- a/docs/TCF Service - Processes.html +++ b/docs/TCF Service - Processes.html @@ -5,9 +5,9 @@ </head> <body lang='EN-US'> - + <h1>Target Communication Framework Services - Processes</h1> - + <ul> <li><a href='#VersionHistory'>Version History</a> <li><a href='#Overview'>Overview</a> @@ -45,18 +45,18 @@ <tr> <td>0.2 <td>2009-02-26 - <td>Added signal and environment commands, and properties for standard I/O redirection + <td>Added signal and environment commands, and properties for standard I/O redirection </table> <h2><a name='Overview'>Overview</a></h2> -<p>Processes service provides access to the target OS's process +<p>Processes service provides access to the target OS's process information, allows to start and terminate a process, and allows to attach and detach a process for debugging. Debug services, like Memory and Run Control, require a process to be attached before they can access it.</p> -<p>If a process is started by this service, its standard input/output streams are +<p>If a process is started by this service, its standard input/output streams are available for client to read/write using <a href='TCF Service - Streams.html'>Streams Service</a>. Stream type of such streams is set to "Processes".</p> @@ -65,11 +65,11 @@ as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</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='CmdGetContext'>Get Context</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Processes • getContext • <i><string: context ID></i> • </font></b></pre> @@ -82,7 +82,7 @@ However, 'Processes.getContext' is supposed to return only process specific data If the ID is not a process ID, 'Processes.getContext' may not return any useful information. </p> - + <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> @@ -104,42 +104,42 @@ R • <i><token></i> • <i><error report></i> • <i><c <li><code><b><font face="Courier New" size=2 color=#333399>"ParentID" : <i><string></i></font></b></code> - parent context ID. - + <li><code><b><font face="Courier New" size=2 color=#333399>"Name" : <i><string></i></font></b></code> - process name. Client UI can show this name to a user. <li><code><b><font face="Courier New" size=2 color=#333399>"Attached" : <i><boolean></i></font></b></code> - true if the context is attached to debugger. - + <li><code><b><font face="Courier New" size=2 color=#333399>"CanTerminate" : <i><boolean></i></font></b></code> - true if the service can terminate the process. <li><code><b><font face="Courier New" size=2 color=#333399>"StdInID" : <i><string></i></font></b></code> - process standard input stream ID. - + <li><code><b><font face="Courier New" size=2 color=#333399>"StdOutID" : <i><string></i></font></b></code> - process standard output stream ID. - + <li><code><b><font face="Courier New" size=2 color=#333399>"StdErrID" : <i><string></i></font></b></code> - process standard error stream ID. </ul> <h3><a name='CmdGetChildren'>Get Children</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Processes • getChildren • <i><string: parent context ID></i> • <i><boolean: attached only></i> • </font></b></pre> <p>The command requests a list of contexts available for process control commands.</p> - + <p>Parent context ID can be null – to retrieve top level of the hierarchy, can be one of context IDs retrieved by previous getChildren commands, or it can be obtained from another service. 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.</p> <p>If <i><boolean: attached only></i> is true, the command returns only those processes that are attached for debugging.</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 context IDs></i> • @@ -147,65 +147,65 @@ R • <i><token></i> • <i><error report></i> • <i><a ⇒ null ⇒ [ ] ⇒ [ <i><context ID list></i> ] - + <i><context ID list></i> ⇒ <i><string: context ID></i> ⇒ <i><context ID list></i> , <i><string: context ID></i> </font></b></pre> <h3><a name='CmdAttach'>Attach</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Processes • attach • <i><string: context ID></i> • </font></b></pre> <p>The command attaches debugger to a process. Services like Run Control, Memory, Breakpoints work only with attached processes.</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='CmdDetach'>Detach</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Processes • detach • <i><string: context ID></i> • </font></b></pre> <p>The command detaches debugger from a process.</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='CmdTerminate'>Terminate</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Processes • terminate • <i><string: context ID></i> • </font></b></pre> <p>The command terminates a process.</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='CmdGetSignalList'>Get Signal List</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Processes • getSignalList • <i><string: context ID></i> • </font></b></pre> <p>The command returns a complete list of available signals. The list containg all signals that can be sent to a given context.</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 signal descriptions></i> • @@ -213,7 +213,7 @@ R • <i><token></i> • <i><error report></i> • <i><a ⇒ null ⇒ [ ] ⇒ [ <i><signal description list></i> ] - + <i><signal description list></i> ⇒ <i><object: signal description></i> ⇒ <i><signal description list></i> , <i><object: signal description></i> @@ -233,7 +233,7 @@ R • <i><token></i> • <i><error report></i> • <i><a <h3><a name='CmdGetSignalMask'>Get Signal Mask</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Processes • getSignalMask • <i><string: context ID></i> • </font></b></pre> @@ -244,7 +244,7 @@ When new context is created it inherits the mask from its parent. If context is not attached the command will return an error.</p> <p>Reply:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> R • <i><token></i> • <i><error report></i> • <i><int: don't stop bitset></i> • <i><int: don't pass bitset></i> • <i><int: pending bitset></i> • </font></b></pre> @@ -256,7 +256,7 @@ R • <i><token></i> • <i><error report></i> • <i><i Note: "pending bitset" is meaningful only if the context is suspended. <h3><a name='CmdSetSignalMask'>Set Signal Mask</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Processes • setSignalMask • <i><string: context ID></i> • <i><int: don't stop bitset></i> • <i><int: don't pass bitset></i> • </font></b></pre> @@ -266,46 +266,46 @@ Bits in the mask control how signals should be handled by debug agent. If context is not attached the command will return an error.</p> <ul> <li>don't stop bitset - signals that should not suspend execution of the context. - By default, debugger suspends a process before it receives a signal. + By default, debugger suspends a process before it receives a signal. <li>don't pass bitset - signals that should not be delivered to the context. </ul> - + <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='CmdSignal'>Signal</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Processes • signal • <i><string: context ID></i> • <i><int: signal></i> • </font></b></pre> <p>The command sends a signal to a context.</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='CmdGetEnvironment'>Get Environment</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Processes • getEnvironment • </font></b></pre> <p>The command returns default set of environment variables used to start a new process.</p> - + <p>Reply:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> R • <i><token></i> • <i><error report></i> • <i><object: environment variables></i> • </font></b></pre> <h3><a name='CmdStart'>Start</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Processes • start • <i><string: working directory></i> • <i><string: program image file></i> • <i><string array: command line></i> • <i><object: environment variables></i> • <i><boolean: attach></i> • @@ -314,7 +314,7 @@ C • <i><token></i> • Processes • start • <i><string ⇒ null ⇒ [ ] ⇒ [ <i><string list></i> ] - + <i><string list></i> ⇒ <i><string></i> ⇒ <i><string list></i> , <i><string></i> @@ -326,12 +326,12 @@ C • <i><token></i> • Processes • start • <i><string <li><i><string: program image file></i> - image file to start process with. <li><i><string array: command line></i> - command line arguments for the process. <li><i><object: environment variables></i> - list of environment variables for the process, - they will be added to default process environment. + they will be added to default process environment. <li><i><boolean: attach></i> - if true debugger should be attached to the process.</p> </ul> - + <p>Reply:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> R • <i><token></i> • <i><error report></i> • <i><context data></i> • </font></b></pre> @@ -342,18 +342,18 @@ R • <i><token></i> • <i><error report></i> • <i><c <p>Processes service broadcasts notification event when a proceess exits. Only processes that were started by the service will generate exit event.</p> - + <pre><b><font face="Courier New" size=2 color=#333399> E • Processes • exited • <i><string: process ID></i> • <i><int: exit code></i> • </font></b></pre> <h2><a name='API'>API</a></h2> - + <pre> <font color=#7F0055>public interface</font> IProcesses <font color=#7F0055>extends</font> IService { <font color=#7F0055>static final</font> String NAME = "Processes"; - + <font color=#3F5FBF>/** * Retrieve context info for given context ID. * A context corresponds to an execution thread, process, address space, etc. @@ -363,8 +363,8 @@ E • Processes • exited • <i><string: process ID></i> • * However, 'Processes.getContext' is supposed to return only process specific data, * If the ID is not a process ID, 'IProcesses.getContext' may not return any * useful information - * - * <font color=#7F9FBF>@param</font> id – context ID. + * + * <font color=#7F9FBF>@param</font> id – context ID. * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. */</font> IToken getContext(String id, DoneGetContext done); @@ -383,10 +383,10 @@ E • Processes • exited • <i><string: process ID></i> • <font color=#3F5FBF>/** * Retrieve children of given context. - * + * * <font color=#7F9FBF>@param</font> 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. + * by previous getContext or getChildren commands. * <font color=#7F9FBF>@param</font> attached_only - if true return only attached process IDs. * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. */</font> @@ -403,38 +403,38 @@ E • Processes • exited • <i><string: process ID></i> • */</font> <font color=#7F0055>void</font> doneGetChildren(IToken token, Exception error, String[] context_ids); } - + <font color=#3F5FBF>/** * Context property names. */</font> <font color=#7F0055>static final</font> String <font color=#3F5FBF>/** The TCF context ID */</font> PROP_ID = "ID", - + <font color=#3F5FBF>/** The TCF parent context ID */</font> PROP_PARENTID = "ParentID", - + <font color=#3F5FBF>/** Is the context attached */</font> PROP_ATTACHED = "Attached", - + <font color=#3F5FBF>/** Can terminate the context */</font> PROP_CAN_TERMINATE = "CanTerminate", - + <font color=#3F5FBF>/** Process name. Client UI can show this name to a user */</font> PROP_NAME = "Name", <font color=#3F5FBF>/** Process standard input stream ID */</font> PROP_STDIN_ID = "StdInID", - + <font color=#3F5FBF>/** Process standard output stream ID */</font> PROP_STDOUT_ID = "StdOutID", - + <font color=#3F5FBF>/** Process standard error stream ID */</font> PROP_STDERR_ID = "StdErrID"; - + <font color=#7F0055>interface</font> ProcessContext { - - <font color=#3F5FBF>/** + + <font color=#3F5FBF>/** * Get context ID. * Same as getProperties().get(“ID”) */</font> @@ -471,7 +471,7 @@ E • Processes • exited • <i><string: process ID></i> • * <font color=#7F9FBF>@return</font> Map 'property name' -> 'property value' */</font> Map<String, Object> getProperties(); - + <font color=#3F5FBF>/** * Attach debugger to a process. * Services like IRunControl, IMemory, IBreakpoints work only with attached processes. @@ -487,15 +487,15 @@ E • Processes • exited • <i><string: process ID></i> • * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. */</font> IToken detach(DoneCommand done); - + <font color=#3F5FBF>/** - * Terminate a process. + * Terminate a process. * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. */</font> IToken terminate(DoneCommand done); } - + <font color=#7F0055>interface</font> DoneCommand { <font color=#7F0055>void</font> doneCommand(IToken token, Exception error); } @@ -506,16 +506,16 @@ E • Processes • exited • <i><string: process ID></i> • <font color=#7F0055>static final</font> String <font color=#3F5FBF>/** Number, bit position in the signal mask */</font> SIG_INDEX = "Index", - + <font color=#3F5FBF>/** String, signal name, for example "SIGHUP" */</font> SIG_NAME = "Name", - + <font color=#3F5FBF>/** Number, signal code, as defined by OS */</font> SIG_CODE = "Code", - + <font color=#3F5FBF>/** String, human readable description of the signal */</font> SIG_DESCRIPTION = "Description"; - + <font color=#3F5FBF>/** * Get list of signals that can be send to the context. * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. @@ -529,17 +529,17 @@ E • Processes • exited • <i><string: process ID></i> • <font color=#7F0055>interface</font> DoneGetSignalList { <font color=#7F0055>void</font> doneGetSignalList(IToken token, Exception error, Collection<Map<String,Object>> list); } - + <font color=#3F5FBF>/** * Get process or thread signal mask. * Bits in the mask control how signals should be handled by debug agent. * When new context is created it inherits the mask from its parent. - * If context is not attached the command will return an error. + * If context is not attached the command will return an error. * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. */</font> IToken getSignalMask(String context_id, DoneGetSignalMask done); - + <font color=#3F5FBF>/** * Call-back interface to be called when "getSignalMask" command is complete. */</font> @@ -553,13 +553,13 @@ E • Processes • exited • <i><string: process ID></i> • */</font> <font color=#7F0055>void</font> doneGetSignalMask(IToken token, Exception error, <font color=#7F0055>int</font> dont_stop, <font color=#7F0055>int</font> dont_pass, <font color=#7F0055>int</font> pending); } - + <font color=#3F5FBF>/** - * Set process or thread signal mask. + * Set process or thread signal mask. * Bits in the mask control how signals should be handled by debug agent. - * If context is not attached the command will return an error. + * If context is not attached the command will return an error. * <font color=#7F9FBF>@param</font> dont_stop - bit-set of signals that should not suspend execution of the context. - * By default, debugger suspends a context before it receives a signal. + * By default, debugger suspends a context before it receives a signal. * <font color=#7F9FBF>@param</font> dont_pass - bit-set of signals that should not be delivered to the context. * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. @@ -581,7 +581,7 @@ E • Processes • exited • <i><string: process ID></i> • * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. */</font> IToken getEnvironment(DoneGetEnvironment done); - + <font color=#3F5FBF>/** * Call-back interface to be called when "getEnvironment" command is complete. */</font> @@ -594,15 +594,15 @@ E • Processes • exited • <i><string: process ID></i> • * <font color=#7F9FBF>@param</font> directory - initial value of working directory for the process. * <font color=#7F9FBF>@param</font> file - process image file. * <font color=#7F9FBF>@param</font> command_line - command line arguments for the process. - * <font color=#7F9FBF>@param</font> environment - list of environment variables for the process. - * if null then default set of environment variables will be used. + * <font color=#7F9FBF>@param</font> environment - list of environment variables for the process. + * if null then default set of environment variables will be used. * <font color=#7F9FBF>@param</font> attach - if true debugger should be attached to the process. * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. */</font> IToken start(String directory, String file, String[] command_line, String[] environment, <font color=#7F0055>boolean</font> attach, DoneStart done); - + <font color=#3F5FBF>/** * Call-back interface to be called when "start" command is complete. */</font> @@ -624,10 +624,10 @@ E • Processes • exited • <i><string: process ID></i> • <font color=#3F5FBF>/** * Process event listener is notified when a process exits. - * Event are reported only for processes that were started by 'start' command. + * Event are reported only for processes that were started by 'start' command. */</font> <font color=#7F0055>interface</font> ProcessesListener { - + <font color=#3F5FBF>/** * Called when a process exits. * <font color=#7F9FBF>@param</font> process_id - process context ID diff --git a/docs/TCF Service - Registers.html b/docs/TCF Service - Registers.html index 11892d390..d94a6da53 100644 --- a/docs/TCF Service - Registers.html +++ b/docs/TCF Service - Registers.html @@ -5,9 +5,9 @@ </head> <body lang='EN-US'> - + <h1>Target Communication Framework Services - Registers</h1> - + <ul> <li><a href='#VersionHistory'>Version History</a> <li><a href='#Overview'>Overview</a> @@ -67,11 +67,11 @@ multiple locations. This allows: <li> to specify offset and size for get/set on large register groups <li> to get/set truncated register values, e.g. only the low 32 bits of a 64-bit register </ol> - + <h2><a name='Cmds'>Commands</a></h2> <h3><a name='CmdGetContext'>Get Context</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Registers • getContext • <i><string: context ID></i> • </font></b></pre> @@ -79,13 +79,13 @@ C • <i><token></i> • Registers • getContext • <i><s <p>The command retrieves context info for given context ID. A context corresponds to an register, register group, register bit field, etc. Exact meaning of a context depends on the target. Target agent should define contexts hierarchy that is:</p> - + <ul type='disc'> <li>Adequately reflects target hardware registers layout; <li>Consistent with the lingo/terminology of the processor manuals; <li>Intuitive to a user. </ul> - + <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> @@ -165,7 +165,7 @@ Service sends contextChanged event to notify changes in context data.</p> ⇒ null ⇒ [ ] ⇒ [ <i><named values list></i> ] - + <i><named values list></i> ⇒ <i><object: named value properties></i> ⇒ <i><named values list></i> , <i><object: named value properties></i> @@ -218,20 +218,20 @@ Service sends contextChanged event to notify changes in context data.</p> </ul> <h3><a name='CmdGetChildren'>Get Children</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Registers • getChildren • <i><string: parent context ID></i> • </font></b></pre> <p>The command requests a list of contexts available for registers access commands.</p> - + <p>Parent context ID is usually a thread ID retrieved through Run Control Service or one of context IDs retrieved by previous getChildren commands. Contexts hierarchy can be simple plain list of registers, or it can form a tree of register groups, registers and bit fields. It is up to target agent developers to choose layout that is most descriptive for a given target.</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 context IDs></i> •<i></i> @@ -239,7 +239,7 @@ R • <i><token></i> • <i><error report></i> • <i><a ⇒ null ⇒ [ ] ⇒ [ <i><context ID list></i> ] - + <i><context ID list></i> ⇒ <i><string: context ID></i> ⇒ <i><context ID list></i> , <i><string: context ID></i> @@ -247,16 +247,16 @@ R • <i><token></i> • <i><error report></i> • <i><a </font></b></pre> <h3><a name='CmdSetRegister'>Set Register</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <token> • Registers • set • <i><string: context ID></i> • <i><string: value></i> • </font></b></pre> <p>Writes value into given register context. Context ID must be one returned by getContexts. Value is BASE64 encoded byte array of binary data. Array size should match the size of the register.</p> - + <p>Result message:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> R • <i><token></i> • <i><error report></i> • </font></b></pre> @@ -265,16 +265,16 @@ R • <i><token></i> • <i><error report></i> • of error.</p> <h3><a name='CmdGetRegister'>Get Register</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <token> • Registers • get • <i><string: context ID></i> • </font></b></pre> <p>Reads register value from given register context. Context ID must be one returned by getContexts. </p> - + <p>Result message:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> R • <i><token></i> • <i><error report></i> • <i><string: value></i> • </font></b></pre> @@ -283,7 +283,7 @@ R • <i><token></i> • <i><error report></i> • <i><s of error. Value is BASE64 encoded byte array of binary data. Array size should match the size of the register.</p> <h3><a name='CmdSetMultiple'>Set Multiple Registers</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <token> • Registers • setm • <i><array of locations></i> • <i><string: value></i> • @@ -293,7 +293,7 @@ C • <token> • Registers • setm • <i><array of locat <i><location list></i> ⇒ <i><location></i> ⇒ <i><location list></i> , <i><location></i> - + <i><location></i> ⇒ [ <i><string: register context ID></i> , <i><int: offset in bytes></i> , <i><int: size in bytes></i> ] </font></b></pre> @@ -301,9 +301,9 @@ C • <token> • Registers • setm • <i><array of locat <p>Writes value into given list of locations in registers. Each location is represented by 3-element array that consists of context ID, offset in the context in bytes and value size in bytes. Value is BASE64 encoded byte array of binary data. Byte array size should match the sum of location sizes.</p> - + <p>Result message:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> R • <i><token></i> • <i><error report></i> • </font></b></pre> @@ -312,7 +312,7 @@ R • <i><token></i> • <i><error report></i> • of error.</p> <h3><a name='CmdGetMultiple'>Get Multiple Registers</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <token> • Registers • getm • <i><array of locations></i> • @@ -322,7 +322,7 @@ C • <token> • Registers • getm • <i><array of locat <i><location list></i> ⇒ <i><location></i> ⇒ <i><location list></i> , <i><location></i> - + <i><location></i> ⇒ [ <i><string: register context ID></i> , <i><int: offset in bytes></i> , <i><int: size in bytes></i> ] </font></b></pre> @@ -330,9 +330,9 @@ C • <token> • Registers • getm • <i><array of locat <p>Reads register values from given list of locations in registers. Each location is represented by 3-element array that consists of context ID, offset in the context in bytes and value size in bytes. </p> - + <p>Result message:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> R • <i><token></i> • <i><error report></i> • <i><string: value></i> • </font></b></pre> @@ -341,12 +341,12 @@ R • <i><token></i> • <i><error report></i> • <i><s of error. Value is BASE64 encoded byte array of binary data. Byte array size should match the sum of location sizes.</p> <h3><a name='CmdSearch'>Search for Registers</a></h3> - + <pre><b><font face="Courier New" size="2" color="#333399"> C • <token> • Registers • search • <i><string: start context ID> • <object:filter properties></i> • </font></b></pre> -<p>Search returns a path to each context with properties matching the filter. A path consists of a list of +<p>Search returns a path to each context with properties matching the filter. A path consists of a list of context ids starting with a direct child of the start context up to the found context. Search is only supported for properties listed in the CanSearch property. @@ -360,9 +360,9 @@ C • <token> • Registers • search • <i><string: star </li> </ul> </p> - + <p>Result message:</p> - + <pre><b><font face="Courier New" size="2" color="#333399"> R • <i><token></i> • <i><error report></i> • <i><array of context Paths></i> • @@ -370,7 +370,7 @@ R • <i><token></i> • <i><error report></i> • <i><a ⇒ null ⇒ [ ] ⇒ [ <i><context Path list></i> ] - + <i><context Path list></i> ⇒ <i><array of context IDs></i> ⇒ <i><context Path list></i> , <i><array of context IDs></i> @@ -404,17 +404,17 @@ R • "1235" • [["ID_G0"]] • </font></b></pre> <h2><a name='Events'>Events</a></h2> - + <p>Registers service broadcasts notification events when registers contexts are changed, and when a register content is altered by "set" commands.</p> - + <pre><b><font face="Courier New" size="2" color="#333399"> E • Registers • contextChanged • E • Registers • registerChanged • <i><string: context ID></i> • </font></b></pre> <h2><a name='API'>API</a></h2> - + <pre> <font color=#3F5FBF>/** * IRegisters service provides access to target CPU register values and properties. @@ -449,7 +449,7 @@ E • Registers • registerChanged • <i><string: context ID></ PROP_MEMORY_CONTEXT = "MemoryContext", <font color=#3F5FBF>/** String, the context ID of a memory context in which a memory mapped register is located */</font> PROP_CAN_SEARCH = "CanSearch", <font color=#3F5FBF>/** Array of String, a list of attribute names which can be searched for starting on this context */</font> PROP_ROLE = "Role"; <font color=#3F5FBF>/** String, the role the register plays in a program execution */</font> - + <font color=#3F5FBF>/** * Role property names. */</font> @@ -459,7 +459,7 @@ E • Registers • registerChanged • <i><string: context ID></ ROLE_FP = "FP", <font color=#3F5FBF>/** Register defining the current frame pointer location */</font> ROLE_RET = "RET", <font color=#3F5FBF>/** Register used to store the return address for calls */</font> ROLE_CORE = "CORE"; <font color=#3F5FBF>/** Indicates register or register groups which belong to the core state */</font> - + <font color=#3F5FBF>/** * Filter property names. */</font> @@ -470,8 +470,8 @@ E • Registers • registerChanged • <i><string: context ID></ <font color=#3F5FBF>/** * Retrieve context info for given context ID. - * - * <font color=#7F9FBF>@param</font> id – context ID. + * + * <font color=#7F9FBF>@param</font> id – context ID. * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. */</font> IToken getContext(String id, DoneGetContext done); @@ -497,7 +497,7 @@ E • Registers • registerChanged • <i><string: context ID></ * 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. - * + * * <font color=#7F9FBF>@param</font> parent_context_id – parent context ID. Can be null – * to retrieve top level of the hierarchy, or one of context IDs retrieved * by previous getChildren commands. @@ -516,9 +516,9 @@ E • Registers • registerChanged • <i><string: context ID></ */</font> <font color=#7F0055>void</font> doneGetChildren(IToken token, Exception error, String[] context_ids); } - + <font color=#3F5FBF>/** - * RegistersContext objects represent register groups, registers and bit fields. + * RegistersContext objects represent register groups, registers and bit fields. */</font> <font color=#7F0055>interface</font> RegistersContext { <font color=#3F5FBF>/** @@ -526,25 +526,25 @@ E • Registers • registerChanged • <i><string: context ID></ * <font color=#7F9FBF>@return</font> context ID. */</font> String getID(); - + <font color=#3F5FBF>/** * Get parent context ID. * <font color=#7F9FBF>@return</font> parent context ID. */</font> String getParentID(); - + <font color=#3F5FBF>/** * Get context (register, register group, bit field) name. * <font color=#7F9FBF>@return</font> context name. */</font> String getName(); - + <font color=#3F5FBF>/** * Get context description. * <font color=#7F9FBF>@return</font> context description. */</font> String getDescription(); - + <font color=#3F5FBF>/** * Get context size in bytes. * Byte arrays in get()/set() methods should be same size. @@ -554,57 +554,57 @@ E • Registers • registerChanged • <i><string: context ID></ * @return context size in bytes. */</font> <font color=#7F0055>int</font> getSize(); - + <font color=#3F5FBF>/** * Check if context value can be read. * <font color=#7F9FBF>@return</font> true if can read value of the context. */</font> <font color=#7F0055>boolean</font> isReadable(); - + <font color=#3F5FBF>/** * Check if reading the context (register) destroys its current value - * it can be read only once. * <font color=#7F9FBF>@return</font> true if read-once register. */</font> <font color=#7F0055>boolean</font> isReadOnce(); - + <font color=#3F5FBF>/** * Check if context value can be written. * <font color=#7F9FBF>@return</font> true if can write value of the context. */</font> <font color=#7F0055>boolean</font> isWriteable(); - + <font color=#3F5FBF>/** * Check if register value can not be overwritten - every write counts. * <font color=#7F9FBF>@return</font> true if write-once register. */</font> <font color=#7F0055>boolean</font> isWriteOnce(); - + <font color=#3F5FBF>/** - * Check if writing the context can change values of other registers. + * Check if writing the context can change values of other registers. * <font color=#7F9FBF>@return</font> true if has side effects. */</font> <font color=#7F0055>boolean</font> hasSideEffects(); - + <font color=#3F5FBF>/** * Check if the register value can change even when target is stopped. * <font color=#7F9FBF>@return</font> true if the register value can change at any time. */</font> <font color=#7F0055>boolean</font> isVolatile(); - + <font color=#3F5FBF>/** * Check if the register value is a floating-point value. * <font color=#7F9FBF>@return</font> true if a floating-point register. */</font> <font color=#7F0055>boolean</font> isFloat(); - + <font color=#3F5FBF>/** * Check endianess of the context. - * Big endian means decreasing numeric significance with increasing bit number. + * Big endian means decreasing numeric significance with increasing bit number. * <font color=#7F9FBF>@return</font> true if big endian. */</font> <font color=#7F0055>boolean</font> isBigEndian(); - + <font color=#3F5FBF>/** * Check if the lowest numbered bit (i.e. bit #0 or bit #1 depending on * getFirstBitNumber() value) should be shown to user as the left-most bit or @@ -612,45 +612,45 @@ E • Registers • registerChanged • <i><string: context ID></ * <font color=#7F9FBF>@return</font> true if the first bit is left-most bit. */</font> <font color=#7F0055>boolean</font> isLeftToRight(); - + <font color=#3F5FBF>/** * If the context has bit field children, bit positions of the fields * can be zero-based or 1-based. * <font color=#7F9FBF>@return</font> first bit position - 0 or 1. */</font> <font color=#7F0055>int</font> getFirstBitNumber(); - + <font color=#3F5FBF>/** - * If context is a bit field, get the field bit numbers in parent context. + * If context is a bit field, get the field bit numbers in parent context. * <font color=#7F9FBF>@return</font> array of bit numbers. */</font> <font color=#7F0055>int</font>[] getBitNumbers(); - + <font color=#3F5FBF>/** * A context can have predefined names (mnemonics) for some its values. * This method returns a list of such named values. * <font color=#7F9FBF>@return</font> array of named values or null. */</font> NamedValue[] getNamedValues(); - + <font color=#3F5FBF>/** * Get the address of a memory mapped register. * <font color=#7F9FBF>@return</font> address. */</font> Number getMemoryAddress(); - + <font color=#3F5FBF>/** - * Get the context ID of a memory context in which a memory mapped register is located. + * Get the context ID of a memory context in which a memory mapped register is located. * <font color=#7F9FBF>@return</font> memory context ID. */</font> String getMemoryContext(); - + <font color=#3F5FBF>/** * Get a list of property names which can be searched for starting on this context * <font color=#7F9FBF>@return</font> collection of property names. */</font> Collection<String> canSearch(); - + <font color=#3F5FBF>/** * Get the role the register plays in a program execution. * <font color=#7F9FBF>@return</font> role name. @@ -662,14 +662,14 @@ E • Registers • registerChanged • <i><string: context ID></ * <font color=#7F9FBF>@return</font> map of all available context properties. */</font> Map<String,Object> getProperties(); - + <font color=#3F5FBF>/** * Read value of the context. * <font color=#7F9FBF>@param</font> done - call back object. * <font color=#7F9FBF>@return</font> - pending command handle. */</font> IToken get(DoneGet done); - + <font color=#3F5FBF>/** * Set value of the context. * <font color=#7F9FBF>@param</font> value - value to write into the context. @@ -690,7 +690,7 @@ E • Registers • registerChanged • <i><string: context ID></ <font color=#3F5FBF>/** * A register context can have predefined names (mnemonics) for some its values. - * NamedValue objects represent such values. + * NamedValue objects represent such values. */</font> <font color=#7F0055>interface</font> NamedValue { <font color=#3F5FBF>/** @@ -698,20 +698,20 @@ E • Registers • registerChanged • <i><string: context ID></ * <font color=#7F9FBF>@return</font> the value as an array of bytes. */</font> byte[] getValue(); - + <font color=#3F5FBF>/** * Get name (mnemonic) of the value. * <font color=#7F9FBF>@return</font> value name. */</font> String getName(); - + <font color=#3F5FBF>/** * Get human readable description of the value. * <font color=#7F9FBF>@return</font> value description. */</font> String getDescription(); } - + <font color=#3F5FBF>/** * Read values of multiple locations in registers. * <font color=#7F9FBF>@param</font> locs - array of data locations. @@ -719,7 +719,7 @@ E • Registers • registerChanged • <i><string: context ID></ * <font color=#7F9FBF>@return</font> - pending command handle. */</font> IToken getm(Location[] locs, DoneGet done); - + <font color=#3F5FBF>/** * Set values of multiple locations in registers. * <font color=#7F9FBF>@param</font> locs - array of data locations. @@ -734,7 +734,7 @@ E • Registers • registerChanged • <i><string: context ID></ */</font> <font color=#7F0055>final class</font> Location { <font color=#3F5FBF>/** Register context ID */</font> - <font color=#7F0055>public final</font> String id; + <font color=#7F0055>public final</font> String id; <font color=#3F5FBF>/** offset in the context, in bytes */</font> <font color=#7F0055>public final int</font> offs; @@ -761,7 +761,7 @@ E • Registers • registerChanged • <i><string: context ID></ */</font> <font color=#7F0055>void</font> doneGet(IToken token, Exception error, byte[] value); } - + <font color=#3F5FBF>/** * 'set' command call back interface. */</font> @@ -801,7 +801,7 @@ E • Registers • registerChanged • <i><string: context ID></ <font color=#3F5FBF>/** * Registers event listener is notified when registers context hierarchy - * changes, and when a register is modified by the service commands. + * changes, and when a register is modified by the service commands. */</font> <font color=#7F0055>interface</font> RegistersListener { @@ -810,12 +810,12 @@ E • Registers • registerChanged • <i><string: context ID></ * Most targets have static set of registers and register properties. * Such targets never generate this event. However, some targets, * for example, JTAG probes, allow user to modify register definitions. - * Clients should flush all cached register context data. + * Clients should flush all cached register context data. */</font> <font color=#7F0055>void</font> contextChanged(); <font color=#3F5FBF>/** - * Called when register content was changed and clients + * Called when register content was changed and clients * need to update themselves. Clients, at least, should invalidate * corresponding cached registers data. * Not every change is notified - it is not possible, diff --git a/docs/TCF Service - Run Control.html b/docs/TCF Service - Run Control.html index ecdc40100..785770f04 100644 --- a/docs/TCF Service - Run Control.html +++ b/docs/TCF Service - Run Control.html @@ -5,9 +5,9 @@ </head> <body lang='EN-US'> - + <h1>Target Communication Framework Services - Run Control</h1> - + <ul> <li><a href='#VersionHistory'>Version History</a> <li><a href='#Overview'>Overview</a> @@ -50,9 +50,9 @@ Command and event parameters are encoded as zero terminated <a href='TCF Specifi <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> - + <p>All run control commands are fully asynchronous, which means they never wait until context is in a particular state. For example, if single step command arrives when context is running, it does not wait until it stops, but returns an error. If a command @@ -66,13 +66,13 @@ to the command and intended destination was not reached. Client can know when an why a context is suspended by listening to events.</p> <h3><a name='CmdGetContext'>Get Context</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • RunControl • getContext • <i><string: context ID></i> • </font></b></pre> <p>The command retrieves context properties for given context ID. -Exact meaning of context depends on the target. +Exact meaning of context depends on the target. A context can represent an execution thread, a process, an 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 @@ -82,7 +82,7 @@ with same IDs, however, each service accesses its own subset of context's attributes and functionality, which is relevant to that service.</p> <p>Reply:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> R • <i><token></i> • <i><error report></i> • <i><context data></i> • @@ -134,7 +134,7 @@ contextChanged event to notify changes in context data.</p> </ul> <h3><a name='CmdGetChildren'>Get Children</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • RunControl • getChildren • <i><string: parent context ID></i> • </font></b></pre> @@ -145,23 +145,23 @@ C • <i><token></i> • RunControl • getChildren • <i>< of context IDs retrieved by previous getChildren commands, or it can be obtained from another service. 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.</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 context IDs></i> • <i><array of context IDs></i> ⇒ null ⇒ [ <i><context ID list></i> ] - + <i><context ID list></i> ⇒ <i><string: context ID></i> ⇒ <i><context ID list></i> , <i><string: context ID></i> </font></b></pre> <h3><a name='CmdSuspend'>Suspend</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • RunControl • suspend • <i><string: context ID></i> • </font></b></pre> @@ -169,9 +169,9 @@ C • <i><token></i> • RunControl • suspend • <i><str <p>The command suspends execution of given context. The command should fail if CanSuspend property of the context is false. If context's IsContainer = true, the command is propagated to context's children. Only contexts with HasState = true can be suspended.</p> - + <p>Result message:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> R • <i><token></i> • <i><error report></i> • </font></b></pre> @@ -272,24 +272,24 @@ to context's children. Only contexts with HasState = true can be resumed.</p> <code>RM_REVERSE_STEP_INTO_RANGE = 15</code> - reverse of <code>RM_STEP_INTO_RANGE</code>. </li> </ul> - + <p>Result message:</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='CmdGetState'>Get State</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • RunControl • getState • <i><string: context ID></i> • </font></b></pre> <p>The command retrieves current state of the context. The command should fail if HasState property of the context is false.</p> - + <p>Result message:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> R • <i><token></i> • <i><error report></i> • <i><boolean: suspended></i> • <i><int: PC></i> • <i><string: last state change reason></i> • <i><state data></i> • @@ -315,24 +315,24 @@ a generic client might be able to handle it better. Predefined reasons are:</p> <p>Context state properties can contain any data relevant to context state. Definition of state properties depends on a target.</p> - + <h3><a name='CmdTerminate'>Terminate</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • RunControl • terminate • <i><string: context ID></i> • </font></b></pre> <p>The command terminates execution of given context. The command should fail if CanTerminate property of the context is false.</p> - + <p>Result message:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> R • <i><token></i> • <i><error report></i> • </font></b></pre> <h2><a name='Events'>Events</a></h2> - + <pre><b><font face="Courier New" size=2 color=#333399> E • RunControl • contextAdded • <i><array of context data></i> • @@ -355,7 +355,7 @@ E • RunControl • containerResumed • <i><array of context IDs&g <i><array of context data></i> ⇒ null ⇒ [ <i><context data list></i> ] - + <i><context data list></i> ⇒ <i><object: context data></i> ⇒ <i><context data list></i> , <i><object: context data></i> @@ -411,7 +411,7 @@ E • RunControl • containerResumed • <i><array of context IDs&g PROP_CAN_TERMINATE = "CanTerminate"; <font color=#3F5FBF>/** - * Context resume modes. + * Context resume modes. */</font> <font color=#7F0055>static final int</font> RM_RESUME = 0, @@ -430,7 +430,7 @@ E • RunControl • containerResumed • <i><array of context IDs&g <font color=#3F5FBF>/** * 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. + * a generic client might be able to handle it better. */</font> <font color=#7F0055>static final</font> String REASON_USER_REQUEST = "Suspended", @@ -445,8 +445,8 @@ E • RunControl • containerResumed • <i><array of context IDs&g <font color=#3F5FBF>/** * Retrieve context info for given context ID. - * - * <font color=#7F9FBF>@param</font> id – context ID. + * + * <font color=#7F9FBF>@param</font> id – context ID. * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed. */</font> IToken getContext(String id, DoneGetContext done); @@ -465,14 +465,14 @@ E • RunControl • containerResumed • <i><array of context IDs&g <font color=#3F5FBF>/** * Retrieve children of given context. - * + * * <font color=#7F9FBF>@param</font> 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. + * by previous getContext or getChildren commands. * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed. */</font> IToken getChildren(String parent_context_id, DoneGetChildren done); - + <font color=#3F5FBF>/** * Client callback interface for getContexts(). */</font> @@ -484,7 +484,7 @@ E • RunControl • containerResumed • <i><array of context IDs&g */</font> <font color=#7F0055>void</font> doneGetChildren(IToken token, RunControlError error, Context[] contexts); } - + <font color=#3F5FBF>/** * A context corresponds to an execution thread, process, address space, etc. * A context can belong to a parent context. Contexts hierarchy can be simple @@ -492,17 +492,17 @@ E • RunControl • containerResumed • <i><array of context IDs&g * 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. + * attributes and functionality, which is relevant to that service. */</font> <font color=#7F0055>interface</font> RunControlContext { - - <font color=#3F5FBF>/** + + <font color=#3F5FBF>/** * Retrieve context ID. * Same as getProperties().get("ID") */</font> String getID(); - - <font color=#3F5FBF>/** + + <font color=#3F5FBF>/** * Retrieve parent context ID. * Same as getProperties().get("ParentID") */</font> @@ -514,21 +514,21 @@ E • RunControl • containerResumed • <i><array of context IDs&g * <font color=#7F9FBF>@return</font> Map of context properties. */</font> Map<String,Object> getProperties(); - + <font color=#3F5FBF>/** * 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. * <font color=#7F9FBF>@return</font> value of PROP_IS_CONTAINER. */</font> <font color=#7F0055>boolean</font> isContainer(); - + <font color=#3F5FBF>/** * Utility method to read context property PROP_HAS_STATE. - * Only context that has a state can be resumed or suspended. + * Only context that has a state can be resumed or suspended. * <font color=#7F9FBF>@return</font> value of PROP_HAS_STATE. */</font> <font color=#7F0055>boolean</font> hasState(); - + <font color=#3F5FBF>/** * Utility method to read context property PROP_CAN_SUSPEND. * Value 'true' means suspend command is supported by the context, @@ -538,29 +538,29 @@ E • RunControl • containerResumed • <i><array of context IDs&g * <font color=#7F9FBF>@return</font> value of PROP_CAN_SUSPEND. */</font> <font color=#7F0055>boolean</font> canSuspend(); - + <font color=#3F5FBF>/** * 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. - * <font color=#7F9FBF>@param</font> mode - resume mode, see RM_*. - * <font color=#7F9FBF>@return</font> value of requested bit of PROP_CAN_RESUME. + * <font color=#7F9FBF>@param</font> mode - resume mode, see RM_*. + * <font color=#7F9FBF>@return</font> value of requested bit of PROP_CAN_RESUME. */</font> <font color=#7F0055>boolean</font> canResume(<font color=#7F0055>int</font> mode); - + <font color=#3F5FBF>/** * 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. - * <font color=#7F9FBF>@param</font> mode - resume mode, see RM_*. - * <font color=#7F9FBF>@return</font> value of requested bit of PROP_CAN_COUNT. + * <font color=#7F9FBF>@param</font> mode - resume mode, see RM_*. + * <font color=#7F9FBF>@return</font> value of requested bit of PROP_CAN_COUNT. */</font> <font color=#7F0055>boolean</font> canCount(<font color=#7F0055>int</font> mode); - + <font color=#3F5FBF>/** * Utility method to read context property PROP_CAN_TERMINATE. * Value 'true' means terminate command is supported by the context, @@ -585,7 +585,7 @@ E • RunControl • containerResumed • <i><array of context IDs&g * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. */</font> IToken suspend(DoneCommand done); - + <font color=#3F5FBF>/** * Send a command to resume a context. * Also resumes children if context is a container. @@ -595,7 +595,7 @@ E • RunControl • containerResumed • <i><array of context IDs&g * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command. */</font> IToken resume(<font color=#7F0055>int</font> mode, <font color=#7F0055>int</font> count, DoneCommand done); - + <font color=#3F5FBF>/** * Send a command to terminate a context. * <font color=#7F9FBF>@param</font> done - command result call back object. @@ -603,10 +603,10 @@ E • RunControl • containerResumed • <i><array of context IDs&g */</font> IToken terminate(DoneCommand done); } - + <font color=#7F0055>class</font> RunControlError <font color=#7F0055>extends</font> Exception { } - + <font color=#7F0055>interface</font> DoneGetState { <font color=#7F0055>void</font> doneGetState(IToken token, Exception error, <font color=#7F0055>boolean</font> suspended, String pc, String reason, Map<String,Object> params); @@ -626,7 +626,7 @@ E • RunControl • containerResumed • <i><array of context IDs&g * <font color=#7F9FBF>@param</font> listener - run control event listener to add. */</font> <font color=#7F0055>void</font> addListener(RunControlListener listener); - + <font color=#3F5FBF>/** * Remove run control event listener. * <font color=#7F9FBF>@param</font> listener - run control event listener to remove. @@ -675,14 +675,14 @@ E • RunControl • containerResumed • <i><array of context IDs&g <font color=#3F5FBF>/** * Called when target simultaneously suspends multiple threads in a container * (process, core, etc.). - * + * * <font color=#7F9FBF>@param</font> 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. * <font color=#7F9FBF>@param</font> pc - program counter of the context. * <font color=#7F9FBF>@param</font> reason - human readable description of suspend reason. * <font color=#7F9FBF>@param</font> params - additional target specific data about suspended context. - * <font color=#7F9FBF>@param</font> suspended_ids - full list of all contexts that were suspended. + * <font color=#7F9FBF>@param</font> suspended_ids - full list of all contexts that were suspended. */</font> <font color=#7F0055>void</font> containerSuspended(String context, String pc, String reason, Map<String,Object> params, String[] suspended_ids); @@ -690,8 +690,8 @@ E • RunControl • containerResumed • <i><array of context IDs&g <font color=#3F5FBF>/** * Called when target simultaneously resumes multiple threads in a container (process, * core, etc.). - * - * <font color=#7F9FBF>@param</font> context_ids - full list of all contexts that were resumed. + * + * <font color=#7F9FBF>@param</font> context_ids - full list of all contexts that were resumed. */</font> <font color=#7F0055>void</font> containerResumed(String[] context_ids); diff --git a/docs/TCF Service - Stack Trace.html b/docs/TCF Service - Stack Trace.html index 33bf4933b..c0ee6d360 100644 --- a/docs/TCF Service - Stack Trace.html +++ b/docs/TCF Service - Stack Trace.html @@ -5,9 +5,9 @@ </head> <body lang='EN-US'> - + <h1>Target Communication Framework Services - Stack Trace</h1> - + <ul> <li><a href='#VersionHistory'>Version History</a> <li><a href='#Overview'>Overview</a> @@ -42,11 +42,11 @@ and event parameters are encoded as zero terminated <a href='TCF Specification.h <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='CmdGetContext'>Get Context</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • StackTrace • getContext • <i><array of context IDs></i> • @@ -54,7 +54,7 @@ C • <i><token></i> • StackTrace • getContext • <i>< ⇒ null ⇒ [ ] ⇒ [ <i><context ID list></i> ] - + <i><context ID list></i> ⇒ <i><string: context ID></i> ⇒ <i><context ID list></i> , <i><string: context ID></i> @@ -65,17 +65,17 @@ Command allows to query multiple contexts at once. Stack Trace context represents single stack frame. If target supports more then one stack per thread, each stack is also represented by a separate context.</p> - + <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> -R • <i><token></i> • <i><array of context data></i> • <i><error report></i> • +R • <i><token></i> • <i><array of context data></i> • <i><error report></i> • <i><array of context data></i> ⇒ null ⇒ [ ] ⇒ [ <i><context data list></i> ] - + <i><context data list></i> ⇒ <i><context data></i> ⇒ <i><context data list></i> , <i><context data></i> @@ -121,7 +121,7 @@ Cached context data should by flushed when parent thread is resumed.</p> </ul> <h3><a name='CmdGetChildren'>Get Children</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • StackTrace • getChildren • <i><string: parent context ID></i> • </font></b></pre> @@ -131,12 +131,12 @@ Parent context usually corresponds to an execution thread. Some targets have more then one stack. In such case children of a thread are stacks, and stack frames are deeper in the hierarchy - they can be retrieved with additional getChildren commands.</p> - + <p>The command will fail if parent thread is not suspended. Client can use Run Control service to suspend a thread.</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 context IDs></i> •<i></i> @@ -144,7 +144,7 @@ R • <i><token></i> • <i><error report></i> • <i><a ⇒ null ⇒ [ ] ⇒ [ <i><context ID list></i> ] - + <i><context ID list></i> ⇒ <i><string: context ID></i> ⇒ <i><context ID list></i> , <i><string: context ID></i> @@ -153,11 +153,11 @@ R • <i><token></i> • <i><error report></i> • <i><a <h2><a name='Events'>Events</a></h2> - + <p>No events are currently defined for Stack Trace service.</p> - + <h2><a name='API'>API</a></h2> - + <pre> <font color=#7F0055>public interface</font> IStackTrace <font color=#7F0055>extends</font> IService { @@ -179,11 +179,11 @@ R • <i><token></i> • <i><error report></i> • <i><a <font color=#3F5FBF>/** * Retrieve context info for given context IDs. - * + * * The command will fail if parent thread is not suspended. * Client can use Run Control service to suspend a thread. - * - * <font color=#7F9FBF>@param</font> id – array of context IDs. + * + * <font color=#7F9FBF>@param</font> id – array of context IDs. * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. */</font> IToken getContext(String[] id, DoneGetContext done); @@ -206,10 +206,10 @@ R • <i><token></i> • <i><error report></i> • <i><a * Some targets have more then one stack. In such case children of a thread * are stacks, and stack frames are deeper in the hierarchy - they can be * retrieved with additional getChildren commands. - * + * * The command will fail if parent thread is not suspended. * Client can use Run Control service to suspend a thread. - * + * * <font color=#7F9FBF>@param</font> parent_context_id – parent context ID. * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. */</font> @@ -227,55 +227,55 @@ R • <i><token></i> • <i><error report></i> • <i><a */</font> <font color=#7F0055>void</font> doneGetChildren(IToken token, Exception error, String[] context_ids); } - + <font color=#3F5FBF>/** - * StackTraceContext represents stack trace objects - stacks and stack frames. + * StackTraceContext represents stack trace objects - stacks and stack frames. */</font> <font color=#7F0055>interface</font> StackTraceContext { - + <font color=#3F5FBF>/** * Get Context ID. * <font color=#7F9FBF>@return</font> context ID. */</font> String getID(); - + <font color=#3F5FBF>/** * Get parent context ID. * <font color=#7F9FBF>@return</font> parent context ID. */</font> String getParentID(); - + <font color=#3F5FBF>/** * Get context name - if context represents a stack. * <font color=#7F9FBF>@return</font> context name or null. */</font> String getName(); - + <font color=#3F5FBF>/** * Get memory address of this frame. * <font color=#7F9FBF>@return</font> address or null if not a stack frame. */</font> Number getFrameAddress(); - + <font color=#3F5FBF>/** * Get program counter saved in this stack frame - * it is address of instruction to be executed when the function returns. * <font color=#7F9FBF>@return</font> program counter or null if not a stack frame. */</font> Number getProgramCounter(); - + <font color=#3F5FBF>/** * Get number of function arguments for this frame. * <font color=#7F9FBF>@return</font> function arguments count. */</font> <font color=#7F0055>int</font> getArgumentsCount(); - + <font color=#3F5FBF>/** * Get address of function arguments area in memory. * <font color=#7F9FBF>@return</font> function arguments address or null if not available. */</font> Number getArgumentsAddress(); - + <font color=#3F5FBF>/** * Get stack frame level. * <font color=#7F9FBF>@return</font> frame level or 0 if not a stack frame. diff --git a/docs/TCF Service - Streams.html b/docs/TCF Service - Streams.html index 3d166f869..5a3378a13 100644 --- a/docs/TCF Service - Streams.html +++ b/docs/TCF Service - Streams.html @@ -5,9 +5,9 @@ </head> <body lang='EN-US'> - + <h1>Target Communication Framework Services - Streams</h1> - + <ul> <li><a href='#VersionHistory'>Version History</a> <li><a href='#Overview'>Overview</a> @@ -58,18 +58,18 @@ can continue data processing concurrently with data transmission. <li> Multicast: multiple clients can receive data from same stream. <li> Subscription model: clients are required to expressed interest in particular streams by subscribing for the service. - <li> Flow control: peers can throttle data flow of individual streams by delaying 'read' and 'write' commands. + <li> Flow control: peers can throttle data flow of individual streams by delaying 'read' and 'write' commands. </ul> <p> Command and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</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='CmdSubscribe'>Subscribe</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Streams • subscribe • <i><string: stream source type></i> • </font></b></pre> @@ -80,7 +80,7 @@ For example, <a href='TCF Service - Processes.html'>Processes Service</a> define "Processes" strem source that represents standard input/output streams. Subscribers receive notifications when a stream of given type is created or disposed. Subscribers are required to respond with 'read' or 'disconnect' commands as necessary.</p> - + <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> @@ -95,13 +95,13 @@ If not disconnected, subscriber is required to send 'read' commands as necessary </p> <h3><a name='CmdUnsubscribe'>Unsubscribe</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Streams • unsubscribe • <i><string: stream source type></i> • </font></b></pre> <p>Unsubscribe the client from given stream source type.</p> - + <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> @@ -109,7 +109,7 @@ R • <i><token></i> • <i><error report></i> • </font></b></pre> <h3><a name='CmdRead'>Read</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Streams • read • <i><string: stream ID></i> • <i><int: size></i> • </font></b></pre> @@ -127,7 +127,7 @@ Pending 'read' commands will be executed in same order as issued. Client can delay sending of 'read' command if it is not ready to receive more data, however, delaying for too long can cause stream buffer overflow and lost of data. .</p> - + <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> @@ -138,12 +138,12 @@ R • <i><token></i> • <i><string: data></i> • <i><e <li><dt><code><b>data</b></code> <dd>BASE64 encoded bytes that were read from the stream. <li><dt><code><b>lost size</b></code> <dd>Number of bytes that were lost because of buffer overflow. -1 means unknown number of bytes were lost. if both 'lost_size' and 'data.length' are non-zero then lost bytes are considered - located right before read bytes. + located right before read bytes. <li><dt><code><b>EOS</b></code> <dd>true if end of stream was reached. </ul> <h3><a name='CmdWrite'>Write</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Streams • write • <i><string: stream ID></i> • <i><int: size></i> • <i><string: data></i> • </font></b></pre> @@ -159,7 +159,7 @@ Remote peer will continue to process other commands while 'write' command is pen Client can send more 'write' commands without waiting for the first command to complete. Doing that improves communication channel bandwidth utilization. Pending 'write' commands will be executed in same order as issued.</p> - + <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> @@ -167,13 +167,13 @@ R • <i><token></i> • <i><error report></i> • </font></b></pre> <h3><a name='CmdEOS'>End of Stream</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Streams • eos • <i><string: stream ID></i> • </font></b></pre> <p>The command sends End Of Stream marker to a stream. No more writing to the stream is allowed after that.</p> - + <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> @@ -181,7 +181,7 @@ R • <i><token></i> • <i><error report></i> • </font></b></pre> <h3><a name='CmdConnect'>Connect</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Streams • connect • <i><string: stream ID></i> • </font></b></pre> @@ -189,7 +189,7 @@ C • <i><token></i> • Streams • connect • <i><string <p>The command connects client to a stream. Some data might be dropped from the stream by the time "connect" command is executed. Client should be able to re-sync with stream data if it wants to read from such stream. If a client wants to read a stream from the beginning it should use "subscribe" command instead of "connect"</p> - + <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> @@ -197,14 +197,14 @@ R • <i><token></i> • <i><error report></i> • </font></b></pre> <h3><a name='CmdDisconnect'>Disconnect</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Streams • disconnect • <i><string: stream ID></i> • </font></b></pre> <p>The command disconnects client from a stream. Note that disconnect does not destroy the stream, client on other channels can continue reading or writing the stream.</p> - + <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> @@ -212,10 +212,10 @@ R • <i><token></i> • <i><error report></i> • </font></b></pre> <h2><a name='Events'>Events</a></h2> - + <p>Streams service sends events when a stream is created or disposed. Only clients with active subscribtion will recceive the events. Clients can change their subscription with <b>subscribe</b> and <b>unsubscribe</b> commands.</p> - + <pre><b><font face="Courier New" size=2 color=#333399> E • Streams • created • <i><string: stream type></i> • <i><string: stream ID></i> • <i><string: context ID></i> • </font></b></pre> @@ -234,16 +234,16 @@ Stream types and context IDs are defined by services that use Streams service to E • Streams • disposed • <i><string: stream type></i> • <i><string: stream ID></i> • </font></b></pre> <p> -Sent when a stream is disposed. +Sent when a stream is disposed. "stream type" - source type of the stream. "stream ID" - ID of the stream. </p> <h2><a name='API'>API</a></h2> - + <pre> <font color=#7F0055>public interface</font> IStreams extends IService { - + <font color=#3F5FBF>/** * Service name. */</font> @@ -251,14 +251,14 @@ Sent when a stream is disposed. <font color=#3F5FBF>/** * Clients can implement StreamsListener interface to be notified - * when a stream is created or disposed. The interface is registered with 'subscribe' command. - * + * when a stream is created or disposed. The interface is registered with 'subscribe' command. + * * When new stream is created, client must decide if it is interested in that particular stream instance. * If not interested, client should send 'disconnect' command to allow remote peer to free resources and bandwidth. * If not disconnected, client is required to send 'read' commands as necessary to prevent stream buffer overflow. */</font> <font color=#7F0055>interface</font> StreamsListener { - + <font color=#3F5FBF>/** * Called when a new stream is created. * <font color=#7F9FBF>@param</font> stream_type - source type of the stream. @@ -268,15 +268,15 @@ Sent when a stream is disposed. * Stream types and context IDs are defined by services that use Streams service to transmit data. */</font> <font color=#7F0055>void</font> created(String stream_type, String stream_id, String context_id); - + <font color=#3F5FBF>/** - * Called when a stream is disposed. + * Called when a stream is disposed. * <font color=#7F9FBF>@param</font> stream_type - source type of the stream. * <font color=#7F9FBF>@param</font> stream_id - ID of the stream. */</font> <font color=#7F0055>void</font> disposed(String stream_type, String stream_id); } - + <font color=#3F5FBF>/** * Clients must subscribe for one or more stream types to be able to send or receive stream data. * Subscribers receive notifications when a stream of given type is created or disposed. @@ -287,7 +287,7 @@ Sent when a stream is disposed. * <font color=#7F9FBF>@return</font> - pending command handle. */</font> IToken subscribe(String stream_type, StreamsListener listener, DoneSubscribe done); - + <font color=#3F5FBF>/** * Call back interface for 'subscribe' command. */</font> @@ -303,7 +303,7 @@ Sent when a stream is disposed. * <font color=#7F9FBF>@return</font> - pending command handle. */</font> IToken unsubscribe(String stream_type, StreamsListener listener, DoneUnsubscribe done); - + <font color=#3F5FBF>/** * Call back interface for 'unsubscribe' command. */</font> @@ -325,7 +325,7 @@ Sent when a stream is disposed. * <font color=#7F9FBF>@return</font> - pending command handle. */</font> IToken read(String stream_id, <font color=#7F0055>int</font> size, DoneRead done); - + <font color=#3F5FBF>/** * Call back interface for 'read' command. */</font> @@ -337,7 +337,7 @@ Sent when a stream is disposed. * <font color=#7F9FBF>@param</font> lost_size - number of bytes that were lost because of buffer overflow. * 'lost_size' -1 means unknown number of bytes were lost. * if both 'lost_size' and 'data.length' are non-zero then lost bytes are considered - * located right before read bytes. + * located right before read bytes. * <font color=#7F9FBF>@param</font> data - bytes read from the stream. * <font color=#7F9FBF>@param</font> eos - true if end of stream was reached. */</font> @@ -358,7 +358,7 @@ Sent when a stream is disposed. * <font color=#7F9FBF>@return</font> - pending command handle. */</font> IToken write(String stream_id, <font color=#7F0055>byte</font>[] buf, <font color=#7F0055>int</font> offset, <font color=#7F0055>int</font> size, DoneWrite done); - + <font color=#3F5FBF>/** * Call back interface for 'write' command. */</font> @@ -370,15 +370,15 @@ Sent when a stream is disposed. */</font> <font color=#7F0055>void</font> doneWrite(IToken token, Exception error); } - + <font color=#3F5FBF>/** - * Send End Of Stream marker to a stream. No more writing to the stream is allowed after that. + * Send End Of Stream marker to a stream. No more writing to the stream is allowed after that. * <font color=#7F9FBF>@param</font> stream_id - ID of the stream. * <font color=#7F9FBF>@param</font> done - command result call back object. * <font color=#7F9FBF>@return</font> - pending command handle. */</font> IToken eos(String stream_id, DoneEOS done); - + <font color=#3F5FBF>/** * Call back interface for 'eos' command. */</font> @@ -398,7 +398,7 @@ Sent when a stream is disposed. * <font color=#7F9FBF>@return</font> - pending command handle. */</font> IToken disconnect(String stream_id, DoneDisconnect done); - + <font color=#3F5FBF>/** * Call back interface for 'disconnect' command. */</font> diff --git a/docs/TCF Service - System Monitor.html b/docs/TCF Service - System Monitor.html index fe1175703..2763e684f 100644 --- a/docs/TCF Service - System Monitor.html +++ b/docs/TCF Service - System Monitor.html @@ -5,9 +5,9 @@ </head> <body lang='EN-US'> - + <h1>Target Communication Framework Services - System Monitor</h1> - + <ul> <li><a href='#VersionHistory'>Version History</a> <li><a href='#Overview'>Overview</a> @@ -49,11 +49,11 @@ as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</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='CmdGetContext'>Get Context</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • SysMonitor • getContext • <i><string: context ID></i> • </font></b></pre> @@ -62,7 +62,7 @@ C • <i><token></i> • SysMonitor • getContext • <i>< A context corresponds to an execution thread or process. Context IDs are valid across TCF services, so it is allowed to issue 'SysMonitor.getContext' command with a context that was obtained from another service.</p> - + <p>Reply:</p> <pre><b><font face="Courier New" size=2 color=#333399> @@ -84,176 +84,176 @@ R • <i><token></i> • <i><error report></i> • <i><c <li><code><b><font face="Courier New" size=2 color=#333399>"ParentID" : <i><string></i></font></b></code> - parent context ID. - + <li><code><b><font face="Courier New" size=2 color=#333399>"CWD" : <i><string></i></font></b></code> - current working directory of the process. - + <li><code><b><font face="Courier New" size=2 color=#333399>"Root" : <i><string></i></font></b></code> - the process's root directory (as set by chroot). - + <li><code><b><font face="Courier New" size=2 color=#333399>"UID" : <i><int></i></font></b></code> - User ID of the process owner. - + <li><code><b><font face="Courier New" size=2 color=#333399>"UGID" : <i><int></i></font></b></code> - Group ID of the process owner. - + <li><code><b><font face="Courier New" size=2 color=#333399>"UserName" : <i><string></i></font></b></code> - user name of the process owner. - + <li><code><b><font face="Courier New" size=2 color=#333399>"GroupName" : <i><string></i></font></b></code> - group name of the process owner. - + <li><code><b><font face="Courier New" size=2 color=#333399>"PID" : <i><int></i></font></b></code> - system process ID. - + <li><code><b><font face="Courier New" size=2 color=#333399>"File" : <i><string></i></font></b></code> - executable file of the process. - + <li><code><b><font face="Courier New" size=2 color=#333399>"State" : <i><string></i></font></b></code> - one character from the string "RSDZTW" where R is running, S is sleeping in an interruptible wait, D is waiting in uninterruptible disk sleep, Z is zombie, T is traced or stopped (on a signal), and W is paging. - + <li><code><b><font face="Courier New" size=2 color=#333399>"PPID" : <i><int></i></font></b></code> - system ID of the parent process. - + <li><code><b><font face="Courier New" size=2 color=#333399>"PGRP" : <i><int></i></font></b></code> - the process group ID of the process. - + <li><code><b><font face="Courier New" size=2 color=#333399>"Session" : <i><int></i></font></b></code> - the session ID of the process. - + <li><code><b><font face="Courier New" size=2 color=#333399>"TTY" : <i><int></i></font></b></code> - the tty the process uses. - + <li><code><b><font face="Courier New" size=2 color=#333399>"TGID" : <i><int></i></font></b></code> - the process group ID of the process which currently owns the tty that the process is connected to. - + <li><code><b><font face="Courier New" size=2 color=#333399>"TracerPID" : <i><int></i></font></b></code> - ID of a process that has attached this process for tracing or debugging. - + <li><code><b><font face="Courier New" size=2 color=#333399>"Flags" : <i><int></i></font></b></code> - the kernel flags word of the process. Details depend on the kernel. - + <li><code><b><font face="Courier New" size=2 color=#333399>"MinFlt" : <i><int></i></font></b></code> - the number of minor faults the process has made which have not required loading a memory page from disk. - + <li><code><b><font face="Courier New" size=2 color=#333399>"CMinFlt" : <i><int></i></font></b></code> - the number of minor faults that the process's waited-for children have made. - + <li><code><b><font face="Courier New" size=2 color=#333399>"MajFlt" : <i><int></i></font></b></code> - the number of major faults the process has made which have required loading a memory page from disk. - + <li><code><b><font face="Courier New" size=2 color=#333399>"CMajFlt" : <i><int></i></font></b></code> - the number of major faults that the process's waited-for children have made. - + <li><code><b><font face="Courier New" size=2 color=#333399>"UTime" : <i><int></i></font></b></code> - the number of milliseconds that this process has been scheduled in user mode. - + <li><code><b><font face="Courier New" size=2 color=#333399>"STime" : <i><int></i></font></b></code> - the number of milliseconds that this process has been scheduled in kernel mode. - + <li><code><b><font face="Courier New" size=2 color=#333399>"CUTime" : <i><int></i></font></b></code> - the number of jiffies that this process's waited-for children have been scheduled in user mode. - + <li><code><b><font face="Courier New" size=2 color=#333399>"CSTime" : <i><int></i></font></b></code> - the number of jiffies that this process's waited-for children have been scheduled in user mode. - + <li><code><b><font face="Courier New" size=2 color=#333399>"Priority" : <i><int></i></font></b></code> - the standard nice value. - + <li><code><b><font face="Courier New" size=2 color=#333399>"Nice" : <i><int></i></font></b></code> - the nice value. - + <li><code><b><font face="Courier New" size=2 color=#333399>"ITRealValue" : <i><int></i></font></b></code> - the time in milliseconds before the next SIGALRM is sent to the process due to an interval timer. - + <li><code><b><font face="Courier New" size=2 color=#333399>"StartTime" : <i><int></i></font></b></code> - the time in milliseconds the process started after system boot. - + <li><code><b><font face="Courier New" size=2 color=#333399>"VSize" : <i><int></i></font></b></code> - virtual memory size in bytes. - + <li><code><b><font face="Courier New" size=2 color=#333399>"PSize" : <i><int></i></font></b></code> - memory pages size in bytes. - + <li><code><b><font face="Courier New" size=2 color=#333399>"RSS" : <i><int></i></font></b></code> - resident Set Size: number of pages the process has in real memory, minus used for administrative purposes. This is just the pages which count towards text, data, or stack space. This does not include pages which have not been demand-loaded in, or which are swapped out. - + <li><code><b><font face="Courier New" size=2 color=#333399>"RLimit" : <i><int></i></font></b></code> - current limit in bytes on the rss of the process. - + <li><code><b><font face="Courier New" size=2 color=#333399>"CodeStart" : <i><int></i></font></b></code> - the address above which program text can run. - + <li><code><b><font face="Courier New" size=2 color=#333399>"CodeEnd" : <i><int></i></font></b></code> - the address below which program text can run. - + <li><code><b><font face="Courier New" size=2 color=#333399>"StackStart" : <i><int></i></font></b></code> - the address of the start of the stack. - + <li><code><b><font face="Courier New" size=2 color=#333399>"Signals" : <i><int></i></font></b></code> - the bitmap of pending signals. - + <li><code><b><font face="Courier New" size=2 color=#333399>"SigBlock" : <i><int></i></font></b></code> - the bitmap of blocked signals. - + <li><code><b><font face="Courier New" size=2 color=#333399>"SigIgnore" : <i><int></i></font></b></code> - the bitmap of ignored signals. - + <li><code><b><font face="Courier New" size=2 color=#333399>"SigCatch" : <i><int></i></font></b></code> - the bitmap of caught signals. - + <li><code><b><font face="Courier New" size=2 color=#333399>"WChan" : <i><int></i></font></b></code> - this is the "channel" in which the process is waiting. It is the address of a system call, and can be looked up in a namelist if you need a textual name. - + <li><code><b><font face="Courier New" size=2 color=#333399>"NSwap" : <i><int></i></font></b></code> - number of pages swapped. - + <li><code><b><font face="Courier New" size=2 color=#333399>"CNSwap" : <i><int></i></font></b></code> - cumulative NSwap for child processes. - + <li><code><b><font face="Courier New" size=2 color=#333399>"ExitSignal" : <i><int></i></font></b></code> - signal to be sent to parent when this process exits. - + <li><code><b><font face="Courier New" size=2 color=#333399>"Processor" : <i><int></i></font></b></code> - CPU number last executed on. - + <li><code><b><font face="Courier New" size=2 color=#333399>"RTPriority" : <i><int></i></font></b></code> - real-time scheduling priority. - + <li><code><b><font face="Courier New" size=2 color=#333399>"Policy" : <i><int></i></font></b></code> - scheduling policy. </ul> <h3><a name='CmdGetChildren'>Get Children</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • SysMonitor • getChildren • <i><string: parent context ID></i> • </font></b></pre> <p>The command requests a list of contexts available for System Monitor commands.</p> - + <p>Parent context ID can be null – to retrieve top level of the hierarchy, can be one of context IDs retrieved by previous getChildren commands, or it can be obtained from another service. 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.</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 context IDs></i> • @@ -261,22 +261,22 @@ R • <i><token></i> • <i><error report></i> • <i><a ⇒ null ⇒ [ ] ⇒ [ <i><context ID list></i> ] - + <i><context ID list></i> ⇒ <i><string: context ID></i> ⇒ <i><context ID list></i> , <i><string: context ID></i> </font></b></pre> <h3><a name='CmdGetCommandLine'>Get Command Line</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • SysMonitor • getCommandLine • <i><string: context ID></i> • </font></b></pre> <p>The command requests a list of progess command line arguments.</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 string></i> • @@ -284,22 +284,22 @@ R • <i><token></i> • <i><error report></i> • <i><a ⇒ null ⇒ [ ] ⇒ [ <i><string list></i> ] - + <i><string list></i> ⇒ <i><string></i> ⇒ <i><string list></i> , <i><string></i> </font></b></pre> <h3><a name='CmdGetEnvironment'>Get Environment</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • SysMonitor • getEnvironment • <i><string: context ID></i> • </font></b></pre> <p>The command requests a list of progess environment variables.</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 string></i> • </font></b></pre> @@ -309,7 +309,7 @@ R • <i><token></i> • <i><error report></i> • <i><a <p>No events are currently defined for System Monitor service.</p> <h2><a name='API'>API</a></h2> - + <pre> <font color=#7F0055>public interface</font> ISysMonitor <font color=#7F0055>extends</font> IService { @@ -317,8 +317,8 @@ R • <i><token></i> • <i><error report></i> • <i><a <font color=#3F5FBF>/** * Retrieve context info for given context ID. - * - * <font color=#7F9FBF>@param</font> id – context ID. + * + * <font color=#7F9FBF>@param</font> id – context ID. * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed. */</font> IToken getContext(String id, DoneGetContext done); @@ -337,10 +337,10 @@ R • <i><token></i> • <i><error report></i> • <i><a <font color=#3F5FBF>/** * Retrieve children of given context. - * + * * <font color=#7F9FBF>@param</font> 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. + * by previous getContext or getChildren commands. * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed. */</font> IToken getChildren(String parent_context_id, DoneGetChildren done); @@ -356,171 +356,171 @@ R • <i><token></i> • <i><error report></i> • <i><a */</font> <font color=#7F0055>void</font> doneGetChildren(IToken token, Exception error, String[] context_ids); } - + <font color=#3F5FBF>/** * Context property names. */</font> <font color=#7F0055>static final</font> String <font color=#3F5FBF>/** The TCF context ID */</font> PROP_ID = "ID", - + <font color=#3F5FBF>/** The TCF parent context ID */</font> PROP_PARENTID = "ParentID", - + <font color=#3F5FBF>/** Current working directory of the process */</font> PROP_CWD = "CWD", - + <font color=#3F5FBF>/** The process's root directory (as set by chroot) */</font> PROP_ROOT = "Root", - + <font color=#3F5FBF>/** User ID of the process owner */</font> PROP_UID = "UID", - + <font color=#3F5FBF>/** Group ID of the process owner */</font> PROP_UGID = "UGID", - + <font color=#3F5FBF>/** User name of the process owner */</font> PROP_USERNAME = "UserName", - + <font color=#3F5FBF>/** Group name of the process owner */</font> PROP_GROUPNAME = "GroupName", - + <font color=#3F5FBF>/** System process ID */</font> PROP_PID = "PID", - + <font color=#3F5FBF>/** Executable file of the process */</font> PROP_FILE = "File", - + <font color=#3F5FBF>/** One character from the string "RSDZTW" where R is running, S is * sleeping in an interruptible wait, D is waiting in uninterruptible * disk sleep, Z is zombie, T is traced or stopped (on a signal), and W * is paging.*/</font> PROP_STATE = "State", - + <font color=#3F5FBF>/** System ID of the parent process */</font> PROP_PPID = "PPID", - + <font color=#3F5FBF>/** The process group ID of the process */</font> PROP_PGRP = "PGRP", - + <font color=#3F5FBF>/** The session ID of the process */</font> PROP_SESSION = "Session", - + <font color=#3F5FBF>/** The tty the process uses */</font> PROP_TTY = "TTY", - + <font color=#3F5FBF>/** The process group ID of the process which currently owns the tty that * the process is connected to. */</font> PROP_TGID = "TGID", - + <font color=#3F5FBF>/** ID of a process that has attached this process for tracing or debugging */</font> PROP_TRACERPID = "TracerPID", - + <font color=#3F5FBF>/** The kernel flags word of the process. Details depend on the kernel */</font> PROP_FLAGS = "Flags", - + <font color=#3F5FBF>/** The number of minor faults the process has made which have not * required loading a memory page from disk */</font> PROP_MINFLT = "MinFlt", - + <font color=#3F5FBF>/** The number of minor faults that the process's waited-for children have made */</font> - PROP_CMINFLT = "CMinFlt", - + PROP_CMINFLT = "CMinFlt", + <font color=#3F5FBF>/** The number of major faults the process has made which have required * loading a memory page from disk */</font> PROP_MAJFLT = "MajFlt", - + <font color=#3F5FBF>/** The number of major faults that the process's waited-for children * have made */</font> PROP_CMAJFLT = "CMajFlt", - + <font color=#3F5FBF>/** The number of milliseconds that this process has been scheduled in user mode */</font> PROP_UTIME = "UTime", - + <font color=#3F5FBF>/** The number of milliseconds that this process has been scheduled in kernel mode */</font> PROP_STIME = "STime", - + <font color=#3F5FBF>/** The number of jiffies that this process's waited-for children have * been scheduled in user mode */</font> PROP_CUTIME = "CUTime", - + <font color=#3F5FBF>/** The number of jiffies that this process's waited-for children have * been scheduled in user mode */</font> PROP_CSTIME = "CSTime", - + <font color=#3F5FBF>/** The standard nice value */</font> PROP_PRIORITY = "Priority", - + <font color=#3F5FBF>/** The nice value */</font> PROP_NICE = "Nice", - + <font color=#3F5FBF>/** The time in milliseconds before the next SIGALRM is sent to the process * due to an interval timer */</font> PROP_ITREALVALUE = "ITRealValue", - + <font color=#3F5FBF>/** The time in milliseconds the process started after system boot */</font> PROP_STARTTIME = "StartTime", - + <font color=#3F5FBF>/** Virtual memory size in bytes */</font> PROP_VSIZE = "VSize", - + <font color=#3F5FBF>/** Memory pages size in bytes */</font> PROP_PSIZE = "PSize", - + <font color=#3F5FBF>/** Resident Set Size: number of pages the process has in real memory, * minus used for administrative purposes. This is just the pages which * count towards text, data, or stack space. This does not include * pages which have not been demand-loaded in, or which are swapped out */</font> PROP_RSS = "RSS", - + <font color=#3F5FBF>/** Current limit in bytes on the rss of the process */</font> PROP_RLIMIT = "RLimit", - + <font color=#3F5FBF>/** The address above which program text can run */</font> PROP_CODESTART = "CodeStart", - + <font color=#3F5FBF>/** The address below which program text can run */</font> PROP_CODEEND = "CodeEnd", - + <font color=#3F5FBF>/** The address of the start of the stack */</font> PROP_STACKSTART = "StackStart", - + <font color=#3F5FBF>/** The bitmap of pending signals */</font> PROP_SIGNALS = "Signals", - + <font color=#3F5FBF>/** The bitmap of blocked signals */</font> PROP_SIGBLOCK = "SigBlock", - + <font color=#3F5FBF>/** The bitmap of ignored signals */</font> PROP_SIGIGNORE = "SigIgnore", - + <font color=#3F5FBF>/** The bitmap of caught signals */</font> PROP_SIGCATCH = "SigCatch", - + <font color=#3F5FBF>/** This is the "channel" in which the process is waiting. It is the * address of a system call, and can be looked up in a name list if you * need a textual name */</font> PROP_WCHAN = "WChan", - + <font color=#3F5FBF>/** Number of pages swapped */</font> PROP_NSWAP = "NSwap", - + <font color=#3F5FBF>/** Cumulative NSwap for child processes */</font> PROP_CNSWAP = "CNSwap", - + <font color=#3F5FBF>/** Signal to be sent to parent when this process exits */</font> PROP_EXITSIGNAL = "ExitSignal", - + <font color=#3F5FBF>/** CPU number last executed on */</font> PROP_PROCESSOR = "Processor", - + <font color=#3F5FBF>/** Real-time scheduling priority */</font> PROP_RTPRIORITY = "RTPriority", - + <font color=#3F5FBF>/** Scheduling policy */</font> PROP_POLICY = "Policy"; - - + + <font color=#3F5FBF>/** * A context corresponds to an execution thread, process, address space, etc. * A context can belong to a parent context. Contexts hierarchy can be simple @@ -528,113 +528,113 @@ R • <i><token></i> • <i><error report></i> • <i><a * 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. + * attributes and functionality, which is relevant to that service. */</font> <font color=#7F0055>interface</font> SysMonitorContext { - - <font color=#3F5FBF>/** + + <font color=#3F5FBF>/** * Get context ID. * Same as getProperties().get(“ID”) */</font> String getID(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get parent context ID. * Same as getProperties().get(“ParentID”) */</font> String getParentID(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get process group ID. * Same as getProperties().get(“PGRP”) */</font> <font color=#7F0055>long</font> getPGRP(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get process ID. * Same as getProperties().get(“PID”) */</font> <font color=#7F0055>long</font> getPID(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get process parent ID. * Same as getProperties().get(“PPID”) */</font> <font color=#7F0055>long</font> getPPID(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get process TTY group ID. * Same as getProperties().get(“TGID”) */</font> <font color=#7F0055>long</font> getTGID(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get tracer process ID. * Same as getProperties().get(“TracerPID”) */</font> <font color=#7F0055>long</font> getTracerPID(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get process owner user ID. * Same as getProperties().get(“UID”) */</font> <font color=#7F0055>long</font> getUID(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get process owner user name. * Same as getProperties().get(“UserName”) */</font> String getUserName(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get process owner user group ID. * Same as getProperties().get(“UGID”) */</font> <font color=#7F0055>long</font> getUGID(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get process owner user group name. * Same as getProperties().get(“GroupName”) */</font> String getGroupName(); - - <font color=#3F5FBF>/** + + <font color=#3F5FBF>/** * Get process state. * Same as getProperties().get(“State”) */</font> String getState(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get process virtual memory size in bytes. * Same as getProperties().get(“VSize”) */</font> <font color=#7F0055>long</font> getVSize(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get process virtual memory page size in bytes. * Same as getProperties().get(“PSize”) */</font> <font color=#7F0055>long</font> getPSize(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get number of memory pages in process resident set. * Same as getProperties().get(“RSS”) */</font> <font color=#7F0055>long</font> getRSS(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get context executable file. * Same as getProperties().get(“File”) */</font> String getFile(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get context current file system root. * Same as getProperties().get(“Root”) */</font> String getRoot(); - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get context current working directory. * Same as getProperties().get(“CWD”) */</font> @@ -646,21 +646,21 @@ R • <i><token></i> • <i><error report></i> • <i><a */</font> Map<String,Object> getProperties(); } - - <font color=#3F5FBF>/** + + <font color=#3F5FBF>/** * Get context command line. */</font> IToken getCommandLine(String id, DoneGetCommandLine done); - + <font color=#7F0055>interface</font> DoneGetCommandLine { <font color=#7F0055>void</font> doneGetCommandLine(IToken token, Exception error, String[] cmd_line); } - <font color=#3F5FBF>/** + <font color=#3F5FBF>/** * Get context environment variables. */</font> IToken getEnvironment(String id, DoneGetEnvironment done); - + <font color=#7F0055>interface</font> DoneGetEnvironment { <font color=#7F0055>void</font> doneGetEnvironment(IToken token, Exception error, String[] environment); } diff --git a/docs/TCF Services.html b/docs/TCF Services.html index 61b1aadf6..4b84061ff 100644 --- a/docs/TCF Services.html +++ b/docs/TCF Services.html @@ -5,12 +5,12 @@ </head> <body lang='EN-US'> - + <h1>Target Communication Framework Services</h1> - + <p>Copyright (c) 2007 Wind River Systems, Inc. Made available under the EPL v1.0 <p>Direct comments, questions to the <a href="mailto:dsdp-tcf-dev@eclipse.org">dsdp-tcf-dev@eclipse.org</a> mailing list - + <h2>Table of Contents</h2> <ul> <li><a href='#VersionHistory'>Version History</a> @@ -48,13 +48,13 @@ For example, <a href='TCF Service - Memory.html'>Memory Service</a> defines grou reading and writing target memory. Service definitions are not part of the <a href='TCF Specification.html'>framework specification</a>, and new services are expected to be defined by developers of tools and target agents. -Defenitions of standard services are provided to achieve certain level of compatibility between tools and targets. - +Defenitions of standard services are provided to achieve certain level of compatibility between tools and targets. + <h2><a name='Syntax'>Syntax Rules Notation</a></h2> - + <p>Format of the protocol messages is defined by syntax rules. Syntax is described using a simple variant of Backus-Naur Form. In particular:</p> - + <ul type='disc'> <li>Italic lower case words in a courier font, enclosed into angular brackets, are used to denote syntactic categories, for example: <b><i><font face="Courier New" size=2 color=#333399><token>. @@ -62,12 +62,12 @@ using a simple variant of Backus-Naur Form. In particular:</p> of the category, for example: <b><i><font face="Courier New" size=2 color=#333399><int: error code></font></i></b> has same meaning as <b><i><font face="Courier New" size=2 color=#333399><int></font></i></b>, but denotes that the integer number used to indicate an "error code". - + <li>A syntax rule consists of a category designation followed by one or more syntax definitions for the category. The category name and each definition are placed on separate lines, bullets are used to denote definitions, for example: </ul> - + <pre><b><font face="Courier New" size=2 color=#333399> <i><chars></i> ⇒ <i><char></i> @@ -76,17 +76,17 @@ using a simple variant of Backus-Naur Form. In particular:</p> <ul type='disc'> <li>Spaces are added for readability only and they are not part of the syntax. - + <li>All text in the category definition, other than categories and spaces, is UTF-8 based representation of a message bytes. - - <li>The symbol ‘•’ designates a zero byte. + + <li>The symbol ‘•’ designates a zero byte. </ul> <h2><a name='ErrorFormat'>Error Report Format</a></h2> <p>Most of TCF standard services use same format for error reporting:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> <i><error report></i> ⇒ @@ -205,4 +205,4 @@ same way as "OTHER".</p> </body> </html> - + diff --git a/docs/TCF Specification.html b/docs/TCF Specification.html index e808f0b5e..5b443425c 100644 --- a/docs/TCF Specification.html +++ b/docs/TCF Specification.html @@ -4,14 +4,14 @@ <title>Target Communication Framework Specification</title> </head> <body lang='EN-US'> - + <h1>Target Communication Framework Specification</h1> - + <p>Copyright (c) 2007, 2008 Wind River Systems, Inc. Made available under the EPL v1.0 <p>Direct comments, questions to the <a href="mailto:dsdp-tcf-dev@eclipse.org">dsdp-tcf-dev@eclipse.org</a> mailing list <h1>Table of Contents</h1> - + <ul> <li><a href='#VersionHistory'>Version History</a> <li><a href='#Overview'>Overview</a> @@ -70,28 +70,28 @@ <td>2009-03-04 <td>Added N message </table> - + <h1><a name='Overview'>Overview</a></h1> - + <p>Today almost every device software development tool on the market has its own method of communication with target system. Communication methods often require individual setup, configuration and maintenance, impose unnecessary limitations. Target Communication Framework goal is to establish common ground in the area of communication protocols between development tools and embedded devices.</p> - + <p>The goal is a single protocol used to communicate between all tools and targets:</p> <p><img src='TCF Specification Image1.png'></p> - + <h2><a name='Goals'>Goals</a></h2> - + <ul type='disc'> <li>Universal, simple, lightweight, vendor agnostic framework for tools and targets to communicate for purpose of debugging, profiling, code patching and other device software development needs. - + <li>Single configuration per target (not per tool per target as today in most cases), or no configuration when possible. - + <li>Minimal overhead and footprint on target side. </ul> @@ -100,125 +100,125 @@ the area of communication protocols between development tools and embedded devic <dl> <dt><b>Peer:</b> <dd>communication endpoint. Both hosts and targets are called peers. A peer can act as a client or a server depending on services it implements. - + <dt><b>Service:</b> <dd>group of related commands, events and semantic define a service. A service can be discovered, added or removed as a group at communication endpoint. - + <dt><b>Message:</b> <dd>a packet of data, formatted according to framework specification and transmitted over communication channel. - + <dt><b>Channel:</b> <dd>communication link connecting two endpoints (peers). A single channel may be used to communicate with multiple services. Multiple channels may be used to connect the same peers, however no command or event ordering is guaranteed across channels. - + <dt><b>Command:</b> <dd>command is a message sent to remote peer in order to request some predefined action there. - + <dt><b>Result:</b> <dd>result is a message sent as a response to a command. - + <dt><b>Event:</b> <dd>event is a message sent to all interested parties in order to notify them about state changes. </dl> <h2><a name='Requirements'>Requirements</a></h2> - + <ul type='disc'> <li>Simple and extensible protocol. - + <li>Small footprint on the target. - + <li>Fully asynchronous, message based communication. - + <li>Two ways of message routing: <ul> <li>Point to point request/response (command/result) communication. - + <li>Subscription based broadcast of notifications (events). - </ul> - + </ul> + <li>Full duplex, symmetric communication: both host and target should be able to send commands and events at same time, though ability to establish communication channel can be limited to host only. - + <li>For each communication channel between two peers, the framework should preserve order of commands, results and events. - + <li>Support for slow and high latency connections. - + <li>Transport protocol agnostic. The framework should work well, at least, on top of: TCP/IP, UDP, USB, RS232 and JTAG. - + <li>The framework should support multiplexing, that is, single target device shared between multiple tools at same time. To reduce footprint on the target, multiplexing can be implemented on host if needed. - + <li>Dynamic discovery of participating targets and hosts. No configuration when possible. - + <li>Dynamic discovery of available services (high level protocols, command sets). Clients can query for available services. - + <li>Services can be added and removed dynamically. - + <li>Framework should define a set of common high level interfaces (services). For example: flow control, memory access, registers access, up-load mechanism, kernel awareness, run control, target file system, console, flash programming. Implementation of these interfaces is optional, but if provided it will support much wider compatibility with various tools. - + <li>Framework should be layered in such a way so it is possible to use different transport - medias (e.g. TCP/IP, RS232, USB, etc) without any changes to individual services. + medias (e.g. TCP/IP, RS232, USB, etc) without any changes to individual services. In other words, transport implementation should be services agnostic, and services implementation should be transport agnostic. - + <li>Each service defines how marshalling is done for command, result and event arguments. This allows existing target agents to remain unchanged. - + <li>Framework should define a preferred marshalling mechanism that new services can use. - + <li>The definition of services (groups of related commands and events) is separate from the definition of the framework itself. The framework provides unified communication mechanism, while services use it to communicate with its clients. - + <li>Anybody (including 3rd parties) can add services without having to modify communication protocol or framework software. - + <li>The framework should support tunneling through a proxy. Proxy may be used, for example: - + <ul type='circle'> - <li>to bridge different transport protocols, like TCP and RS232; - - <li>to make a RS232 or USB target connection accessible from multiple hosts; - + <li>to bridge different transport protocols, like TCP and RS232; + + <li>to make a RS232 or USB target connection accessible from multiple hosts; + <li>to access targets behind firewalls or otherwise not directly accessible </ul> - + <li>A proxy should be able to provide services in addition to those implemented by a target. Such distribution of services allows target services to be implemented on a host, thereby reducing the footprint on the target. For example, debug information, stack back trace or OS awareness can be implemented by a proxy on a host. To provide this functionality, proxy services would typically use low-level target services, like memory access. - + <li>Supports of concurrent requests. Maximum number of concurrent requests (window size) can be limited on target side. Simple agents only have to support window size of 1. Framework should maintain a queue of additional requests, so tools don't need to know the window size. This may only be relevant for certain transport protocols e.g. UDP. - + <li>Events can be broadcasted at any time, i.e. no polling should be required. - + <li>Protocol should support a standard mechanism of sending data larger than MTU. </ul> - + <h2><a name='Syntax'>Syntax Rules Notation</a></h2> - + <p>Format of the protocol messages is defined by syntax rules. Syntax is described using a simple variant of Backus-Naur Form. In particular:</p> - + <ul type='disc'> <li>Italic lower case words in a courier font, enclosed into angular brackets, are used to denote syntactic categories, for example: <b><i><font face="Courier New" size=2 color=#333399><token>. @@ -226,7 +226,7 @@ using a simple variant of Backus-Naur Form. In particular:</p> of the category, for example: <b><i><font face="Courier New" size=2 color=#333399><int: error code></font></i></b> has same meaning as <b><i><font face="Courier New" size=2 color=#333399><int></font></i></b>, but denotes that the integer number used to indicate an “error code”. - + <li>A syntax rule consists of a category designation followed by one or more syntax definitions for the category. The category name and each definition are placed on separate lines, bullets are used to denote definitions, for example: @@ -237,13 +237,13 @@ using a simple variant of Backus-Naur Form. In particular:</p> </font></b></pre> <li>Spaces are added for readability only and they are not part of the syntax. - + <li>All text in the category definition, other then categories and spaces, is UTF-8 based representation of a message bytes. - - <li>The symbol ‘•’ designates a zero byte. + + <li>The symbol ‘•’ designates a zero byte. </ul> - + <h1><a name='Design'>Framework Software Design Considerations</a></h1> <p>The framework will be packaged, distributed and installed on a host as separate @@ -251,7 +251,7 @@ product. It should be installed as system service and require no configuration f most common case – target connected over TCP or UDP on a local network. For more complicated setup, framework should have easily accessible and user friendly GUI with all relevant configuration options.</p> - + <p>Framework should use a dynamic discovery protocol to locate targets and other hosts running instances of the framework when possible, and maintain a dynamic list of available communication endpoints, as well as lists of services available at each endpoint. @@ -261,49 +261,49 @@ JTAG to a remote host. It should also be possible to add target configuration ma Development tools will access this data through the Locator Service API and use it, for example, to present a user a list of available targets that have capabilities needed by a particular tool.</p> - + <p>Framework should provide software libraries to be used by tools and target agents developers. The libraries should be available at least for ANSI C and Java. On host side, at least Windows, Solaris and Linux must be supported. Libraries will provide APIs for low-level communication protocol, Locator Service, preferred marshaling and predefined common services.</p> - + <p>The proposed target communication protocol is text-based. It allows extensions, which define messages with blocks of binary data, but it is not a recommended data formatting, and its usage is supposed to be limited. Text-based protocols have both advantages and disadvantages in compare with binary protocols.</p> - + <p>Advantages:</p> - + <ul type='disc'> <li>The software for text-based protocols is easier to develop and debug since they use a relatively human-friendly communication. - + <li>It is possible to use huge selection of existing tools and library routines to view, edit, validate, and transform text-based data. - + <li>Text based definition is in line with current trend in Internet protocols: most popular protocols such as SMTP and HTTP are text-based. </ul> - + <p>Disadvantages:</p> - + <ul type='disc'> <li>Text-based protocols usually need more bytes to store numerical data than binary protocols do. - + <li>Parsing of text-based data is not efficient compared to parsing of binary data since text-based data is usually not stored in a way similar to how it is stored in computer memory. - + <li>It is seldom possible to read only part of a text-based message since the exact byte offset to a data item is generally not known. </ul> - + <p>A possible alternative to consider is binary, variable length encoding like BaseStream.</p> - + <h2><a name='Concurrency'>Concurrency</a></h2> - + <p>Concurrent asynchronous communication is much faster then synchronous, because it alleviates communication channel latency and allows better bandwidth utilization. But it also requires proper design of framework software. Concurrency, in general, @@ -316,7 +316,7 @@ execution path is strictly contained in predefined subset of code (compartment), no code, except for reentrant libraries, is executed by multiple threads. Each compartment has a message queue and other threads communicate with the compartment thread by posting messages to the queue.</p> - + <p>Framework APIs are designed to be compatible with the compartment threading model. Hence the API functions do not contain any thread synchronization primitives to protect against multiple threads using the functions. All framework APIs belong to a single @@ -329,15 +329,15 @@ such as Java, this is typically done by a single callback object argument contai both the data and the function. The result listener is called asynchronously when the job is done. This approach is commonly known as asynchronous<b>, </b>event-driven<b> </b>or<b> </b>callback-based<b> </b>programming<b>.</b></p> - + <p>One important characteristic of an asynchronous code is that the methods defined by the user will often be called from within the framework itself, rather than from the user's application code. The framework often plays the role of the main program in coordinating and sequencing application activity. This phenomenon is called Inversion of Control (also known as the Hollywood Principle - "Don't call us, we'll call you").</p> - + <h2><a name='Reflection'>Reflection</a></h2> - + <p>Communication between development tools and embedded devices must allow a host to collect target side data and build a reflection of target state. Reflection is usually incomplete – a subset of all remote data. Reflection is always delayed – it @@ -345,36 +345,36 @@ represents a remote peer state in the past. Reflection can be updated by polling data changes or by listening to events (event is communication message that is sent asynchronously by a peer to notify others about state change). Reflection is correct if it represents a state that actually did happen on remote peer.</p> - + <p>Reflection is coherent if it is exactly equal to subset of peer state at a single moment of time and that moment of time is not too far in the past. Non-coherent reflection can have parts of data representing peer state at different moments of time. Coherent reflection is more valuable for a user, because non-coherent reflection can have logically conflicting data if that data was collected at different time.</p> - + <p>Traditionally, debuggers would ensure coherence of state reflection by collecting data only while target is suspended, and flushing all (or most) reflection data (reducing observed subset to zero) when target is resumed. This approach does not work well for multithreaded, multicore or real time targets. Maintaining correctness and coherence of a non-empty reflection while target is running requires additional support from target agent, communication software and debugger itself.</p> - + <p>Since remote peer state is changing over time, coherent reflection can be built only if:</p> - + <ul type='disc'> <li>Observed subset of state is properly selected and dynamically re-selected. Observing too much can overflow communication channel. Observing too little has little value for a user. - + <li>Observer is listening to all relevant events. - + <li>Events are coming in exactly same order as corresponding changes happen. - + <li>Events are properly ordered relative to other messages that carry state data. - + <li>All changes in observed subset of peer state are reported by events. - + <li>All event messages must either contain a complete description of a change or they all should not contain any state data at all. If client is getting some data from events and required to retrieve new values of other changed data by using other means @@ -383,24 +383,24 @@ only if:</p> Sending deltas with events is usually more efficient then using data retrieval commands to update reflection. </ul> - + <h2><a name='Ordering'>Message ordering</a></h2> - + <p>The transmission order of commands, results and events is important, it coveys valuable information about target state transitions and it should be preserved when possible. Consider an example:</p> - + <p>Client transmits: </p> - + <pre> Command X=2 </pre> <p>Then, as result of some activity of another client or the target itself, X is assigned value 3.</p> - + <p>Target transmits:</p> - + <pre> Event X=3 Result X=2 @@ -414,12 +414,12 @@ will have no clue what to show – 2 or 3. In fact, the client will have to decision about each message it receives: either trust message data as correct last known target state, or assume the message came in out-of-order and ignore it, or re-request the information from the target.</p> - + <p>Note that re-requesting data from the target, in general, does not solve the problem of interpretation of messages when order is not preserved. For example, after sending a request to read value of X, X could change at about the same time, and client could receive:</p> - + <pre> Event X=2 Result X=3 @@ -431,10 +431,10 @@ last one. A client could assume value of X unknown every time it receives a noti of X change, and then re-request the data again. But this is expensive and, if events coming in frequently, client can end up in infinite loop re-requesting the data again and again, and it will never have trustworthy data about current target state.</p> - + <p>Developers should be careful when using multithreading or multiple queues in software design – it can easily cause message reordering.</p> - + <p>The framework itself is required to preserve message order. However, if for whatever reason a target agent cannot preserve message order, the result will be that clients of the service can receive messages in the wrong order. When this is the case it should @@ -442,57 +442,57 @@ be well documented, so tools developers are aware and can make the best of the s In most cases it will not cause any trouble, but there is no perfect way to restore actual sequence of events and maintain data coherency after ordering was lost, and in some cases it can severely impact tool functionality and user experience.</p> - + <h1><a name='Transport'>Transport Layer</a></h1> - + <p>Tools are required to be transport protocol agnostic, so most of the layer functionality is used internally by framework and is not exposed to clients. This layer maintains a collection of transport protocol handlers. Each handler is designed to provide:</p> - + <ul type='disc'> <li>Enumeration of available peers, including both automatically discovered and manually configured peers. Handler fires notification events when peers are added or removed. Enumeration can be implemented by scanning JTAG chain, by broadcasting special UDP packet and waiting for responses, by communicating with ICE hardware, or by any other suitable means. - + <li>Bidirectional point-to-point communication of data packets. Packets are arrays of bytes of arbitrary size. Transport handler and underlying protocol are responsible for adding all necessary control data, headers, error checking bits, addresses, fragmentation/defragmentation, flow control, transmission retries and whatever necessary to ensure lossless, order-preserving delivery of packets. - + <li>Configuration UI should allow user to inspect and modify properties of both manually configured and automatically discovered peers, setup new peers, view connections status and statistics. </ul> - + <p>Existing service discovery protocols can be used together with the framework, for example:</p> - + <ul type='disc'> <li>Zero Configuration Networking (Zeroconf), see <a href='http://www.zeroconf.org/'>http://www.zeroconf.org</a>; - + <li>Service Location Protocol (SLP), developed by the IETF; - + <li>Jini, which is Sun's Java-base approach to service discovery, see <a href='http://www.sun.com/jini'>http://www.sun.com/jini</a>; - + <li>Salutation, developed by an open industry consortium, called the Salutation Consortium; - + <li>Microsoft's Universal Plug and Play (UPnP), see <a href='http://www.upnp.org/'>http://www.upnp.org</a>; - + <li>Bluetooth Service Discovery Protocol (SDP). </ul> - + <p>Service discovery protocols, as well as transport protocols will be supported by framework plug-ins, they are not part of framework code itself, and they can be developed by 3rd parties. Note that existing discovery protocols define term “service” differently - as an independent communication endpoint (usually a TCP/IP port). In this document it is called “peer” (host, target, communication endpoint), and a peer can provide multiple services over single communication channel.</p> - + <p>Using of standard discovery protocols should be optional, because it can potentially cause conflict or interference between development tools and application being developed over a use of same standard protocol – devices software often includes implementation @@ -507,19 +507,19 @@ of the communication channel for a particular peer, and for sending and receivin data packets. The protocol define contents of a part of a packet, the rest of the packet is treated as array of bytes at this level. The communication protocol implementation also provides:</p> - + <ul type='disc'> <li>Multiplexing – opening multiple channels per peer. - + <li>Proxy – packet forwarding in behalf of other hosts. </ul> - + <p>Protocol defines three packet types: commands (requests), results (responses), and events. Each packet consists of several protocol defined control fields followed by byte array of data. Binary representation of control fields is a sequence of zero terminated ASCII strings. Format of data array depends on a service. We recommend using framework preferred marshaling for data formatting.</p> - + <p>Syntax:</p> <pre><b><font face="Courier New" size=2 color=#333399> <i><message></i> @@ -530,37 +530,37 @@ using framework preferred marshaling for data formatting.</p> </font></b></pre> <h2><a name='ProtocolCommands'>Commands</a></h2> - + <pre><b><font face="Courier New" size=2 color=#333399> <i><command></i> ⇒ C • <i><token> </i>• <i><service name> </i>• <i><command name> </i>• <i><byte array: arguments></i> </font></b></pre> <p>Command packets start with string “C”.</p> - + <pre><b><font face="Courier New" size=2 color=#333399> <i><token></i> ⇒ <i><chars></i> </font></b></pre> - + <p>Token is unique string generated by framework for each command. It is used to match results to commands.</p> - + <pre><b><font face="Courier New" size=2 color=#333399> <i><service name></i> ⇒ <i><chars></i> </font></b></pre> - + <p>Service name is used to identify a service that handles the command, it is same string as returned by Service.getName().</p> - + <pre><b><font face="Courier New" size=2 color=#333399> <i><command name></i> ⇒ <i><chars></i> </font></b></pre> - + <p>Command name interpretation depends on a service.</p> - + <p>A command should always be answered with result packed. Result does not have to be positive – it can include an error code, or it can be special "N" result that indicates that command was not recognized, but there always must be one. Since client @@ -574,7 +574,7 @@ unlimited number of requests, since this will use resources in forms of memory t store the requests and time to process them.</p> <h2><a name='ProtocolResults'>Results</a></h2> - + <pre><b><font face="Courier New" size=2 color=#333399> <i><result></i> ⇒ N • <i><token></i> • @@ -587,23 +587,23 @@ result, and “N” if command is not recognized. Receiving of “R& There should be exactly one “R” or “N” result for each command. In addition, command execution can produce any number of intermediate “P” results. “P” results can be sent before “R”, and it can serve, for example, as command execution progress report when execution takes long time.</p> - + <pre><b><font face="Courier New" size=2 color=#333399> <i><token></i> ⇒ <i><chars></i> </font></b></pre> - + <p>Token should match token field of one of the pending commands that produced the result.</p> <h2><a name='ProtocolEvents'>Events</a></h2> - + <pre><b><font face="Courier New" size=2 color=#333399> <i><event></i> ⇒ E • <i><service name></i> • <i><event name></i> • <i><byte array: event data></i> </font></b></pre> <p>Event packets start with string “E”.</p> - + <pre><b><font face="Courier New" size=2 color=#333399> <i><service name></i> ⇒ <i><chars></i> @@ -611,14 +611,14 @@ example, as command execution progress report when execution takes long time.</p <p>Service name identifies a service that fired event, same string as returned by Service.getName().</p> - + <pre><b><font face="Courier New" size=2 color=#333399> <i><event name></i> ⇒ <i><chars></i> </font></b></pre> - + <p>Event name meaning depends on a service.</p> - + <p>Events are used to notify clients about changes in peer state. Services should provide sufficient variety of events for clients to track remote peer state without too much of polling. Clients, interested in a particular aspect of the target state, @@ -637,7 +637,7 @@ force clients to poll for changes and can also degrade performance. A balanced a is the best.</p> <h2><a name='ProtocolFlowControl'>Flow Control</a> </h2> - + <p>It often happens that one side of communication channel produces messages faster then they can be transmitted over the channel or can be consumed by another side. This will cause channel traffic congestion (flooding). Framework will deal with the @@ -660,14 +660,14 @@ indicate level of congestion. When a peer receives flow control message with con it should try to reduce its transmition speed.</p> <h2><a name='ProtocolExamples'>Message Examples</a></h2> - + <p>Examples use simplified command arguments and result data. See service description for actual data formats.</p> - + <p>Executing <b><i>suspend</i></b> command from <b><i>RunControl</i></b> service:</p> - + <p> </p> - + <pre> Send : C 1 RunControl suspend “Thread1” Receive: E RunControl suspended “Thread1” @@ -675,7 +675,7 @@ Receive: R 1 “Success” </pre> <p>Same command, but target was already suspended:</p> - + <pre> Receive: E RunControl suspended “Thread1” … @@ -685,7 +685,7 @@ Receive: R 2 “Already suspended” <p>Same command, but target was suspended (by another client) after sending the command, but before command was executed: </p> - + <pre> Receive: E RunControl running “Thread1” … @@ -695,40 +695,40 @@ Receive: R 3 “Already suspended” </pre> <h2><a name='API'>Framework API</a></h2> - + <pre> <font color=#3F5FBF>/** - * + * * Class Protocol provides static methods to access Target Communication Framework root objects: * 1. the framework event queue and dispatch thread; * 2. local instance of Locator service, which maintains a list of available targets; * 3. list of open communication channels. */</font> <font color=#7F0055>public class</font> Protocol { - + <font color=#7F0055>private static</font> IEventQueue <i>event_queue</i>; - + <font color=#3F5FBF>/** * Before TCF can be used it should be given an object implementing IEventQueue interface. * The implementation maintains a queue of objects implementing Runnable interface and * executes <code>run</code> methods of that objects in a sequence by a single thread. * The thread in referred as TCF event dispatch thread. Objects in the queue are called TCF events. * Executing <code>run</code> method of an event is also called dispatching of event. - * + * * Only few methods in TCF APIs are thread safe - can be invoked from any thread. - * If a method description does not say "can be invoked from any thread" explicitly - + * If a method description does not say "can be invoked from any thread" explicitly - * the method must be invoked from TCF event dispatch thread. All TCF listeners are * invoked from the dispatch thread. - * + * * <font color=#7F9FBF>@param</font> event_queue - IEventQueue implementation. */</font> <font color=#7F0055>public static void</font> setEventQueue(IEventQueue event_queue); - + <font color=#3F5FBF>/** * <font color=#7F9FBF>@return</font> instance of IEventQueue that should be used for TCF events. */</font> <font color=#7F0055>public static</font> IEventQueue getEventQueue(); - + <font color=#3F5FBF>/** * Returns true if the calling thread is TCF dispatch thread. * Use this call to ensure that a given task is being executed (or not being) @@ -738,7 +738,7 @@ Receive: R 3 “Already suspended” * <font color=#7F9FBF>@return</font> true if running on the dispatch thread. */</font> <font color=#7F0055>public static boolean</font> isDispatchThread(); - + <font color=#3F5FBF>/** * Causes runnable to have its run * method called in the dispatch thread of the framework. @@ -753,7 +753,7 @@ Receive: R 3 “Already suspended” * method should be executed asynchronously.</font> */</font> <font color=#7F0055>public static void</font> invokeLater(Runnable runnable); - + <font color=#3F5FBF>/** * Causes runnable to have its run * method called in the dispatch thread of the framework. @@ -765,21 +765,21 @@ Receive: R 3 “Already suspended” */</font> <font color=#7F0055>public static void</font> invokeAndWait(Runnable runnable) <font color=#7F0055>throws</font> InterruptedException; - + <font color=#3F5FBF>/** * Get instance of the framework locator service. * The service can be used to discover available remote peers. - * + * * @return instance of ILocator. */</font> <font color=#7F0055>public static</font> ILocator getLocator(); - + <font color=#3F5FBF>/** * Return an array of all open channels. * @return an array of IChannel */</font> <font color=#7F0055>public static</font> IChannel[] getOpenChannels(); - + <font color=#3F5FBF>/** * Interface to be implemented by clients willing to be notified when * new TCF communication channel is opened. @@ -787,7 +787,7 @@ Receive: R 3 “Already suspended” <font color=#7F0055>public interface</font> ChannelOpenListener { <font color=#7F0055>public void</font> onChannelOpen(IChannel channel); } - + <font color=#3F5FBF>/** * Add a listener that will be notified when new channel is opened. * @param listener @@ -805,21 +805,21 @@ Receive: R 3 “Already suspended” * The message is sent to all open communication channels – broadcasted. */</font> <font color=#7F0055>public static void</font> sendEvent(String service, String name, byte[] data); - + <font color=#3F5FBF>/** * Call back after TCF messages sent by this host up to this moment are delivered * to their intended target. This method is intended for synchronization of messages * across multiple channels. - * + * * Note: Cross channel synchronization can reduce performance and throughput. - * Most clients don't need cross channel synchronization and should not call this method. - * - * @param done will be executed by dispatch thread after communication + * Most clients don't need cross channel synchronization and should not call this method. + * + * @param done will be executed by dispatch thread after communication * messages are delivered to corresponding targets. */</font> <font color=#7F0055>public static void</font> sync(Runnable done); } - + <font color=#3F5FBF>/** * IChannel represents communication link connecting two endpoints (peers). * The channel asynchroniously transmits messages: commands, results and events. @@ -828,7 +828,7 @@ Receive: R 3 “Already suspended” * ordering is guaranteed across channels. */</font> <font color=#7F0055>public interface</font> IChannel { - + <font color=#3F5FBF>/** * Channel state IDs */</font> @@ -836,12 +836,12 @@ Receive: R 3 “Already suspended” <i><font color=#0000C0>STATE_OPENNING</font></i> = 0, <i><font color=#0000C0>STATE_OPEN</font></i> = 1, <i><font color=#0000C0>STATE_CLOSED</font></i> = 2; - + <font color=#3F5FBF>/** * <font color=#7F9FBF>@return</font> channel current state, see STATE_* */</font> int getState(); - + <font color=#3F5FBF>/** * Send command message to remote peer for execution. Commands can be queued * locally before transmission. Sending commands too fast can fill up @@ -851,17 +851,17 @@ Receive: R 3 “Already suspended” * <font color=#7F9FBF>@param</font> name - command name * <font color=#7F9FBF>@param</font> args - command arguments encoded into array of bytes * <font color=#7F9FBF>@param</font> done - call back object - * <font color=#7F9FBF>@return</font> pending command handle + * <font color=#7F9FBF>@return</font> pending command handle */</font> IToken sendCommand(IService service, String name, <font color=#7F0055>byte</font>[] args, ICommandListener done); - + <font color=#3F5FBF>/** * Command listener interface. Clients implement this interface * to receive command results. */</font> <font color=#7F0055>interface</font> ICommandListener { - + <font color=#3F5FBF>/** * Called when progress message (intermediate result) is received * from remote peer. @@ -869,7 +869,7 @@ Receive: R 3 “Already suspended” * <font color=#7F9FBF>@param</font> data - progress message arguments encoded into array of bytes */</font> <font color=#7F0055>void</font> progress(<font color=#7F0055>byte</font>[] data); - + <font color=#3F5FBF>/** * Called when command result received from remote peer. * <font color=#7F9FBF>@param</font> token - command handle @@ -884,7 +884,7 @@ Receive: R 3 “Already suspended” */</font> <font color=#7F0055>void</font> terminated(IToken token, Exception error); } - + <font color=#3F5FBF>/** * Send result message to remote peer. Messages can be queued locally before * transmission. Sending messages too fast can fill up communication channel @@ -894,26 +894,26 @@ Receive: R 3 “Already suspended” * <font color=#7F9FBF>@param</font> results - result message arguments encoded into array of bytes */</font> <font color=#7F0055>void</font> sendResult(IToken token, <font color=#7F0055>byte</font>[] results); - + <font color=#3F5FBF>/** * Get current level of outbound traffic congestion. - * + * * <font color=#7F9FBF>@return</font> integer value in range –100..100, where –100 means no pending * messages (no traffic), 0 means optimal load, and positive numbers * indicate level of congestion. - * + * * Note: in-bound traffic congestion is detected by framework and reported to * remote peer without client needed to be involved. Clients willing to provide * additional data about local congestion should register itself using * Protocol.addCongestionMonitor(). */</font> int getCongestion(); - + <font color=#3F5FBF>/** * Channel listener interface. */</font> <font color=#7F0055>interface</font> IChannelListener { - + <font color=#3F5FBF>/** * Called when a channel is opened. */</font> @@ -934,26 +934,26 @@ Receive: R 3 “Already suspended” */</font> <font color=#7F0055>void</font> congestionLevel(int level); } - + <font color=#3F5FBF>/** * Subscribe a channel listener. The listener will be notified about changes of * outbound traffic congestion level. * <font color=#7F9FBF>@param</font> listener - channel listener implementation */</font> <font color=#7F0055>void</font> addChannelListener(IChannelListener listener); - + <font color=#3F5FBF>/** * Remove a channel listener. * <font color=#7F9FBF>@param</font> listener - channel listener implementation */</font> <font color=#7F0055>void</font> removeChannelListener(IChannelListener listener); - + <font color=#3F5FBF>/** * Command server interface. * This interface is to be implemented by service providers. */</font> <font color=#7F0055>interface</font> ICommandServer { - + <font color=#3F5FBF>/** * Called every time a command is received from remote peer. * <font color=#7F9FBF>@param</font> token - command handle @@ -962,19 +962,19 @@ Receive: R 3 “Already suspended” */</font> <font color=#7F0055>void</font> command(IToken token, String name, <font color=#7F0055>byte</font>[] data); } - + <font color=#3F5FBF>/** * Subscribe a command server. The server will be notified about command * messages received through this channel for given service. * <font color=#7F9FBF>@param</font> service - local service implementation - * <font color=#7F9FBF>@param</font> server - implementation of service commands listener + * <font color=#7F9FBF>@param</font> server - implementation of service commands listener */</font> <font color=#7F0055>void</font> addCommandServer(IService service, ICommandServer listener); - + <font color=#3F5FBF>/** * Remove a command server. * <font color=#7F9FBF>@param</font> service - local service implementation - * <font color=#7F9FBF>@param</font> server - implementation of service commands listener + * <font color=#7F9FBF>@param</font> server - implementation of service commands listener */</font> <font color=#7F0055>void</font> removeCommandServer(IService service, ICommandServer listener); @@ -993,31 +993,31 @@ Receive: R 3 “Already suspended” */</font> <font color=#7F0055>void</font> event(String name, <font color=#7F0055>byte</font>[] data); } - + <font color=#3F5FBF>/** * Subscribe an event message listener for given service. * <font color=#7F9FBF>@param</font> service - remote service proxy - * <font color=#7F9FBF>@param</font> server - implementation of service event listener + * <font color=#7F9FBF>@param</font> server - implementation of service event listener */</font> <font color=#7F0055>void</font> addEventListener(IService service, IEventListener listener); - + <font color=#3F5FBF>/** * Unsubscribe an event message listener for given service. * <font color=#7F9FBF>@param</font> service - remote service proxy - * <font color=#7F9FBF>@param</font> server - implementation of service event listener + * <font color=#7F9FBF>@param</font> server - implementation of service event listener */</font> <font color=#7F0055>void</font> removeEventListener(IService service, IEventListener listener); - + <font color=#3F5FBF>/** * <font color=#7F9FBF>@return</font> IPeer object representing local endpoint of communication channel. */</font> IPeer getLocalPeer(); - + <font color=#3F5FBF>/** * <font color=#7F9FBF>@return</font> IPeer object representing remote endpoint of communication channel. */</font> IPeer getRemotePeer(); - + <font color=#3F5FBF>/** * <font color=#7F9FBF>@return</font> collection of services available on local peer. */</font> @@ -1054,14 +1054,14 @@ Receive: R 3 “Already suspended” * Return null if implementation of the interface is not available. */</font> <V <font color=#7F0055>extends</font> IService> V getRemoteService(Class<V> service_interface); - + <font color=#3F5FBF>/** * Install a service proxy object on this channel. * This method can be called only from channel open call-back. * It allows a client to extends TCF by adding proxy objects for non-standard services. * Client, wishing to become service proxy provider, should register itself * using either Protocol.addChannelOpenListener() or IChannel.addChannelListener(). - * It is not allowed to register more then one proxy for a given service interface. + * It is not allowed to register more then one proxy for a given service interface. */</font> <V <font color=#7F0055>extends</font> IService> <font color=#7F0055>void</font> setServiceProxy(Class<V> service_interface, IService service_proxy); @@ -1069,34 +1069,34 @@ Receive: R 3 “Already suspended” * Close communication channel. */</font> <font color=#7F0055>void</font> close(); - + <font color=#3F5FBF>/** * Close channel in case of communication error. * <font color=#7F9FBF>@param error</font> - cause of channel termination */</font> <font color=#7F0055>void</font> terminate(Throwable error); - + <font color=#3F5FBF>/** * Redirect this channel to given peer using this channel remote peer locator service as a proxy. * <font color=#7F9FBF>@param peer_</font> - peer that will become new remote communication endpoint of this channel */</font> <font color=#7F0055>void</font> redirect(IPeer peer); } - - + + <font color=#3F5FBF>/** * Object implemeting IToken interface is created by framework for every * command sent over communication channel. It is used to match command to its * results, and also can be used to cancel commands. */</font> <font color=#7F0055>public</font> interface IToken { - + <font color=#3F5FBF>/** * Try to cancel a command associated with given token. A command can be * canceled by this method only if it was not transmitted yet to remote peer * for execution. Successfully canceled command does not produce any result * messages. - * + * * <font color=#7F9FBF>@return</font> true if successful. */</font> <font color=#7F0055>boolean</font> cancel(); @@ -1110,55 +1110,55 @@ Receive: R 3 “Already suspended” separate from protocol specification, a service designer can choose any data format that suits the service requirements best. However, to promote better compatibility and to simplify service design and implementation, we recommend to use <b>JSON</b> for data formatting.</p> - + <p><b>JSON</b> (pronounced like the English given name <i>Jason</i>), which stands for "<b>J</b>ava<b>S</b>cript <b>O</b>bject <b>N</b>otation", is a lightweight, text-based, language-independent computer data interchange format. <b>JSON</b> is a subset of the object literal notation of JavaScript but its use does not require JavaScript.</p> - + <p><b>JSON</b> represents data with the same basic types that programming languages use. <b>JSON</b>'s basic types are:</p> - + <ul type='disc'> - <li>Number (integer, real, or floating-point) - - <li>String (double-quoted with backslash escapement) - + <li>Number (integer, real, or floating-point) + + <li>String (double-quoted with backslash escapement) + <li>Boolean (<code>true</code> and <code>false</code>) - - <li>Array (an ordered sequence of values) - - <li>Object (collection of key/value pairs) - - <li><code>null</code> + + <li>Array (an ordered sequence of values) + + <li>Object (collection of key/value pairs) + + <li><code>null</code> </ul> - + <p>The structures used in most programming languages easily map directly onto JSON's structures, and back again.</p> - + <p>JSON maps data onto Unicode string. Then the string is mapped onto array of bytes using UTF-8 encoding.</p> - + <p>JSON specification:</p> - + <pre><b><font face="Courier New" size=2 color=#333399> <i><object></i> ⇒ {} ⇒ { <i><members></i> } - + <i><members></i> ⇒ <i><string></i> : <i><value></i> ⇒ <i><members></i> , <i><string></i> : <i><value></i> - + <i><array></i> ⇒ [] ⇒ [ <i><elements></i> ] - + <i><elements></i> ⇒ <i><value></i> ⇒ <i><elements</i>> , <i><value></i> - + <i><value></i> ⇒ <i><string></i> ⇒ <i><number></i> @@ -1167,14 +1167,14 @@ using UTF-8 encoding.</p> ⇒ <i><boolean></i> ⇒ null -<i><boolean></i> +<i><boolean></i> ⇒ true ⇒ false <i><string></i> ⇒ "" ⇒ " <i><chars></i> " - + <i><chars></i> ⇒ <i><char></i> ⇒ <i><chars> <char></i> @@ -1196,23 +1196,23 @@ using UTF-8 encoding.</p> ⇒ <<i>int> <fraction></i> ⇒ <<i>int> <exponent></i> ⇒ <<i>int> <fraction> <exponent></i> - + <i><int></i> ⇒ <i><digit></i> - ⇒ <<i>digit 1-9> <digits></i> + ⇒ <<i>digit 1-9> <digits></i> ⇒ - <<i>digit></i> ⇒ - <<i>digit 1-9> <digits</i>> - -<i><fraction></i> - ⇒ . <i><digits></i> - -<i><exponent></i> - ⇒ <i><e></i> <i><digits></i> - -<i><digits></i> + +<i><fraction></i> + ⇒ . <i><digits></i> + +<i><exponent></i> + ⇒ <i><e></i> <i><digits></i> + +<i><digits></i> ⇒ <i><digit></i> - ⇒ <<i>digits></i> <<i>digit></i> - + ⇒ <<i>digits></i> <<i>digit></i> + <i><e></i> ⇒ e ⇒ e+ @@ -1224,11 +1224,11 @@ using UTF-8 encoding.</p> </font></b></pre> <p>See <a href='http://www.json.org/'>www.json.org</a> for more details.</p> - + <h2><a name='JSONExamples'>Examples</a></h2> - + <p>This is a JSON array containing two objects:</p> - + <pre> [ { @@ -1251,7 +1251,7 @@ using UTF-8 encoding.</p> } ] </pre> - + <h1><a name='Locator'>Locator Service</a></h1> <p>Locator Service uses transport layer to search for peers and to collect data about @@ -1304,7 +1304,7 @@ at services it implements (use IChannel.getRemoteServices() method to get a map <h2><a name='LocatorCommands'>Locator Service Commands</a></h2> <h3><a name='LocatorCommandRedirect'>redirect</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Locator • redirect • <i><string: peer ID></i> • </font></b></pre> @@ -1317,9 +1317,9 @@ Locator service starts acting as a proxy.</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='LocatorCommandSync'>sync</a></h3> - + <pre><b><font face="Courier New" size=2 color=#333399> C • <i><token></i> • Locator • sync • </font></b></pre> @@ -1333,7 +1333,7 @@ for sync result a client makes sure that all commands, that were issued before s <pre><b><font face="Courier New" size=2 color=#333399> R • <i><token></i> • </font></b></pre> - + <h2><a name='LocatorEvents'>Locator Service Events</a></h2> <pre><b><font face="Courier New" size=2 color=#333399> @@ -1366,20 +1366,20 @@ E • Locator • peerRemoved • <i><string: peer ID></i> • <font color=#3F5FBF>/** * Base interface for all service interfaces. A client can get list of available services * by calling IChannel.getLocalServices() and IChannel.getRemoteServices(). - * + * * Remote services are represented by a proxy objects that implement service interfaces by * translating method calls to TCF messages and sending them to a remote peer. * When communication channel is open, TCF automatically creates proxies for standard services. - * TCF clients can provides addition proxies for non-standard services by calling IChannel.setServiceProxy(). + * TCF clients can provides addition proxies for non-standard services by calling IChannel.setServiceProxy(). */</font> <font color=#7F0055>public</font> interface IService { - + <font color=#3F5FBF>/** * Get unique name of this service. */</font> String getName(); } - + <font color=#3F5FBF>/** * Both hosts and targets are represented by objects * implementing IPeer interface. A peer can act as host or @@ -1388,7 +1388,7 @@ E • Locator • peerRemoved • <i><string: peer ID></i> • * calling ILocator.getPeers */</font> <font color=#7F0055>public interface</font> IPeer { - + <font color=#7F0055>static final</font> String <i><font color=#0000C0>ATTR_ID</font></i> = <font color=#2A00FF>"ID"</font>, <i><font color=#0000C0>ATTR_NAME</font></i> = <font color=#2A00FF>"Name"</font>, @@ -1398,33 +1398,33 @@ E • Locator • peerRemoved • <i><string: peer ID></i> • <i><font color=#0000C0>ATTR_IP_ALIASES</font></i> = <font color=#2A00FF>"Aliases"</font>, <i><font color=#0000C0>ATTR_IP_ADDRESSES</font></i> = <font color=#2A00FF>"Addresses"</font>, <i><font color=#0000C0>ATTR_IP_PORT</font></i> = <font color=#2A00FF>"Port"</font>; - - + + <font color=#3F5FBF>/** * <font color=#7F9FBF>@return</font> map of peer attributes */</font> Map<String, String> getAttributes(); - + <font color=#3F5FBF>/** * <font color=#7F9FBF>@return</font> peer unique ID, same as getAttributes().get(ATTR_ID) */</font> String getID(); - + <font color=#3F5FBF>/** * <font color=#7F9FBF>@return</font> peer name, same as getAttributes().get(ATTR_NAME) */</font> String getName(); - + <font color=#3F5FBF>/** * Same as getAttributes().get(ATTR_OS_NAME) */</font> String getOSName(); - + <font color=#3F5FBF>/** * Same as getAttributes().get(ATTR_TRANSPORT_NAME) */</font> String getTransportName(); - + <font color=#3F5FBF>/** * Open channel to communicate with this peer. * Note: the channel is not fully open yet when this method returns. @@ -1433,7 +1433,7 @@ E • Locator • peerRemoved • <i><string: peer ID></i> • */</font> IChannel openChannel() <font color=#7F0055>throws</font> IOException; } - + <font color=#3F5FBF>/** * ILocator service uses transport layer to search for peers and to collect data about * peer's attributes and capabilities (services). Discovery mechanism depends on @@ -1441,14 +1441,14 @@ E • Locator • peerRemoved • <i><string: peer ID></i> • * hosts, are added to local list of peers. * Automatically discovered targets require no further configuration. Additional targets * can be configured manually. - * + * * Clients should use Protocol.getLocator() to obtain local instance of ILocator, * then ILocator.getPeers() can be used to get of available peers (hosts and targets). */</font> <font color=#7F0055>public interface</font> ILocator <font color=#7F0055>extends</font> IService { - + <font color=#7F0055>static final</font> String <i><font color=#0000C0>NAME</font></i> = <font color=#2A00FF>"Locator"</font>; - + <font color=#3F5FBF>/** * Auto-configuration command and response codes. */</font> @@ -1460,38 +1460,38 @@ E • Locator • peerRemoved • <i><string: peer ID></i> • * <font color=#7F9FBF>@return</font> Locator service name: "Locator" */</font> String getName(); - + <font color=#3F5FBF>/** * Get map (ID -> IPeer) of available peers (hosts and targets). * The method return cached (currently known to the framework) list of peers. * The list is updated according to event received from transport layer */</font> Map<String,IPeer> getPeers(); - + <font color=#3F5FBF>/** * Redirect this service channel to given peer using this service as a proxy. */</font> IToken redirect(String peer_id, DoneRedirect done); - + <font color=#7F0055>interface</font> DoneRedirect { <font color=#7F0055>void</font> doneRedirect(IToken token, Exception error); } - + <font color=#3F5FBF>/** * Call back after TCF messages sent to this target up to this moment are delivered. * This method is intended for synchronization of messages * across multiple channels. - * + * * Note: Cross channel synchronization can reduce performance and throughput. - * Most clients don't need channel synchronization and should not call this method. - * - * @param done will be executed by dispatch thread after communication + * Most clients don't need channel synchronization and should not call this method. + * + * @param done will be executed by dispatch thread after communication * messages are delivered to corresponding targets. - * + * * This is internal API, TCF clients should use {@code org.eclipse.tm.tcf.protocol.Protocol}. */</font> IToken sync(DoneSync done); - + <font color=#7F0055>interface</font> DoneSync { <font color=#7F0055>void</font> doneSync(IToken token); } @@ -1500,17 +1500,17 @@ E • Locator • peerRemoved • <i><string: peer ID></i> • * Add a listener for locator service events. */</font> <font color=#7F0055>void</font> addListener(Listener listener); - + <font color=#3F5FBF>/** * Remove a listener for locator service events. */</font> <font color=#7F0055>void</font> removeListener(Listener listener); - + <font color=#7F0055>interface</font> Listener { <font color=#7F0055>void</font> peerAdded(IPeer peer); - + <font color=#7F0055>void</font> peerRemoved(IPeer peer); - + <font color=#7F0055>void</font> peerChanged(IPeer peer); } } @@ -1518,4 +1518,4 @@ E • Locator • peerRemoved • <i><string: peer ID></i> • </body> </html> - + |