The WTX protocol permits a number of tools running on a host system to communicate with one or more host-based target servers, in order to operate on targets running VxWorks (see Figure 4-1).Target servers can also connect to VxSim, a target simulator. A target server can connect to only one target, but a tool can connect to more than one target server at a time, allowing multi-processor application development.   

The WTX protocol is usually accessed by Tcl commands or C functions rather than directly (see Figure 4-2). Introductory material for protocol and language bindings is presented in 4.4 WTX Tcl API and in 4.5 WTX C API. Tornado provides a Tcl interpreter and 4.4 WTX Tcl API offers many interactive examples. You may want to work through the Tcl examples to become familiar with WTX even if you plan to program primarily in a compiled C environment.

The WTX Java API provides a set of Java classes permitting access to the WTX protocol services. It is built on top of the WTX C API using the Java Native Interface. Use this interface to create tools that access the target server or the Tornado registry when Java is the implementation language. This API is unsupported. It can be downloaded from the Wind River System WEB server (www.wrs.com).    

The online reference material under Tornado API Guide>WTX Protocol, WTX Tcl Library, and WTX C Library gives detailed descriptions of WTX services, error messages, and API parameters.

The WTX protocol provides the interface between the tools and the target server. A tool requests information or an action of the target server, WTX conveys that request, and the target server makes an appropriate response. Figure 4-3 is a schematic representation of a series of interactions between WindSh (a tool) and the target server, showing how WTX commands fit into the process.      

All WTX messages are defined in installDir/host/include/wtxmsg.h. Their names are prefixed with "WTX_MSG_". They all contain a WTX_CORE structure (shown below) which carries the identifier of the tool making the request and an errCode field. The errCode contains OK (0) when the call succeeds or an error status code (a value other than 0) when the call fails. The error status corresponds to the errno set by the server. The error status values are defined in installDir/host/include/wtxerr.h.

typedef struct wtx_core                 /* WTX message core */ 
    { 
    UINT32       objId;                 /* identifier */ 
    WTX_ERROR_T  errCode;               /* service error code */ 
    UINT32       protVersion;           /* WTX protocol version */ 
    } WTX_CORE;

The target server option -Wd filename is designed to simplify debugging WTX tools. This option causes all the WTX messages exchanged between the connected tools and the target server to be written to the specified file. A sample file is as follows:

User Name                 : chrisc 
Started                   : Fri Jan  8 17:59:37 1999 
Target Server Name        : t80-202@couesnon 
Target Name               : t80-202 
Target Server Options     : tgtsvr.ex -V -Wd /tmp/WTXtrace t80-202  
Host                      : SunOS couesnon 5.5.1 Generic_103640-12 sun4u 
 
0       8    WTX_TOOL_ATTACH                        Fri Jan  8 17:59:48 1999 
    In 
        WTX_MSG_TOOL_DESC 
            WTX_CORE 
                objId             0x0 
                errCode           0 
                protVersion       0 
            WTX_TOOL_DESC 
                id                0x0 
                toolName          wtxtcl 
                toolArgv          Unknown 
                toolVersion       Unknown 
                userName          chrisc@couesnon 
                pReserved         Unknown 
                next              Unknown 
    Out status          Ok 
        WTX_MSG_TOOL_DESC 
            WTX_CORE 
                objId             0x0 
                errCode           0 
                protVersion       0 
            WTX_TOOL_DESC 
                id                0x1a5278 
                toolName          wtxtcl 
                toolArgv          Unknown 
                toolVersion       Unknown 
                userName          chrisc@couesnon 
                pReserved         Unknown 
                next             Unknown