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

From EDM2
Jump to: navigation, search



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.

Testt101.gif 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.

Chapter 2. Using TestTool

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.

Testt102.gif 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:

Menu Key Stroke
Common Characteristics Table Alt-O
Service-Specific Characteristics Table Alt-C
Service-Specific Status Table Alt-S
Multicast Buffer Alt-M
Service Flags Alt-F
Media Specific Status Table Alt-D
CCB Interface Table Alt-B
Help Screen Alt-H

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.

Testing with TestTool

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.

User Commands

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:

Name Description Name Description
CHKDATA Toggle Data Checking READMAC Read MAC Service Specific Characteristic
CHKIND Check Indications RUN Run Script File
CHKLK Check Receive
Lookahead Length
RXBUF Display Receive Buffer
CHKSTAT Check Status Variable RXRLS Receive Release
CHKTOKEN Check Token Ring RXWAIT Toggle Wait for Release
CLRIND Clear Indications SERVER Set the Server Mode
CLRMAC Clear MAC to Initial State SETSTAT Set Status Variable
ECHO Toggle Echo Mode SLEEP Sleep
EDITBUF Edit Current Transmit Buffer SRVTX Server Transmit
EXIT Exit TestTool STRESS Stress Test
HELP Help Screen TXBUF Display Transmit Buffer (s)
JUMP Jump to Script Label TXSIZE Set Transmit Buffer Size and Count
LOG Start Log to File USEGDT Toggle GDT Usage
MONITOR Set Monitor Mode WKSTA Set Tool into "Workstation" Mode
QUIT Exit TestTool ? Pop up Help List

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:

Name Description Name Description
ADDMC Add Multicast or Group Address MODOPEN Modify Open Parameters
CLOSE Close Adapter OPEN Open Adapter
CSTAT Clear Statistics READLOG Read Error Log
DELMC Delete Multicast or Group Address RESET Reset MAC
FILTER Set Packet Filter SETLOCK Set Lookahead Length
FUNADR Set Functional Address SETSTN Set Station Address
INITDIAG Initiate Diagnostics USTAT Update Statistics
INTREQ Interrupt Request    

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:

Name Description Name Description
INDICOFF Indication Off MULTRAN Transmit Multiple Frames
INDICON Indication On TRAN Transmit Buffer

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:

Name This gives the command name and a brief description of the command. For example: ADDMC - add multicast adders
Syntax The Syntax section gives the format of the command and the type of operands allowed. Most commands allow hexadecimal as well as decimal values for numeric parameters. If a numeric parameter has a 0x preceding the value, then the value is taken as hexadecimal. The default interpretation is decimal. An exception to this default is network addresses. Network addresses are always interpreted as hexadecimal, and require no preceding Ox. For example, 0x13 is interpreted as a decimal 19 for most commands, while 13 is interpreted as decimal 13.
Description The Description section describes what the command does. It also gives utilization hints when appropriate.
Example The Example section gives one or more examples of command usage.
See Also The optional See Also section lists related commands.

ADDMC - Add Multicast or Group Address

Syntax ADDMC <NetAddr>
Description Adds a multicast or group address to the multicast address list. After adding a multicast address (or setting the group address), the MAC may send up frames sent to that multicast/group address (see restrictions set by the filter). If the MAC controls a Token Ring adapter, then this command sets the current group address. It is the MAC's responsibility to return an error if too many multicast addresses have been added by returning OUT_OF_RESOURCE or INVALID_PARAMETER. If any attempt is made to add an illegal multicast address, it is the MAC's responsibility to return INVALID_PARAMETER. If an attempt is made to add a multicast address which is already in the list, the MAC must return INVALID_PARAMETER. If the MAC is Token Ring, the group address may be overwritten; no requirement is made to delete the previous group address. The MAC must be able to contain as many multicast or group addresses as the service specific characteristics table specifies. If the MAC does not support multicast or group addresses, it must respond with NOT_SUPPORTED. If a MAC supports multicast addresses, then it cannot support group or functional addresses, and vice-versa. See the service flags in the service-specific characteristics table in the NDIS specification.
Example ADDMC C0 00 80 01 02 03
This sets the group address to "C0 00 80 01 02 03" for a Tolled Ring type MAC. This is an example of a legal group address for an 802.5 type MAC.

