|
70
|
1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
|
2 |
<html>
|
|
|
3 |
<head>
|
|
|
4 |
<title>Target Communication Framework Services</title>
|
|
|
5 |
</head>
|
|
|
6 |
|
|
|
7 |
<body lang='EN-US'>
|
|
|
8 |
|
|
|
9 |
<h1>Target Communication Framework Services</h1>
|
|
|
10 |
|
|
|
11 |
<p>Copyright (c) 2007 Wind River Systems, Inc. Made available under the EPL v1.0
|
|
|
12 |
<p>Direct comments, questions to the <a href="mailto:dsdp-tcf-dev@eclipse.org">dsdp-tcf-dev@eclipse.org</a> mailing list
|
|
|
13 |
|
|
|
14 |
<h2>Table of Contents</h2>
|
|
|
15 |
<ul>
|
|
|
16 |
<li><a href='#VersionHistory'>Version History</a>
|
|
|
17 |
<li><a href='#Overview'>Overview</a>
|
|
|
18 |
<li><a href='#Syntax'>Syntax Rules Notation</a>
|
|
|
19 |
<li><a href='#ErrorFormat'>Error Report Format</a>
|
|
|
20 |
<li><a href='#Services'>Services</a>
|
|
|
21 |
</ul>
|
|
|
22 |
|
|
|
23 |
<h2><a name='VersionHistory'>Version History</a></h2>
|
|
|
24 |
|
|
|
25 |
<table border=1 cellpadding=8>
|
|
|
26 |
<tr>
|
|
|
27 |
<th>Version
|
|
|
28 |
<th>Date
|
|
|
29 |
<th>Change
|
|
|
30 |
<tr>
|
|
|
31 |
<td>0.1
|
|
|
32 |
<td>2008-01-10
|
|
|
33 |
<td>Initial contribution
|
|
|
34 |
<tr>
|
|
|
35 |
<td>1.0
|
|
|
36 |
<td>2008-05-06
|
|
|
37 |
<td>Approved
|
|
|
38 |
<tr>
|
|
|
39 |
<td>1.1
|
|
|
40 |
<td>2008-06-25
|
|
|
41 |
<td>Enhanced error reporting format, see <a href='http://bugs.eclipse.org/bugs/show_bug.cgi?id=232410'>Bug 232410</a>
|
|
|
42 |
</table>
|
|
|
43 |
|
|
|
44 |
<h2><a name='Overview'>Overview</a></h2>
|
|
|
45 |
|
|
|
46 |
TCF communication model is based on the idea of services. A service is a group of related commands, events and semantics.
|
|
|
47 |
For example, <a href='TCF Service - Memory.html'>Memory Service</a> defines group of command and events for
|
|
|
48 |
reading and writing target memory.
|
|
|
49 |
Service definitions are not part of the <a href='TCF Specification.html'>framework specification</a>, and new services
|
|
|
50 |
are expected to be defined by developers of tools and target agents.
|
|
|
51 |
Defenitions of standard services are provided to achieve certain level of compatibility between tools and targets.
|
|
|
52 |
|
|
|
53 |
<h2><a name='Syntax'>Syntax Rules Notation</a></h2>
|
|
|
54 |
|
|
|
55 |
<p>Format of the protocol messages is defined by syntax rules. Syntax is described
|
|
|
56 |
using a simple variant of Backus-Naur Form. In particular:</p>
|
|
|
57 |
|
|
|
58 |
<ul type='disc'>
|
|
|
59 |
<li>Italic lower case words in a courier font, enclosed into angular brackets, are
|
|
|
60 |
used to denote syntactic categories, for example: <b><i><font face="Courier New" size=2 color=#333399><token>.
|
|
|
61 |
</font></i></b>Category name can be followed by colon and a text, which explains semantics
|
|
|
62 |
of the category, for example: <b><i><font face="Courier New" size=2 color=#333399><int:
|
|
|
63 |
error code></font></i></b> has same meaning as <b><i><font face="Courier New" size=2 color=#333399><int></font></i></b>,
|
|
|
64 |
but denotes that the integer number used to indicate an "error code".
|
|
|
65 |
|
|
|
66 |
<li>A syntax rule consists of a category designation followed by one or more syntax
|
|
|
67 |
definitions for the category. The category name and each definition are placed on
|
|
|
68 |
separate lines, bullets are used to denote definitions, for example:
|
|
|
69 |
</ul>
|
|
|
70 |
|
|
|
71 |
<pre><b><font face="Courier New" size=2 color=#333399>
|
|
|
72 |
<i><chars></i>
|
|
|
73 |
⇒ <i><char></i>
|
|
|
74 |
⇒ <i><chars> <char></i>
|
|
|
75 |
</font></b></pre>
|
|
|
76 |
|
|
|
77 |
<ul type='disc'>
|
|
|
78 |
<li>Spaces are added for readability only and they are not part of the syntax.
|
|
|
79 |
|
|
|
80 |
<li>All text in the category definition, other than categories and spaces, is UTF-8
|
|
|
81 |
based representation of a message bytes.
|
|
|
82 |
|
|
|
83 |
<li>The symbol ‘•’ designates a zero byte.
|
|
|
84 |
</ul>
|
|
|
85 |
|
|
|
86 |
<h2><a name='ErrorFormat'>Error Report Format</a></h2>
|
|
|
87 |
|
|
|
88 |
<p>Most of TCF standard services use same format for error reporting:</p>
|
|
|
89 |
|
|
|
90 |
<pre><b><font face="Courier New" size=2 color=#333399>
|
|
|
91 |
<i><error report></i>
|
|
|
92 |
⇒
|
|
|
93 |
⇒ null
|
|
|
94 |
⇒ <i><object: error description></i>
|
|
|
95 |
</font></b></pre>
|
|
|
96 |
|
|
|
97 |
<p>Empty or null error report means success. Error description provides error details, including
|
|
|
98 |
error code and a short, localizable, human readable explanation of the error.</p>
|
|
|
99 |
|
|
|
100 |
<p>Error description properties are:</p>
|
|
|
101 |
<dl>
|
|
|
102 |
<dt><b><font face="Courier New" size=2 color=#333399>"Code" : <i><integer></i></font></b>
|
|
|
103 |
<dd>Error code. Can belong to one of predefined ranges:
|
|
|
104 |
<ul>
|
|
|
105 |
<li> 0x0-0xffff Standard TCF codes, includes a limited subset of POSIX errors, and OTHER error code, which
|
|
|
106 |
can be used together with "AltCode"
|
|
|
107 |
<li> 0x10000-0x1ffff Service specific codes
|
|
|
108 |
<li> 0x20000-0x2ffff Reserved codes - will never be used by the TCF standard
|
|
|
109 |
</ul>
|
|
|
110 |
|
|
|
111 |
<dt><b><font face="Courier New" size=2 color=#333399>"Time" : <i><integer></i></font></b>
|
|
|
112 |
<dd> Error timestamp, in milliseconds since midnight, January 1, 1970 UTC
|
|
|
113 |
|
|
|
114 |
<dt><b><font face="Courier New" size=2 color=#333399>"Service" : <i><string></i></font></b>
|
|
|
115 |
<dd> Name of the service that reported the error. Required when "Code" is service specific code.
|
|
|
116 |
|
|
|
117 |
<dt><b><font face="Courier New" size=2 color=#333399>"Format" : <i><string></i></font></b>
|
|
|
118 |
<dd> Error description format supports separation between constant and variable parts
|
|
|
119 |
of error message ("Format" and "Params"). This is done to support localization.
|
|
|
120 |
Format string is expected to allow translation into foreign languages by means of string table lookup.
|
|
|
121 |
The format string syntax is defined in the Java language library
|
|
|
122 |
<b><font face="Courier New" size=2>java.text.MessageFormat</font></b>.
|
|
|
123 |
In order to simplify clients written in other languages, only a subset of the syntax is supported:
|
|
|
124 |
<ul>
|
|
|
125 |
<li> Supported format types: (none), number
|
|
|
126 |
<li> Supported format styles:
|
|
|
127 |
<ul>
|
|
|
128 |
<li> number: (none), "integer", "percent"
|
|
|
129 |
</ul>
|
|
|
130 |
</ul>
|
|
|
131 |
|
|
|
132 |
<dt><b><font face="Courier New" size=2 color=#333399>"Params" : <i><array></i></font></b>
|
|
|
133 |
<dd> An array of values to be used together with "Format" to create the error message.
|
|
|
134 |
|
|
|
135 |
<dt><b><font face="Courier New" size=2 color=#333399>"Severity" : <i><integer></i></font></b>
|
|
|
136 |
<dd> Predefined severity values:
|
|
|
137 |
<ul>
|
|
|
138 |
<li>0 - error (default)
|
|
|
139 |
<li>1 - warning
|
|
|
140 |
<li>2 - fatal
|
|
|
141 |
</ul>
|
|
|
142 |
|
|
|
143 |
<dt><b><font face="Courier New" size=2 color=#333399>"AltCode" : <i><integer></i></font></b>
|
|
|
144 |
<dd> Alternative error code. This can be used to represent,
|
|
|
145 |
for example, OS, POSIX, or other vendor specific error codes
|
|
|
146 |
|
|
|
147 |
<dt><b><font face="Courier New" size=2 color=#333399>"AltOrg" : <i><string></i></font></b>
|
|
|
148 |
<dd> ID of organization defining "AltCode", for example "Linux", "VxWorks", "Wind River", etc
|
|
|
149 |
|
|
|
150 |
<dt><b><font face="Courier New" size=2 color=#333399>"CausedBy" : <i><object: error description></i></font></b>
|
|
|
151 |
<dd> A nested error description. Can be used to describe a root cause of this error.
|
|
|
152 |
</dl>
|
|
|
153 |
|
|
|
154 |
<p>All fields except "Code" are optional.</p>
|
|
|
155 |
|
|
|
156 |
<p>Standard error codes:
|
|
|
157 |
<pre><code>
|
|
|
158 |
OTHER = 1
|
|
|
159 |
JSON_SYNTAX = 2
|
|
|
160 |
PROTOCOL = 3
|
|
|
161 |
BUFFER_OVERFLOW = 4
|
|
|
162 |
CHANNEL_CLOSED = 5
|
|
|
163 |
COMMAND_CANCELLED = 6
|
|
|
164 |
UNKNOWN_PEER = 7
|
|
|
165 |
BASE64 = 8
|
|
|
166 |
EOF = 9
|
|
|
167 |
ALREADY_STOPPED = 10
|
|
|
168 |
ALREADY_EXITED = 11
|
|
|
169 |
ALREADY_RUNNING = 12
|
|
|
170 |
ALREADY_ATTACHED = 13
|
|
|
171 |
IS_RUNNING = 14
|
|
|
172 |
INV_DATA_SIZE = 15
|
|
|
173 |
INV_CONTEXT = 16
|
|
|
174 |
INV_ADDRESS = 17
|
|
|
175 |
INV_EXPRESSION = 18
|
|
|
176 |
INV_FORMAT = 19
|
|
|
177 |
INV_NUMBER = 20
|
|
|
178 |
INV_DWARF = 21
|
|
|
179 |
SYM_NOT_FOUND = 22
|
|
|
180 |
UNSUPPORTED = 23
|
|
|
181 |
</code></pre>
|
|
|
182 |
</p>
|
|
|
183 |
|
|
|
184 |
<p>Service specific error code definitions, if any, are part of service specfications.
|
|
|
185 |
Standard and service specific error codes can be extended over time. A
|
|
|
186 |
client that does not recognize a specific error code should treat it in the
|
|
|
187 |
same way as "OTHER".</p>
|
|
|
188 |
|
|
|
189 |
<p>For encoding of <b><i><font face="Courier New" size=2 color=#333399><object></font></i></b>,
|
|
|
190 |
<b><i><font face="Courier New" size=2 color=#333399><string></font></i></b>, etc., see
|
|
|
191 |
<a href='TCF Specification.html#JSON'>JSON - Preferred Marshaling</a>.
|
|
|
192 |
|
|
|
193 |
<h2><a name='Services'>Services</h2>
|
|
|
194 |
<ul>
|
|
|
195 |
<li><a href='TCF Service - Memory.html'>Memory Service</a>
|
|
|
196 |
<li><a href='TCF Service - Processes.html'>Processes Service</a>
|
|
|
197 |
<li><a href='TCF Service - Run Control.html'>Run Control Service</a>
|
|
|
198 |
<li><a href='TCF Service - Registers.html'>Registers Service</a>
|
|
|
199 |
<li><a href='TCF Service - Stack Trace.html'>Stack Trace Service</a>
|
|
|
200 |
<li><a href='TCF Service - Breakpoints.html'>Breakpoints Service</a>
|
|
|
201 |
<li><a href='TCF Service - File System.html'>File System Service</a>
|
|
|
202 |
<li><a href='TCF Service - System Monitor.html'>System Monitor Service</a>
|
|
|
203 |
<li><a href='TCF Service - Streams.html'>Streams Service</a>
|
|
|
204 |
</ul>
|
|
|
205 |
|
|
|
206 |
</body>
|
|
|
207 |
</html>
|
|
|
208 |
|