The target server acts as a broker for the communication path to the target and provides services commonly required by the Tornado tools. In order to support new CPU architectures, new object-module formats, and new communications back ends with minimum programming effort, the corresponding parts of the target server are structured as shared libraries on UNIX or dynamically linked libraries (DLLs) on Windows.¹ The remainder of the target server, known as the target server core, is independent of the target architecture, the target operating system, and of the communications transport layer.

This chapter examines the communications back end. It shows how a back end fits into the architecture of the target server, how the back end is implemented in Tornado, and how to implement new back ends, either for the WDB agent or for non-WDB agents such as emulators. For an overview of the target server and its components, see 1.3 The Target Server and the WTX Protocol. To add a new object-module-format loader, see 3. Object-Module Loader. This chapter gives an overall orientation; for details, see the online reference material under Tornado API Reference>Target Server Back End Interface.

A target server session typically involves the following activities:

The portion of the Tornado target server that communicates with the target is called the back end. Many back ends are supported, each dedicated to an alternative host-target connection. All back ends share a single purpose: to provide a set of primitive services for the target server core. Depending on the back end, executing these routines can be as simple as forwarding a request to the target agent (the WDB RPC back end) or as complex as translating the request to an entirely different protocol (an emulator back end).

Some back ends (WDB back ends) are designed to communicate with the target agent supplied with VxWorks, which is called the WDB agent. (See Figure 2-1.) The WDB agent uses the Wind DeBug (WDB) protocol to communicate between the host and target operating system. The key advantage of this protocol, from a programming perspective, is that it corresponds one-to-one with the target server back-end API. There is a back-end function corresponding to each WDB protocol request. When using the WDB agent, the back end manages the mechanics of transmitting the request to the target over whatever hardware medium provides host-target communication. Creating a new back end is a matter of writing the necessary host and target code to transport WDB protocol messages.²  

Other back ends (non-WDB back ends) are designed to communicate with alternative agents, such as an emulator that serves as a hardware debug agent. (See Figure 2-2). If a back end does not use the WDB agent, the back end itself must provide the requested service. The underlying service could be provided by another software agent (for example, a ROM monitor) or by a hardware agent (for example, an in-circuit emulator or ICE). Virtually any cross-development framework can be supported in a back end because the back-end API is general. It is also possible, if necessary, to return a "service not available" error or to fill in the TGT_OPS table with a NULL pointer if it is impossible to implement the service as requested by the target server. 

This chapter provides background information on the structure of a target server back end, followed by descriptions of how to write new back ends for the WDB agent and for a non-WDB agent. Writing a new back end allows you to use a different communication protocol or to use a new method for providing services to the Tornado tools; none of the tools needs to be modified because the tools communicate only with the target server. Our discussion provides an overall orientation; throughout this chapter, refer to the reference entries in Part 2 for details.

This section discusses several aspects of back-end implementation that are similar for both WDB and non-WDB back ends.

• It provides a description of the FLAG_DESC data structure and the bkendFlagsGet( ) routine which is used to retrieve those flags so they can be sent to the back end.

• It also provides a prototype of the back-end initialization routine, with an explanation of the parameters passed to the back end by the target server and a description of the TGT_OPS and BKEND_INFO data structures (filled by the initialization routine).

• This section also covers event notification requirements and methods, as well as issues relating to target-board rebooting.

• In addition, message logging facilities provided for WDB back ends are discussed. These facilities may be of interest to writers of non-WDB back ends as a source of sample target-server target-agent interactions.

A target server can only use one back end at a time. The back end is attached when the target server is started. The -B option specifies which back end to attach. For example, to use the back end named wdbserial, select wdbserial in the target server initialization window, which invokes the target server with the following command:

% tgtsvr ... -B wdbserial ...

Back ends are linked with the target server dynamically using DLLs. At run time, the target server searches installDir/host/hostType/lib/backend, which contains a DLL for each available back end, and loads the specified back end.³ The back end can have any name, but we recommend you choose names that are short, lower case, and suggest the connection strategy to which they refer. If the requested back end is not found, the attachment fails and the target server abandons its start-up sequence, exiting with an error condition.

Once the correct DLL is found, the target server asks if the back end handles special flags with the bkendFlagsGet( ) routine. If the back end exports this routine, the target server calls the routine and appends the returned flags array to its own array. When it finishes parsing the command line, the target server calls an initialization routine that attaches the back end. Besides initializing the back end, this routine fills in a table of function pointers (the TGT_OPS structure) used by the target server to call the back-end functions and a structure (the BKEND_INFO structure) which describes how the back end notifies the target server of asynchronous events. Finally, the initialization routine calls bkendTgtConnect( ) to attach the target server to a specified target.

A back end can export a flag-parsing routine to handle any back-end specific command line parameters. if the loaded back end exports such a routine, the target server runs the routine to get a list of the parameters the back end needs to access. The parameters are contained in the FLAG_DESC structure (defined in installDir/host/include/flagutil.h). The target server adds the flags to its own array of recognized flags and parses its entire command line.

