![[Contents]](icons/contents.gif){kind=icon}
![[Index]](icons/index.gif){kind=icon}
![[Prev]](icons/prev.gif){kind=icon}
![[Next]](icons/next.gif){kind=icon}
The following two protocols are particularly important, because they mediate all contact between a Tornado tool and the target:
Figure 1-1 illustrates the role of these two protocols in Tornado.
The WDB agent carries out requests transmitted from the target server, and replies with the results. The WDB agent contains a compact implementation of UDP/IP, which supports an RPC messaging protocol called WDB. The WDB protocol is a core minimum of the services necessary to respond to requests from the Tornado tools. These protocol requests include memory transactions, breakpoint/event notification services, virtual I/O support, and tasking control. The WDB protocol uses the Sun Microsystems specification for External Data Representation (XDR) for data transfer.
The WDB agent synthesizes the target-control strategies of task-level and system-wide debugging. The agent can execute in either mode and switch dynamically between them, provided the appropriate drivers are present in the Board Support Package (BSP). This permits debugging of any aspect of an embedded application whether it is a task, an interrupt service routine, or the kernel itself.
A significant feature provided by the WDB agent is its ability to interpret a simple language called Gopher (for a description of the Gopher language, see 4.3.11 Gopher Support). Gopher scripts are very compact strings that specify a target data structure (or a list of structures) of arbitrary complexity to be gathered and transferred to the host. Because this technique is interpretive, the target is not burdened with specialized routines to gather state information for every system object.
By virtue of a Gopher script, application developers can likewise gather application-object state information without burdening the application with state-information routines. The Gopher interpreter itself is very small (smaller than the amount of the memory that would otherwise be required by target routines to gather only the most essential system objects), and the language is compact to reduce communication overhead. The Gopher language is accessible at higher-level Tornado APIs.
The WDB agent's interface to communications drivers avoids the run-time I/O system, so that the WDB agent remains independent of the run-time OS. Drivers for the WDB agent are low-level drivers that provide both interrupt-driven and polling-mode operation. Polling mode is required to support system-level control of the target.
The WDB agent itself is independent of the target operating system: it attaches to run-time OS services through a virtual-function run-time interface. The WDB agent can execute before VxWorks is running (as in the early stages of porting a BSP to a new board) or even stand-alone.
Should your application require different function from that provided by the WDB agent, the target server can communicate with alternative agents by means of an alternative back end. For more information on non-WDB agents and back ends, see 2. Target Server Back End.
Target servers run on Tornado host systems. Each target server represents one development target. All tools access a target through its server, whose responsibility is to satisfy each tool's requests for target actions or target information. The target server manages all of the details of communicating with the target, so that tools are not concerned themselves with host-target transport details. Tornado tools use the WTX protocol to communicate with a target server.
In some cases, a request from a Tornado tool is passed directly to the WDB agent for execution on the target system. In other cases, requests can be managed entirely within the target server. For example, the target server caches recently-used regions of memory. This enables the target server to respond directly when a target-memory read hits a memory region that is already cached in the target server, thereby avoiding the need for an actual host-target transaction.
The target server architecture is shown schematically in Figure 1-2. and outlined in the following paragraphs.
The "front end" of the target server, this layer connects to Tornado tools, receives protocol requests and prepares replies, in the meantime calling target server subroutines to provide the services required.
The target server core contains the interpreter for the WTX protocol. It is here that the target server determines what services to perform locally on the host, and what services to pass along to the back end to transmit to the target. WTX services that can be carried out entirely in the target server are implemented in the target server core; general-purpose callbacks used by other parts of the target server also reside here.
The target server uses the symbol list contained in every object module to build a host-resident symbol table representing all loaded functions and variable names on the target system. Names from system and application modules alike are included in the target symbol table. The object module loader uses the symbol table to resolve external references and relocate symbolic references. Tornado tools can also manipulate the symbol table through WTX requests.
Central to the Tornado architecture is its ability to incrementally load object modules into the target system. Because modules can be loaded dynamically, development cycles are much shorter: when a developer changes a particular feature, only the affected module needs to be recompiled and reloaded, not the entire application. The loader uses the system symbol table to resolve undefined references in modules being loaded, dynamically linking newly loaded modules to previously loaded modules.
In addition, the target server provides the ability to unload modules from the system. When a module is removed, all the associated symbols are removed from the symbol table and memory is reclaimed.
Object modules come in many formats. The target server utilizes shared libraries on UNIX hosts and dynamically linked libraries (DLLs) on Windows hosts to isolate the OMF reader from the target server core. This makes it simple to add new object module formats without requiring a new release of the target server.
The loader requires memory from the target pool when allocating space for the linked module, and host-resident Tornado tools, such as the shell or debugger, also use some target memory as a working area. Rather than call upon the target to manage a pool of memory on the host tools' behalf, the target server manages a pool of target memory for all allocation requests originating on the host. The target memory manager maintains all bookkeeping structures (such as a free block list and block headers) on the host, and thus provides zero-overhead target memory allocation. When a tool asks for 24 bytes, it receives exactly 24 bytes of target memory (subject to alignment). The size of the pool managed by the target server is configured at target start-up time, but it can increase dynamically.
Some regions of target memory are good candidates for caching. The target memory cache, by default, caches the program text sections of all target-resident modules. Because it is highly unorthodox to modify the text of the program (beyond adding breakpoints), this use of the cache provides a considerable boost in performance for cross-debugging.
Your WTX application can call on the target server to disassemble a region of target memory. The target server disassembly facility differs from GDB disassembly in that it produces chip-manufacturer standard output instead of FSF standard output. The disassembler for each chip resides in its own shared library which is dynamically linked when the target server attaches to the target.
The Target Server File System (TSFS) is a full-featured VxWorks file system, but the files operated on by using the file system are actually located on the host. TSFS uses a WDB driver to transfer requests from the I/O system to the target server. The target server reads the request and executes it using the host file system and the host-target communication path. It is possible to access host files randomly without copying the entire file to the target, to load an object module from a virtual file source, to supply the file name to routines such as ld( ) and copy( ), and even to open a socket without installing the TCP/IP stack on the target.
Perhaps one of the most convenient aspects of the target server is its handling of the drudgery associated with managing a host-target connection mechanism. The back-end manager maps a transport-independent layer of subroutine calls, used by the rest of the target server, into the appropriate transport-dependent calls for a particular back end.
In some cases, certain back-end requests have no direct mapping to a particular back end. For instance, it is unlikely that an emulator can support the parsing of a Gopher script. In this case the back-end manager decomposes the request into more easily mapped target-memory reads. Likewise, the back-end manager behaves correctly in response to the inability of a back end to perform some types of breakpoint strategies. By virtue of Tornado's back-end management, tool providers can concentrate on enhanced functionality instead of porting to yet another connection strategy.
Whether it is as simple as an Ethernet connection, or as complicated as an emulator connection, the target server back end does whatever is required to communicate a WDB request to the target agent. As with the OMF readers, the target server back ends are organized as shared libraries on UNIX hosts, and as DLLs on Windows hosts. This allows introducing a new connection mechanism at any time.
The target server uses multiple threads to service WTX requests, target events, load requests, and VIO events efficiently. Figure 1-3 shows the various threads.
Each thread services a unique WTX client. When a tool connects to the target server, the target server creates a thread for it which processes all tool requests and exists until the tool disconnects.
This thread waits for and performs load requests. This allows the load to be performed asynchronously, so clients are free to do other operations while the load is in progress. It also means a load can be cancelled in process.
This thread waits for inputs from a target server virtual console and sends data to the associated virtual I/O channel. On Windows it is created when the target server is started with the -C (virtual console) option. On UNIX it is always available because UNIX permits consoles to be created at any time using wtxConsoleCreate and this thread is in place to support all consoles.
This thread waits for and handles target events. (For more information, see 2. Target Server Back End).
A central feature of Tornado is the rich set of APIs that allow access to each level of the technology. These APIs are outlined here to provide a broad view of what options are available to developers who wish to extend the Tornado environment.
The easiest APIs to learn about are those based on Tcl, in part because of the interactive nature of Tcl, but also because extensive examples are readily available. (If you are not familiar with Tcl, see the Tornado User's Guide: Tcl for an overview of the language and for references to more detailed expositions.) The Tcl source for all standard Tornado tools is included with every Tornado installation: for example, procedures for examining semaphores, dumping memory, spawning tasks, and so on are available for customization, extension, or simply for their educational value. On UNIX hosts, every aspect of the user interface is also under user control, from dialogs to menu items. (The graphical interface on Windows hosts is somewhat less configurable, in part due to the existence of interface standards on that platform).
The Tornado APIs are shown graphically in Figure 1-4. The following paragraphs discuss each interface:
This API provides a set of Tcl commands to create and configure graphical user interfaces (such as menus, buttons, dialog boxes, or charts). You can use this interface to create new Tornado tools or to customize existing tools like the launcher or browser.
This API provides a complete set of C routines covering all the WTX protocol services. Use this interface to create tools that access the target server or the Tornado registry, when you use C as the implementation language. The CrossWind debugger is implemented using this API.
The WTX Tcl API provides a complete set of Tcl commands covering all the WTX protocol services. Use this interface to create tools that access the target server or the Tornado registry, when you use Tcl as the implementation language. The Tornado shell and browser (and, on UNIX hosts, the launcher) are implemented through this API.
The WTX protocol defines a set of RPC requests interpreted by the target server or the Tornado registry. You can use RPC calls to send WTX protocol requests directly, but in order to simplify application development, we recommend the use of the WTX C or Tcl APIs instead.
Several C subroutine libraries provide callbacks to target server core services. These callbacks are required to write support for either a new object module format (OMF) reader, or a new target communication back end. The libraries listed in Table 1-1 collectively constitute the target server core API. The associated DLLs are shown in Table 1-2 and Table 1-3 for UNIX and Windows.
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
The OMF (object module format) reader interface specifies a set of format-independent subroutine calls to manage object code. A new shared library or DLL to support a new object-code format must define the subroutines specified by this interface.
The back-end interface specifies a set of transport-independent subroutine calls to manage communication with the target agent. A new shared library or DLL to support a new transport mechanism must define the subroutines specified by this interface.
The WDB agent relies on low-level device drivers to connect with the target server. The agent interface specifies what routines a device driver must provide to the WDB agent.
The remaining chapters of this manual discuss these APIs in more detail. Reference entries for all subroutines, protocols, and interfaces appear in the online reference material under Tornado API Reference.
The Tornado tree unifies all Wind River Systems products under a single directory with a common root. This greatly facilitates installation, and reduces the administrative overhead of managing path and environment variables.
The tree design makes it possible for Wind River Systems or third parties to add new products to the tree, and even update previously installed products to reflect the existence of the new product. For instance, on UNIX hosts the launcher can be extended to include an additional button to launch the new product, without requiring a rebuild or re-release of the base Tornado product.
The top-level Tornado directory structure includes three major directories (see the Tornado User's Guide: Directories and Files). Most references in this manual will be to files in the installDir/host directory, although this is not always the case. For example, if you install Tornado in /group/wind on a UNIX host or in C:\Tornado on a Windows host, the full pathname for the file shown as installDir/host/resource/tcl/app-config/WindSh is /group/wind/host/resource/tcl/app-config/WindSh (which is also $WIND_BASE/host/resource/tcl/app-config/WindSh) on UNIX or C:\Tornado\host\resource\tcl\app-config\WindSh on Windows.
|
|||||||||||||||||||
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
|
|
|||||||||||||||||||
In addition to the formal Tornado APIs, you can customize or enhance Tornado by overriding, changing, or adding to the files under the installDir/host/resource subdirectory. This directory contains all components of the Tornado implementation that do not require compilation, notably the Tcl procedures that implement the user interface (in installDir/host/resource/tcl).
Aside from Tcl source, the resource directory collects such things as mappings between target architectures and OMF libraries, bitmaps for screen objects, definitions for services that extend the WDB protocol, help files, and (on UNIX hosts) X Window System resources.
The installDir/host/resource/tcl/app-config directory includes a subdirectory for each Tornado tool. Every Tornado tool begins execution by sourcing all Tcl procedures contained in its resource subdirectory. For example, the shell (whose main Tcl source is in the file installDir/host/resource/tcl/shell.tcl) sources all of the files in the directory installDir/host/resource/tcl/app-config/WindSh, in alphabetical order. Thus, new features (such as buttons or menu items) can be added to Tornado tools by adding a new file to the appropriate subdirectory. (For local or personal customization, however, it is usually better to save customizations in a private .wind directory; see the Tornado User's Guide: Directories and Files for more information.)
Files are read in shell collating order (the same order that the files would be displayed by the ls or dir commands). This is why these files typically start with two numbers: so that new additions to this directory can be interleaved with existing files easily. In addition, to add a later modification that further extends an existing NetShow extension, you could provide a file called 01NetShow2.tcl, which would be read immediately after 01NetShow.tcl.
Fully harnessing the interpretive nature of the Tornado environment is the key to a successful Tornado integration. Wind River Systems encourages the enhancement of the Tornado environment using this technique. Unlike many other development frameworks, Tornado remains open to the extent that third parties can not only introduce new components, but override the look, feel, and even functionality of previously existing Tornado components.
To the extent that your organization permits it, you can also benefit other Tornado users by sharing your Tornado resource extensions. The comp.os.vxworks newsgroup is one appropriate vehicle, as is the archive maintained by the Wind River Users Group. See the Tornado User's Guide: Customer Service for information about finding these resources on the World Wide Web.
