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:

Initializing the Target Server

1. The target server is invoked with the following syntax:

UNIX:

% tgtsvr -V -B mybkend ... &

Windows:

c:> tgtsvr -V -B mybkend ...

where -V enables verbose diagnostic messages and -B specifies the back end.

1. The target server loads the back-end DLL specified with the -B parameter. (In the example, the back end is named mybkend; in the discussion, replace mybkend with the name of the back end you are developing.) The target server asks the back end if it can be customized through special command-line arguments.

1. If so, the target server parses its command-line argument and feeds the information to the back end.

1. Next, the target server registers itself with the registry, wtxregd, so that tools can connect to it.

1. The target server initializes the back end by calling a function named mybkendInitialize( ) in the DLL. Every back end must provide an initialization routine which has the name of the back end followed by Initialize. The routine mybkendInitialize( ) initializes the back end, fills in a TGT_OPS structure with the address of each back end function, and a BKEND_INFO structure with the method chosen to alert the target server when events come to the back end. The TGT_OPS structure is defined in installDir/host/include/host.h and the BKEND_INFO structure is defined in installDir/host/include/bkendlib.h.

1. The target server connects the back end to the target by calling the back-end target-connect function.

1. Finally, the target server performs other initialization, such as loading the OMF reader and reading the symbols in the OS core file.

Servicing Tool Requests

1. The target server launches a thread to wait for WTX protocol requests sent by tools and another to wait for target events. Whenever a target event occurs, the back end notifies the target server using the method specified in BKEND_INFO. The target server then queries the back end for information about the event and notifies the tools that have registered to receive notification of the event.

1. If a tool makes a request, the target server either satisfies the request itself (for example, by looking up a symbol in the host-resident symbol table) or forwards the request to the back end (for example, by requesting that the back end set a breakpoint or read memory).

Shutting Down the Target Server

1. When the target server exits, it calls the back-end disconnect routine to clean up all resources that have been allocated by the back end.

1. Next, the target server disconnects all tools and removes its name from the Tornado registry (wtxregd).

1. Finally, the target server exits.

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

Figure 2-1:  WDB Back End

  

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. 

Figure 2-2:  Non-WDB Back End

  

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.

1:  The Tornado implementation is designed to work in both UNIX and Windows environments; thus, in most cases the terms can be used interchangeably. In this chapter, DLL refers to both Windows DLLs and UNIX shared libraries unless an explicit distinction is made.

2:  The current implementation of this protocol is based on Sun Microsystems RPC 4.0, which can be implemented on virtually any transport layer.