When the target server attaches a back end, it calls the initialization routine of the named back end. The main purpose of this routine is to fill in the TGT_OPS structure defined in installDir/host/include/tgtlib.h, and the BKEND_INFO structure defined in installDir/host/include/bkendlib.h. It also performs whatever back-end initialization is appropriate.

The TGT_OPS structure, whose location is passed as an argument to the back-end initialization routine, is a collection of function pointers. The initialization routine fills this structure with pointers to functions that provide the back-end services. The implementation of the services is entirely back-end dependent. By virtue of the coupling, it is possible to support many back ends, each providing the same service in its own way. Once the TGT_OPS structure is filled in and returned, the target server is ready to start communicating with the target.

The BKEND_INFO structure, whose location is also passed as an argument to the back-end initialization routine, contains information about the newly loaded back end. This information consists of the back-end version and the asynchronous events notification. Once the BKEND_INFO structure is filled, the target server launches a thread which handles the asynchronous events according to the given method.

The name of the initialization routine is standardized so that the target server can find and attach the back end chosen by the user. It is composed of the back-end file name (without extension) plus the word Initialize. For our example back end, called mybkend, the initialization routine is mybkendInitialize( ), which is defined in mybkend.c. This name indicates the DLL that the target server loads as well as the back-end initialization routine to call. The back-end name is passed to the target server by the -B option when the target server is started.

The back-end initialization routine must match the following prototype:

STATUS mybkendInitialize 
    ( 
    char *       tgtName,    /* network unique target name to connect */ 
    TGT_OPS *    pTgtOps     /* vector of back end functions to fill */ 
    BKEND_INFO * pBkendInfo  /* Backend notification method */ 
    )

The first parameter, tgtName, passed to the back-end initialization routine from the target server specifies the target name. The meaning of the parameter is completely back-end dependent. For example, the wdbrpc back end uses the tgtName as the target's IP address while the wdbserial back end doesn't use tgtName. The only restriction is that tgtName must be unique for each target server.

The second parameter passed to the back-end initialization routine, pTgtOps, is a pointer to the TGT_OPS structure (defined in installDir/host/include/tgtlib.h), which declares the target server back-end interface. The initialization routine must fill this structure with the appropriate information and function pointers so that the target server understands what the back end can do. When the target server needs to perform a service, it calls the appropriate back-end function.

The tgtConnected field is a boolean variable that is TRUE if the target board is connected to the target server by the back end. This boolean must be set to FALSE by the initialization routine because the board is not yet connected. It is set to TRUE by the target server if the target-board connection succeeds.

The tgtLink field is a TGT_LINK_DESC structure also defined in installDir/host/include/tgtlib.h. This structure describes the communication link with the board and is composed of three fields:

typedef struct 
    { 
    char *     name;              /* target/host link name */ 
    u_int      type;              /* target/host link type */ 
    u_int      speed;             /* target/host link speed in bps */ 
    } TGT_LINK_DESC;

The tgtSupInfo field is a target server spare field.

The tgtEventFd field obsolete. The file descriptor that the back end uses to wake up the target server when an asynchronous event arrives from the target system is now stored in the BKEND_INFO structure. The back end should set tgtEventFd to NONE.

The last parameter passed to the back-end initialization routine, pbkendInfo, is a pointer to a BKEND_INFO structure (defined in installDir/host/include/bkendlib.h). This structure describes information related to the currently attached back end. The key item is the asynchronous notification method provided by the back end.

The target server initializes BKEND_INFO with the following values:

bkendinfo.tgtBkInfoSize = sizeof (bkend_info); 
bkendinfo.tgtBkVersion = BKEND_VERSION_2

The tgtBkInfoSize field is set by the target server to the size of its BKEND_INFO structure. The tgtBkVersion field is set to BKEND_VERSION_2 (defined in installDir/host/include/ bkendlib.h) for the current version. The back end should check these values and reset tgtBkVersion if necessary.

During the initialization phase, the back end fills in the structure with its method of notifying the target server of asynchronous events. An excerpt from the WDB serial back-end initialization routine is as follows:

... 
 
pbkInfo->tgtBkVersion = BKEND_VERSION_2;     /* Backend version 2 */ 
 
/* we'll provide our polling method ( on NT ) */ 
 
#ifdef WIN32 
pbkInfo->INFO.POLLING_METHOD.bkEndPollingMethod = POLL_BKROUTINE_MODE; 
pbkInfo->INFO.POLLING_METHOD.BKEND_NOTIF_METHOD.bkEndSelectRtn = 
win32SerialSelect; 
#else 
 
/* on UNIX we give the tty file desc */ 
 
pbkInfo->INFO.POLLING_METHOD.bkEndPollingMethod = POLL_SELECT_MODE; 
pbkInfo->INFO.POLLING_METHOD.BKEND_NOTIF_METHOD.pollingFd = EventFd; 
#endif 
return (OK);

After attaching and initializing the back end, the target server is able to perform actions on the connected board by calling back-end functions. The syntax of all back-end functions is similar. Functions usually take two pointers as arguments: the first points to a structure that contains parameters specifying the service input data; the second points to a structure that is filled in with the data returned by the service. One or both structure pointers may be omitted when a service requires no input or output data. Each function must return a WDB status code: either WDB_OK on success, or an appropriate WDB error code describing the error encountered during the service call. The complete error code list is located in the file installDir/share/src/agents/wdb/wdb.h.