ADDMC 01 02 03 04 05 06
This sets the multicast address to "01 02 03 04 05 06" for an Ethernet type MAC. This is an example of a legal 802.3 multicast address.


CHKDATA - Toggle Data Checking

Description Toggles the data checking on received frames. TestTool checks that the data is the descending byte data described in MULTRAN. If data checking is enabled, a 'C' will be placed in the upper right corner of the menu bar.
Turns data checking on if was previously off, or off if data checking previously on.

CHKIND - Check Indications

Syntax CHKIND <Count> [<Type>]
Description Checks the indication queue. If only the count is present, TestTool counts the total number of indications present since the last CLRIND command (or startup) and compares that total to the given count. If they are equal, the current NDIS return status is set to SUCCESS (for use with a conditional JUMP command). If they are not equal, the current NDIS return status is set to GENERAL_FAILURE. Therefore if checking both the number of indications and the return code of the latest MAC command, one must check the return code first, because the return code will be over-written by the CHKIND command. If a type is present, the command will count only that type of indications for comparison. The valid types are: Tx for Transmit Completion, Rx for Receive Lookaheads and Receive Chains, Stat for Status Indications, IComp for Indication Completes, and GenReq for General Request Confirmations. For Stat type indications, another parameter may be added which indicates the type of status indication. The valid types of status indication are: Ring for a ring status, Adapter for an adapter check, Start for a reset start, End for a reset end, and Int for an interrupt request status.
Example CHKIND 4
Checks for four indications in the indication queue. If exactly four are found, the NDIS return code is set to SUCCESS, else it is set to GENERAL_FAILURE.

Checks for two TransmitConfirm indications. If exactly two TransmitConfirm indications are found, the NDIS return code is set to SUCCESS, else it is set to GENERAL_FAILURE.

CHKIND 1 Stat Ring
Checks for one Ring Status indication. If exactly one Ring Status indication is found, the NDIS return code is set to SUCCESS, else it is set to GENERAL_FAILURE.

CHKLK - Check Receive Lookahead Length

Syntax CHKLK <Length>
Description Checks whether the last Receive Lookahead length was equal to the given length. This is useful in scripts to check whether a MAC correctly implements the Set Lookahead Length NDIS request.
Example CHKLK 128
Checks whether the last Receive Lookahead length was 128 bytes long. If it was, the NDIS return code is set to SUCCESS, else it is set to GENERAL_FAILURE.
See Also SRVTX

CHKSTAT - Check Status Variable

Syntax CHKSTAT <Value>
Description Checks whether the status variable is equal to the value given on the command line. If it is equal, the NDIS status value is set to SUCCESS, else it is set to GENERAL_FAILURE. This status variable is a good way to keep track of the failure of a script without having to abort the first error.
Example CHKSTAT 128
Checks whether the last status variable is equal to 128.

CHKTOKEN - Check Token Ring

Description Checks whether the current MAC is a Token Ring 802.5 MAC. TestTool checks the media type of the MAC in the Service Specific Characteristics table. If the type is 802.5, then the current NDIS return value is set to SUCCESS. If it is not equal to 802.5, then the current NDIS return value is set to GENERAL_FAILURE.
This checks if the MAC is a Token Ring MAC, and if it is, it jumps to the NextTest label.

CLOSE - Close Adapter

Syntax CLOSE
Description Decouples the adapter from a network so that packets cannot be sent or received. This command should force the MAC to reset functional or multicast addresses currently set.
Example CLOSE

CLRIND - Clear Indications Counters

Description Clears the TestTool indications counters. TestTool receives indications from Wedge and classifies these indications. For each class, there is a counter which TestTool increments upon encountering an indication of that type. In this manner, one can test for a certain number of transmit confirms or received frames. The CLRIND command can clear these counters before a tested action.
Example CLRIND
Clears indications counters.

