| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head> |
| <title>Target Communication Framework Services</title> |
| </head> |
| |
| <body lang='EN-US'> |
| |
| <h1>Target Communication Framework Services</h1> |
| |
| <p>Copyright (c) 2007 Wind River Systems, Inc. Made available under the EPL v1.0</p> |
| <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> |
| |
| <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='Overview'>Overview</a></h2> |
| |
| <p>TCF communication model is based on the idea of services. A service is a group of related commands, events and semantics. |
| For example, <a href='TCF Service - Memory.html'>Memory Service</a> defines group of command and events for |
| reading and writing target memory. |
| Service definitions are not part of the <a href='TCF Specification.html'>framework specification</a>, and new services |
| are expected to be defined by developers of tools and target agents. |
| Defenitions of standard services are provided to achieve certain level of compatibility between tools and targets.</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: <b><i><font face="Courier New" size="2" color="#333399"><token>. |
| </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"><int: |
| error code></font></i></b> has same meaning as <b><i><font face="Courier New" size="2" color="#333399"><int></font></i></b>, |
| but denotes that the integer number used to indicate an "error code".</li> |
| |
| <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><chars></i> |
| ⇒ <i><char></i> |
| ⇒ <i><chars> <char></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 ‘•’ 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><error report></i> |
| ⇒ |
| ⇒ null |
| ⇒ <i><object: error description></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><integer></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><integer></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><string></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><string></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><array></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><integer></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><integer></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><string></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><object: error description></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"><object></font></i></b>, |
| <b><i><font face="Courier New" size="2" color="#333399"><string></font></i></b>, etc., see |
| <a href='TCF Specification.html#JSON'>JSON - Preferred Marshaling</a>.</p> |
| |
| <h2><a name='Services'>Services</h2> |
| <ul> |
| <li><a href='TCF Specification.html#Locator'>Locator Service</a></li> |
| <li><a href='TCF Service - Memory.html'>Memory Service</a></li> |
| <li><a href='TCF Service - Processes.html'>Processes Service</a></li> |
| <li><a href='TCF Service - Run Control.html'>Run Control Service</a></li> |
| <li><a href='TCF Service - Registers.html'>Registers Service</a></li> |
| <li><a href='TCF Service - Stack Trace.html'>Stack Trace Service</a></li> |
| <li><a href='TCF Service - Breakpoints.html'>Breakpoints 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> |
| <li><a href='TCF Service - File System.html'>File System Service</a></li> |
| <li><a href='TCF Service - System Monitor.html'>System Monitor Service</a></li> |
| <li><a href='TCF Service - Terminals.html'>Terminals Service</a></li> |
| <li><a href='TCF Service - Streams.html'>Streams Service</a></li> |
| <li><a href='TCF Service - Disassembly.html'>Disassembly Service</a></li> |
| <li><a href='TCF Service - Context Query.html'>Context Query Service</a></li> |
| </ul> |
| |
| </body> |
| </html> |