Because the connection to the back-end interface is indirect, through a table of function pointers initialized when the back end is attached, there are no naming restrictions on back-end functions. Their scope is local to the back end, as all other modules access the back end through the function table. A complete description of the function interface is provided in the online reference material under Tornado API Reference>Target Server Back End Interface.

The target server not only sends requests and information to the target, it also needs feedback from the target about what is occurring there. When a target event (such as hitting a breakpoint or an exception) occurs, the target server must be notified. The back-end interface provides two notification methods, synchronous and asynchronous. The notification method is provided to the target server by the BKEND_INFO structure pointer.

Three methods can be provided:

No asynchronous mechanism is provided. The back end cannot handle asynchronous events. When this method is specified, no asynchronous events are sent to the target server. The target-server back-end thread uses synchronous requests to get events from the target. After each WTX request, it issues a bkendEventGet( ) call to get any events from the target.

The back end provides a file descriptor which can be put into a select( ) routine. When this method is specified, the thread handling the events waits on this descriptor using select( ). When this file descriptor becomes active because the emulator or target agent has written to it, the back-end thread gets the events.

The back end provides a routine which behaves like the select( ) routine. When this method is specified, the back-end thread pends on the provided routine until the routine returns something positive. When this occurs, the back-end thread receives the pending events.

With the two asynchronous methods, the target server calls the back end bkendEventGet( ) function only to get the event information. Those methods are more efficient because no polling for events is required.

After issuing a bkendEventGet( ) command, the target server calls bkendEvtPending( ) to see if other events are pending, and calls bkendEventGet( ) again if bkendEvtPending( ) indicates that other events are available to be read. This method allows the target server to upload multiple target events without having to enter the select loop each time.

The target server is a multi-threaded application. This allows a back end to export its own select-like routine instead of being limited to a selectable file descriptor. This is particularly useful on WIN32 hosts where select( ) addresses only sockets and not other handles such as serial lines or files. The select-like routine can be expanded to address such devices. It allows the target server back-end thread to sleep (thus not consuming CPU cycles) until events arrive. This routine must match the following prototype:

int bkendSelect (int timeout);

The timeout given by the target server is always WAIT_FOREVER (-1).

The return value should follow the following convention:

The target server has something to read. It calls the bkendEventGet( ) and bkendEvtPending( ) routines to purge all the pending events.

Timeout, or another thread is taking the back end. The target server back-end thread waits until the actual thread dealing with the back end finishes its transaction, and pick up the resulting events afterward by calling bkendEvtPending( ) and bkendEventGet( ) if events are pending.

An error occurred. The back-end thread terminates.

It is possible that two threads may use the back ends routines at the same time: a synchronous thread (the one servicing a WTX request), which can call all the routines given in the TGT_OPS structure, and the asynchronous thread (the one which is pending on the given select-like routine). You will have to handle the race condition here. The simplest way is to make the back-end thread return from the select-like routine with a 0 status. This causes the target server to wait until the other thread completes its transaction before asking if there are pending events.

For a discussion of how to inform the target server that a select-like routine is used, see 2.2.1 Attachment and Initialization.

To keep the target server synchronized with the target agent during a target reboot, the back end must call the routine targetServerRestart( ). A reboot detection mechanism is not optional, and the target server does not function properly if the back end fails to call this routine.

If the target server does not exit gracefully, which usually occurs because there is an error in the back end, it leaves its name in the registry. This prevents you from reusing the same name when you restart the target server. On UNIX, clean up the registry using the "unregister" button of the Tornado launcher. On Windows, select Target Server>Manage on the Tools menu and select Unregister. On either host you can create a wtxtcl script, unreg, like the following:

#!/bin/sh 
# 
# unreg - remove a name from the registery 
# 
# Syntax: unreg <targetServerName> 
# 
echo -n Unregistering $1 ... 
 
wtxtcl << EOF 
 
set seekName $1 
set allNames [wtxInfo] 
 
set pos [lsearch -glob \$allNames \*\$seekName\* ] 
if { \$pos < 0} { 
    puts "invalid name" 
    exit 
    } 
 
set fullName [lindex [lindex \$allNames \$pos ] 0 ] 
wtxUnregister \$fullName 
 
EOF 
 