CLRMAC - Clear MAC to Initial State

Description Sets the filter to 0, deletes all multicast addresses in the multicast list, closes the adapter, and then sets the current station address to the permanent station address. The command invokes multiple NDIS requests.
Example CLRMAC

CSTAT - Clear Statistics

Syntax CSTAT
Description Resets the MACs statistics counters. All statistics must be reset to zero in an atomic operation. If a statistic is not supported, the MAC must ensure that that statistic counter remains -1 after a clear statistics command.
Example CSTAT
See Also USTAT

DELMC - Delete Multicast or Group Address

Syntax DELMC <NetAddr>
Description If the MAC is an 802.5 (Token Ring) MAC, then this command deletes the given group address. If the MAC is an 802.3 or DIX+802.3 MAC, then this command deletes the given multicast actress from the current multicast address list. In either case, the MAC should no longer send up frames which correspond to the given group/multicast address. If the given address is not currently in the multicast list or set as the current group address, then the MAC must return INVALID_PARAMETER.
Example DELMC C0 00 80 01 02 03
Deletes the 802.5 group address C0 00 80 0l 02 03 from the MAC's group address list. The MAC should no longer send up frames corresponding to that group address.

ECHO - Toggle Echo Mode

Syntax ECHO
Description When ECHO is on, all received packets/frames have their destination address set to the source address and the source address set to the current station's address. Thus all frames are echoed back to the sender. This can consume all the CPU time on a machine if echo is on, loopback is supported, and the machine transmits a frame which it can receive, such as a broadcast frame. In this case the machine will continuously echo the one frame sent out. A similar situation can occur when multiple machines have echo on.
Example ECHO

EDITBUF - Edit Current Transmit Buffer

Syntax EDITBUF <i|#> <hexdata>
i - immediate buffer
# - the number of the transmit buffer after the immediate buffer
Description Sets the data in the transmit buffer. Transmit buffers must first be allocated with the TXSIZE command, and then they can be initialized with data. The immediate buffer is automatically allocated as 64 bytes long and may be used immediately. Buffers start with the immediate buffer and numbered buffers follow. Therefore, the immediate buffer is first, the 0 buffer is second, the 1 buffer is third, and so forth. The hexdata describes the initializing data for the given buffer. Note: although the data is hexadecimal notation, any repeat prefix is interpreted as decimal. See examples below. Any given initializing data which does not fit into the transmit buffer will be discarded. If a transmit buffer has not been allocated with the TXSIZE command, the EDITBUF command will be ignored.
Example EDITBUF I 10 40 62*FF
Fills the immediate buffer with 0x10, 0x40, and 62 of 0xFF's.

Sets the first nine bytes of the 3 buffer (actually the 5th buffer, counting the immediate and the 0 buffer) with "0F 42 AD DE EF BE 10 AD".


EXIT - Exit TestTool

Syntax EXIT
Description Exits TestTool. Useful when wanting to run another program.
Example EXIT
See Also QUIT

FILTER - Set Packet Filter

Syntax FILTER <FilterMask>
Description Tells the MAC what kind of received packets should be accepted. The given filter is actually a bit-mask, with the different bits representing types of packets. If the bit for a packet type is set, the MAC should send that packet to the above protocol.

Bit         Packet Type
0            Directed and group/multicast
1            Broadcast
2            Any (promiscuous bit)
3            Source routing

The promiscuous bit is related to the MAC's support of promiscuous mode in the service-specific characteristics table service flags. IF the MAC supports promiscuous mode and if the filter is set with the promiscuous bit set, then any packet on the LAN should be sent up by the MAC to the protocol. Promiscuous mode support includes sending packets which are not addressed to the current station address. Essentially, promiscuous mode is useful for a network monitor.

Example FILTER 3
This sets bit 0 and bit 1 for the filter mask. This allows directed, group/multicast, and broadcast packets to be sent up to the protocol.

