NDIS Driver Developer's Tool Kit for OS/2 and DOS TestTool User's Manual
- 1 Preface
- 2 Chapter 1. Introduction
- 3 Chapter 2. Using TestTool
- 4 Chapter 3. Command Descriptions
- 4.1 ADDMC - Add Multicast or Group Address
- 4.2 CHKDATA - Toggle Data Checking
- 4.3 CHKIND - Check Indications
- 4.4 CHKLK - Check Receive Lookahead Length
- 4.5 CHKSTAT - Check Status Variable
- 4.6 CHKTOKEN - Check Token Ring
- 4.7 CLOSE - Close Adapter
- 4.8 CLRIND - Clear Indications Counters
- 4.9 CLRMAC - Clear MAC to Initial State
- 4.10 CSTAT - Clear Statistics
- 4.11 DELMC - Delete Multicast or Group Address
- 4.12 ECHO - Toggle Echo Mode
- 4.13 EDITBUF - Edit Current Transmit Buffer
- 4.14 EXIT - Exit TestTool
- 4.15 FILTER - Set Packet Filter
- 4.16 FUNADR - Set Functional Address
- 4.17 HELP - Help Screen
- 4.18 INDICOFF - Indication Off
- 4.19 INDICON - Indication On
- 4.20 INITDIAG - Initiate Diagnostics
- 4.21 INTREQ - Interrupt Request
- 4.22 JUMP - Jump to Script Label
- 4.23 LOG - Start Log to File
- 4.24 MODOPEN - Modify Open Parameters
- 4.25 MONITOR - Set Monitor Mode
- 4.26 MULTRAN - Transmit Multiple Frames
- 4.27 OPEN - Open Adapter
- 4.28 QUIT - Exit TestTool
- 4.29 READLOG - Read Error Log
- 4.30 READMAC - Read MAC Service Specific Characteristic Table
- 4.31 RESET- Reset MAC
- 4.32 RUN - Run Script File
- 4.33 RXBUF - Display Receive Buffer
- 4.34 RXRLS - Receive Release
- 4.35 RXWAIT - Toggle Wait for Release
- 4.36 SERVER - Set Server Mode
- 4.37 SETLOOK - Set Lookahead Length
- 4.38 SETSTAT - Set Status Variable
- 4.39 SETSTN - Set Station Address
- 4.40 SLEEP - Sleep
- 4.41 SRTVX - Server Transmit
- 4.42 STRESS - Stress Test
- 4.43 TRAN - Transmit Buffer
- 4.44 TXBUF - Display Transmit Buffer(s)
- 4.45 TXSIZE - Set Transmit Buffer Size and Count
- 4.46 USEGDT - Toggle GDT Usage
- 4.47 USTAT - Update Statistics
- 4.48 WKSTA - Set Workstation Mode
- 4.49 ? - Pop up Help List
- 5 Notices
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.
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.
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
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.
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:
|Common Characteristics Table||Alt-O|
|Service-Specific Characteristics Table||Alt-C|
|Service-Specific Status Table||Alt-S|
|Media Specific Status Table||Alt-D|
|CCB Interface Table||Alt-B|
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 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.
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 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.
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 are issued in order to prepare for running Script Test Files or for Stress Testing.
The following are the Control Commands:
|CHKDATA||Toggle Data Checking||READMAC||Read MAC Service Specific Characteristic|
|CHKIND||Check Indications||RUN||Run Script File|
|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|
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:
|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|
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:
|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
|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
|See Also||DELMC, FILTER|
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.
|See Also||MULTRAN, STRESS|
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.
CHKIND 2 Tx
CHKIND 1 Stat Ring
CHKLK - Check Receive Lookahead 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.
CHKSTAT - Check Status Variable
|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.|
JUMP SUCCESS NextTest
This checks if the MAC is a Token Ring MAC, and if it is, it jumps to the NextTest label.
CLOSE - Close Adapter
|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.|
|See Also||ADDMC, DELMC, OPEN|
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.|
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.|
CSTAT - Clear Statistics
|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.|
DELMC - Delete Multicast or Group Address
|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.
|See Also||ADDMC, CLOSE, FILTER|
ECHO - Toggle Echo Mode
|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.|
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.
EDITBUF 3 1A 0F 42 AD DE EF BE 10 AD
|See Also||TRAN, TXSIZE|
EXIT - Exit TestTool
|Description||Exits TestTool. Useful when wanting to run another program.|
FILTER - Set Packet Filter
|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
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.
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
|Description||Pops up a brief description of every command. Help pops back down with any key pressed.|
Pops up help screen
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
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.|
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.|
Skips the execution of the next command.
JUMP INVALID_PARAMETER FilterNotAccepted
LOG - Start Log to File
|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.
MODOPEN - Modify Open Parameters
|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
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.
|See Also||SERVER, WKSTA|
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
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
MULTRAN 10 100 200 0
MULTRAN 32 50 3000 1 01 02 03 04 05 06
MULTRAN 20 30 1500 2
|See Also||TRAN, SERVER, WKSTA|
OPEN - Open Adapter
|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.|
Opens the MAC connection to the network.
|See Also||CLOSE, MODOPEN|
QUIT - Exit TestTool
READLOG - Read Error Log
|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.|
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.
READMAC MCC 40 = 10
READMAC MSC 10 & 08
RESET- Reset MAC
|Description||Resets the MAC software and adapter hardware.|
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
|Description||Display the receive buffer. "P" is pause mode.|
Displays the current receive buffer in non-pause mode.
RXRLS - Receive Release
|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.|
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.|
|See Also||SRVTX, STRESS, WKSTA|
SETLOOK - Set Lookahead 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
|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
|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
|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.|
Tells the server to transmit 50 broadcast frames, ranging from an initial zero data length to a maximum data length frame.
SRVTX 500 16 4000
SRVTX 500 16 4000 0
SRVTX 600 14 1514 1 01 02 03 04 05 06
SRVTX 200 50 100 2
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.|
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 5000
STRESS 1000000 5000 NOSTOP
STRESS 1000000 5000 NOCHECK
|See Also||SERVER, WKSTA|
TRAN - Transmit Buffer
|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.|
|See Also||EDITBUF, TXBUF, TXSIZE|
TXBUF - Display Transmit Buffer(s)
|Description||Display the transmit buffer, "P" is pause mode.|
Displays the transmit buffer(s) in pause mode. TestTool will pause if the buffer(s) are longer than the message area.
|See Also||EDITBUF, RXBUF, TRAN, TXSIZE|
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.
|See Also||EDITBUF, TRAN, TXBUF|
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.|
Toggles GDT usage on/off.
|See Also||MULTRAN, TRAN|
USTAT - Update Statistics
|Description||Causes the MAC to atomically update the statistics in its statistics table. If statistics are always current, this MAC request should return SUCCESS.|
Statistics should be up to date after this command is executed.
WKSTA - Set Workstation Mode
|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.|
|See Also||SERVER, STRESS, SRVTX|
? - Pop up Help List
|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.|
- 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 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