echo ` done.'

This is an example of the helpful utilities you can create with the wtxtcl shell. For more information on WTX Tcl, see 4. The WTX Protocol, the Tornado User's Guide: Tcl Appendix, and the online reference material under Tornado API Reference>WTX TCL Library.

A message logging facility exists for all WDB back ends. This facility logs all transactions between the back end and the target agent to a file or terminal. Message logging simplifies diagnosing connection problems between the host and target because one can look at the sequence of transactions that led to the problem. This facility can also be used to help new back-end designers understand requests exchanged between existing back ends and the target.

All back ends that connect to the WDB agent send requests to the target using the library installDir/ host/src/tgtsvr/backend/share/rpccore.c, which contains the logging calls. This logging mechanism is back-end-specific, and is only provided for WDB back ends.

Message logging is enabled when the target server is started with the -Bd fileName option. For example, to save log information in the file named /tmp/WDB.log, invoke the target server with a command like the following:

% tgtsvr ... -Bd /tmp/tgtDebug.log ...

The file name must be specified; otherwise message logging is not enabled. If the file already exists, log information is added at the end of the file. Each time a request is logged to the file, output is flushed to assure that the last request written in the log file is actually the last request sent even if the target server hangs.

The length of the debug file can be controlled by the -Bm logMaxSize option. With this flag, a file is created, or reset if it already exists, and is written as a circular file: when the file length reaches logMaxSize, the file is rewritten from the beginning, overriding the existing data. If this flag is not set or set with a 0 value, a file is created, or opened in append mode if it already exists, and is truncated.

To make a new back end accessible to the Configure pop-up window under the target server option of the Tools menu, add your backend DLL to installDir/host/x86-win32/lib/backend.

Back-end-specific flags must be supplied in the target server launch command edit box, since Tornado cannot automatically know how many and what kind of arguments the back end supports. To do so, add necessary code to handle backend specific flags to:

installDir/host/resource/tcl/app-config/Tornado/01TgtSvrConfigure.win32.tcl and installDir/host/resource/tcl/app-config/Tornado/01TgtSvrManage.win32.tcl.

The back ends provided by Wind River Systems support a variety of communication alternatives, but not all cases are supported. Customers interested in using an unsupported communication link must write a new back end.

Developing a back end to communicate with the WDB agent is simple: because all the services are already implemented in the WDB agent, the new back end only needs to transport WDB RPC messages.

The key development steps are:

• Write a back end which utilizes RPC core functions, if necessary. For a new machine, you must write clnt_xxx.c.

• Write a device driver on the target, if necessary.

This section describes the Wind DeBug (WDB) version 1.0 protocol. It is the protocol used by the Tornado target server back ends that communicate with the WDB agent (WDB RPC, WDB Serial, and NetROM). See Figure 2-1 for a diagram of how these back ends connect to the WDB agent.

WDB is an RPC-based protocol which uses UDP. The WDB agent acts as a server for requests sent by the target server. For more information, see one of the many generally available references on UDP and Sun RPC.

See installDir/share/src/agents/wdb/wdbP.h for some key definitions:

• The UDP port that the agent accepts requests from, WDBPORT, is 0x4321.

• The agent's RPC program number, WDBPROG, is 0x55555555.

• The agent's RPC version number, WDBVERS, is 1.

A WDB request packet sent to the agent contains the following parts, as shown in Figure 2-3:  

• A 20-byte IP header.

• An 8-byte UDP header. It consists of four 16-bit words. WDBPORT is word 2.

• A 40-byte RPC request header. It consists of ten 32-bit words. WDBPROG is word 3. WDBVERS is word 4. The RPC procedure number is word 5.

• An XDR stream. The first 12 bytes of this stream is WDB-parameter-wrapper information. The rest of the stream is the XDR-encoded parameters for the procedure. (See installDir/share/src/agents/wdb for more information on the WDB_XDR functions.)

The WDB parameter wrapper contains three 4-byte words. The first word is a checksum over the whole RPC packet (RPC header plus XDR stream). The second word is the packet size. These two words enable the agent to determine if a corrupted packet has arrived. The third word is a sequence number. The low order two bytes of the sequence number are used to allow the agent to ignore old or duplicated requests (which can occur with UDP transport). The high order two bytes are the host ID. When a host issues a WDB_TARGET_CONNECT request, the host ID portion of the sequence number is recorded. If a request arrives from a non-connected host, the RPC fails with the RPC error status PROG_UNAVAIL or SYSTEM_ERR, depending on whether the agent is already connected to another target server or not. The WDB_TARGET_CONNECT request always establishes a new connection, if necessary by dropping the old one. If the host wants to test whether or not the agent is already connected before trying to establish a connection, it should first issue a WDB_TARGET_PING request and see if the RPC fails with error status PROG_UNAVAIL. If so the connection is busy.

The routine xdr_WDB_PARAM_WRAPPER is used to encode or decode the entire XDR stream (the procedure parameters plus the 12-byte parameter wrapper). The following example is a code stub from the host routine rpcCoreClntCall( ):

seqNumber++ ; 
... 
wdbParamWrapper.xdr = inProc;         /* xdr func for proc params */ 
wdbParamWrapper.pParams = in;         /* pointer to proc params */ 
wdbParamWrapper.seqNum = processId | seqNumber;     /* seq nb */ 
... 
clntStatus = clnt_call (pWdbClnt, procNum, xdr_WDB_PARAM_WRAPPER, 
&wdbParamWrapper,...);

A WDB reply packet sent by the agent contains the following parts, as shown in Figure 2-4:

• A 20-byte IP header.

• An 8-byte UDP header.

• A 24-byte RPC reply header.

• An XDR stream. The first 12 bytes of this stream is WDB-reply-wrapper information. The rest of the stream is the XDR-encoded reply from the procedure.

Like the WDB parameter wrapper, the WDB reply wrapper contains three 4-byte words. The first word is a checksum over the whole RPC packet (RPC header plus XDR stream). The second word is the packet size. These two words enable the host to determine if a corrupted reply was returned (and, if so, to reissue the request). The third word is the WDB error status. The high order bit is set if there are events pending on the target, in which case the host can issue a WDB_EVENT_GET request to upload the event. The rest of the word is the actual error status.  

Figure 2-4:   WDB Reply Packet

After a remote procedure is called, the program should perform error checking. Error status can be communicated in one of two ways: in the RPC header or in the reply wrapper. If the failure is reported in the third word of the RPC header, then the host's clnt_call returns an RPC error status. These have conventional meanings according to the RPC specification. In addition, the WDB agent uses a couple of special codes:

The RPC procedure requested is not configured into the agent. The agent is scalable, so this usually means the agent was built without that service.

The agent refused to execute the procedure because it is connected to another host.

The agent refused to execute the procedure because it is not connected to any host. If you were previously connected, the target has rebooted.

Even if the RPC call succeeds (meaning that the agent tries to execute your command), the command may still fail. The errCode field in the reply wrapper can be checked; if the lower 31 bits are zero, the command succeeded. (Remember that the high order bit is set if there are events pending on the target.) If the value is non-zero, then the procedure failed and the word contains the error code. Error codes have the format WDB_ERR_XXX. The error-code definitions are located in installDir/share/src/agents/wdb/wdb.h.

The routine xdr_WDB_REPLY_WRAPPER is used to encode or decode the entire XDR stream (the reply data plus the 12-byte reply wrapper). The following pseudo code shows how it works:

Asynchronous events can be generated on the target. These include exceptions, breakpoints, and task exiting. These events are queued on the target until the host uploads them with the WDB_EVENT_GET service. In order to prevent the host from polling for events, the agent has two ways to notify the host that events are pending: (1) by setting the high order bit in the errCode status of the reply wrapper; (2) by sending a notify packet.

Normally the agent only sends data to the host in response to RPC requests. The convention is that if the host receives data when it is not waiting for a reply, it means that an event is pending on the target. This allows the target server to select( ) on file descriptors associated with the host tools which are connected as well as with the target. If the target file descriptor becomes active, the host issues a WDB_EVENT_GET request to upload the event (and keeps uploading events until the high order bit in the errCode field is clear). The actual notify packet sent by the agent is a packet that can not be confused with an RPC reply (in case it sends the notify packet just as the host issues an RPC request). In fact, it sends a bogus RPC request.

To provide the necessary host-side support for a new communication pathway, you must write a new back-end DLL to transport WDB protocol messages. Fortunately, most of the back-end code is generic RPC⁴ code to transport WDB protocol messages; thus you can reuse Wind River's rpccore library⁵ . Consequently, you can only need to write the back end's initialization code and, if necessary, the client-side RPC implementation.

A WDB back end consists of three parts: (1) the initialization routine, which initializes the back end; (2) the RPC core which manages WDB RPC requests, including XDR; and (3) the client-side RPC implementation, which sends and receives the RPC messages over the network medium. (See Figure 2-5.)  

The bkendInit( ) routine is the back-end DLL's entry point and must initialize the back end. To do this, it performs the following services:

1. It creates the CLIENT data structure, which the RPC core uses to communicate with the WDB agent. The CLIENT structure is a standard RPC data structure that contains information needed by the RPC core, such as pointers to buffers and to the functions for sending and receiving data. It is important to create a CLIENT structure appropriate to the network medium your back end is using: for example, Wind River's wdbrpc back end calls clnt_udpcreate ( ) so that the back end can send UDP messages over the network; the wdbserial back end calls clnt_ttycreate ( ) so that the back end can communicate over a serial device.

1. It initializes the TGT_LINK_DESC information in the TGT_OPS structure.

1. It calls rpcCoreInit( ) to handle the rest of the back-end initialization. This routine is part of the installDir/host/src/tgtsvr/backend/share/rpccore.c support library, which handles all the generic parts of the protocol including:

• translating back-end requests into WDB-agent requests, including XDR encoding and decoding

• packet sequencing and checksum

• timeout and retransmission

• asynchronous event notification

• back-end logging

In the following sections, we examine the wdbserial back end to demonstrate how to write a new WDB back end. The wdbserial back end consists of two main modules, the wdbserial.c module, which implements the back-end initialization routine, and clnt_tty.c, which provides the client-side RPC implementation for a serial device (see Client-Side RPC Implementation).

The wdbserial.c module consists of one routine, wdbserialInit( ). The target server invokes wdbserialInit( ) after it loads the back end in order to initialize it. The wdbserialInit( ) call creates an RPC CLIENT structure for communicating over a serial device and establishes a link, initializes the generic RPC core library to operate the target agent using the WDB (Wind DeBug) protocol, and initializes a data structure describing the back-end link with the agent. The wdbserial.c code shows how these steps are carried out.

After the usual preamble of comments, copyright notice, and inclusion of system header files, wdbserial.c includes the Tornado host header files from the installDir/host/include directory:

Windows `95 and NT hosts must include backend.h by means of the following #ifdef:

