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