Tornado API

Programmer's Guide

2.0

Edition 1

[Copyright][Online Manuals]

Contents

1 Tornado Architecture
1.1 Introduction
1.2 The WDB Agent and the WDB Protocol
1.3 The Target Server and the WTX Protocol
1.4 Target Server Threads
1.5 Overview of Tornado APIs
1.6 Tornado Tree Organization
1.6.1 Path Name Conventions
1.6.2 Tornado Libraries
1.6.3 Resources
1.7 Coding Conventions
2 Target Server Back End
2.1 Introduction
2.1.1 Target Server Overview
2.1.2 Back-End Overview
WDB Back Ends
Non-WDB Back Ends
2.2 Back-End Implementation
2.2.1 Attachment and Initialization
The Flag Parsing Routine
The Initialization Routine
The TGT_OPS Structure
The BKEND_INFO Structure
2.2.2 Back-End Functions
2.2.3 Event Notification
2.2.4 Designing a select-like routine
2.2.5 Handling Target-Board Reboots
2.2.6 Cleaning Up the Tornado Registry
2.2.7 Message Logging
2.2.8 Informing Windows About a New Back End
2.3 Writing a New WDB Back End
2.3.1 Overview of Writing a WDB Back End
2.3.2 WDB Protocol
Protocol Overview
Requests Sent to the Agent
Replies Sent by the Agent
Reply Errors
Asynchronous Notification Sent By the Agent
2.3.3 Host-Side Code
Back-End Initialization: wdbserial.c
Client-Side RPC Implementation
Building a Back End for UNIX Hosts
Building a Back End for Windows Hosts
2.3.4 Target-Side Code
Writing a Network Interface Driver
Writing a WDB Packet Driver
Build Issues
2.3.5 Testing
2.4 Writing a Non-WDB Back End
2.4.1 Overview of Writing a Non-WDB Back End
Design
Implementation
Wind River Conventions
Testing
2.4.2 Setting Up the Back-End Developer's Kit
Design Considerations
Implementation
Porting
Testing
2.4.3 Getting Started
Creating a Framework
Implementation
Building the Back End on UNIX
Building on Windows NT and Windows 95
Testing
2.4.4 Implementing Mandatory Member Functions
Implement Read and Write
Implement Context Management
Implement Event Handling
2.4.5 Implementing Optional Member Functions
2.4.6 Performance
3 Object-Module Loader
3.1 Introduction
3.2 Terminology
3.3 Loader Overview
Linking and Loading
Bootstrapping the Target Server Symbol Table
3.4 Using the Target Server Loader
3.4.1 Loader Usage from the Tornado Shell
3.4.2 Loader Usage From wtxtcl
3.4.3 Loader Usage From the WTX C API
3.4.4 Asynchronous Load Operation
3.5 Loader Architecture
3.5.1 Object-Module Configuration in Target Memory
Relocatable Files
Fully Linked Files
3.5.2 Module Management
3.5.3 Symbol Management
3.5.4 Loader Options
Symbol Scope
Module Visibility
Module Type
Common Symbols
Special Options
3.6 Memory Management
3.6.1 Memory Alignment
3.6.2 Target Server Memory Cache
3.6.3 Target Virtual Memory and Cache Management
3.6.4 Type Abstractions and Address Manipulation
3.7 Generic Loader-Library Interface
3.8 Target Server Loader Thread
3.9 Writing an OMF Manager
3.9.1 Dynamically Linked Library Implementation
3.9.2 Installing a Shared-Library Manager
3.9.3 Naming Conventions
Interface Routines
File Names
3.9.4 The RU Interface
3.9.5 The OMF Interface
3.9.6 Byte Order
3.9.7 OMF Header Processing
3.9.8 Determining the Size of the Segments
3.9.9 Reading the Object-Module Symbol Table
3.9.10 Determining the Compiler Signature
3.9.11 Allocating Memory For the Segments if Required
3.9.12 Reading in the Segments
3.9.13 Target Server Symbol-Table Processing
3.9.14 Relocating the Object Modules
Reading in Relocation Entries
Relocation Process
3.9.15 Downloading Relocated Modules to Target Memory
3.9.16 Managing Memory
3.9.17 Notes on Asynchronous Load Operation
3.9.18 Utility Functions and Error Logging
4 The WTX Protocol
4.1 Introduction
4.2 Protocol Overview
4.2.1 Language Support
4.2.2 WTX Protocol Usage
4.2.3 WTX Message Format
4.2.4 Debugging WTX Tools
4.3 WTX Facilities
4.3.1 Session Management
4.3.2 Symbolic Debugging Support
4.3.3 Attaching to a Target Server
4.3.4 Target Memory Access
4.3.5 Target Memory Disassembly
4.3.6 Object-Module Management
4.3.7 Symbol Management
4.3.8 Context Management
4.3.9 Virtual I/O
4.3.10 Event Management
Event-String Examples
Asynchronous notification (C API only)
4.3.11 Gopher Support
How the Gopher Language Works
A Gopher Script for Sample Data Structures
The Gopher Result Tape
Sending the Gopher Script to the Target Agent
4.4 WTX Tcl API
4.4.1 Description
4.4.2 Starting a wtxtcl Session
4.4.3 Attaching to a Target Server
4.4.4 Obtaining Target Server Information
4.4.5 Working with Memory
4.4.6 Disassembling Memory
4.4.7 Working with the Symbol Table
4.4.8 Working with Object Modules
4.4.9 Working with Tasks
4.4.10 Working with Events
Registering for Events
Unregistering for Events
Checking the Event Queue
Generating and Retrieving Events
4.4.11 Working with Virtual I/O
Virtual Output
Virtual Input
4.4.12 Calling Target Routines
4.4.13 Working With Multiple Connections
4.4.14 Timeout Handling
wtxTimeout
wtxCmdTimeout
-timeout
4.4.15 Error Handling
4.5 WTX C API
4.5.1 Description
4.5.2 WTX C API Archive
4.5.3 Initializing a Session
4.5.4 Obtaining Target Server Information
4.5.5 Attaching to a Target Server
4.5.6 Application Example
4.6 Integrating WTX with Applications
4.6.1 Using the Tcl and C APIs Together
4.6.2 Integrating WTX Tcl with Other Tcl Applications
5 Extending Tornado Tools
5.1 Introduction
5.2 Outlining the Example Problem
5.3 Extracting Information from a Structure
5.3.1 Definitions and Structures
5.3.2 Locating the Start of the First Structure
5.3.3 Listing All Network Interfaces
5.3.4 Listing the Contents of Each Structure
5.4 The Shell Presentation
5.5 The Browser Presentation
5.5.1 UNIX Implementation
Creating the Hierarchy Window Display
Installing the New Browser Panel
5.5.2 Windows Implementation
6 Adding Tools to Tornado
6.1 Introduction
6.2 Creating a Tornado Application
6.2.1 Example Specifications
6.2.2 Directories and File Naming
6.2.3 Building the Application
6.2.4 Compiling the Application
UNIX Hosts
Windows Hosts
6.2.5 Testing the Application
UNIX Hosts
Windows Hosts
6.2.6 Creating Documentation
6.3 Installing a New Application in Tornado
6.3.1 The Tornado Launcher (UNIX Hosts)
6.3.2 The Launch Toolbar (Windows Hosts)
6.4 Distributing and Publishing New Applications
7 Integrating Third-Party Toolchains
7.1 Introduction
7.2 Creating the Makefile fragment
7.3 Exposing the Toolchain to the Project Facility
7.4 Testing
7.5 Sample Makefile
A Tcl Coding Conventions
A.1 Introduction
A.2 File Heading
A.3 Tcl Module Layout
A.4 Tcl Procedure Layout
A.5 Tcl Code Outside Procedures
A.6 Declaration Formats
Variables
Procedures
A.7 Code Layout
Vertical Spacing
Horizontal Spacing
Indentation
Comments
A.8 Naming Conventions
A.9 Tcl Style
Index