This sets the promiscuous bit and indicates that all packets should be sent up to a protocol.

FUNADR - Set Functional Address

Syntax FUNADR <Functional Address>.
Description Set the IEEE 802.5 functional address specification. An 802.5 functional address contains 6 bytes, just as a normal 802.5 network address does. However, the NDIS specification takes advantage of the fact that the first two bytes of at 802.5 functional address are always identical. Therefore, only the last 4 bytes are significant. Functional addresses are bit masks, so deleting a functional address means clearing a bit in the current functional address. When the current functional address is 0, no functional packets will be received.
Example FUNADR 01 02 03 04
This sets the current functional address to "01 02 03 04".

HELP - Help Screen

Syntax HELP
Description Pops up a brief description of every command. Help pops back down with any key pressed.
Example HELP
Pops up help screen
See Also ?

INDICOFF - Indication Off

Description Used to prevent the generation ReceiveLookahead, ReceiveChain, and Status Indications from the MAC. INDICOFF commands may be nested. For indications to be turned back on, the INDICON command must be used as many times as the INDICOFF command.
This turns off indications.

Command'         'Indications After Command
INDICOFF       Off
INDICOFF       Off Off
INDICON        Off
INDICOFF       Off Off
INDICOFF       Off Off Off
INDICON        Off
INDICON        Off
INDICON        On

This example shows how indication control can be nested. Indications are turned off by the first INDICOFF, and are not turned back on until the last INDICON. The second INDICOFF turns indications doubly. The second INDICON negates only one of the previous INDICOFF commands. Indications control may be thought of as similar to parentheses.


INDICON - Indication On

Description Re-enable indications after having disabled them.
Example Turns indications back on, or, if multiple INDICOFF commands were used,counters one of those INDICOFF commands. If indications were not off, this should be ignored by the MAC.

INITDIAG - Initiate Diagnostics

Description Causes the MAC to run hardware diagnostics and update its status information in the MAC-specific status section of the characteristics table. This may not be supported by all MACs. While the diagnostics are running, the MAC must set the diagnostics bit in the status field in the MAC service-specific status table. If any errors are encountered during the diagnostics, the appropriate bits must be set in the status field of the service-specific status table.

INTREQ - Interrupt Request

Description Request an asynchronous status indication at some interrupt context. A MAC may choose not to generate this status indication if another asynchronous status indication is pending.
Example INTREQ

JUMP - Jump to Script Label

