NDIS Driver Developer's Tool Kit for OS/2 and DOS TestTool User's Manual

Purpose of this Manual
This document is the user manual for the NDIS Driver Test Tool (hereafter called TestTool). TestTool verifies the conformance of a network device driver to the NDIS specification version 2.0.1 and provides a method of stress testing the driver under load.

Prerequisite Knowledge
The information in this manual is oriented towards experienced programmers who are running and/or writing the scripts for TestTool. It is assumed that the reader is an experienced programmer familiar with OS/2 and NDIS.

TestTool is a powerful and general tool which allows exercise of every aspect of a driver's NDIS functionality. Many NDIS commands are not implemented by a specific driver. Hence a thorough general understanding of NDIS as well as the specific adapter card and its driver is necessary to derive full benefit from TestTool.

Chapter 1. Introduction
The NDIS specification provides a standardized way for network protocols to communicate with the hardware or physical layer of the network system. TestTool provides a way of testing that a driver conforms to the NDIS specification. TestTool also includes an interactive mode for testing compliance of individual segments of the driver during its development. Because the specification has several lends of communication between a MAC and a protocol, TestTool has multiple levels built in to test communications at each level.

TestTool consists of two separate software pieces, see Figure 1-1. One piece, Wedge, is an NDIS driver which is loaded at system initialization time, runs in Kernel Mode, and binds at its lower boundary with your MAC driver. The second piece, IBMTool runs in User Mode and controls TestTool's interface with the user. Upon execution of TestTool, an input output control (IOCtl) call allows IBMTool to take control of Wedge. This split into two separate programs is totally transparent to the user, who needs only be concerned with the aggregate, TestTool.

Figure 1-1: TestTool Configuration

At initialization, the Protocol Manager issues a system request to bind the MAC driver to Wedge. Successful Binding is necessary for the operation of TestTool, and is checked for at TestTool start up.

User Interface
Part of the user interface for TestTool is menu driven. At the top of the screen is the Menu Bar, enabling the user to display one or more of the NDIS support tables or receive help. Additionally, some status indications are displayed at the right of the Menu Bar. Below the Display Window is the Command Line, used for the entering of interactive commands. The bottom half of the screen is the Message Area, used for displaying messages from TestTool. See Figure 2-1.

Figure 2-1: Interactive Screen

Since TestTool is screen oriented, there are several keys which manipulate aspects of TestTool.

Tab key moves the cursor down into the message area, so that the up and down arrow keys will scroll the history of the message area up and down. This is a toggle. When the cursor key is in the message area, the Tab key will move the cursor back up to the command line.

Up/down arrow keys scroll up and down the command line history. This allows previous commands to be more easily repeated and even allows repetition of historical commands after editing.

Left/right arrow keys move the cursor left and right within the current command line.

Insert key toggles whether typing will insert at the cursor point or type over. The default is typeover mode. In typeover mode, the cursor will be a thin underline. In insert mode, the cursor will be a full block.

F10 key moves the cursor up to the status bar. Left and right arrow keys will change the currently displayed table. This is a toggle key. When the cursor is up on the status bar, the F10 key will move the cursor back down to the command line.

Alt key selects one of the status bar menu items. Each of the menu items has a letter which is highlighted. When the alt key is pressed with that highlighted letter, that item is selected.

Display Tables and Help Screen
Tables are displayed in the Display Window. Each table has an assigned key stroke and can be displayed at any time during testing, except while stress test is running. If tests are run that add values to the tables or update statistics within the tables, the new values are changed and display during the test. The following tables and help screens are available:

The table mentioned above conform in contents to their description in the 3Com**/Microsoft** LAN Manager** Network Driver Interface Specification, version 2.0.1 (October 8, 1990), as modified by IBM.

TestTool Modes
TestTool executes ID one (and only one) of three basic modes: Monitor Mode, Server Mode, or Workstation Mode. Additionally, while in one of the three basic modes, TestTool can also be places in Echo Mode. The commands MONITOR, SERVER, WKSTA, and ECHO allow the user to place TestTool into the indicated mode.

Monitor Mode is the default mode for TestTool. Its principal usage is for interactive testing of a MAC. In Monitor Mode the user can issue the full range of a TestTool comments (with the exception of JUMP). Monitor Mode may be used for stand-alone testing as well as in a networked environment for transmission or reception testing. However, in Monitor Mode, TestTool will not respond to TestTool command packets as produced by the SRVTX, WRSTA, and STRESS commands.

Workstation Mode can be used for transmission, reception or stress testing. When TestTool is first placed in Workstation Mode, it broadcasts a TestTool command packet advertising its presence ant requesting all modes running in Server Mode to respond with their address (see MULTRAN ant SRVTX). Nodes running in Workstation Mode will respond to TestTool command packets issued by a node in Server Mode requesting stress testing (see STRESS).

Server Mode can be used far transmission, reception or stress testing. Nodes running in Server Mode will respond to TestTool command packets issued by a node in Workstation mode requesting either transmission (see SRVTX) or the server address (see WKSTA). In order to conduct stress testing, the node initiating the test must be in Server Mode. It is strongly recommended that at most a single node on a network be in Server Mode.

