Target Communication Framework Services
Copyright (c) 2007 Wind River Systems, Inc. Made available under the EPL v1.0
Direct comments, questions to the dsdp-tcf-dev@eclipse.org mailing list
Table of Contents
Version
| Date
| Change
|
0.1
| 2008-01-10
| Initial contribution
|
1.0
| 2008-05-06
| Approved
|
1.1
| 2008-06-25
| Enhanced error reporting format, see Bug 232410
|
TCF communication model is based on the idea of services. A service is a group of related commands, events and semantics.
For example, Memory Service defines group of command and events for
reading and writing target memory.
Service definitions are not part of the framework specification, 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.
Format of the protocol messages is defined by syntax rules. Syntax is described
using a simple variant of Backus-Naur Form. In particular:
- Italic lower case words in a courier font, enclosed into angular brackets, are
used to denote syntactic categories, for example: <token>.
Category name can be followed by colon and a text, which explains semantics
of the category, for example: <int:
error code> has same meaning as <int>,
but denotes that the integer number used to indicate an "error code".
- 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:
<chars>
⇒ <char>
⇒ <chars> <char>
- Spaces are added for readability only and they are not part of the syntax.
- All text in the category definition, other than categories and spaces, is UTF-8
based representation of a message bytes.
- The symbol ‘•’ designates a zero byte.
Most of TCF standard services use same format for error reporting:
<error report>
⇒
⇒ null
⇒ <object: error description>
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.
Error description properties are:
- "Code" : <integer>
- Error code. Can belong to one of predefined ranges:
- 0x0-0xffff Standard TCF codes, includes a limited subset of POSIX errors, and OTHER error code, which
can be used together with "AltCode"
- 0x10000-0x1ffff Service specific codes
- 0x20000-0x2ffff Reserved codes - will never be used by the TCF standard
- "Time" : <integer>
- Error timestamp, in milliseconds since midnight, January 1, 1970 UTC
- "Service" : <string>
- Name of the service that reported the error. Required when "Code" is service specific code.
- "Format" : <string>
- 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
java.text.MessageFormat.
In order to simplify clients written in other languages, only a subset of the syntax is supported:
- Supported format types: (none), number
- Supported format styles:
- number: (none), "integer", "percent"
- "Params" : <array>
- An array of values to be used together with "Format" to create the error message.
- "Severity" : <integer>
- Predefined severity values:
- 0 - error (default)
- 1 - warning
- 2 - fatal
- "AltCode" : <integer>
- Alternative error code. This can be used to represent,
for example, OS, POSIX, or other vendor specific error codes
- "AltOrg" : <string>
- ID of organization defining "AltCode", for example "Linux", "VxWorks", "Wind River", etc
- "CausedBy" : <object: error description>
- A nested error description. Can be used to describe a root cause of this error.
All fields except "Code" are optional.
Standard error codes:
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
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".
For encoding of <object>,
<string>, etc., see
JSON - Preferred Marshaling.