Syntax JUMP [["!"] <Condition> [<Label>]
Description Jumps to skip execution of some TestTool commands. The condition parameter is any NDIS return code, e.g., SUCCESS, REQUEST_QUEUED, and FRAME_REJECTED. TestTool will not, however, be notified of the return status of TransferData. This allows synchronous events to be checked without regard for the possibilities of asynchronous frame reception. If the "!" is not present, the jump is taken if the last MAC call returned the given condition code. If the "!" is present, then the JUMP is taken if the last MAC call did not return the given condition code. No whitespace may exist between the "!" and the NDIS return code. If the condition is not present, the jump is always taken. A label in a script is a command line starting with a colon followed immediately by a label. For this command, a label would be the rest of the line following the colon. Whitespace is not allowed in labels. If the label is not present on the command line, then the jump command merely skips the next command. This command is valid only when TestTool is reading command input from a file.
Example JUMP
Skips the execution of the next command.

Skips the execution of the next command if the last returned status code from the MAC was FRAME_NOT_RECOGNIZED.

Skips the execution of the next comment if the last returned status was not SUCCESS.

Label in a script file. Ignored during execution and searched for in the JUMP command. If identical labels exist in a script file, a JUMP command will start execution at the first of these identical labels in the file.

JUMP NextTransmit
Starts executing counts in the script at the first occurrence of the NextTransmit label.

Starts executing commands in the script file at the first occurrence of the FilterNotAccepted label if the last NDIS return code from the MAC was INVALID_PARAMETER.

LOG - Start Log to File

Syntax LOG [<Filename>]
Description Starts or stops logging all messages and commands to log file. If logging is off, then the filename parameter must be present. Logging will then start being output to that file. If logging is on, and the filename parameter is not present, then logging is turned off. If logging is on and the filename parameter is present, then logging remains on, but the new file is used to store further log output. The letter L appears on the right hand side of the status line (at the top of the screen) when logging is on.
Example LOG test1.log
Starts logging to test1.log of all commands and messages.

If logging was on, this turns logging off. Otherwise this is invalid syntax.

MODOPEN - Modify Open Parameters

Syntax MODOPEN <OpenOptions>
Description Direct a MAC to change the adapter specific OpenOptions on the adapter. The parameter is actually only a numeric value, although the value may control multiple options. This command is MAC specific. However, Token Ring adapters usually support this command as an entry into the Modify Open Parameters command on the TMS380. Refer to the TMS380 documentation on open parameters.
Example MODOPEN 0x0020
Sets bit 5 in the token ring adapter's open option
See Also OPEN

MONITOR - Set Monitor Mode

Description Sets Monitor mode for TestTool. Monitor mode is the neutral and default mode of TestTool. In Monitor mode, TestTool will not respond to server command packets (as produced by the SRVTX ant WKSTA commands), nor will it respond to workstation command packets (as produced by commands such as STRESS).
Sets monitor mode in TestTool.

MULTRAN - Transmit Multiple Frames

Syntax MULTRAN [<Count> [<Min><Max><Type>]]
Description Transmit # number of frames of length <min> to length <max> of the given type. TestTool attempts to evenly space out the transmitted frame lengths amidst the given minimum and maximum lengths. The default number of frames to transmit is 50. The default minimum frame length is the length of the header, and the default maximum frame length is the maximum frame length detailed in the MACs service-specific characteristic table. The type parameter is explained below.

Type Syntax        Description
0                           Broadcast, the default
1 <netaddr>          Directed to the given address.
2                           Directed to the current server.

If there is no current server and a server type frame is specified, the directed address will be zero filled. The data in the frame is continuously decreasing, with the terminating byte being one. Therefore, the first byte of data is (data_length & 0xFF), the second byte is (data_length-1) & 0xFF), the third byte is (data_length-2 & 0xFF), etc. The data length is the length of the frame minus the length of the header. The header length is media specific.

Example MULTRAN 1 512
Transmit a 512-byte frame. If the header was 16 bytes long (like an 802.5 frame), the data would be: F0 EF EE ED EC EB EA E9 ... 02 01 00 FF FE ... 03 02 01

Transmit 50 frames ranging from the length of the topology header length to the MAC specified maximum frame length.

Transmit 15 frames ranging from the length of the topology header length to the MAC specified maximum frame length.

MULTRAN 10 100 200 0
Transmit 10 broadcast frames ranging from 100 bytes to 200 bytes in length.

MULTRAN 32 50 3000 1 01 02 03 04 05 06
Transmit 32 frames ranging from 50 bytes to 3000 bytes in length, directed to the '01 02 03 04 05 06' network address.

MULTRAN 20 30 1500 2
Transmit 20 frames ranging from 30 bytes to 1500 bytes in length directed to the current server.


OPEN - Open Adapter

Syntax OPEN <OpenOptions>
Description Activate an adapter's network connection. The open option is adapter specific. For an example, most TMS380 MAC's utilize this option to initialize the TMS380.
Example OPEN
Opens the MAC connection to the network.

OPEN 0x0020
Sets bit 5 in the token ring adapter's open option.


QUIT - Exit TestTool

Syntax QUIT
Description Exits TestTool.
Example QUIT
TestTool terminates.
See Also EXIT

READLOG - Read Error Log

Syntax READLOG <LogLen>
Description Causes the read error log request to be issued to the adapter and reads <LogLen> bytes. The error log is adapter specific in composition.
Example READLOG 10

READMAC - Read MAC Service Specific Characteristic Table