Next, wdbserial.c imports the prototypes to rpcCoreInit( ), which initializes the RPC core library, and clnttty_creat ( ), which creates an RPC connection over a serial link.

When the target server calls wdbserialInitialize( ), it passes pointers to the TGT_OPS and BKEND_INFO structures. (For more information on these structures, see The TGT_OPS Structure and The BKEND_INFO Structure.)

STATUS wdbserialInitialize 
    ( 
    char *       tgtName,    /* target name to connect to (unused) */ 
    TGT_OPS *    pTgtOps     /* back-end function */ 
    BKEND_INFO * pBkendInfo  /* Backend notification method */ 
    )

Windows hosts optionally enable logging of debugging messages from the lower-level serial support:

#ifdef WIN32 
    dbg_on = GetDebugFlag(); 
#endif /* WIN32 */

Next, the back end must enable RPC communications over a serial link by creating the CLIENT data structure. If your back end uses an unsupported link type you will need to implement a clntXXX_create( ) call for your communication medium. Wind River implemented clnttty_create( ) for the wdbserial back end.

The back end initializes the RPC client-side transport to the WDB agent: first, struct timeval is initialized with the user's specified timeout; then clnttty_create( ) is called to create the RPC link to the target. Note that the clntty_create( ) call is retried until it succeeds or exceeds the user-specified number of retries.

