Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorEugene Tarassov2019-07-24 20:04:23 +0000
committerEugene Tarassov2019-07-24 20:20:07 +0000
commite86b66160bab3e7742350b0b5790fe57f772d655 (patch)
treea78a19cded95ba70d1e50071d4cbdd90d5c1ebb0
parente1b87d42fd5d2d309fc39bc282765b794484de9a (diff)
downloadorg.eclipse.tcf-e86b66160bab3e7742350b0b5790fe57f772d655.tar.gz
org.eclipse.tcf-e86b66160bab3e7742350b0b5790fe57f772d655.tar.xz
org.eclipse.tcf-e86b66160bab3e7742350b0b5790fe57f772d655.zip
TCF Docs: improved specifications of TCF services
-rw-r--r--docs/TCF Agent Porting Guide.html9
-rw-r--r--docs/TCF Error Report Format.html162
-rw-r--r--docs/TCF Getting Started.html5
-rw-r--r--docs/TCF JSON.html157
-rw-r--r--docs/TCF Linux Agent Prototype.html11
-rw-r--r--docs/TCF Lua Integration.html5
-rw-r--r--docs/TCF Service - Breakpoints.html2
-rwxr-xr-xdocs/TCF Service - Context Query.html2
-rw-r--r--docs/TCF Service - Context Reset.html2
-rw-r--r--docs/TCF Service - Debug Print.html2
-rw-r--r--docs/TCF Service - Diagnostics.html2
-rw-r--r--docs/TCF Service - Disassembly.html2
-rw-r--r--docs/TCF Service - Expressions.html2
-rw-r--r--docs/TCF Service - File System.html2
-rw-r--r--docs/TCF Service - Line Numbers.html2
-rw-r--r--docs/TCF Service - Locator.html435
-rw-r--r--docs/TCF Service - Memory Map.html4
-rw-r--r--docs/TCF Service - Memory.html4
-rw-r--r--docs/TCF Service - Path Map.html4
-rwxr-xr-xdocs/TCF Service - PortForward.html4
-rwxr-xr-xdocs/TCF Service - PortServer.html4
-rw-r--r--docs/TCF Service - Processes.html4
-rw-r--r--docs/TCF Service - Profiler.html2
-rw-r--r--docs/TCF Service - Registers.html4
-rw-r--r--docs/TCF Service - Run Control.html4
-rwxr-xr-xdocs/TCF Service - Stack Trace.html4
-rw-r--r--docs/TCF Service - Streams.html4
-rw-r--r--docs/TCF Service - Symbols.html2
-rw-r--r--docs/TCF Service - System Monitor.html4
-rw-r--r--docs/TCF Service - Terminals.html4
-rw-r--r--docs/TCF Services.html159
-rw-r--r--docs/TCF Specification.html531
-rw-r--r--docs/TCF Syntax Rules Notation.html75
-rw-r--r--docs/index.html4
-rw-r--r--plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/ILocator.java4
35 files changed, 897 insertions, 730 deletions
diff --git a/docs/TCF Agent Porting Guide.html b/docs/TCF Agent Porting Guide.html
index 1f8171206..719571df5 100644
--- a/docs/TCF Agent Porting Guide.html
+++ b/docs/TCF Agent Porting Guide.html
@@ -8,12 +8,9 @@
<h1>TCF Agent Porting Guide</h1>
- <p>
- Copyright (c) 2009, 2015 Wind River Systems, Inc. and others. Made available under the EPL v1.0
- </p>
- <p>
- Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list
- </p>
+<p>Copyright (c) 2009-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/>
+Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p>
+<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p>
<h2>Table of Contents</h2>
<ul>
diff --git a/docs/TCF Error Report Format.html b/docs/TCF Error Report Format.html
new file mode 100644
index 000000000..8726b1be4
--- /dev/null
+++ b/docs/TCF Error Report Format.html
@@ -0,0 +1,162 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <title>Error Report Format</title>
+</head>
+
+<body lang='EN-US'>
+
+<h1>Error Report Format</h1>
+
+<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/>
+Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p>
+<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p>
+
+<h2>Table of Contents</h2>
+<ul>
+ <li><a href='#VersionHistory'>Version History</a></li>
+ <li><a href='#ErrorFormat'>Error Report Format</a></li>
+</ul>
+
+<h2><a name='VersionHistory'>Version History</a></h2>
+
+<table border=1 cellpadding=8>
+ <tr>
+ <th>Version</th>
+ <th>Date</th>
+ <th>Change</th>
+ </tr>
+ <tr>
+ <td>0.1</td>
+ <td>2008-01-10</td>
+ <td>Initial contribution</td>
+ </tr>
+ <tr>
+ <td>1.0</td>
+ <td>2008-05-06</td>
+ <td>Approved</td>
+ </tr>
+ <tr>
+ <td>1.1</td>
+ <td>2008-06-25</td>
+ <td>Enhanced error reporting format, see <a href='http://bugs.eclipse.org/bugs/show_bug.cgi?id=232410'>Bug 232410</a></td>
+ </tr>
+</table>
+
+
+<h2><a name='ErrorFormat'>Error Report Format</a></h2>
+
+<p>TCF standard services use same format for error reporting:</p>
+
+<pre><b><font face="Courier New" size="2" color="#333399">
+<i>&lt;error report&gt;</i>
+ &rArr;
+ &rArr; null
+ &rArr; <i>&lt;object: error description&gt;</i>
+</font></b></pre>
+
+<p>Error reports use JSON for message encoding, see
+<a href='TCF JSON.html'>JSON - Preferred Marshaling</a>.</p>
+
+<p>Empty or null error report means success. Error description provides error details, including
+error code and a short, localizable, human readable explanation of the error.</p>
+
+<p>Error description properties are:</p>
+<dl>
+ <dt><b><font face="Courier New" size="2" color="#333399">"Code" : <i>&lt;integer&gt;</i></font></b></dt>
+ <dd>Error code. Can belong to one of predefined ranges:
+ <ul>
+ <li> 0x0-0xffff Standard TCF codes, includes a limited subset of POSIX errors, and OTHER error code, which
+ can be used together with "AltCode"</li>
+ <li> 0x10000-0x1ffff Service specific codes</li>
+ <li> 0x20000-0x2ffff Reserved codes - will never be used by the TCF standard</li>
+ </ul>
+ </dd>
+
+ <dt><b><font face="Courier New" size="2" color="#333399">"Time" : <i>&lt;integer&gt;</i></font></b></dt>
+ <dd> Error timestamp, in milliseconds since midnight, January 1, 1970 UTC</dd>
+
+ <dt><b><font face="Courier New" size="2" color="#333399">"Service" : <i>&lt;string&gt;</i></font></b></dt>
+ <dd> Name of the service that reported the error. Required when "Code" is service specific code.</dd>
+
+ <dt><b><font face="Courier New" size="2" color="#333399">"Format" : <i>&lt;string&gt;</i></font></b></dt>
+ <dd> Error description format supports separation between constant and variable parts
+ of error message ("Format" and "Params"). This is done to support localization.
+ Format string is expected to allow translation into foreign languages by means of string table lookup.
+ The format string syntax is defined in the Java language library
+ <b><font face="Courier New" size="2">java.text.MessageFormat</font></b>.
+ In order to simplify clients written in other languages, only a subset of the syntax is supported:
+ <ul>
+ <li> Supported format types: (none), number</li>
+ <li> Supported format styles:
+ <ul>
+ <li> number: (none), "integer", "percent"</li>
+ </ul>
+ </li>
+ </ul>
+ </dd>
+
+ <dt><b><font face="Courier New" size="2" color="#333399">"Params" : <i>&lt;array&gt;</i></font></b></dt>
+ <dd> An array of values to be used together with "Format" to create the error message.</dd>
+
+ <dt><b><font face="Courier New" size="2" color="#333399">"Severity" : <i>&lt;integer&gt;</i></font></b></dt>
+ <dd> Predefined severity values:
+ <ul>
+ <li>0 - error (default)</li>
+ <li>1 - warning</li>
+ <li>2 - fatal</li>
+ </ul>
+ </dd>
+ <dt><b><font face="Courier New" size="2" color="#333399">"AltCode" : <i>&lt;integer&gt;</i></font></b></dt>
+ <dd> Alternative error code. This can be used to represent,
+ for example, OS, POSIX, or other vendor specific error codes</dd>
+
+ <dt><b><font face="Courier New" size="2" color="#333399">"AltOrg" : <i>&lt;string&gt;</i></font></b></dt>
+ <dd> ID of organization defining "AltCode", for example "Linux", "VxWorks", "Wind River", etc</dd>
+
+ <dt><b><font face="Courier New" size="2" color="#333399">"CausedBy" : <i>&lt;object: error description&gt;</i></font></b></dt>
+ <dd> A nested error description. Can be used to describe a root cause of this error.</dd>
+</dl>
+
+<p>All fields except "Code" are optional.</p>
+
+<p>Standard error codes:</p>
+<pre><code>
+ OTHER = 1
+ JSON_SYNTAX = 2
+ PROTOCOL = 3
+ BUFFER_OVERFLOW = 4
+ CHANNEL_CLOSED = 5
+ COMMAND_CANCELLED = 6
+ UNKNOWN_PEER = 7
+ BASE64 = 8
+ EOF = 9
+ ALREADY_STOPPED = 10
+ ALREADY_EXITED = 11
+ ALREADY_RUNNING = 12
+ ALREADY_ATTACHED = 13
+ IS_RUNNING = 14
+ INV_DATA_SIZE = 15
+ INV_CONTEXT = 16
+ INV_ADDRESS = 17
+ INV_EXPRESSION = 18
+ INV_FORMAT = 19
+ INV_NUMBER = 20
+ INV_DWARF = 21
+ SYM_NOT_FOUND = 22
+ UNSUPPORTED = 23
+ INV_DATA_TYPE = 24
+ INV_COMMAND = 25
+</code></pre>
+
+<p>Service specific error code definitions, if any, are part of service specfications.
+Standard and service specific error codes can be extended over time. A
+client that does not recognize a specific error code should treat it in the
+same way as "OTHER".</p>
+
+<p>For encoding of <b><i><font face="Courier New" size="2" color="#333399">&lt;object&gt;</font></i></b>,
+<b><i><font face="Courier New" size="2" color="#333399">&lt;string&gt;</font></i></b>, etc., see
+<a href='TCF JSON.html'>JSON - Preferred Marshaling</a>.</p>
+
+</body>
+</html>
diff --git a/docs/TCF Getting Started.html b/docs/TCF Getting Started.html
index 2583e4ada..72a8776ed 100644
--- a/docs/TCF Getting Started.html
+++ b/docs/TCF Getting Started.html
@@ -8,8 +8,9 @@
<h1>Target Communication Framework: Getting Started</h1>
-<p>Copyright (c) 2007, 2017 Wind River Systems, Inc. and others. Made available under the EPL v1.0
-<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list
+<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/>
+Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p>
+<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p>
<h2>Table of Contents</h2>
<ul>
diff --git a/docs/TCF JSON.html b/docs/TCF JSON.html
new file mode 100644
index 000000000..23f5c1684
--- /dev/null
+++ b/docs/TCF JSON.html
@@ -0,0 +1,157 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <title>JSON - Preferred Marshaling</title>
+</head>
+<body lang='EN-US'>
+
+<h1>JSON - Preferred Marshaling</h1>
+
+<p>The TCF message data format is service specific. Since service specifications are
+separate from the 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 using <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>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>
+ </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>&lt;object&gt;</i>
+ &rArr; {}
+ &rArr; { <i>&lt;members&gt;</i> }
+
+<i>&lt;members&gt;</i>
+ &rArr; <i>&lt;string&gt;</i> : <i>&lt;value&gt;</i>
+ &rArr; <i>&lt;members&gt;</i> , <i>&lt;string&gt;</i> : <i>&lt;value&gt;</i>
+
+<i>&lt;array&gt;</i>
+ &rArr; []
+ &rArr; [ <i>&lt;elements&gt;</i> ]
+
+<i>&lt;elements&gt;</i>
+ &rArr; <i>&lt;value&gt;</i>
+ &rArr; <i>&lt;elements</i>&gt; , <i>&lt;value&gt;</i>
+
+<i>&lt;value&gt;</i>
+ &rArr; <i>&lt;string&gt;</i>
+ &rArr; <i>&lt;number&gt;</i>
+ &rArr; <i>&lt;object&gt;</i>
+ &rArr; <i>&lt;array&gt;</i>
+ &rArr; <i>&lt;boolean&gt;</i>
+ &rArr; null
+
+<i>&lt;boolean&gt;</i>
+ &rArr; true
+ &rArr; false
+
+<i>&lt;string&gt;</i>
+ &rArr; ""
+ &rArr; " <i>&lt;chars&gt;</i> "
+
+<i>&lt;chars&gt;</i>
+ &rArr; <i>&lt;char&gt;</i>
+ &rArr; <i>&lt;chars&gt; &lt;char&gt;</i>
+
+<i>&lt;char</i>&gt;
+ &rArr; <i>&lt;any Unicode except " or \ or control&gt;</i>
+ &rArr; \"<i></i>
+ &rArr; \\<i></i>
+ &rArr; \/<i></i>
+ &rArr; \b<i></i>
+ &rArr; \f<i></i>
+ &rArr; \n<i></i>
+ &rArr; \r<i></i>
+ &rArr; \t<i></i>
+ &rArr; \u <i>&lt;four-hex-digits&gt;</i>
+
+<i>&lt;number</i>&gt;
+ &rArr; <i>&lt;int&gt;</i>
+ &rArr; &lt;<i>int&gt; &lt;fraction&gt;</i>
+ &rArr; &lt;<i>int&gt; &lt;exponent&gt;</i>
+ &rArr; &lt;<i>int&gt; &lt;fraction&gt; &lt;exponent&gt;</i>
+
+<i>&lt;int&gt;</i>
+ &rArr; <i>&lt;digit&gt;</i>
+ &rArr; &lt;<i>digit 1-9&gt; &lt;digits&gt;</i>
+ &rArr; - &lt;<i>digit&gt;</i>
+ &rArr; - &lt;<i>digit 1-9&gt; &lt;digits</i>&gt;
+
+<i>&lt;fraction&gt;</i>
+ &rArr; . <i>&lt;digits&gt;</i>
+
+<i>&lt;exponent&gt;</i>
+ &rArr; <i>&lt;e&gt;</i> <i>&lt;digits&gt;</i>
+
+<i>&lt;digits&gt;</i>
+ &rArr; <i>&lt;digit&gt;</i>
+ &rArr; &lt;<i>digits&gt;</i> &lt;<i>digit&gt;</i>
+
+<i>&lt;e&gt;</i>
+ &rArr; e
+ &rArr; e+
+ &rArr; e-
+ &rArr; E
+ &rArr; E+
+ &rArr; E-
+
+</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>
+ [
+ {
+ "Precision": "zip",
+ "Latitude": 37.7668,
+ "Longitude": -122.3959,
+ "City": "SAN FRANCISCO",
+ "State": "CA",
+ "Zip": "94107",
+ "Country": "US"
+ },
+ {
+ "Precision": "zip",
+ "Latitude": 37.371991,
+ "Longitude": -122.026020,
+ "City": "SUNNYVALE",
+ "State": "CA",
+ "Zip": "94085",
+ "Country": "US"
+ }
+ ]
+</pre>
+
+</body>
+</html>
diff --git a/docs/TCF Linux Agent Prototype.html b/docs/TCF Linux Agent Prototype.html
index 90156d408..f8895c214 100644
--- a/docs/TCF Linux Agent Prototype.html
+++ b/docs/TCF Linux Agent Prototype.html
@@ -9,12 +9,9 @@
<h1>TCF Agent Prototype Implementation</h1>
-<p>
- Copyright (c) 2009 Wind River Systems, Inc. Made available under the EPL v1.0
-</p>
-<p>
- Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list
-</p>
+<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/>
+Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p>
+<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p>
<h2>Table of Contents</h2>
<ul>
@@ -203,7 +200,7 @@ Any thread can queue new events.</p>
<h3>JSON Library</h3>
<p>The module contains utility functions for parsing and generating of JSON text.
-TCF standard services use JSON as messages format. See <a href='TCF Specification.html#JSON'>JSON - Preferred Marshaling</a>
+TCF standard services use JSON as messages format. See <a href='TCF JSON.html'>JSON - Preferred Marshaling</a>
for JSON description.</p>
<p>Files:</p>
<ul>
diff --git a/docs/TCF Lua Integration.html b/docs/TCF Lua Integration.html
index a99b0ae5c..5818f6b1d 100644
--- a/docs/TCF Lua Integration.html
+++ b/docs/TCF Lua Integration.html
@@ -8,8 +8,9 @@
<h1>Target Communication Framework: Lua Integration</h1>
-<p>Copyright (c) 2007, 2012 Wind River Systems, Inc. Made available under the EPL v1.0
-<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list
+<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/>
+Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p>
+<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p>
<h2><a name='TcfLua'>TCF Integration with Lua</a></h2>
diff --git a/docs/TCF Service - Breakpoints.html b/docs/TCF Service - Breakpoints.html
index 2c0afe0b5..7fba67a37 100644
--- a/docs/TCF Service - Breakpoints.html
+++ b/docs/TCF Service - Breakpoints.html
@@ -118,7 +118,7 @@ channels, target agent should treat it as single breakpoint with multiple refere
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>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='Cmds'>Commands</a></h2>
diff --git a/docs/TCF Service - Context Query.html b/docs/TCF Service - Context Query.html
index c7bd91202..fb83240ed 100755
--- a/docs/TCF Service - Context Query.html
+++ b/docs/TCF Service - Context Query.html
@@ -57,7 +57,7 @@ starts with a "/" the first part of the query must match a child of
the root of the context tree.</p>
<p>The service uses standard format for error reports,
-see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='SyntaxandSemantics'>Syntax and Semantics</a></h2>
diff --git a/docs/TCF Service - Context Reset.html b/docs/TCF Service - Context Reset.html
index 6849c3e90..857a79466 100644
--- a/docs/TCF Service - Context Reset.html
+++ b/docs/TCF Service - Context Reset.html
@@ -39,7 +39,7 @@
</p>
<p>
The service uses standard format for error reports,
- see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.
+ see <a href='TCF Error Report Format.html'>Error Report Format</a>.
</p>
<h2><a name='Cmds'>Commands</a></h2>
<h3><a name='CmdGetCapabilities'>Get Capabilities</a></h3>
diff --git a/docs/TCF Service - Debug Print.html b/docs/TCF Service - Debug Print.html
index 538a3c663..15e933c00 100644
--- a/docs/TCF Service - Debug Print.html
+++ b/docs/TCF Service - Debug Print.html
@@ -46,7 +46,7 @@
</p>
<p>The service uses standard format for error reports,
-see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='Cmds'>Commands</a></h2>
diff --git a/docs/TCF Service - Diagnostics.html b/docs/TCF Service - Diagnostics.html
index 09bf6e08e..85508f8de 100644
--- a/docs/TCF Service - Diagnostics.html
+++ b/docs/TCF Service - Diagnostics.html
@@ -48,7 +48,7 @@
communication channel functionality and reliability.</p>
<p>The service uses standard format for error reports,
-see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='Cmds'>Commands</a></h2>
diff --git a/docs/TCF Service - Disassembly.html b/docs/TCF Service - Disassembly.html
index 84b16d61c..4f7e2b1f2 100644
--- a/docs/TCF Service - Disassembly.html
+++ b/docs/TCF Service - Disassembly.html
@@ -41,7 +41,7 @@
<p>While disassembly is dependent upon a specific processor architecture, the memory from which it is derived is not. So for a given memory context, or buffer, the specified ISA used to disassemble the memory bytes is subjective to the Tool or user.</p>
<p>The service uses standard format for error reports,
-see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='Cmds'>Commands</a></h2>
diff --git a/docs/TCF Service - Expressions.html b/docs/TCF Service - Expressions.html
index 118f9d960..a86cd1078 100644
--- a/docs/TCF Service - Expressions.html
+++ b/docs/TCF Service - Expressions.html
@@ -61,7 +61,7 @@ it can be evaluated multiple times, for example, each time the target is suspend
</ol>
<p>The service uses standard format for error reports,
-see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='Cmds'>Commands</a></h2>
diff --git a/docs/TCF Service - File System.html b/docs/TCF Service - File System.html
index 01ddbcad4..894dc21cc 100644
--- a/docs/TCF Service - File System.html
+++ b/docs/TCF Service - File System.html
@@ -175,7 +175,7 @@ Tools and targets can define additional attributes. Predefined attributes are:</
<h2><a name='ErrorCodes'>Error codes</a></h2>
<p>The service uses standard format for error reports,
-see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<p>Currently, the following values are defined for service specific error codes (other values may be
defined by future versions of this protocol):</p>
diff --git a/docs/TCF Service - Line Numbers.html b/docs/TCF Service - Line Numbers.html
index d7203bd83..fed09b48e 100644
--- a/docs/TCF Service - Line Numbers.html
+++ b/docs/TCF Service - Line Numbers.html
@@ -120,7 +120,7 @@ continues range of code addresses. Code Area data object is collection of area p
</font></b></pre>
<p>The service uses standard format for error reports,
-see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='Cmds'>Commands</a></h2>
diff --git a/docs/TCF Service - Locator.html b/docs/TCF Service - Locator.html
new file mode 100644
index 000000000..fcce86b11
--- /dev/null
+++ b/docs/TCF Service - Locator.html
@@ -0,0 +1,435 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <title>Target Communication Framework Services - Locator</title>
+</head>
+<body lang='EN-US'>
+
+<h1>Target Communication Framework Services - Locator</h1>
+
+<ul>
+ <li><a href='#VersionHistory'>Version History</a>
+ <li><a href='#Overview'>Overview</a>
+ <li><a href='#Cmds'>Commands</a>
+ <li><a href='#Interfaces'>Interfaces</a>
+ <li><a href='#API'>API</a>
+</ul>
+
+<h1>Locator Service</h1>
+
+<h2><a name='VersionHistory'>Version History</a></h2>
+
+<table border=1 cellpadding=8>
+ <tr>
+ <th>Version
+ <th>Date
+ <th>Change
+ <tr>
+ <td>1.0
+ <td>2008-05-06
+ <td>Initial
+</table>
+
+<h2><a name='Overview'>Overview</a></h2>
+
+<p>The Locator service uses the transport layer to search for peers and to collect data about
+the peer's attributes and capabilities (services). The discovery mechanism depends on the transport
+protocol and is part of that protocol handler. Targets, known by other hosts, are
+added to local list of peers. <font color=red>Security? </font>Automatically discovered
+targets require no further configuration. Additional targets can be configured manually.</p>
+
+<p>All TCF peers must implement Locator service. The implementation is part of the framework itself.
+It is the only required service, all other services are optional and, formally, not part of the framework.</p>
+
+<h2><a name='LocatorPeer'>Peer Attributes</a></h2>
+
+<p><i>&lt;object: peer data&gt;</i> is collection of peer attributes. It should, at least, contain member
+<b><font face="Courier New" size=2 color=#333399>"ID" : <i>&lt;string&gt;</i></font></b>.
+It can also contain a number of components describing peer properties and capabilities.
+Predefined attributes are:</p>
+
+<ul>
+ <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i>&lt;string&gt;</i></font></b></code>
+ - unique ID of the peer.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"ServiceManagerID" : <i>&lt;string&gt;</i></font></b></code>
+ - unique ID of service manager that is represented by this peer.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"AgentID" : <i>&lt;string&gt;</i></font></b></code>
+ - agent unique ID.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"Name" : <i>&lt;string&gt;</i></font></b></code>
+ - human readable peer name.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"OSName" : <i>&lt;string&gt;</i></font></b></code>
+ - peer OS name, if applicable.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"TransportName" : <i>&lt;string&gt;</i></font></b></code>
+ - name of a trasport protocol to use to connect to this peer, for example: TCP.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"Host" : <i>&lt;string&gt;</i></font></b></code>
+ - peer host name, if transport is TCP or UDP.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"Aliases" : <i>&lt;string&gt;</i></font></b></code>
+ - peer host name aliases, if transport is TCP or UDP.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"Addresses" : <i>&lt;string&gt;</i></font></b></code>
+ - peer IP addresses, if transport is TCP or UDP.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"Port" : <i>&lt;string&gt;</i></font></b></code>
+ - peer port number, if transport is TCP or UDP.
+</ul>
+
+<p>Most clients do not need to know any peer attributes other than ID and Name. Clients are expected to call the IPeer.openChannel()
+method and let the framework check peer attributes and create appropriate communication channel that is best suited for
+communication with the peer. After a channel is established, a client can learn the peer capabilities by looking
+at what services it implements (use IChannel.getRemoteServices() method to get a map of services).</p>
+
+<p>The service uses standard format for error reports,
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
+
+<h2><a name='Cmds'>Commands</a></h2>
+
+<h3><a name='CmdRedirect'>redirect</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C &bull; <i>&lt;token&gt;</i> &bull; Locator &bull; redirect &bull; <i>&lt;peer&gt;</i> &bull;
+
+<i>&lt;peer&gt;</i>
+ &rArr; <i>&lt;string: peer ID&gt;</i>
+ &rArr; <i>&lt;object: peer data&gt;</i>
+</font></b></pre>
+
+<p>The command redirects the channel to become connected to the given peer.
+The Locator service starts acting as a proxy.</p>
+
+<p>Reply:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R &bull; <i>&lt;token&gt;</i> &bull; <i>&lt;error report&gt;</i> &bull;
+</font></b></pre>
+
+<h3><a name='CmdSync'>sync</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C &bull; <i>&lt;token&gt;</i> &bull; Locator &bull; sync &bull;
+</font></b></pre>
+
+<p>The sync command does nothing and simply returns back an empty result. The command is used for
+cross channel synchronization. Since commands are executed in order they were issued, by waiting
+for sync result a client makes sure that all commands, that were issued before sync, are fully processed.</p>
+
+<p>Reply:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R &bull; <i>&lt;token&gt;</i> &bull;
+</font></b></pre>
+
+<h3><a name='CmdGetAgentID'>Get Agent ID</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C &bull; <i>&lt;token&gt;</i> &bull; Locator &bull; getAgentID &bull;
+</font></b></pre>
+
+<p>Get agent ID of the agent providing the locator service.
+The agent ID can be used to identify the agent among all the peers.</p>
+
+<p>Reply:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R &bull; <i>&lt;token&gt;</i> &bull; <i>&lt;error report&gt;</i> &bull; <i>&lt;string: agent ID&gt;</i> &bull;
+</font></b></pre>
+
+<h2><a name='LocatorEvents'>Locator Service Events</a></h2>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+E &bull; Locator &bull; Hello &bull; <i>&lt;array: service names&gt;</i> &bull;
+E &bull; Locator &bull; peerAdded &bull; <i>&lt;object: peer data&gt;</i> &bull;
+E &bull; Locator &bull; peerChanged &bull; <i>&lt;object: peer data&gt;</i> &bull;
+E &bull; Locator &bull; peerRemoved &bull; <i>&lt;string: peer ID&gt;</i> &bull;
+E &bull; Locator &bull; peerHeartBeat &bull; <i>&lt;string: peer ID&gt;</i> &bull;
+</font></b></pre>
+
+<dl>
+ <dt><b>Hello</b>
+ <dd>is the first message sent by the framework after establishing a communication channel.
+ The message lets other side of the channel know capabilities of this peer.
+ Message data consists of an array of service names that are provided by the peer.
+ The service name list is a complete and unambiguous declaration of peer's capabilities.
+ To avoid ambiguity, different services (even slightly different, like versions of same service)
+ must have different names. Framework delays all other communications between peers until exchange
+ of Hello messages is complete.
+ <dt><b>peerAdded</b>
+ <dd>is sent when the service discovers a new peer.
+ <dt><b>peerChanged</b>
+ <dd>is sent when peer attributes change.
+ <dt><b>peerRemoved</b>
+ <dd>is sent when the service deletes information about a peer.
+ <dt><b>peerHeartBeat</b>
+ <dd>is sent periodically when the service receives a communication from the peer
+ that confirms that the peer is still alive.
+</dl>
+
+<h2><a name='Interfaces'>Interfaces</a></h2>
+
+<pre>
+<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().
+ */</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
+ * target depending on services it implements.
+ * List of currently known peers can be retrieved by
+ * calling ILocator.getPeers()
+ *
+ * A TCF agent houses one or more service managers. A service manager has a one or more
+ * services to expose to the world. The service manager creates one or more peers
+ * to represent itself, one for every access path the agent is
+ * reachable by. For example, in agents accessible via TCP/IP, the
+ * service manger would create a peer for every subnet it wants to participate in.
+ * All peers of particular service manager represent identical sets of services.
+ *
+ * @noimplement This interface is not intended to be implemented by clients.
+ * Client can extends the abstract IPeer implementation: AbstractPeer.
+ */</font>
+<font color=#7F0055>public interface</font> IPeer {
+
+ <font color=#3F5FBF>/**
+ * Peer property names. Implementation can define additional properties.
+ */</font>
+ <font color=#7F0055>static final</font> String
+ <font color=#3F5FBF>/** Peer unique ID */</font>
+ <i><font color=#0000C0>ATTR_ID</font></i> = <font color=#2A00FF>"ID"</font>,
+
+ <font color=#3F5FBF>/** Unique ID of service manager that is represented by this peer */</font>
+ <i><font color=#0000C0>ATTR_SERVICE_MANGER_ID</font></i> = <font color=#2A00FF>"ServiceManagerID"</font>,
+
+ <font color=#3F5FBF>/** Agent unique ID */</font>
+ <i><font color=#0000C0>ATTR_AGENT_ID</font></i> = <font color=#2A00FF>"AgentID"</font>,
+
+ <font color=#3F5FBF>/** Peer name */</font>
+ <i><font color=#0000C0>ATTR_NAME</font></i> = <font color=#2A00FF>"Name"</font>,
+
+ <font color=#3F5FBF>/** Name of the peer operating system */</font>
+ <i><font color=#0000C0>ATTR_OS_NAME</font></i> = <font color=#2A00FF>"OSName"</font>,
+
+ <font color=#3F5FBF>/** Transport name, for example TCP, SSL */</font>
+ <i><font color=#0000C0>ATTR_TRANSPORT_NAME</font></i> = <font color=#2A00FF>"TransportName"</font>,
+
+ <font color=#3F5FBF>/** If present, indicates that the peer can forward traffic to other peers */</font>
+ <i><font color=#0000C0>ATTR_PROXY</font></i> = <font color=#2A00FF>"Proxy"</font>,
+
+ <font color=#3F5FBF>/** Host DNS name or IP address */</font>
+ <i><font color=#0000C0>ATTR_IP_HOST</font></i> = <font color=#2A00FF>"Host"</font>,
+
+ <font color=#3F5FBF>/** Optional list of host aliases */</font>
+ <i><font color=#0000C0>ATTR_IP_ALIASES</font></i> = <font color=#2A00FF>"Aliases"</font>,
+
+ <font color=#3F5FBF>/** Optional list of host addresses */</font>
+ <i><font color=#0000C0>ATTR_IP_ADDRESSES</font></i> = <font color=#2A00FF>"Addresses"</font>,
+
+ <font color=#3F5FBF>/** IP port number, must be decimal number */</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&lt;String, String&gt; 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> service manager unique ID, same as getAttributes().get(ATTR_SERVICE_MANAGER_ID)
+ */</font>
+ String getServiceManagerID();
+
+ <font color=#3F5FBF>/**
+ * <font color=#7F9FBF>@return</font> agent unique ID, same as getAttributes().get(ATTR_AGENT_ID)
+ */</font>
+ String getAgentID();
+
+ <font color=#3F5FBF>/**
+ * <font color=#7F9FBF>@return</font> peer name, same as getAttributes().get(ATTR_NAME)
+ */</font>
+ String getName();
+
+ <font color=#3F5FBF>/**
+ * <font color=#7F9FBF>@return</font> agent OS name, same as getAttributes().get(ATTR_OS_NAME)
+ */</font>
+ String getOSName();
+
+ <font color=#3F5FBF>/**
+ * <font color=#7F9FBF>@return</font> transport name, 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.
+ * It's state is IChannel.STATE_OPENNING.
+ * Protocol.Listener will be called when the channel will be opened or closed.
+ */</font>
+ IChannel openChannel() <font color=#7F0055>throws</font> IOException;
+}
+</pre>
+
+<h2><a name='API'>API</a></h2>
+
+<pre>
+<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 transport protocol
+ * and is part of that protocol handler. Targets, known to other hosts, can be found through
+ * remote instances of ILocator service. 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 list of available peers (hosts and targets).
+ *
+ * <font color=#7F9FBF>@noimplement</font> This interface is not intended to be implemented by clients.
+ */</font>
+<font color=#7F0055>public interface</font> ILocator <font color=#7F0055>extends</font> IService {
+
+ <font color=#7F0055>static final</font> String NAME = "Locator";
+
+ <font color=#3F5FBF>/**
+ * Peer data retention period in milliseconds.
+ */</font>
+ <font color=#7F0055>static final</font> <font color=#7F0055>long</font> DATA_RETENTION_PERIOD = 60 * 1000;
+
+ <font color=#3F5FBF>/**
+ * Auto-configuration protocol version.
+ */</font>
+ static char CONF_VERSION = '2';
+
+ <font color=#3F5FBF>/**
+ * Auto-configuration command and response codes.
+ */</font>
+ <font color=#7F0055>static final int</font>
+ CONF_REQ_INFO = 1,
+ CONF_PEER_INFO = 2,
+ CONF_REQ_SLAVES = 3,
+ CONF_SLAVES_INFO = 4,
+ CONF_PEERS_REMOVED = 5;
+
+ <font color=#3F5FBF>/**
+ * <font color=#7F9FBF>@return</font> Locator service name: "Locator"
+ */</font>
+ String getName();
+
+ <font color=#3F5FBF>/**
+ * Get map (ID -&gt; 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&lt;String,IPeer&gt; getPeers();
+
+ <font color=#3F5FBF>/**
+ * Redirect this service channel to given peer using this service as a proxy.
+ * <font color=#7F9FBF>@param</font> peer_id - Peer ID.
+ */</font>
+ IToken redirect(String peer_id, DoneRedirect done);
+
+ <font color=#3F5FBF>/**
+ * Redirect this service channel to given peer using this service as a proxy.
+ * <font color=#7F9FBF>@param</font> peer - Peer attributes.
+ */</font>
+ IToken redirect(Map&lt;String,String&gt; peer, 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.
+ *
+ * <font color=#7F9FBF>@param</font> 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.tcf.protocol.Protocol}.
+ */</font>
+ IToken sync(DoneSync done);
+
+ <font color=#7F0055>interface</font> DoneSync {
+ <font color=#7F0055>void</font> doneSync(IToken token);
+ }
+
+ <font color=#3F5FBF>/**
+ * Get agent ID of the agent providing the locator service.
+ *
+ * The agent ID can be used to identify the agent among all the peers
+ * returned by {@link #getPeers()}.
+ */</font>
+ IToken getAgentID(DoneGetAgentID done);
+
+ <font color=#7F0055>interface</font> DoneGetAgentID {
+ <font color=#7F0055>void</font> doneGetAgentID(IToken token, Exception error, String agentID);
+ }
+
+ <font color=#3F5FBF>/**
+ * Add a listener for ILocator service events.
+ */</font>
+ <font color=#7F0055>void</font> addListener(LocatorListener listener);
+
+ <font color=#3F5FBF>/**
+ * Remove a listener for ILocator service events.
+ */</font>
+ <font color=#7F0055>void</font> removeListener(LocatorListener listener);
+
+ <font color=#3F5FBF>/**
+ * ILocator service event listener interface
+ */</font>
+ <font color=#7F0055>interface</font> LocatorListener {
+ <font color=#3F5FBF>/**
+ * A new peer is added into locator peer table.
+ * <font color=#7F9FBF>@param</font> peer
+ */</font>
+ <font color=#7F0055>void</font> peerAdded(IPeer peer);
+
+ <font color=#3F5FBF>/**
+ * Peer attributes have changed.
+ * <font color=#7F9FBF>@param</font> peer
+ */</font>
+ <font color=#7F0055>void</font> peerChanged(IPeer peer);
+
+ <font color=#3F5FBF>/**
+ * A peer is removed from locator peer table.
+ * <font color=#7F9FBF>@param</font> id - peer ID
+ */</font>
+ <font color=#7F0055>void</font> peerRemoved(String id);
+
+ <font color=#3F5FBF>/**
+ * Peer heart beat detected.
+ * <font color=#7F9FBF>@param</font> id - peer ID
+ */</font>
+ <font color=#7F0055>void</font> peerHeartBeat(String id);
+ }
+}
+</pre>
+
+</body>
+</html>
diff --git a/docs/TCF Service - Memory Map.html b/docs/TCF Service - Memory Map.html
index f2b5d179d..c59d7d13b 100644
--- a/docs/TCF Service - Memory Map.html
+++ b/docs/TCF Service - Memory Map.html
@@ -39,10 +39,10 @@
<p>The service provides basic operations to get and set memory mapping on a
target. Command and event parameters are encoded as zero terminated <a
-href='TCF Specification.html#JSON'>JSON</a> strings.</p>
+href='TCF JSON.html'>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>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='Cmds'>Commands</a></h2>
diff --git a/docs/TCF Service - Memory.html b/docs/TCF Service - Memory.html
index 7efa58933..d530c7a4f 100644
--- a/docs/TCF Service - Memory.html
+++ b/docs/TCF Service - Memory.html
@@ -49,10 +49,10 @@
<h2><a name='Overview'>Overview</a></h2>
<p>The service provides basic operations to read/write memory on a target. Command
-and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p>
+and event parameters are encoded as zero terminated <a href='TCF JSON.html'>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>
+see <a href='TCF Error Report Format.html'>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,
diff --git a/docs/TCF Service - Path Map.html b/docs/TCF Service - Path Map.html
index ae604fa15..6a65148df 100644
--- a/docs/TCF Service - Path Map.html
+++ b/docs/TCF Service - Path Map.html
@@ -39,10 +39,10 @@
<p>The service manages file path translation across systems. Command and event
parameters are encoded as zero terminated <a
-href='TCF Specification.html#JSON'>JSON</a> strings.</p>
+href='TCF JSON.html'>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>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='Cmds'>Commands</a></h2>
diff --git a/docs/TCF Service - PortForward.html b/docs/TCF Service - PortForward.html
index 13495276f..6f5d05917 100755
--- a/docs/TCF Service - PortForward.html
+++ b/docs/TCF Service - PortForward.html
@@ -67,9 +67,9 @@
if you want to re-instantiate the connection.<br>
</p>
<p>Command are encoded as zero terminated <a
- href="TCF%20Specification.html#JSON">JSON</a> strings.</p>
+ href='TCF JSON.html'>JSON</a> strings.</p>
<p>The service uses standard format for error reports, see <a
- href="TCF%20Services.html#ErrorFormat">Error Report Format</a>.</p>
+ href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name="Cmds">Commands</a></h2>
<h3><a name="CmdGetConfig">getConfig</a></h3>
<pre><b><font color="#333399" face="Courier New" size="2">
diff --git a/docs/TCF Service - PortServer.html b/docs/TCF Service - PortServer.html
index de7d308b7..32986888d 100755
--- a/docs/TCF Service - PortServer.html
+++ b/docs/TCF Service - PortServer.html
@@ -65,9 +65,9 @@
one connected to through the value-add).<br>
</p>
<p>Command are encoded as zero terminated <a
- href="TCF%20Specification.html#JSON">JSON</a> strings.</p>
+ href='TCF JSON.html'>JSON</a> strings.</p>
<p>The service uses standard format for error reports, see <a
- href="TCF%20Services.html#ErrorFormat">Error Report Format</a>.</p>
+ href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name="Cmds">Commands</a></h2>
<h3><a name="CmdGetConfig">getConfig</a></h3>
<b><font color="#333399" face="Courier New" size="2">
diff --git a/docs/TCF Service - Processes.html b/docs/TCF Service - Processes.html
index d24120e7f..6d97be7a2 100644
--- a/docs/TCF Service - Processes.html
+++ b/docs/TCF Service - Processes.html
@@ -61,10 +61,10 @@ available for client to read/write using <a href='TCF Service - Streams.html'>St
streams is set to "Processes".</p>
<p>Command and event parameters are encoded
-as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p>
+as zero terminated <a href='TCF JSON.html'>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>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='Cmds'>Commands</a></h2>
diff --git a/docs/TCF Service - Profiler.html b/docs/TCF Service - Profiler.html
index 0bc1d0915..a8f9b7462 100644
--- a/docs/TCF Service - Profiler.html
+++ b/docs/TCF Service - Profiler.html
@@ -35,7 +35,7 @@
<p><font color=#FF7000>TBD</font></p>
<p>The service uses standard format for error reports,
-see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='Cmds'>Commands</a></h2>
diff --git a/docs/TCF Service - Registers.html b/docs/TCF Service - Registers.html
index fd298042c..9f5786674 100644
--- a/docs/TCF Service - Registers.html
+++ b/docs/TCF Service - Registers.html
@@ -55,10 +55,10 @@
<h2><a name='Overview'>Overview</a></h2>
<p>The service provides basic operations to read/write CPU and hardware registers. Command
-and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p>
+and event parameters are encoded as zero terminated <a href='TCF JSON.html'>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>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
In addition to commands that can set/get individual register context values, the service defines commands to set/get values at
multiple locations. This allows:
diff --git a/docs/TCF Service - Run Control.html b/docs/TCF Service - Run Control.html
index 84da3dd3c..0b434bc06 100644
--- a/docs/TCF Service - Run Control.html
+++ b/docs/TCF Service - Run Control.html
@@ -55,10 +55,10 @@
<h2><a name='Overview'>Overview</a></h2>
<p>The service provides basic run control operations for execution contexts on a target.
-Command and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p>
+Command and event parameters are encoded as zero terminated <a href='TCF JSON.html'>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>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='Cmds'>Commands</a></h2>
diff --git a/docs/TCF Service - Stack Trace.html b/docs/TCF Service - Stack Trace.html
index 9899d6a79..0ac734324 100755
--- a/docs/TCF Service - Stack Trace.html
+++ b/docs/TCF Service - Stack Trace.html
@@ -48,10 +48,10 @@
<h2><a name='Overview'>Overview</a></h2>
<p>The service implements thread stack back tracing. Command
-and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p>
+and event parameters are encoded as zero terminated <a href='TCF JSON.html'>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>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='Cmds'>Commands</a></h2>
diff --git a/docs/TCF Service - Streams.html b/docs/TCF Service - Streams.html
index ba68da3bf..2ba6445b0 100644
--- a/docs/TCF Service - Streams.html
+++ b/docs/TCF Service - Streams.html
@@ -61,10 +61,10 @@
<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> Command and event parameters are encoded as zero terminated <a href='TCF JSON.html'>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>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='Cmds'>Commands</a></h2>
diff --git a/docs/TCF Service - Symbols.html b/docs/TCF Service - Symbols.html
index cb39f132a..17a81f8b1 100644
--- a/docs/TCF Service - Symbols.html
+++ b/docs/TCF Service - Symbols.html
@@ -35,7 +35,7 @@
<p><font color=#FF7000>TBD</font></p>
<p>The service uses standard format for error reports,
-see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='Cmds'>Commands</a></h2>
diff --git a/docs/TCF Service - System Monitor.html b/docs/TCF Service - System Monitor.html
index 6eeba35bb..8c2eee685 100644
--- a/docs/TCF Service - System Monitor.html
+++ b/docs/TCF Service - System Monitor.html
@@ -49,10 +49,10 @@ and some resource utilization data. The service can be used by a client to provi
similar to Unix 'top' utility or Windows 'Task Manager'.</p>
<p>Command and event parameters are encoded
-as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p>
+as zero terminated <a href='TCF JSON.html'>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>
+see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='Cmds'>Commands</a></h2>
diff --git a/docs/TCF Service - Terminals.html b/docs/TCF Service - Terminals.html
index e2c947a29..6cc860d8c 100644
--- a/docs/TCF Service - Terminals.html
+++ b/docs/TCF Service - Terminals.html
@@ -50,10 +50,10 @@ available for client to read/write using <a href="TCF Service - Streams.html">St
streams is set to "Terminals".</p>
<p>Command and event parameters are encoded
-as zero terminated <a href="TCF Specification.html#JSON">JSON</a> strings.</p>
+as zero terminated <a href='TCF JSON.html'>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>
+see <a href="TCF Error Report Format.html">Error Report Format</a>.</p>
<h2><a name="Cmds">Commands</a></h2>
diff --git a/docs/TCF Services.html b/docs/TCF Services.html
index b51c87fe6..843ef09e2 100644
--- a/docs/TCF Services.html
+++ b/docs/TCF Services.html
@@ -8,15 +8,14 @@
<h1>Target Communication Framework Services</h1>
-<p>Copyright (c) 2007 Wind River Systems, Inc. Made available under the EPL v1.0</p>
+<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/>
+Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p>
<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p>
<h2>Table of Contents</h2>
<ul>
<li><a href='#VersionHistory'>Version History</a></li>
<li><a href='#Overview'>Overview</a></li>
- <li><a href='#Syntax'>Syntax Rules Notation</a></li>
- <li><a href='#ErrorFormat'>Error Report Format</a></li>
<li><a href='#Services'>Services</a></li>
</ul>
@@ -38,11 +37,6 @@
<td>2008-05-06</td>
<td>Approved</td>
</tr>
- <tr>
- <td>1.1</td>
- <td>2008-06-25</td>
- <td>Enhanced error reporting format, see <a href='http://bugs.eclipse.org/bugs/show_bug.cgi?id=232410'>Bug 232410</a></td>
- </tr>
</table>
<h2><a name='Overview'>Overview</a></h2>
@@ -54,149 +48,14 @@ Service definitions are not part of the <a href='TCF Specification.html'>framewo
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.</p>
-<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:&nbsp;<b><i><font face="Courier New" size="2" color="#333399">&lt;token&gt;.
- </font></i></b>Category name can be followed by colon and a text, which explains semantics
- of the category, for example: <b><i><font face="Courier New" size="2" color="#333399">&lt;int:
- error code&gt;</font></i></b> has same meaning as <b><i><font face="Courier New" size="2" color="#333399">&lt;int&gt;</font></i></b>,
- but denotes that the integer number used to indicate an "error code".</li>
-
- <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:</li>
-</ul>
-
-<pre><b><font face="Courier New" size="2" color="#333399">
-<i>&lt;chars&gt;</i>
- &rArr; <i>&lt;char&gt;</i>
- &rArr; <i>&lt;chars&gt; &lt;char&gt;</i>
-</font></b></pre>
-
-<ul type='disc'>
- <li>Spaces are added for readability only and they are not part of the syntax.</li>
-
- <li>All text in the category definition, other than categories and spaces, is UTF-8
- based representation of a message bytes.</li>
-
- <li>The symbol &lsquo;&bull;&rsquo; designates a zero byte.</li>
-</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>&lt;error report&gt;</i>
- &rArr;
- &rArr; null
- &rArr; <i>&lt;object: error description&gt;</i>
-</font></b></pre>
-
-<p>Empty or null error report means success. Error description provides error details, including
-error code and a short, localizable, human readable explanation of the error.</p>
-
-<p>Error description properties are:</p>
-<dl>
- <dt><b><font face="Courier New" size="2" color="#333399">"Code" : <i>&lt;integer&gt;</i></font></b></dt>
- <dd>Error code. Can belong to one of predefined ranges:
- <ul>
- <li> 0x0-0xffff Standard TCF codes, includes a limited subset of POSIX errors, and OTHER error code, which
- can be used together with "AltCode"</li>
- <li> 0x10000-0x1ffff Service specific codes</li>
- <li> 0x20000-0x2ffff Reserved codes - will never be used by the TCF standard</li>
- </ul>
- </dd>
-
- <dt><b><font face="Courier New" size="2" color="#333399">"Time" : <i>&lt;integer&gt;</i></font></b></dt>
- <dd> Error timestamp, in milliseconds since midnight, January 1, 1970 UTC</dd>
-
- <dt><b><font face="Courier New" size="2" color="#333399">"Service" : <i>&lt;string&gt;</i></font></b></dt>
- <dd> Name of the service that reported the error. Required when "Code" is service specific code.</dd>
-
- <dt><b><font face="Courier New" size="2" color="#333399">"Format" : <i>&lt;string&gt;</i></font></b></dt>
- <dd> Error description format supports separation between constant and variable parts
- of error message ("Format" and "Params"). This is done to support localization.
- Format string is expected to allow translation into foreign languages by means of string table lookup.
- The format string syntax is defined in the Java language library
- <b><font face="Courier New" size="2">java.text.MessageFormat</font></b>.
- In order to simplify clients written in other languages, only a subset of the syntax is supported:
- <ul>
- <li> Supported format types: (none), number</li>
- <li> Supported format styles:
- <ul>
- <li> number: (none), "integer", "percent"</li>
- </ul>
- </li>
- </ul>
- </dd>
-
- <dt><b><font face="Courier New" size="2" color="#333399">"Params" : <i>&lt;array&gt;</i></font></b></dt>
- <dd> An array of values to be used together with "Format" to create the error message.</dd>
-
- <dt><b><font face="Courier New" size="2" color="#333399">"Severity" : <i>&lt;integer&gt;</i></font></b></dt>
- <dd> Predefined severity values:
- <ul>
- <li>0 - error (default)</li>
- <li>1 - warning</li>
- <li>2 - fatal</li>
- </ul>
- </dd>
- <dt><b><font face="Courier New" size="2" color="#333399">"AltCode" : <i>&lt;integer&gt;</i></font></b></dt>
- <dd> Alternative error code. This can be used to represent,
- for example, OS, POSIX, or other vendor specific error codes</dd>
-
- <dt><b><font face="Courier New" size="2" color="#333399">"AltOrg" : <i>&lt;string&gt;</i></font></b></dt>
- <dd> ID of organization defining "AltCode", for example "Linux", "VxWorks", "Wind River", etc</dd>
-
- <dt><b><font face="Courier New" size="2" color="#333399">"CausedBy" : <i>&lt;object: error description&gt;</i></font></b></dt>
- <dd> A nested error description. Can be used to describe a root cause of this error.</dd>
-</dl>
-
-<p>All fields except "Code" are optional.</p>
-
-<p>Standard error codes:</p>
-<pre><code>
- OTHER = 1
- JSON_SYNTAX = 2
- PROTOCOL = 3
- BUFFER_OVERFLOW = 4
- CHANNEL_CLOSED = 5
- COMMAND_CANCELLED = 6
- UNKNOWN_PEER = 7
- BASE64 = 8
- EOF = 9
- ALREADY_STOPPED = 10
- ALREADY_EXITED = 11
- ALREADY_RUNNING = 12
- ALREADY_ATTACHED = 13
- IS_RUNNING = 14
- INV_DATA_SIZE = 15
- INV_CONTEXT = 16
- INV_ADDRESS = 17
- INV_EXPRESSION = 18
- INV_FORMAT = 19
- INV_NUMBER = 20
- INV_DWARF = 21
- SYM_NOT_FOUND = 22
- UNSUPPORTED = 23
- INV_DATA_TYPE = 24
- INV_COMMAND = 25
-</code></pre>
+<p>Format of the protocol messages is defined by syntax rules, see
+<a href='TCF Syntax Rules Notation.html'>Syntax Rules Notation</a>.</p>
-<p>Service specific error code definitions, if any, are part of service specfications.
-Standard and service specific error codes can be extended over time. A
-client that does not recognize a specific error code should treat it in the
-same way as "OTHER".</p>
+<p>TCF standard services use JSON for message encoding, see
+<a href='TCF JSON.html'>JSON - Preferred Marshaling</a>.</p>
-<p>For encoding of <b><i><font face="Courier New" size="2" color="#333399">&lt;object&gt;</font></i></b>,
-<b><i><font face="Courier New" size="2" color="#333399">&lt;string&gt;</font></i></b>, etc., see
-<a href='TCF Specification.html#JSON'>JSON - Preferred Marshaling</a>.</p>
+<p>TCF standard services use same format for error reporting, see
+<a href='TCF Error Report Format.html'>Error Report Format</a>.</p>
<h2><a name='Services'>Services</h2>
<ul>
@@ -209,7 +68,7 @@ same way as "OTHER".</p>
<li><a href='TCF Service - Expressions.html'>Expressions Service</a></li>
<li><a href='TCF Service - File System.html'>File System Service</a></li>
<li><a href='TCF Service - Line Numbers.html'>Line Numbers Service</a></li>
- <li><a href='TCF Specification.html#Locator'>Locator Service</a></li>
+ <li><a href='TCF Service - Locator.html'>Locator Service</a></li>
<li><a href='TCF Service - Memory.html'>Memory Service</a></li>
<li><a href='TCF Service - Memory Map.html'>Memory Map Service</a></li>
<li><a href='TCF Service - Path Map.html'>Path Map Service</a></li>
diff --git a/docs/TCF Specification.html b/docs/TCF Specification.html
index b1fac7593..6306f54db 100644
--- a/docs/TCF Specification.html
+++ b/docs/TCF Specification.html
@@ -7,8 +7,9 @@
<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="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list
+<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/>
+Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p>
+<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p>
<h1>Table of Contents</h1>
@@ -19,7 +20,6 @@
<li><a href='#Goals'>Goals</a>
<li><a href='#Definitions'>Definitions</a>
<li><a href='#Requirements'>Requirements</a>
- <li><a href='#Syntax'>Syntax Rules Notation</a>
</ul>
<li><a href='#Design'>Framework Software Design Considerations</a>
<ul>
@@ -38,16 +38,7 @@
</ul>
<li><a href='#API'>API</a>
<li><a href='#JSON'>JSON - Preferred Marshaling</a>
- <ul>
- <li><a href='#JSONExamples'>JSON - Examples</a>
- </ul>
<li><a href='#Locator'>Locator Service</a>
- <ul>
- <li><a href='#LocatorPeer'>Peer Attributes</a>
- <li><a href='#LocatorCommands'>Locator Service Commands</a>
- <li><a href='#LocatorEvents'>Locator Service Events</a>
- <li><a href='#LocatorAPI'>Locator Service API</a>
- </ul>
</ul>
<h2><a name='VersionHistory'>Version History</a></h2>
@@ -212,36 +203,9 @@ them about state changes.
<li>Events can be broadcasted at any time, i.e. no polling should be required.
<li>The protocol should support a standard mechanism of sending data larger than MTU.
-</ul>
-
-<h2><a name='Syntax'>Syntax Rules Notation</a></h2>
-<p>The protocol message format is defined by syntax rules. The 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>&lt;token&gt;.
- </font></i></b>Category name can be followed by colon and a text, which explains the semantics
- of the category, for example: <b><i><font face="Courier New" size=2 color=#333399>&lt;int:
- error code&gt;</font></i></b> has same meaning as <b><i><font face="Courier New" size=2 color=#333399>&lt;int&gt;</font></i></b>,
- but denotes that the integer number is used to indicate an &ldquo;error code&rdquo;.
-
- <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:
- <pre><b><font face="Courier New" size=2 color=#333399>
- <i>&lt;chars&gt;</i>
- &rArr; <i>&lt;char&gt;</i>
- &rArr; <i>&lt;chars&gt; &lt;char&gt;</i>
- </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 message bytes.
-
- <li>The symbol &lsquo;&bull;&rsquo; designates a zero byte.
+ <li>Format of the protocol messages is defined by syntax rules, see
+ <a href='TCF Syntax Rules Notation.html'>Syntax Rules Notation</a>.
</ul>
<h1><a name='Design'>Framework Software Design Considerations</a></h1>
@@ -1109,493 +1073,12 @@ Receive: R 3 &ldquo;Already suspended&rdquo;
<p>The TCF message data format is service specific. Since service specifications are
separate from the 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 using <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>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>
- </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>&lt;object&gt;</i>
- &rArr; {}
- &rArr; { <i>&lt;members&gt;</i> }
-
-<i>&lt;members&gt;</i>
- &rArr; <i>&lt;string&gt;</i> : <i>&lt;value&gt;</i>
- &rArr; <i>&lt;members&gt;</i> , <i>&lt;string&gt;</i> : <i>&lt;value&gt;</i>
-
-<i>&lt;array&gt;</i>
- &rArr; []
- &rArr; [ <i>&lt;elements&gt;</i> ]
-
-<i>&lt;elements&gt;</i>
- &rArr; <i>&lt;value&gt;</i>
- &rArr; <i>&lt;elements</i>&gt; , <i>&lt;value&gt;</i>
-
-<i>&lt;value&gt;</i>
- &rArr; <i>&lt;string&gt;</i>
- &rArr; <i>&lt;number&gt;</i>
- &rArr; <i>&lt;object&gt;</i>
- &rArr; <i>&lt;array&gt;</i>
- &rArr; <i>&lt;boolean&gt;</i>
- &rArr; null
-
-<i>&lt;boolean&gt;</i>
- &rArr; true
- &rArr; false
-
-<i>&lt;string&gt;</i>
- &rArr; ""
- &rArr; " <i>&lt;chars&gt;</i> "
-
-<i>&lt;chars&gt;</i>
- &rArr; <i>&lt;char&gt;</i>
- &rArr; <i>&lt;chars&gt; &lt;char&gt;</i>
-
-<i>&lt;char</i>&gt;
- &rArr; <i>&lt;any Unicode except " or \ or control&gt;</i>
- &rArr; \"<i></i>
- &rArr; \\<i></i>
- &rArr; \/<i></i>
- &rArr; \b<i></i>
- &rArr; \f<i></i>
- &rArr; \n<i></i>
- &rArr; \r<i></i>
- &rArr; \t<i></i>
- &rArr; \u <i>&lt;four-hex-digits&gt;</i>
-
-<i>&lt;number</i>&gt;
- &rArr; <i>&lt;int&gt;</i>
- &rArr; &lt;<i>int&gt; &lt;fraction&gt;</i>
- &rArr; &lt;<i>int&gt; &lt;exponent&gt;</i>
- &rArr; &lt;<i>int&gt; &lt;fraction&gt; &lt;exponent&gt;</i>
-
-<i>&lt;int&gt;</i>
- &rArr; <i>&lt;digit&gt;</i>
- &rArr; &lt;<i>digit 1-9&gt; &lt;digits&gt;</i>
- &rArr; - &lt;<i>digit&gt;</i>
- &rArr; - &lt;<i>digit 1-9&gt; &lt;digits</i>&gt;
-
-<i>&lt;fraction&gt;</i>
- &rArr; . <i>&lt;digits&gt;</i>
-
-<i>&lt;exponent&gt;</i>
- &rArr; <i>&lt;e&gt;</i> <i>&lt;digits&gt;</i>
-
-<i>&lt;digits&gt;</i>
- &rArr; <i>&lt;digit&gt;</i>
- &rArr; &lt;<i>digits&gt;</i> &lt;<i>digit&gt;</i>
-
-<i>&lt;e&gt;</i>
- &rArr; e
- &rArr; e+
- &rArr; e-
- &rArr; E
- &rArr; E+
- &rArr; E-
-
-</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>
- [
- {
- "Precision": "zip",
- "Latitude": 37.7668,
- "Longitude": -122.3959,
- "City": "SAN FRANCISCO",
- "State": "CA",
- "Zip": "94107",
- "Country": "US"
- },
- {
- "Precision": "zip",
- "Latitude": 37.371991,
- "Longitude": -122.026020,
- "City": "SUNNYVALE",
- "State": "CA",
- "Zip": "94085",
- "Country": "US"
- }
- ]
-</pre>
+simplify service design and implementation, we recommend using <a href='TCF JSON.html'>JSON</a> for data formatting.</p>
<h1><a name='Locator'>Locator Service</a></h1>
<p>The Locator service uses the transport layer to search for peers and to collect data about
-the peer's attributes and capabilities (services). The discovery mechanism depends on the transport
-protocol and is part of that protocol handler. Targets, known by other hosts, are
-added to local list of peers. <font color=red>Security? </font>Automatically discovered
-targets require no further configuration. Additional targets can be configured manually.</p>
-
-<p>All TCF peers must implement Locator service. The implementation is part of the framework itself.
-It is the only required service, all other services are optional and, formally, not part of the framework.</p>
-
-<h2><a name='LocatorPeer'>Peer Attributes</a></h2>
-
-<p><i>&lt;object: peer data&gt;</i> is collection of peer attributes. It should, at least, contain member
-<b><font face="Courier New" size=2 color=#333399>"ID" : <i>&lt;string&gt;</i></font></b>.
-It can also contain a number of components describing peer properties and capabilities.
-Predefined attributes are:</p>
-
-<ul>
- <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i>&lt;string&gt;</i></font></b></code>
- - unique ID of the peer.
-
- <li><code><b><font face="Courier New" size=2 color=#333399>"ServiceManagerID" : <i>&lt;string&gt;</i></font></b></code>
- - unique ID of service manager that is represented by this peer.
-
- <li><code><b><font face="Courier New" size=2 color=#333399>"AgentID" : <i>&lt;string&gt;</i></font></b></code>
- - agent unique ID.
-
- <li><code><b><font face="Courier New" size=2 color=#333399>"Name" : <i>&lt;string&gt;</i></font></b></code>
- - human readable peer name.
-
- <li><code><b><font face="Courier New" size=2 color=#333399>"OSName" : <i>&lt;string&gt;</i></font></b></code>
- - peer OS name, if applicable.
-
- <li><code><b><font face="Courier New" size=2 color=#333399>"TransportName" : <i>&lt;string&gt;</i></font></b></code>
- - name of a trasport protocol to use to connect to this peer, for example: TCP.
-
- <li><code><b><font face="Courier New" size=2 color=#333399>"Host" : <i>&lt;string&gt;</i></font></b></code>
- - peer host name, if transport is TCP or UDP.
-
- <li><code><b><font face="Courier New" size=2 color=#333399>"Aliases" : <i>&lt;string&gt;</i></font></b></code>
- - peer host name aliases, if transport is TCP or UDP.
-
- <li><code><b><font face="Courier New" size=2 color=#333399>"Addresses" : <i>&lt;string&gt;</i></font></b></code>
- - peer IP addresses, if transport is TCP or UDP.
-
- <li><code><b><font face="Courier New" size=2 color=#333399>"Port" : <i>&lt;string&gt;</i></font></b></code>
- - peer port number, if transport is TCP or UDP.
-</ul>
-
-<p>Most clients do not need to know any peer attributes other than ID and Name. Clients are expected to call the IPeer.openChannel()
-method and let the framework check peer attributes and create appropriate communication channel that is best suited for
-communication with the peer. After a channel is established, a client can learn the peer capabilities by looking
-at what services it implements (use IChannel.getRemoteServices() method to get a map of services).</p>
-
-<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 &bull; <i>&lt;token&gt;</i> &bull; Locator &bull; redirect &bull; <i>&lt;peer&gt;</i> &bull;
-
-<i>&lt;peer&gt;</i>
- &rArr; <i>&lt;string: peer ID&gt;</i>
- &rArr; <i>&lt;object: peer data&gt;</i>
-</font></b></pre>
-
-<p>The command redirects the channel to become connected to the given peer.
-The Locator service starts acting as a proxy.</p>
-
-<p>Reply:</p>
-
-<pre><b><font face="Courier New" size=2 color=#333399>
-R &bull; <i>&lt;token&gt;</i> &bull; <i>&lt;error report&gt;</i> &bull;
-</font></b></pre>
-
-<h3><a name='LocatorCommandSync'>sync</a></h3>
-
-<pre><b><font face="Courier New" size=2 color=#333399>
-C &bull; <i>&lt;token&gt;</i> &bull; Locator &bull; sync &bull;
-</font></b></pre>
-
-<p>The sync command does nothing and simply returns back an empty result. The command is used for
-cross channel synchronization. Since commands are executed in order they were issued, by waiting
-for sync result a client makes sure that all commands, that were issued before sync, are fully processed.</p>
-
-<p>Reply:</p>
-
-<pre><b><font face="Courier New" size=2 color=#333399>
-R &bull; <i>&lt;token&gt;</i> &bull;
-</font></b></pre>
-
-<h2><a name='LocatorEvents'>Locator Service Events</a></h2>
-
-<pre><b><font face="Courier New" size=2 color=#333399>
-E &bull; Locator &bull; Hello &bull; <i>&lt;array: service names&gt;</i> &bull;
-E &bull; Locator &bull; peerAdded &bull; <i>&lt;object: peer data&gt;</i> &bull;
-E &bull; Locator &bull; peerChanged &bull; <i>&lt;object: peer data&gt;</i> &bull;
-E &bull; Locator &bull; peerRemoved &bull; <i>&lt;string: peer ID&gt;</i> &bull;
-E &bull; Locator &bull; peerHeartBeat &bull; <i>&lt;string: peer ID&gt;</i> &bull;
-</font></b></pre>
-
-<dl>
- <dt><b>Hello</b>
- <dd>is the first message sent by the framework after establishing a communication channel.
- The message lets other side of the channel know capabilities of this peer.
- Message data consists of an array of service names that are provided by the peer.
- The service name list is a complete and unambiguous declaration of peer's capabilities.
- To avoid ambiguity, different services (even slightly different, like versions of same service)
- must have different names. Framework delays all other communications between peers until exchange
- of Hello messages is complete.
- <dt><b>peerAdded</b>
- <dd>is sent when the service discovers a new peer.
- <dt><b>peerChanged</b>
- <dd>is sent when peer attributes change.
- <dt><b>peerRemoved</b>
- <dd>is sent when the service deletes information about a peer.
- <dt><b>peerHeartBeat</b>
- <dd>is sent periodically when the service receives a communication from the peer
- that confirms that the peer is still alive.
-</dl>
-
-<h2><a name='LocatorAPI'>Locator Service API</a></h2>
-
-<pre>
-<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().
- */</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
- * target depending on services it implements.
- * List of currently known peers can be retrieved by
- * calling ILocator.getPeers()
- *
- * A TCF agent houses one or more service managers. A service manager has a one or more
- * services to expose to the world. The service manager creates one or more peers
- * to represent itself, one for every access path the agent is
- * reachable by. For example, in agents accessible via TCP/IP, the
- * service manger would create a peer for every subnet it wants to participate in.
- * All peers of particular service manager represent identical sets of services.
- *
- * @noimplement This interface is not intended to be implemented by clients.
- * Client can extends the abstract IPeer implementation: AbstractPeer.
- */</font>
-<font color=#7F0055>public interface</font> IPeer {
-
- <font color=#3F5FBF>/**
- * Peer property names. Implementation can define additional properties.
- */</font>
- <font color=#7F0055>static final</font> String
- <font color=#3F5FBF>/** Peer unique ID */</font>
- <i><font color=#0000C0>ATTR_ID</font></i> = <font color=#2A00FF>"ID"</font>,
-
- <font color=#3F5FBF>/** Unique ID of service manager that is represented by this peer */</font>
- <i><font color=#0000C0>ATTR_SERVICE_MANGER_ID</font></i> = <font color=#2A00FF>"ServiceManagerID"</font>,
-
- <font color=#3F5FBF>/** Agent unique ID */</font>
- <i><font color=#0000C0>ATTR_AGENT_ID</font></i> = <font color=#2A00FF>"AgentID"</font>,
-
- <font color=#3F5FBF>/** Peer name */</font>
- <i><font color=#0000C0>ATTR_NAME</font></i> = <font color=#2A00FF>"Name"</font>,
-
- <font color=#3F5FBF>/** Name of the peer operating system */</font>
- <i><font color=#0000C0>ATTR_OS_NAME</font></i> = <font color=#2A00FF>"OSName"</font>,
-
- <font color=#3F5FBF>/** Transport name, for example TCP, SSL */</font>
- <i><font color=#0000C0>ATTR_TRANSPORT_NAME</font></i> = <font color=#2A00FF>"TransportName"</font>,
-
- <font color=#3F5FBF>/** If present, indicates that the peer can forward traffic to other peers */</font>
- <i><font color=#0000C0>ATTR_PROXY</font></i> = <font color=#2A00FF>"Proxy"</font>,
-
- <font color=#3F5FBF>/** Host DNS name or IP address */</font>
- <i><font color=#0000C0>ATTR_IP_HOST</font></i> = <font color=#2A00FF>"Host"</font>,
-
- <font color=#3F5FBF>/** Optional list of host aliases */</font>
- <i><font color=#0000C0>ATTR_IP_ALIASES</font></i> = <font color=#2A00FF>"Aliases"</font>,
-
- <font color=#3F5FBF>/** Optional list of host addresses */</font>
- <i><font color=#0000C0>ATTR_IP_ADDRESSES</font></i> = <font color=#2A00FF>"Addresses"</font>,
-
- <font color=#3F5FBF>/** IP port number, must be decimal number */</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&lt;String, String&gt; 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> service manager unique ID, same as getAttributes().get(ATTR_SERVICE_MANAGER_ID)
- */</font>
- String getServiceManagerID();
-
- <font color=#3F5FBF>/**
- * <font color=#7F9FBF>@return</font> agent unique ID, same as getAttributes().get(ATTR_AGENT_ID)
- */</font>
- String getAgentID();
-
- <font color=#3F5FBF>/**
- * <font color=#7F9FBF>@return</font> peer name, same as getAttributes().get(ATTR_NAME)
- */</font>
- String getName();
-
- <font color=#3F5FBF>/**
- * <font color=#7F9FBF>@return</font> agent OS name, same as getAttributes().get(ATTR_OS_NAME)
- */</font>
- String getOSName();
-
- <font color=#3F5FBF>/**
- * <font color=#7F9FBF>@return</font> transport name, 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.
- * It's state is IChannel.STATE_OPENNING.
- * Protocol.Listener will be called when the channel will be opened or closed.
- */</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
- * peers attributes and capabilities (services). Discovery mechanism depends on transport protocol
- * and is part of that protocol handler. Targets, known to other hosts, can be found through
- * remote instances of ILocator service. 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 list 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>
- <font color=#7F0055>static final int</font>
- <i><font color=#0000C0>CONF_REQ_INFO</font></i> = 1,
- <i><font color=#0000C0>CONF_PEER_INFO</font></i> = 2,
- <i><font color=#0000C0>CONF_REQ_SLAVES</font></i> = 3,
- <i><font color=#0000C0>CONF_SLAVES_INFO</font></i> = 4;
-
- <font color=#3F5FBF>/**
- * <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&lt;String,IPeer&gt; getPeers();
-
- <font color=#3F5FBF>/**
- * Redirect this service channel to given peer using this service as a proxy.
- * @param peer_id - Peer ID.
- */</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
- * 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);
- }
-
- <font color=#3F5FBF>/**
- * 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=#3F5FBF>/**
- * A new peer is added into locator peer table.
- * @param peer
- */</font>
- <font color=#7F0055>void</font> peerAdded(IPeer peer);
-
- <font color=#3F5FBF>/**
- * Peer attributes have changed.
- * @param peer
- */</font>
- <font color=#7F0055>void</font> peerChanged(IPeer peer);
-
- <font color=#3F5FBF>/**
- * A peer is removed from locator peer table.
- * @param id - peer ID
- */</font>
- <font color=#7F0055>void</font> peerRemoved(String id);
-
- <font color=#3F5FBF>/**
- * Peer heart beat detected.
- * @param id - peer ID
- */</font>
- <font color=#7F0055>void</font> peerHeartBeat(String id);
- }
-}
-</pre>
+the peer's attributes and capabilities (services), see <a href='TCF Service - Locator.html'>Locator Service</a>.</p>
</body>
</html>
diff --git a/docs/TCF Syntax Rules Notation.html b/docs/TCF Syntax Rules Notation.html
new file mode 100644
index 000000000..b2b72f7c9
--- /dev/null
+++ b/docs/TCF Syntax Rules Notation.html
@@ -0,0 +1,75 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <title>Syntax Rules Notation</title>
+</head>
+
+<body lang='EN-US'>
+
+<h1>Syntax Rules Notation</h1>
+
+<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/>
+Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p>
+<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p>
+
+<h2>Table of Contents</h2>
+<ul>
+ <li><a href='#VersionHistory'>Version History</a></li>
+ <li><a href='#Syntax'>Syntax Rules Notation</a></li>
+</ul>
+
+<h2><a name='VersionHistory'>Version History</a></h2>
+
+<table border=1 cellpadding=8>
+ <tr>
+ <th>Version</th>
+ <th>Date</th>
+ <th>Change</th>
+ </tr>
+ <tr>
+ <td>0.1</td>
+ <td>2008-01-10</td>
+ <td>Initial contribution</td>
+ </tr>
+ <tr>
+ <td>1.0</td>
+ <td>2008-05-06</td>
+ <td>Approved</td>
+ </tr>
+</table>
+
+<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:&nbsp;<b><i><font face="Courier New" size="2" color="#333399">&lt;token&gt;.
+ </font></i></b>Category name can be followed by colon and a text, which explains semantics
+ of the category, for example: <b><i><font face="Courier New" size="2" color="#333399">&lt;int:
+ error code&gt;</font></i></b> has same meaning as <b><i><font face="Courier New" size="2" color="#333399">&lt;int&gt;</font></i></b>,
+ but denotes that the integer number used to indicate an "error code".</li>
+
+ <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:</li>
+</ul>
+
+<pre><b><font face="Courier New" size="2" color="#333399">
+<i>&lt;chars&gt;</i>
+ &rArr; <i>&lt;char&gt;</i>
+ &rArr; <i>&lt;chars&gt; &lt;char&gt;</i>
+</font></b></pre>
+
+<ul type='disc'>
+ <li>Spaces are added for readability only and they are not part of the syntax.</li>
+
+ <li>All text in the category definition, other than categories and spaces, is UTF-8
+ based representation of a message bytes.</li>
+
+ <li>The symbol &lsquo;&bull;&rsquo; designates a zero byte.</li>
+</ul>
+
+</body>
+</html>
diff --git a/docs/index.html b/docs/index.html
index 4c924d1d9..a74430768 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -6,8 +6,8 @@
<body>
<h1>Target Communication Framework</h1>
-<p>Copyright (c) 2007, 2008 Wind River Systems, Inc. and others. Made available under the EPL v1.0
-(Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license).</p>
+<p>Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL v1.0<br/>
+Agent portion made available under your choice of EPL v1.0 or EDL v1.0 dual-license.</p>
<p>Direct comments, questions to the <a href="https://dev.eclipse.org/mailman/listinfo/tcf-dev">tcf-dev@eclipse.org</a> mailing list</p>
<h2>Available Documentation</h2>
diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/ILocator.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/ILocator.java
index fd68c2152..b979b1821 100644
--- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/ILocator.java
+++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/ILocator.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2007, 2013 Wind River Systems, Inc. and others.
+ * Copyright (c) 2007-2019 Wind River Systems, Inc. and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
@@ -102,7 +102,7 @@ public interface ILocator extends IService {
/**
* Get agent ID of the agent providing the locator service.
- * <p>
+ *
* The agent ID can be used to identify the agent among all the peers
* returned by {@link #getPeers()}.
*/

Back to the top