Syntax READMAC <TableID> <ByteOffset> [<Operation><TestVAlue>]
Description Reads a byte at <ByteOffset> from the <TableID> MAC table and then may either test for equality or perform a logical AND operation with the given test value. The command returns SUCCESS if the equality is true or if the AND operation returns a non-zero result. If the converse is true, the command returns GENERAL_FAILURE. This command is useful in test scripts because TestTool can jump conditionally to labels depending upon the current return status.
Example READMAC MCC 35
Reads byte 35 of the MCC and prints the byte value down in the message area. This form does not return any value for conditional jumps.

Checks byte 40 of the MCC and tests whether it is equal to 10. If the byte is 40, the command returns SUCCESS. If it is not equal to 40, the command returns GENERAL_FAILURE.

Reads byte 10 of the MSC and checks if bit 3 is set. If the bit is set, the command returns SUCCESS. If it is not set, the command returns GENERAL_FAILURE.


Syntax RESET
Description Resets the MAC software and adapter hardware.
Example RESET

RUN - Run Script File

Syntax Run <ScriptFile> [<LogFile>]
Description Starts executing commands from a file. If the optional LogFile parameter is given then logging will be set to that file. If logging was previously on, then logging to that file will be terminated. When done executing commands from that file, TestTool will return to interactive usage.
Example RUN addmc.scr
Starts executing commands from the addmc.scr script file.

RXBUF - Display Receive Buffer

Syntax RXBUF ["P"]
Description Display the receive buffer. "P" is pause mode.
Example RXBUF
Displays the current receive buffer in non-pause mode.

Displays the buffer in pause mode. TestTool pauses every page for the user to press a key.

RXRLS - Receive Release

Syntax RXRLS <Handle>
Description Releases a receive chain frame descriptor back to the MAC. When the MAC performs a Receive Chain, Wedge will not perform an automatic Receive Release if the RXWAIT is set on.

If the Receive Release is not automatically performed, a manual RXRLS command must be performed. A MAC possesses a finite number of receive chain descriptor. These must be freed back to the MAC, or the MAC will run out of these receive descriptors. The handles for these receive chain descriptors will be given in the receive chain message.

Example RXRLS 14
Releases receive chain descriptor given by the handle 14 in a receive chain call.

RXWAIT - Toggle Wait for Release

Description Toggles whether Wedge will perform return WAIT_FOR_RELEASE from Receive Chain calls. If the RXWAIT is set on, an R will appear in the right hand side of the status line (at the top) and any calls to Wedge of Receive Chain will return WAIT_FOR_RELEASE. If RXWAIT is off, SUCCESS is always returned from Receive Chain.
Example RXWAIT
See Also RXRLS

SERVER - Set Server Mode

Description Sets TestTool to Server Mode. When TestTool is in Server Mode, it will respond to remote requests for transmission and can initiate a stress test.
Example SERVER

SETLOOK - Set Lookahead Length

Syntax SETLOOK <Length>
Description Sets the length of lookahead information for ReceiveLookahead. The lookahead length is maintained by the MAC. The NDIS specification states that the lookahead length maintained by a MAC may be increased, but it may never be decreased. Therefore , if the current lookahead length is higher than the requested length, the request will return SUCCESS , and the maintained lookahead length will remain at the higher value. Most MAC drivers will limit lookahead lengths by returning INVALID_PARAMETER for lookahead lengths greater than 256. If INVALID_PARAMETER is returned, the maintained length is not modified.
Example SETLOOK 128
Sets the current lookahead length to 128, unless the current lookahead length is already greater than 128.

SETSTAT - Set Status Variable

Syntax SETSTAT <Value>
Description Set the status variable to the integer value passed on the command line. This variable is useful in scripts, because it can retain failure/success status of a script. In this manner, a test can continue running after a failure, although the failure is still remembered.
Example SETSTAT 12
Sets the status variable to 12.

SETSTN - Set Station Address