/* set the connection timeout to the current value */ 
 
tv.tv_sec  = timeout; 
tv.tv_usec = 0; 
... 
resendCnt = recallNum; 
 
do 
{ 
    /* create the backend client and connect the target deamon */ 
 
pClnt = clnttty_create (pTtyDevName, baudRate, WDBPROG, WDBVERS, tv); 
 
} 
while ((pClnt == NULL) && (--resendCnt > 0)); 
...

If the RPC client-side initialization fails, the back end sets errno to the appropriate error number, logs an error message, and returns ERROR to indicate that the called routine failed.

if (pClnt == NULL) 
{ 
... 
errno = WTX_ERR_SVR_INVALID_DEVICE; 
 
WPWR_LOG_ERR ("%s\n",  
            clnt_spcreateerror ("wdbserial backend client create")); 
return (ERROR); 
}

If the RPC client initialization succeeds, the back end calls rpcCoreInit( ) to initialize the rpccore library for use over the serial device. The rpccore library provides all the support necessary to operate the WDB target agent in response to target server requests. In particular, rpcCoreInit( ) initializes the TGT_OPS structure, specifying that the target server should call rpccore routines to perform the various back-end operations.

rpcCoreInit (pClnt, timeout, recallNum, pTgtOps); 
...

Finally, the back end describes the target link type. If your back end uses a new link type, define a TGT_LINK_XXX macro in installDir/host/h/tgtlib.h.

pTgtOps->tgtLink.name = "WDB Agent across serial line"; 
pTgtOps->tgtLink.type = TGT_LINK_SERIAL_RPC; 
pTgtOps->tgtLink.speed = baudRate; 
 
return (OK); 
}

If your back end must communicate over an unsupported network medium, you must provide a client-side RPC implementation. As a starting point, you should use the clnt_udp.c which is part of Sun Microsystem's public domain RPC distribution and is provided in installDir/target/unsupported/rpc4.0/rpc.

Your implementation must provide the following services:

• A clntXXX_create( ) routine (where XXX describes the device type you are using): this routine must open the device for communication and return a pointer to a CLIENT data structure. The CLIENT structure should contain the information needed to perform RPC, including pointers to the clnt_ops functions for managing the transmission of data and data such as file descriptors.

• The clnt_ops functions: these functions perform the basic RPC operations over a specific network medium.

By including the generic makefile templates provided with Tornado, it is easy to write a makefile for a back end.

# Makefile - for WDB serial backend

After the modification history, specify the suffixes of the shared library that will be built:

.SUFFIXES:   .so .sl

Next, include the makefile templates provided by the Tornado development environment. These fragments make it easy to build a portable makefile.

include      $(WIND_BASE)/host/include/make/generic.mh 
include      $(WIND_BASE)/host/include/make/$(HOST).mh

Set the INCLUDES macro to specify that the compiler can find header files in the installDir/host/include and the installDir/share/src/agents/wdb directories. Specify any other directories that the compiler needs to search to find your back-end header files:

INCLUDES = $(WIND_INC) $(WIND_SHARE_INC)

Specify which modules should be linked to create the back end. List both the back end modules and the rpccore modules (the modules in ../share):

BKEND_OBJS = clnt_tty.o wdbserial.o  
 
BKEND_XDR_OBJS = ../share/ctx.o ../share/ctxcreat.o \ 
                ../share/ctxstep.o ../share/evtdata.o \ 
                ../share/evtpoint.o ../share/memory.o \ 
                ../share/regs.o ../share/rpccksum.o \ 
                ../share/rpccore.o ../share/tgtinfo.o \ 
                ../share/wrapper.o ../share/xdrcore.o

State the name of the back end:

SH_BKEND_OBJS = wdbserial.$(SHLIB_EXT)