Finally, Echo Mode can co-exist with any one of the three basic modes. While in Echo Mote, TestTool will re-transmit any frames which it receives back to their sender. At most one machine at a time should be in Echo Mode to avoid the possibility of perpetually echoing the same frame across the Network.

Stand Alone Testing
TestTool can be used in a non networked, stand-alone environment to conduct basic testing of a MAC driver. Of course, with only one note, neither transmission nor reception can be exercised. During stand-alone testing, neither Workstation nor Monitor Mode is appropriate.

Transmission/Reception Testing
TestTool can be used to test a MAC driver both for transmission and reception. While this testing can be accomplished manually with both machines in Monitor Mode, it can be more easily accomplished with one machine, containing the MAC under test, in Workstation Mode and a second machine in Server Mode.

Transmission can be tested either with the TRAN or MULTRAN commands. Transmission may be tested manually by the TRAN command, which initiates a single transmission of the current TX buffer. Transmission can also be tested by the MULTRAN command, which initiates multiple transmission of increasing length, TestTool generated data. MULTRAN can be used to direct transmission to the current server.

Reception can be tested with the SRVTX command. This command causes a TestTool command packet to be sent to a second machine, running TestTool in Server Mode, instructing the server to transmit frames back to the machine whose ability to receive is being tested. Frames are transmitted from the server in the same format as the MULTRAN command, with increasing length, TestTool generated data.

Stress Testing
Stress testing is designed, using multiple computers an one network, to test a MAC's performance. The object of a stress test is to load down a network server with as many frames as possible. This tests whether the MAC driver will corrupt data or become non-functional during heavy network traffic conditions. In order to perform Stress testing all machines must be running TestTool. One machine, containing the MAC under test should be running TestTool in Server Mode, the remainder of the machines should be running TestTool in Workstation Mode.

Stress testing is initiated by issuing the STRESS command from the machine in Server Mode. That machine then a broadcasts a TestTool command packet to alert the workstations that stress testing is to commence and to instruct them as to how many frames to transmit. The workstations then bombard the server with frames, and the server attempts to echo these frames back. TestTool keeps track of activity and checks for data corruption.

Script Files
TestTool allows the use of automated tests that do not require interaction from the keyboard. All of the commands that can be used in interactive mode can be entered into an ASCII Script File. The commands in this Script File will be executed by issuing the RUN command.

Along with the interactive commands, there is a special decision command, JUMP, which can perform conditional or unconditional jumps to subsequent commands in the Script File. A Script File may also contain a label to be used in conjunction with the JUMP command.

User Commands can be issued to control the status and actions of TestTool or to perform interactive NDIS compliance testing.

In order to prepare for running Script Test Files or for Stress Test, Control Commands may be issued. In order to interactively test for compliance with the NDIS specification, General Requests and Direct Primitives commands may be issued. These commands deal with various aspects of the NDIS specification.

Control Commands
Control Commands are issued in order to prepare for running Script Test Files or for Stress Testing.

The following are the Control Commands:

General Requests
TestTool provides the ability to send single or multiple requests to all of the general request functions specified in the NDIS. The requests are sent to the MAC as described in the NDIS and the codes returned by the MAC are displayed in the interactive screen. If the MAC returns REQUEST_QUEUED, TestTool will also display the subsequent General Request Confirmation, including the request handle, completion code, and return code.

The following are the General Request User Commands:

Direct Primitives
TestTool supports sending direct primitive commands to the MAC. TestTool also accepts and processes direct commands from a MAC to TestTool.

When a direct primitive command is processed by TestTool, it displays the command and its parameters. When the command completes, TestTool displays the return codes. Part of the job of TestTool is to create a unique handle for each direct primitive command sent to a MAC. It also tests to be sure that a MAC returns completion codes associated with the appropriate handle.

The following are the Direct Primitive User Commands:

Chapter 3. Command Descriptions
This chapter is devoted to detailed descriptions of each User Command, arranged in alphabetical order. These descriptions are given in the following format:

Notices
January, 1996

Issued by:
 * IBM Corporation
 * Personal Software Products
 * 11400 Burnet Road
 * Austin, Texas 78758

Second Edition (January 1996)

First Edition (May 1993)

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or program(s) described in this publication at any time.

It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

Copyright Notices
© '''Copyright International Business Machines Corporation 1993. All rights reserved.'''

Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Disclaimers
References in this products to IBM products, programs or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of the intellectual property rights of IBM may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products except those expressly designated by IBM, are the responsibility of the user.

IBM may have patents or pending patent applications covering subject matter this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries in writing to the IBM Director of Commercial relations IBM Corporation Purchase NY 10577 - USA

Trademarks
The following terms denoted by an asterisk (*) in this publication are trademarks of the IBM Corporation in the United States and/or other countries:
 * IBM OS/2

The following terms denoted by a double asterisk (**) in this publication are trademarks of other companies as follows:
 * Microsoft    Microsoft Corporation
 * LAN Manager  Microsoft Corporation
 * 3Com         3Com Corporation