Syntax SETSTN <NetAddr>
Description Sets the network address of the network adapter which the MAC controls. After this command successfully completes, the hardware should respond to directed packets sent to the new network address.
Example SETSTN 01 02 03 04 05 06
Sets the current station address to '01 02 03 04 05 06'.

SLEEP - Sleep

Syntax SLEEP <Seconds>
Description Causes TestTool to pause for the given number of seconds. This is useful in certain scripts where a command may cause an asynchronous event, and the script needs to catch this event with certainty. Sleeping (and subsequent testing) can simulate a timeout wait.
Example SLEEP 5
Makes TestTool sleep for 5 seconds.

SRTVX - Server Transmit

Syntax SRVTX [<count> [<min_length> [<max_length> [<type>]]]]
Description Tells current server to transmit a frame. The syntax is similar to MULTRAN. The count indicates how many frames that the server should transmit. The min_length and max_length parameters indicate the minimum length and maximum range limits for frame length. Specified frame lengths do include the length of the header. So, if a given max_length was 100 and the media type was 802.3 (14 bytes of header), the last (and longest) frame would possess only 86 bytes of actual data. The defaults are the same as for the MULTRAN command. Type 0 (the default) indicates that frames should be broadcast. Type 1 indicates that the frame destination is specified on the command line. Type 2 indicates that the frames should be directed only toward the workstation requesting the frames.
Example SRVTX
Tells the server to transmit 50 broadcast frames, ranging from an initial zero data length to a maximum data length frame.

SRVTX 1000
Tells the server to transmit 1000 broadcast frames, ranging from an initial zero length frame to a maximum data length frame.

SRVTX 500 16 4000
Tells the server to transmit 500 broadcast frames, ranging from an initial 16 byte frame to a 4000 byte frame. If the MAC does not support a 4000 byte length frame, the ending limit will be truncated to the maximum length which the MAC specifies.

SRVTX 500 16 4000 0
The same command as above as type 0 frames (broadcast) are the default.

SRVTX 600 14 1514 1 01 02 03 04 05 06
Tells the server to transmit 600 frames, ranging from 14 bytes in length to 1514 bytes in length. The frames are all directed at the net address 01 02 03 04 05 06.

SRVTX 200 50 100 2
Tells the server to transmit 200 frames ranging from 50 bytes length 100 bytes in length. The frames are all directed at the workstation which requested the frames.

STRESS - Stress Test

Syntax STRESS [<count> [<tolerance> ["NOSTOP" ["NOCHECK"]]]]
Description Starts a stress test from a server. The server transmits a broadcast frame. All workstations which receive this broadcast frame extract the stress test parameters: frame count, tolerance, error stops, and data integrity checking. The count is the number of directed frames which each workstation will attempt to transmit to the server. The tolerance number details the number of contiguous OUT_OF_RESOURCE's which a workstation or server will accept before aborting the test. The tolerance level prevents TestTool from endlessly attempting transmits upon a non-functional MAC. If "NOSTOP" is added as a parameter, then TestTool will not stop in the middle of the data-check function when it detects an error. If this parameter is not present, then an "int 3" will be executed and a kernel debugger will stop the machine so that the error within the faulty frame and the hardware state may be examined. The frame will be entirely contained within a contiguous buffer, and the error within the frame data will be pointed to by the ES:DI register pair. If "NOCHECK" is added as a parameter, then the data-check function will not be called. The stress test may be aborted at any time by a Control-H.
Example STRESS
Starts a stress test where all workstations transmit 100,000 frames, and the tolerance for all machines is 10,000 contiguous OUT_OF_RESOURCE TransmitChains. The test will check data integrity and if a packet is corrupted, the test will halt using a debugger detectable int 3.

Stress 1000000
Starts a stress test identical to the previous example, except that each workstation will transmit 1,000,000 frames.

STRESS 1000000 5000
Starts a stress test identical to the previous example, except that the tolerance level is halved to only 5,000 contiguous OUT_OF_RESOURCE TransmitChains.

STRESS 1000000 5000 NOSTOP
Starts a stress test identical to the previous example except that TestTool will not stop when a corrupted frame is encountered. Using the NOSTOP option is useful when it is known that data corruption occurs, but one wishes to know the frequency of this corruption.