Next, specify any extra compiler flags you need:

LOCAL_CFLAGS = -DPORTABLE -DHOST $(DYN_LK_FLAGS) 
... 
default: lib $(SH_BKEND_OBJS)

Finally, an inference rule states that the back end is built from C source modules that are linked into the shared library. If you need to link the back end with other libraries or are using C++, you must modify this rule.

.c.$(SHLIB_EXT):$(BKEND_OBJS) $(BKEND_XDR_OBJS) 
        $(SHARED_LD) $(SHARED_LDFLAGS) -o $(SH_BKEND_LIB)/$*.$(SHLIB_EXT) \ 
         $(BKEND_OBJS) $(BKEND_XDR_OBJS) 
... 
include     $(WIND_BASE)/host/include/make/generic2.mh

The WDB target agent needs a means to send and receive UDP/IP datagrams over the physical network connection. There are two protocol stacks that can be used, the full VxWorks network protocol stack and a lightweight UDP/IP interpreter. The full network protocol stack provides a rich set of functionality, while the lightweight UDP/IP interpreter requires much less target memory. The choice of protocol stacks affects the type of driver that must be written for the physical device. 

Drivers that interface with the VxWorks TCP/IP network stack are called network interface drivers. Details of how to write a network interface driver are covered in The BSP Porting Kit (an optional product). The advantage of creating such a driver is that, in addition to being used as a debug communication path, it can also be used for application network communication. To use a network interface driver, configure the target agent for network communication (the default configuration).

Drivers that interface with the target agent's UDP/IP interpreter are called WDB packet drivers. Such drivers have the advantage that they do not require the TCP/IP stack to be present on the target. This can save space on resource-constrained targets. The agent's UDP/IP interpreter has the advantage of small size (only 800 bytes) but it also has limited functionality.

To create a WDB packet driver, start with the template driver in installDir/target/src/drv/wdb/wdbTemplatePktDrv.c. Use of the template is documented in the source file.

You must also modify the agent's startup code to initialize the new communication pathway. The target agent configuration code is provided in installDir/target/src/config/usrWdb.c. To initialize your custom packet driver, add initialization code to usrWdb.c similar to the section bracketed with
#if  (WDB_COMM_TYPE == WDB_COMM_TYPE_CUSTOM).

To build the packet driver, copy it into your BSP directory and use the standard techniques described in the Tornado User's Guide: Projects or the VxWorks Programmer's Guide: Configuration and Build. The makefile templates provided in installDir/target/h/make assist in developing a portable makefile. Modify the makefile in your BSP directory so that these modules are built and linked into your VxWorks image.

Use the wtxtest test suite to verify the new back-end connection. This facility exercises all back-end functions over your new link. For more information about wtxtest, see the online reference material under Tornado Reference>Tornado Tools.

This section addresses the task of writing a back end that communicates with an agent (such as an emulator) other than the WDB agent. In this case, your back end methods must service back-end API requests directly, in other words, by way of a proprietary emulator API. For a general approach highlighting some of the issues involved in this process, see 2.4.1 Overview of Writing a Non-WDB Back End. The remainder of this chapter presents an example implementation. The complete source code for the acecpu32 example back end plus a back-end development class library, which implements the back-end framework as a C++ abstract base class, are provided in the Back-End Developer's Kit.

The following tasks are involved in writing a non-WDB back end:

• writing the initialization routine

• writing the back-end methods to provide basic run control

• adding advanced features (such as target function invocations)

• testing the back end

The initialization routine is the entry point of the back end. It performs the back-end initialization and attachment. Even before the rest of the back-end functions are implemented, this routine can be called to test correct attachment between the back end and the target server.

Once the attachment and initialization procedures have been carried out successfully, you are ready to begin the major task of writing, documenting, and testing the back-end functions. The remainder of this section outlines the key development issues and suggests one approach to implementing a back end.

The first step in your implementation is to determine what functions your back end must provide. The easiest way to establish this is by using the Back-End Developer's Kit as a basis. It contains a sample back end, the acecpu32, which is an implementation for the fictitious ACE C API. It operates an emulator supporting Motorola CPU32 microprocessors through BDM. It provides a structure and an implementation of common back-end services, including Gopher and checksum, which are emulator independent. You will need to support memory and register accesses, event handling on the target, communication with the emulator or other agent, state handling, and other emulator-dependent services.

Figure 2-7 shows the structure of the acecpu32 implementation.   

Figure 2-8 shows how the Event_T class, which manages target event information, is implemented to queue WDB_EVT_DATA.   

The recommended plan for implementing the back end is to add support incrementally for the desired services, exercising them with the wtxtcl shell at each stage. (For more information on wtxtcl, see 4.4 WTX Tcl API.) Initially, you should write enough of the framework so that the target server can load your skeleton back end. Then you can add the key functions, testing them to make sure that you are on the right track. If you plan to support both UNIX and Windows hosts, we recommend that you build and test on both hosts in parallel.

1. First, create a directory in installDir/host/src/tgtsvr/backend for the back end. By convention, the name of the back end and its directory should be a short, descriptive phrase which is all lower-case, such as acecpu32, for the ACE CPU32 emulator back end.

1. Next, implement a skeleton back-end module which initializes the back end. The module must contain the back-end initialization routine and any other necessary routines. The target server will call the initialization routine when it loads the back end. You may find it helpful to provide stubs for other functions which log an error message to the console. Then you can start the target server with your back end and use the wtxtcl shell to test that it invokes functions in response to WTX requests.

1. Implement the functions to read and write memory and registers.

1. Implement the functions to set breakpoints, stop execution, resume execution, and step a context.

1. Add event handling. At this point you should be able to get CrossWind, the source-level debugger, to operate successfully.

1. Implement desired optional functions, such as the ability to invoke functions on the target.

1. Tune performance. If you can optimize memory and register reads, you can improve performance significantly.

By implementing the back-end functions in this order, you will be able to verify quickly that different layers of the Tornado development environment interface correctly with your back end and the emulator you are supporting.

The interface between the target server and the back end is documented in 2.2 Back-End Implementation. In addition, 2.2.1 Attachment and Initialization describes the WDB data structures used to pass information into and out of the back end. Your back end methods must also use the WDB error codes. Both the error codes and the data structures are declared in installDir/share/src/agents/wdb/wdb.h.

The Wind River C coding conventions are documented in the Tornado User's Guide: C and C++ Coding Conventions. The following additional conventions have been adopted for C++ and the Back-End Developer's Kit:

• Class names end with _T.

• Member function names end with _m.

• Member data names end with _.

• Static member function names end with _s.

• Wind River C conventions for naming and indentation.

Finally, we recommend that you do not use C++ static objects in the back end because you will have no control over when their constructors and destructors are called. Instead, manage the objects with new and delete.

Back-end testing relies on the wtxtcl shell provided with Tornado. This shell allows you to send WTX protocol requests to the target server, the same kinds of requests the tools send. Using wtxtcl, you can interactively invoke the back-end methods to verify that they work correctly. Program wtxtcl in Tcl, which Wind River has extended to support the WTX protocol.

This section and the two sections that follow it use the libraries and methods of the Back-End Developer's Kit as an example implementation for the CPU32 emulator. You may be able to use significant portions of this framework for your back end.

The Back-End Developer's Kit consists of a class library that provides the basic back-end framework, an example back end for acecpu32, sample test scripts, and this document. The library also implements common back-end methods, including Gopher and checksum, which are emulator-independent. By integrating this back-end framework into a new back end, you will not have to spend time developing and debugging these back-end services. To take advantage of this framework, derive a vendor-specific back-end class from the abstract base class Backend_T, declared in backend.h as shown in the following example:

... 
#include "backend.h" 
... 
// Declaration of Vendor-specific back end class 
 
class Ace_T : public Backend_T 
    { 
    // Backend_T methods which you are overriding go here 
    ... 
    // Your vendor-specific methods and data go here 
    };

Once you have derived your vendor-specific class, determine what other classes and objects you need in your system. If you are integrating an existing C API for operating the emulator, you may find that the acecpu32 example back end can be modified.

Some of the classes and objects you may need include the following:

• an event class for handling events on the target

• a communication object to communicate with the emulator

• an object for handling state

• a parsing object to operate an emulator's ASCII interface if there is no binary interface

Figure 2-9 shows the architecture of the acecpu32 back end.     

After installing the libraries supplied with the Back-End Developer's Kit, follow the implementation procedure laid out in 2.4.1 Overview of Writing a Non-WDB Back End. When you begin tuning performance, if your emulator can perform an operation more efficiently than the default implementation (for example, a memory scan) override Backend_T's methods.

For an example of how to use WDB data structures and error codes, look at the acecpu32 example code in installDir/host/src/tgtsvr/backend/acecpu32.

The Back-End Developer's Kit's class library is supported only on Solaris 2.5.1 and 2.6, Windows NT, and Windows 95 hosts. The source code for this library is provided and can be readily ported to other hosts because of the limited use of operating system calls. Furthermore, the Tornado development environment provides generic makefile stubs which abstract most of the host-dependent build issues.

The Back-End Developer's Kit provides example test scripts which are located in installDir/host/src/tgtsvr/backend/bedk/tests. You can use these scripts as a basis for your own test scripts.

The first task is to get the basic skeleton of the back end operating. This means the target server should be able to start up, load the back-end DLL, and initialize, connect, and disconnect the back end.

In order to create the skeleton back end, carry out the following steps:

• Write acecpu32.cpp, which contains the routine acecpu32Init( ). This file is the "main" of the back-end DLL.

• Declare your vendor-specific back-end class, Ace_T, writing stubs for the mandatory methods. This code belongs in the modules that implement the back end, acecpu32Backend.h and acecpu32Backend.cpp. The methods are not yet supported, but it is convenient to have them log a message to the console and return a value indicating that they were successfully invoked.

• Modify the example makefile to compile your back end.

• Use wtxtcl to test that the skeleton back end loads, and that you can execute back-end methods.

To implement the skeleton back end, write the "main" back-end module, acecpu32.cpp, which initializes the back end by creating a vendor-specific back-end object, an instance of Ace_T.