STRESS 1000000 5000 NOCHECK
Starts a stress test identical to the previous example, except that TestTool will not check data. This option is useful in preliminary testing, when one wishes to test a MAC for resource management. This stress test will verify that the workstations will transmit all one million frames and not hang. Detecting one problem at a time can be useful.


TRAN - Transmit Buffer

Syntax TRAN
Description Transmits the current Tx buffer(s). Each transmit is made of one or more buffers. The sizes these buffers is set by TXSIZE, the data is initialized by EDITBUF, and the data is displayed by TXBUF.
Example TRAN

TXBUF - Display Transmit Buffer(s)

Syntax TXBUF["P"]
Description Display the transmit buffer, "P" is pause mode.
Example TXBUF
Displays the transmit buffer(s) in pause mode. TestTool will pause if the buffer(s) are longer than the message area.

Displays the transmit buffer(s)in pause mode. TestTool will pause if the buffer(s) are longer than the message area.


TXSIZE - Set Transmit Buffer Size and Count

Syntax TXSIZE <buffer size> [<buffer size>....]
Description Sets the number and size of buffers for transmission. The numbering scheme for the buffers is detailed in the description of EDITBUF. Each number parameter allocates a buffer of that size for use in transmission. This command attempts to allocate each transmission buffer in different segment, to test that the MAC handles the far pointers properly. The newly allocated buffers are initialized to all zeroes. In addition, the command frees all previously allocated transmission buffers if any exist. The NDIS specification states that the immediate buffer must contain at least the frame header, but may be no larger than 64 bytes. However, following buffers may be as large as needed, or may even be of zero size.
Example TXSIZE 64 256 0 100
Sets the immediate data buffer as 64 bytes long, buffer 0 as 256 bytes long, buffer 1 as zero bytes long, and buffer 2 as 100 bytes long.

Sets the immediate buffer as 40 bytes long and frees the previously allocated transmission buffers.


USEGDT - Toggle GDT Usage

Description Toggle GDT usage in communication with the MAC under OS/2. This affects both transmission and reception. TestTool (and Wedge) will use physical or virtual pointers depending on whether UseGDT is on or off. Under DOS, NDIS does not distinguish between virtual and physical addresses, because DOS does not support memory mapping. In this case, segment:offset addresses will always be used. The default status for UseGDt is false, because the NDIS spec requires all MACS to support physical addresses. Virtual address support is optional in NDIS.
Example USEGDT
Toggles GDT usage on/off.

USTAT - Update Statistics

Syntax USTAT
Description Causes the MAC to atomically update the statistics in its statistics table. If statistics are always current, this MAC request should return SUCCESS.
Example USTAT
Statistics should be up to date after this command is executed.

WKSTA - Set Workstation Mode

Syntax WKSTA
Description The WKSTA command first sends out a broadcast frame advertising its presence. Network nodes running TestTool in server mode reply with a directed packet to the workstation. The workstation node then stores the address of the last server to respond. That address is used by certain commands requiring remote service, such as MULTRAN, STRESS, and SRVTX. Since a race condition exists when multiple servers are on the same network, TestTool cannot guarantee which server will be remembered as the server for a workstation. It is suggested that only one server be active on an network at any one time.
Example WKSTA

? - Pop up Help List

Syntax ?
Description Pops up a detailed help list. On the left is a list of all the TestTool commands available. On the right is the detailed description of the command currently highlighted on the left. The up and down arrow keys will navigate up and down the left-hand list of commands. Hitting the Enter or Return key will leave the help screen upon the top, but will drop down to the command entry line. The currently selected command will be already typed, although no parameters will be added to the command line. For instance, if the currently selected command is RXRLS and enter is hit, then the command line will contain only "RXRLS" and the cursor will be on the second space immediately following RXRLS. At this point, the parameter to RXRLS should be entered.
See Also HELP


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.


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


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


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

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation