Revision as of 17:14, 24 April 2016

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

About This Document

This document proposes extensions to the current Network Driver Interface Specification (NDIS) 2.0.1 dated October 5, 1990. These extensions are required in order for IBM* to properly implement the IEEE 802.2 CCB interface as an NDIS protocol driver. These extensions would not necessarily require a change to existing media access control (MAC) device drivers. In fact, these extensions are intended only for 802.5 type MAC device drivers. A MAC device driver can indicate that the extensions in this document are supported by setting the minor NDIS version to 02 in the common characteristics table.

The proposal would add a new primitive to the NDIS interface and also extend the MAC service specific characteristics table (SSC) and the MAC media specific statistics (MSS) for 802.5 Details of these extensions are given in the following sections.

Note: NDIS 2.0.1 is jointly authored by 3Com** and Microsoft.** The SSC and MSS are tables defined in the NDIS. The extensions to NDIS 2.0.1, as described in this document, are derived by IBM.

This document refers to the following publications for additional information:

Microsoft/3Com LAN Manager** Network Driver Interface Specification (NDIS), Version 2.0.1, October 8, 1990.
Microsoft LAN Manager Programmer's Guide for NDIS, Version 2.0.1, June 1990
IBM LAN Technical Reference

1.0 New General Request to Modify OPEN Parms

Purpose: Modify Open Parameters

PUSH WORD       ProtID          ;Module ID of Protocol
PUSH WORD       ReqHandle       ;Unique handle for this request or 0
PUSH WORD       OpenOptions     ;New Open Options for adapter
PUSH WORD       0               ;Pad parameter - must be 0
PUSH WORD       16              ;Opcodes for this request
PUSH WORD       MACDS           ;DS of called MAC module
Call Request            

Returns:

           0x0000       SUCCESS
           0x0002       REQUEST_QUEUED
           0x0003       OUT_OF_RESOURCE
           0x0007       INVALID_PARAMETER
           0x0008       INVALID_FUNCTION
           0x0009       NOT_SUPPORTED
           0x00FF       GENERAL_FAILURE

Description:

This command directs a MAC device driver to change the adapter specific OpenOptions on the adapter. For IBM Token-Ring compatible adapters, OpenOptions are defined in the IBM LAN Technical Reference Manual.

1.2 Change to Service Flags to Support ModifyOpenParms

Bit 17 of the Service flags in the MAC device driver SCC indicates if the MAC device driver supports the modification of the Open parameters with the new ModifyOpenParms NDIS primitive.

2.0 Proposed Changes to the MAC SSC

The MAC SSC will be extended to include a pointer to a new table.

Note: The pointer to this new table is included immediately following the Max number of data blocks in the current definition of the MAC SSC.

This new table has the following structure:

        BYTE            AdapterConfig (DIR. STATUS)
        BYTE            Reserved
        BYTE(10)        MicroCodeLevel (DIR.STATUS)
        DWORD           AdapterParmsAddr (DIR.STATUS)
        DWORD           AdapterMACAddr (DIR. STATUS)
        WORD            SRAMAddress (DIR. INITIALIZE)
        WORD            BringUps (DIR. INITIALIZE and DIR.OPEN.ADAPTER)
        WORD            AdapterType (DIR. STATUS)

The previous values are needed to support the IBM IEEE 802.2 CCB interface DIR.STATUS and DIR.INITIALIZE commands. These commands are defined in the IBM LAN Technical Reference as follows:

Previous Value	New Value and Location
AdapterConfig	adapter_config in DIR.STATUS
MicroCodeLevel	microcode_level in DIR.STATUS
AdapterParmAddr	adapter_parms_addr in DIR.STATUS
AdapterMACAddr	adapter_mac_addr in DIR.STATUS
SRAMAddress	SRAM_address in DIR.INITIALIZE
BringUps	bring_ups in DIR.INTIALIZE and DIR.OPEN.ADAPTER
AdapterType	adapter_type in DIR.STATUS

Note that a protocol can determine if the MAC device driver supports this extended table format by looking at the minor NDIS version byte of the common characteristics table. This byte is set to 02 for this version. A MAC device driver may not need to support the extended SSC format but needs to support version 2.02 for some other reason (for example ModifyOpenParms). This can be done by setting the minor NDIS version byte of the CCT to 02 and setting the pointer to the previously defined structure to NULL.

Also note that even though link speed is already returned in the common characteristics table, it should also be returned in the AdapterConfig byte.

Certain adapter cards may not be able to support all of the fields in this structure. For these MAC device drivers, binary 0's can be inserted in those fields that are not supported.

3.0 Proposed Changes to the MAC 802.5 Media Specific Statistics

The MAC media specific statistics (MSS) are extended to include the following information:

    WORD        RingUtilizationMeasurement (DIR.STATUS)

Note: The fields defined here are included immediately following the number of underruns in the current definition of the MAC MSS.

The previous value is needed in order to support the IBM IEEE 802.2 CCB interface DIR.STATUS. It is defined in the IBM LAN Technical Reference as follows:

RingUtilizationMeasurement is ring utilization measurement in (DIR.STATUS)

Note that a protocol can determine if the MAC device driver supports this extended table format by looking at the minor NDIS version byte of the common characteristics table. This byte is set to 02 for this version. 'The 802.5 statistics structure version level is also 02 in the 802.5 MSS.

Note that if this counter is not supported, it must be set to FFFF.

4.0 Proposed Changes to the Status Indication General Request

An additional Status Indication is being proposed to inform the upper layers of status changes concerning the presence of the PCMCIA LAN adapters. Existing protocol stacks that do not support this new NDIS primitive will have to rely on existing NDIS support for error indications. For situations where the new Status Indication is not supported the existing Ring Status Status Indication of Lobe Wire Fault would be appropriate. The Status Indication is called AdapterPresence.

Purpose: Return a change in the Presence of a LAN Adapter.

PUSH WORD       MACID           ;Module ID of MAC
PUSH WORD       Status          ;New Adapter Status
PUSH LPBYTE     Indicate        ;Virtual address if indicate flag
PUSH WORD       6               ;Adapter Presences Indication
PUSH WORD       ProtDS          ;DS of called protocol module
Call Status             

Returns:
                 0x0000  SUCCESS

Called by LAN MAC drivers to indicate a change in the presence of a LAN Adapter. The status codes for the MAC drivers are encoded in a 16 bit mask, where the bits for the mask are defined as:

Bit	Meaning
15	Ejection Request
14	Ejection Complete
13	Insertion Request
12	Insertion Complete
11	Card Insertion
10	Card Removal
9	PM Resume(Reserved)
8	PM Suspend (Reserved)
7-0	Reserved

For further details refer to the PCMCIA Card Services Interface Specification, Release 2.00 and Network Driver Interface Specification, Version 2.01.

Note: Currently, only the NetBEUI device driver supports these proposed extensions. This implementation in NetBEUI only supports the Card Insertion and Card Removal status codes. The Card Removal status code is reported as a Lobe Wire Fault to the application.

Notices

May, 1995

Issued by:

IBM Corporation

Personal Software Products

11400 Burnet Road

Austin, Texas 78758

First Edition (May 1992)

Second Edition (May 1993)

Third Edition (May 1995)

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

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

Disclaimers

References in this publication 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 IBM's intellectual property rights or other legally protectible rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility.

IBM may have patents or pending patent applications covering subject matter in 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.

Trademarks

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

IBM

OS/2

The following terms, denoted by a double asterisk (**) in this publication, are trademarks of other companies as follows:

Microsoft	Microsoft Corporation
Microsoft LAN Manager	Microsoft Corporation
3Com	3Com Corporation

NDIS Implementation Information
for IBM LAN Systems
Extended NIF Format

About This Document

This document describes a new way in which IBM implements an extended NIF file. This new, enhanced NIF file in IBM* LAN Adapter and Protocol Support* (LAPS) will replace the current implementation of NIF files and corresponding PROTOCOL.INI file fragment that accompanied each network driver of the 3Com** and Microsoft** LAN Manager** implementations.

This document also defines the syntax of NIF files and the action LAPS takes based on that syntax.

This document is for developers who are writing IBM Network Driver Interface Specification (NDIS) 2.0.1 media access control (MAC) device drivers to be run with (LAPS) on IBM Operating System/2* (OS/2*) or with the IBM LAN Support Program on DOS.

Note: NDIS 2.0.1 is jointly authored by 3Com and Microsoft. The new NIF file enhancements are jointly authored by IBM and Microsoft. These NIF extensions have been implemented by IBM in LAPS, which is a component of the OS/2 Extended Services* program, OS/2 LAN Server 2.0*, OS/2 LAN Enabler 2.0*, TCP/IP for OS/2 1;2.1*, OS/2 LAN Server 3.0*, OS/2 Network Transport Services 1.0*, and IBM LAN Support Program 1 3. IBM makes no representation as to the usability of NDIS MAC drivers having these extensions and the corresponding NIF file with Microsoft LAN Manager.

This document refers to the following publications for additional information:

Microsoft/3Com LAN Manager Network Driver Interface Specification (NDIS), Version 2 0.1, October 8, 1990
NDIS implementation Information for IBM LAN Systems, OS/2 Messaging and National Language Support, May 1993
NDIS Implementation Information for IBM LAN Systems, NDIS Extensions, May 1993

1.0 NDIS NIF File Definition

The NIF files were originally defined by Microsoft. These files defined certain characteristics about MAC drivers and protocol drivers that assisted the Microsoft SETUP program in installing these drivers. To help the configuration and installation of IBM NDIS drivers, LAPS will be extending the use of the NIF files for IBM NDIS MAC drivers during the configuration and installation process. In addition, the Microsoft SETUP utility created individual PROTOCOL.INI files which were later merged into a master PROTOCOL.INI. LAPS operates on only one PROTOCOL.INI and requires that all the NIF and driver programs exist in a common subdirectory. Therefore, LAPS ignores some lines in the NIF files as originally defined by the Microsoft specification.

Note that in prior releases of the Microsoft specification, NIF files were used only for MAC drivers, while XIF files were used for protocol drivers. XIF files will no longer exist, and NIF files will be used to represent both MAC drivers and protocol drivers.

2.0 NIF Format Definition and Description

This chapter describes the format of the enhanced NIF file. This format will replace the previous format. LAPS uses these files to build Presentation Manager windows for configuration.

The format as defined here consists of a section and its attributes. Certain sections are common to all NIF files. These common sections must be listed at the beginning of the NIF file. The common section is generally followed by sections for each parameter needed by the driver. Following is the basic format of a NIF file:

[common_section]
keyword = value
keyword = value
  .
  .
  .
[parameter section]
keyword = value 
keyword = value
  .
  .
  .
[parameter section]
keyword = value
<E0F>

2.1 Common Sections

Note: Entries enclosed in braces {} are optional. Text surrounded by less than and greater than symbols < > is not significant and is used for information purposes only.

[component name]
 Type = <Driver type>
 Title = <Component name displayed to the user>
 Version= Component version number>
 Drivername= <Driver name for PROTOCOL.INI>
 {Xports= <Transport name> {,<transport name>,...,<Transport name>}}
 {Exec = <Executable expression>}
 {Copyfile = <8.3 File name> {,<8.3 File name>,...,<8.3 File name>}}

[File]
 Name = Filename> {,<Filename>,...,<FileName>}
 {Path = <Location of above files>}

Definitions:

[component_name]
This can be anything although it is recommended that this be the NIF file name without the file extension.

Type	Defines the driver type as follows:
	NDIS	This is used for MAC drivers only. A MAC driver of this type would expect a DEVICE= statement in CONFIG.SYS for every instance of the driver to be loaded. It would also expect a numeric digit appended to the driver name in the PROTOCOL.INI file for every nth instance of the driver, where n is greater than 1.

	NDIS_SNGL	This is used for MAC drivers only. A MAC driver of this type would expect only one DEVICE= statement in CONFIG.SYS regardless of how many instances of the driver were configured. It would also expect every instance of the driver name to be identical (no numeric digit appended) in the PROTOCOL.INI file.
	NDIS_MULT	This is used for MAC drivers only. A MAC driver of this type would expect a DEVICE= statement in CONFIG.SYS for every instance of the driver to be loaded in much the same way as a driver of type NDIS. However, it would also expect that subsequent instances of the DEVICE= statements in the CONFIG.SYS file be built using the names on the NAME = statement in the NIF file. The first DEVICE= would be given the first name on the NAME= statement, the second DEVICE= would be given the second name on the NAME= statement, and so on. The number of adapters supported for drivers of this type is limited to the number of files listed on the NAME= statement in the NIF file. As with a driver of type NDIS, it would also expect a numeric digit appended to the drivername in the PROTOCOL.INI file for every nth instance of the driver where n is greater than 1.
	PROTOCOL	NDIS protocol driver
	SERVICE	There are no services defined at this time.
	Title	Defines the component name that would be displayed to the user during configuration. For a MAC driver, this is the adapters supported by this driver. For a protocol driver, this is the type of protocol that was provided by this driver.
	Version	Defines the version of the component. The recommended format for this field is xxx where x can be any numeric digit. Although this field is not used by LAPS at this time, it may be used in the future to implement some form of driver versioning. In that case, xxx would be treated as a DecNum as defined later in this section.
	DriverName	Defines the name that is placed in PROTOCOL.INI.
	Xports	Defines for an NDIS driver the list of transports with which the driver has been tested and certified. This is done by comparing this value with the drivername field of all protocol drivers.
	Exec	Defines an executable file that would be called after the driver is installed and configured. It is ignored by LAPS at this time.
	CopyFile	Allows for specification of files to be copied if this configuration is to be used on another system. The IBMCOM subdirectory is assumed by LAPS and should be omitted.
	File.Name	Defines the name of the device driver that will be added to CONFIG.SYS using a DEVICE= statement. No path should be included with this keyboard.
	File.Path	Defines the location of all previously listed device drivers. This keyword would be ignored by LAPS since all drivers are placed in \IBMCOM\MACS or in \IBM\PROTOCOL. This keyword is optional.

Any of the previous keywords that require more than one value should be specified on a single line. This can be done by separating each value with a comma.

2.2 Parameter Section

Although parameter definitions are not required, most NIF files have them following the common information. Each parameter and its attributes are grouped in sections with the parameter name as the section name. The parameter name, enclosed in brackets, precedes each section, with attributes on separate lines. Keywords are pre-defined (there are no "roll your own" keywords). Configuration code ignores unrecognized keywords. The format of the parameter section is as follows:

[parameter_name]
Tag =   < Interrupt | IOAddress | DMA Channel | RamAddress | RamAddrSize | RomAddress |
                RomAddrSize >
Display =       < "display text" >
Type =  < DecNum | Hexadecimal | HexNum | String | HexString | None | Decimal>
StrLength = < X > (where X is a Decimal value)
Default =       < Default Value >
Range = < 1 - X | X >
Step =  <X>
Set =   < Value1, Value2,...,ValueX >
NlsSet =        < Value1, Value2,...,ValueX >
Scope = < Global | Local >
Optional =      < Yes | No >
Editable =      < Yes | No >
Virtual =       < Yes | No >
Help =  < "help text" >

Definitions:

[parameter_]

The parameter name (also the section name). It is placed in PROTOCOL.INI as it appears here without the brackets and followed by an equal sign (=) if required.

Tag

A tag used to help identify and manage parameter cross-checking and conflict identification. The tag is not placed in PROTOCOL.INI. Tag can have the following values:

Interrupt

Identifies an interrupt level

IOAddress

Identifies an I/O address

DMAChannel

Identifies a DMA channel

RamAddress

Identifies a RAM address

RamAddrSize

Identifies the RAM size

RomAddress

Identifies a ROM address

RomAddrSize

Identifies the ROM size

Note: LAPS does not currently use the tag keyword.

Display

Identifies the text that is displayed to the user when prompted for input for this parameter. This a required field.

Type

Identifies the data type of the parameter. It may have the following values:

Decimal

UnSigned numeric value, for example, the number 256. It is converted to a 31-bit signed numeric value, so it cannot exceed that value.

DecNum

UnSigned numeric value. It is converted to a 32-bit unsigned numeric value, so it cannot exceed that value.

Hexadecimal

Signed numeric value. The hexadecimal equivalent of a signed decimal value. This is placed in PROTOCOL.INI. with 0x preceding the hexidecimal value (the 0x should be omitted in the NIF file).

HexNum

Unsigned numeric value. The hexadecimal equivalent of an unsigned decimal value. This is place in PROTOCOL.INI with 0x preceding the hexadecimal value (the 0x should be omitted in the NIF file).

String

String consists of ASCII characters. Strings containing commas or blank space must be enclosed in quotes. It is placed in PROTOCOL.INI by LAPS as a quoted string.

HexString

String consisting of valid hexadecimal characters. It is validated by the configuration utility and placed in PROTOCOL.INI as a quoted string.

None

The parameter itself is the value. This is also assumed if the keyboard is absent.

StrLength

Identifies the maximum length of the string or HexString parameter type and is required for these types.

Default

The optional default value for the current parameter.

Range

An optional range in the form:

DecNum - DecNum for decimal types

HexNum-HexNum for hexidecimal or hexstring types.

Note: If no upper bound is specified, it implies that there is no maximum value (Nomax).

Step

Optional step value used in conjunction with the range to provide for modulo or rounding. It can be a numeric or the special value K, for Kilobytes. Step defaults to 1. This keyword is optional.

Set

An optional set of valid values for the parameter in the form:

DecNum1,...,DecNumN for decimal types

HexNum1,...HexNumN for hexadecimal and/or hexString types

String1,...,StringN for String types

Note: Set and range are mutually exclusive.

NlsSet

An optional set of valid values for the parameter in the form:

DecNum1,...,DecNumN for decimal types

HexNum1,...,HexNumN for hexadecimal and/or hexString types

String1,...,StringN for String types

Note: NlsSet and range are mutually exclusive.

Note: The NlsSet is the translated version of the Set value. The reason for this is that the PROTOCOL.INI file can remain in English (so the network driver doesn't need to be concerned with translated values in PROTOCOL.INI), but the user will be able to configure a translated value.

Scope

This keyword defines how the parameter should be treated if the driver supports multiple instances. This applies to transport drivers only. Values for scope are:

Global

Only one instance of the parameter can be entered. It apples to all adapters bound by the protocol. This is the default.

Local

Optional values are allowed on a per adapter basis. In PROTOCOL.INI, the parameter values, separated by commas, follow the equal sign (=).

Optional

Optionally specifies whether the parameter is required at all times or not:

NO

Required for Basic (and Advanced) configuration.

YES

Optional. If not changed by the user, and there is no default, the parameter is omitted from PROTOCOL.INI. In this case, it is assumed that the device driver has hard-coded the default. YES is the default.

Editable

Optionally specifies whether the user can edit parameter values.

NO

The field is displayed but cannot be edited by the user.

YES

The field is displayed and can be edited by the user. YES is the default.

Virtual

Optionally specifies whether this parameter is for checking only; it should not be placed in PROTOCOL.INI.

NO

The parameter is needed. It is a candidate for PROTOCOL.INI. NO is the default.

YES

The parameter is used for conflict detection only. It must not be placed in PROTOCOL.INI.

Help

Help text for the parameter. The text can contain spaces as well as carriage returns and line feeds (CR/LF). Help text can span lines, but it must be surrounded by quotes. This keyword is optional. If a keyword is omitted, the default is assumed.

Note: The title, display, help, and NlsSet parameter values are considered to be NLS translatable and should be placed in quotes.

2.3 Multiple NIF Files per Driver

In some cases, a single driver can support more than one type of adapter. In this environment, a parameter that applies to one type of driver may not apply to another type of driver. An example of this might be a driver that supports both Micro Channel* and AT*-bus systems. For AT-bus systems, it may be required to have the interrupt (IRQ) level as a parameter in the NIF file. For Micro Channel systems, this parameter is not required. In order for a single driver to support both environments, multiple NIF files can be created with a different set of parameters defined in each. The driver name would be the same in both NIFs; however, each would have a different title name. For example, the driver names could be the names of the two adapters supported.

3.0 NIF File Example

This example is the original NDIS MAC driver that was shipped with LAPS in Extended Services for OS/2 and OS/2 LAN Server 2.0 for support of the IBM Token-Ring Network 16/4 Bus Master Server Adapter/A.

[IBMTRBM]
 Type = NDIS_SNGL
 Title = "IBM Token-Ring Network Busmaster Server Adapter"
 Version= 1.0
 DriverName = IBMTRBM$
 XPORTS = NETBEUI LANDD
 COPYFILE = MACS\MONT400.BIN, MACS\WRTRAM.BIN, LT4.MSG, LT4H.MSG

[File]
 Name= IBMTRBM.OS2
 Path= IBMCOM\MACS

[NetAddress]
 Display = "Network adapter address"
 Type= HexString
 Range = 400000000000- 7FFFFFFFFFFF
 Optional= Yes
 Editable= Yes
 Virtual = No
 Help = "This parameter overrides the network address of the network
 adapter card. The value of this parameter is a hexadecimal string of
 12 digits, as in 400001020304. The address
 must be unique among all other network adapter addresses on the 
 network."

[AdapBuffSize] 
 Display = "Adapter card buffer size" 
 Type= Decimal
 Default = "1032"
 Range= 96-2048
 Step = 8
 Optional= Yes
 Editable = Yes 
 Virtual= No 
 Help = This parameter specifies the size of the buffers on the 
 network adapter card. The value of this parameter must be a multiple 
 of 8. Increase this parameter if you are sending large frames 
 through the network."

[AdapMinTran]
 Display= "Minimum adapter card transmit buffers"
 Type = Decimal
 Default = "4" 
 Range = 4 - 676
 Optional = Yes 
 Editable= Yes 
 Virtual= No 
 Help = "This parameter specifies the minimum amount of buffer 
 resources reserved for transmit buffers. This  parameter value 
 can be increased in a system that is transmit bound."

[AdapMaxTran]
 Display = "Maximum adapter card transmit buffers"
 Type = Decimal 
 Default = "48" 
 Range = 6 - 676 
 Optional= Yes 
 Editable = Yes 
 Virtual = No
 Help = "This parameter specifies the maximum amount of buffer resources 
 reserved for transmit buffers. This parameter specifies the maximum 
 amount of buffers contained in the buffer resource pool that are 
 available for transmitting data. By default, this parameter defines 
 the minimum number of buffers available for receiving data and can 
 be reduced in a system that is receive bound."

[MaxTransmits] 
 Display = "Maximum number of queued transmits"
 Type = Decimal
 Default = "31" 
 Range = 1 - 459 
 Optional = Yes 
 Editable = Yes
 Virtual = No
 Help = "This parameter specifies the maximum number of transmit queue 
 entries. The network adapter driver allocates approximately 260 
 bytes for each transmit queue entry. The value of this parameter 
 should be high enough to accommodate the sum of all Maximum Number 
 of Queued Transmits parameter values for all protocol drivers using 
 the adapter concurrently."

[MinRcvBuffs]
 Display = "Minimum number of adapter driver receive buffers"
 Type = Decimal
 Default = "20"
 Range = 1 - 3260
 Optional = Yes
 Editable = Yes
 Virtual = No
 Help = "This parameter specifies the minimum number of receive buffers
 that are allocated. The value must have the following relationship:
 (Minimum Adapter Driver Receive Buffers value x Size of Adapter Driver
 Receive Buffer value) > size of the largest frame on the network.
 This value must be > 4500 bytes on a 4MB network, and > 18000 bytes on
 a 16MB network"

[SizWorkBuf]
 Display = "Size of adapter driver receive buffer"
 Type = Decimal
 Default = "2048"
 Range = 96 - 18000
 Optional = Yes
 Editable= Yes
 Virtual= No
 Help = "This parameter specifies the size of each receive buffer.
 Refer to the Minimum Adapter Driver Receive Buffers parameter for more
 information about the value of this parameter."

4.0 SNIFFLE - A NIF validator

SNIFFLE is a standalone utility which is intended to aid in the development of Network Information Files(NIFs). Invoked against one or more NIFs, SNIFFLE will ensure that the NIF sections, keywords, and values are consistent both with this specification and with each other. If an error is detected, SNIFFLE will indicate the location of the error and provide a description of the error condition. The code used to perform validation is identical to that used in LAPS; thus, if a NIF is acceptable to SNIFFLE, it will be acceptable to LAPS as well.

SNIFFLE.EXE is provided on the diskette that accompanies this document. An example of its use for the IBMTOK.NIF would be to type the following at an OS/2 command prompt:

SNIFFLE IBMTOK.NIF

Notices

May, 1993

Issued by:

IBM Corporation

Personal Software Products

11400 Burnet Road

Austin, Texas 78758

First Edition (May 1992)

Second 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

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

Disclaimers

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

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

Trademarks

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

IBM

OS/2

AT

Micro Channel

Operating System 2

LAN Server 2.0

Extended Services

LAN Adapter and Protocol Support

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

White Paper on
NetBIOS Applications Interoperability

1.0 NetBIOS Applications Interoperability
1.1 Configuration
1.2 Initialization
1.3 NetBIOS Linkage
1.4 NCB Handler
1.5 NCB Completion
1.6 NetBIOS Command Descriptions
2.0 Extensions to LM10 Specifications
2.1 DDID Support for LM10 Protocol Driver
2.2 Resource Consideration
2.3 Implementation Specific Information
2.4 Reserved NCB Command Codes
Notices

1.0 NetBIOS Applications Interoperability

NetBIOS applications including IBM's LAN Server, Data Base, etc., can run over OEM LM10 protocols. OEM LM10 protocols such as IPX, DECNet, ATTISO, AILANBIO can be used instead of IBM's NetBIOS (NETBEUI) protocol to run NetBIOS applications.

The IBM NetBIOS NB30* (NETBIOS.OS2), LAN Server (HPFS386.IFS) and LAN Redirector (NETWKSTA.200) use the NetBIOS LM10 interface. We will refer to these three (NetBIOS.OS2, HPFS386.IFS and NETWKSTA.200) as LM10 applications hereafter. During initialization, each one of the LM10 application performs a standard DosDevIoctl to the LM10 NetBIOS driver to get the far address of the direct I/O routing. This routine is analogous to a real mode INT 5C handler, i.e., it gets called with a pointer to a Network Control Block (NCB). This pointer to NCB can be a physical address or a virtual address. Each of the LM10 application drivers provides two standardized routines. PhysNCBDone and VirtNCBDone for handling NCB completion. Based on the type of NCB (physical or virtual) address, the LM10 NetBIOS driver returns to PhysNCBDone or VirtlNCBDone on completion.

Even though the LM10 protocol driver returns to only one callback routine, all of the three drivers (NETBIOS NB30, NETWKSTA.200 and HPFS386.IFS) can coexist. HPFS386.IFS first gets the completion NCB and determines whether that ncb belongs to HPFS386.IFS. If not, it passes it to NETWKSTA.200. NETWKSTA.200 passes it to NETBIOS.OS2 if it does not belong to NETWKSTA.200.

LM10 NetBIOS drivers never get a synchronous NCB, and therefore, they need not process synchronous or asynchronous NetBIOS options. The drivers just call a PhysNCBDone or a VirtNCBDone routine when processing is complete.

The NB30 NetBIOS takes the responsibility of locking all the NCBs and the buffers passed in the NCBs for ring3 and locking all the buffers passed in the NCBs for ring0 NB30 NetBIOS applications. Whereas LAN Server and Requestor take the responsibility of locking all the NCBs and the buffers passed in from their NCBs (for example from the LAN Server NetBiosSubmit API). A convention has been defined to support OEM-defined NCBs such that the NB30 NetBIOS, LAN Server and Requestor can still perform the appropriate locking and other actions for their extended NCBs.

1.1 Configuration

LM10 NetBIOS drivers are installed by inserting a DEVICE= statement in the CONFIG.SYS file. All LM10 NetBIOS drivers must be installed before the IBM supplied NETWKSTA.200 driver.

Each LM10 NetBIOS driver controls one or more NetBIOS networks and a single system may have multiple LM10 NetBIOS drivers installed. All the three LM10 application drivers (NETBIOS, NETWKSTA.200 and HPFS386.IFS) support multiple LM10 NetBIOS drivers using different logical adapter numbers.

Each LM10 NetBIOS driver is described to the NB30 NetBIOS driver by NETBIOS section in PROTOCOL.INI configuration file. The format of each LM10 NetBIOS driver under NETBIOS section is:

< adapter# > = < driver name >, < lana number >

where,

< driver name >	is the OS/2 driver name for the LM10 NetBIOS driver.
<lana number >	is the LAN adapter number for the NetBIOS network represented by this statement. Default is 0.

Each LM10 NetBIOS driver is described to LAN Server and LAN Redirector by a statement under the [network] section in the IBMLAN.INI configuration file. Each entry in the [network] section represents a "virtual network" adapter. The format of each LMl0 NetBIOS network definition is:

< network name > = < driver name >, < lana number >, < type >, < #sessions >, < #ncbs >, < #name >

where,

< driver name >	is the OS/2 driver name for the NetBIOS driver.
< lana number >	is the LAN adapter number for the NetBI0S network represented by this statement. Default is 0.
< type >	is the type of the NetBIOS driver. For NetBIOS drivers that support the interface described in this document, the type field must be LM10 1. Default is LM10. NB30, the other valid value for this field, is not described in this document.
< #sessions >	is the number of session resources that LAN Manager will request from the NetBIOS driver at init time. The default is driver dependent.
< #ncbs >	is the number of NetBIOS Network Control Blocks (NCBs) that LAN Manager will request from the NetBIOS driver at init time. The default is driver dependent.
<#names >	is the number of name resources that LAN Manager will request from the NetBIOS driver at init time. The default is driver dependent.

The requester uses the virtual networks specified on the WRKNETS line of the [requester] section of the IBMLAN.INI file to determine which networks to use when establishing sessions to remote servers. The server uses the virtual networks specified on the SRVNETS line in the [server] section of the IBMLAN.INI file to determine on which virtual networks to listen for incoming connections. For example configuring "SRVNETS=NET1, NET2" would request that the server listen for incoming requests on the adapter and driver specified by NET1 as well as the adapter and driver specified on the NET2 line.

The configuration information provided under the LM10 NetBIOS (NETBEUI) driver section in PROTOCOL.INI file is used to initialize the LM10 NetBIOS driver. This is the total pool of resources that NB30 NetBIOS.OS2, LAN Server and Requestor share. LAN Server and Requestor get their resources based on the configuration in the virtual network statements (net#) in IBMLA N.INI file. The remaining pool of resources is given to the NB30 NetBIOS driver to distribute to standard NetBIOS applications.

The adapter# statements under the NETBIOS section in the PROTOCOL.INI and the net# statements in IBMLAN.INI file allow applications to open LM10 NetBIOS drivers by logical network name, independent of the actual driver name and LANA number.

1.2 Initialization

LM10 NetBIOS drivers should perform device initialization at load time just like any other OS/2 device driver. In addition to supporting the standard driver initialization sequence, LM10 NetBIOS drivers must also support the DosDevIoctl command that is issued by each of the LM10 applications during system initialization. The LM10 NetBIOS driver initialization sequence is:

Respond to the device Init command at driver load time by allocating packet buffers, setting up tables, and running start-up diagnostics as appropriate.
Respond to the sequence DosOpen, DosDevIoctl: NetBIOSLinkage, DosClose. Each of the LM10 NetBIOS applications use this mechanism to pass the entry points of their PhysNCBDone and VirtNCBDone routines and other configuration parameters. The LM10 NetBIOS driver is responsible for filling in a table of parameters that the LM10 NetBIOS application needs.

LM10 NetBIOS drivers must be prepared to respond to multiple initialization sequences of DosOpen/DosDevIoctl: NetBIOSLinkage/ DosClose. For a driver supporting multiple LANAs, this would happen once for each LANA defined in the subset of LANAs defined in the NETBIOS section of PROTOCOL.INI and the [networks] section of IBMLAN.INI file.

1.3 NetBIOS Linkage

Shown below is the format of the Ioctl request packet that the LM10 NetBIOS driver will recruit as the result of one of the LM10 NetBIOS application performing the DosDevIoctl: NetBIOSLinkage call.

Request Packet
	13-BYTE	Request header
	BYTE	Device category = 81h
	BYTE	Device control function = 62h
	DWORD	Parameter Packet buffer address
	DWORD	Buffer address of NetBIOSLinkage structure
Parameter Packet
	WORD	Parameter packet length in bytes
	WORD	Data packet length in bytes

Note that the GDT selectors allocated via the AllocGDTSelector Device Help are not valid to use during initialization. Any access to memory that normally would be done via an allocated GDT selector must be done via PhysToVirt.

The LM10 NetBIOS driver will only have to respond to DosOpen and DosClose if bit 11 of the Device Attribute field in the Device Driver Header is set.

DWORD	PhysNCBDone handler address
BYTE	LANA number
BYTE	Pad
DWORD	VirtNCBDone handler address.
WORD	Flags:
	bit
	0= 0: Only physical buffer address will be provided in the NCB.
	1: Physical buffer address and, when possible, virtual buffer address will be provided in the NCB.

PhysNCBDone and VirtNCBDone addresses that are passed to the LM10 NetBIOS driver are only valid after completion of CONFIG.SYS processing by OS/2.

LM10 NetBIOS drivers should determine if the given version of NB30 NetBIOS or NETWKSTA.200 or HPFS386.IFS software supports the VirtNCBDone entry point by checking the Parameter Packet length. If the length is less than 14 bytes, the VirtNCBDone entry point is not available.

LM10 NetBIOS drivers should determine if the given version of LM10 NetBIOS application is capable of providing virtual buffer addresses in NCBs by checking the Parameter Packet length and by examining the bit 0 of the Parameter Packet word at offset 15. If the length is less than 16 bytes, OR if bit 0 or the Parameter Packet word at offset 15 is set to 0, then the LM10 NetBIOS application will not provide virtual buffer addresses in NCBs.

LM10 NetBIOS driver should complete the Ioctl request by filling in the NetBIOSLinkage structure whose address is conveyed in the Ioctl request packet. The format of the NetBIOSLinkage structure is shown below:

NetBIOSLinkage Structure

WORD

Bytes of data returned in this table

WORD

Bytes of data actually available

BYTE

Reserved

WORD

Net driver type (1= NCB, 2 = MCB)

WORD

Network status:

bit

0 =0: Reserved, must be zero 1 =0: Normal driver

=1: Loopback driver

2 =1:LM10 NetBIOS driver supports

NCB.SEND.NO.ACK

3 =1: LM10 NetBIOS driver support

NCB.GATHER.SEND, NCB.SCATTER.RECEIVE

and NCB.TRANSCEIVE

4 =2: LM10 NetBIOS driver supports interrupt time submission of NCBs.

5 =1: LM10 NetBIOS driver uses virtual addresses if available.

6-15 =0: Reserved, must be zero

DWORD

Network bandwidth (bits/second)

WORD

Maximum sessions

WORD

Maximum number of NCBs

WORD

Maximum number of names

WORD

NetBIOS driver's DS value

DWORD

NetBIOS NCB Handler address

BYTE

of commands in OEM Extension Table

OEMExt Table

WORD

ExtStruct

....

WORD

ExtStruct

Where the format of the ExtStruct is as shown below:

Cmd

BYTE

Extended NCB command Opcode value

CmdInfo

WORD

Command descriptor bits:

bit

0

=1: uses standard buffer

1

=1: uses second buffer

2

=1: require buffers to be locked

3

=1: can be asynchronous

4

=1: can be cancelled

5

=0: Reserved, must be zero

6-7

=0: invalid encoding

=1: is a regular command

=2: is a privilege command

=3: is an exclusive command

8

=1: uses NCB_LSN field

9

=1: uses NCB_NUM field

10

=1: uses NCB_NAME field

11

=1: uses NCB_CALLNAME field

12

=0: buffer segments must be read-write

=1: buffer segments may be read-only

13

=1: establishes a session (returns new 1sn)

14

=0: Reserved, must be zero

15

=0: Reserved, must be zero

The OEMExtTable is an optional table that can have zero entries. It defines NCB commands that are OEM-defined extensions to the standard NetBIOS interface. The CmdInfo parameter describes the extended NCB's usage of buffers and asynchronous notification. It also indicates whether the command is cancellable and whether the requesting ring 3 application needs to have opened the NetBIOS driver in privileged or exclusive mode to issue the command. The LAN Redirector software that supports ring 3 NetBIOS applications needs this information to provide correct addressing and protection in making application-level buffers available to the LM10 NetBIOS driver in physical address form.

1.4 NCB Handler

One of the LM10 NetBIOS application obtains the address of the NetBIOS NCB handler at system initialization time using the NetBIOSLinkage DosDevIoctl described earlier. The NetBIOS NCB handler is entered via a far call. The calling conventions are essentially identical to those for real-mode INT 5C, except that ES:BX is the virtual address of the NCB to be executed.

Entry
	ES:BX	Virtual address of NCB
	DX:AX	(UNDEFINED Previously Physical address of NCB)
	DS	NetBIOS driver's DS
	TOS:DWORD	Return address
	TOS+4:DWORD	Virtual address of NCB
	TOS+8:DWORD	(UNDEFINED Previously Physical address of NCB)
Return
	AX	NetBIOS-defined immediate return code

The virtual address of the NCB (passed in ES:BX and TOS+4) is always a GDT address and is accessible by the NetBIOS driver (both at task time and interrupt time) until the driver has completed the NCB (or rejected it via the immediate return code).

Parameters are passed both in registers and on the stack. The NTCB handler must preserve BP and always exit via a far return with parameter removed from the stack and with immediate NCB return code in AX. These conventions allow the handler to be coded in high level languages.

Note that if the immediate result code is non-zero, the NCB is considered to be complete and an NCBDone routine must NOT be called.

The addresses within the NCB contained in the NCB_BUFFER and NCB_CALLNAME fields are physical addresses that are guaranteed to be valid until the invocation of PhysNCBDone or VirtNCBDone.

The LAN Redirector software also provides virtual buffer addresses in the NCB_NAME field for the following NetBIOS commands: NCB.CHAIN.SEND, NCB.CHAIN.SEND.NO.ACK, NCB.SEND. NCB.SEND.NO.ACK, NCB.RECEIVE and NCB.RECEIVE.ANY. For commands that carry a single buffer, the virtual address of the buffer is conveyed in the first four bytes of the NCB.NAME. For commands that carry two buffers addresses (e.g., NCB.CHAIN.SEND), the virtual addresses are contained one after the other in the first eight bytes of the NCB_NAME field. LAN Redirector or LAN Server software may not always supply the virtual address within the NCB. In these cases, the SELECTOR portion of the virtual addresses in the NCB_NAME field will be zero. Therefore, NetBIOS drivers should only attempt to use the supplied virtual address if the address SELECTOR field is non-zero. LM10 NetBIOS drivers should use the information passed at NetBIOSLinkage time to determine if the given software is capable of supplying virtual addresses in NCBs.

The values of NCB_POST and NCB_CMD_CPLT fields are reserved and must not be modified during the course of NCB processing.

The LM10 NetBIOS NCB handler should not distinguish between synchronous and asynchronous NCBs. It need just start the necessary I/O and return. NCB completion and synchronization is handled by the NCBDone routine.

[Note] The NCB handler MUST NOT block at any time.

1.5 NCB Completion

The LM10 NetBIOS driver must issue a far call to either PhysNCBDone or VirtNCBDone upon completing processing of an NCB (usually at interrupt time). The far addresses of PhysNCBDone and VirtNCBDone are passed to the driver at initialization time via the NetBIOSLinkage DosDevloctl. The address of the NCB being completed must be passed to the given NCBDone on the stack.

The LM10 NetBIOS driver must satisfy the following conditions when calling PhysNCBDone or VirtNCBDone:

The LM10 NetBIOS driver must always call the given NCBDone routine in protected mode.
The stack segment at the time of the call must be the same stack segment on which the driver was entered (either at interrupt time or at task time). If the NetBIOS driver uses the Device Help GoProt in an interrupt handler, then the driver should use the stack segment that was resumed from GoProt.

The stack should be set up as follows:

PhysNCBDone
	TOS:DWORD	Return address
	TOS+4:DWORD	Physical address of NCB
VirtNCBDone
	TOS:DWORD	Return address.
	TOS+4:DWORD	Virtual address of NCB as passed to the NetBIOS driver's NCB handler in ES:BX

The NCB_RETCODE field must have been completed with a suitable return code value.
NCBs_POST and NCB_CMD_CPLT fields must contain the values that they had at NCB submission time.
All NetBI0S processing of this NCB must be complete. The internals of NCBDone reserve the right to modify the NCB in any way.
Common Problems, Hints and Suggestions
- It is recommended that LM10 NetBIOS drivers for LAN Redirector, LAN Server and NB30 NetBIOS support a configurable "call" time-out. This parameter specifies the maximum amount of time that the driver will wait for a response from the remote machine when handling NCB.CALL, NCB.ADD.NAME and NCB.ADD.GROUP.NAME commands. The parameter should be settable via system configuration files.
- When transferring blocks of data using the REP instruction, a maximum size of 2K is allowed. Please refer to the OS/2 Device driver guidelines.
- For performance reasons, it is recommended that PhysToGDT be used whenever possible instead of PhysToVirt.
- The NCB handler MUST NOT block at any time.
- When a session is aborted (as opposed to hung-up), the driver should return the error code 18H (Session Ended Abnormally). The error code OAH (Session closed) should only be resumed when either end hangs up the session.
- LAN Server or LAN Redirector or NETBIOS NB30 driver needs this information for its session handling.
- The virtual address passed (on the stack) to the VirtNCBDone must be the SAME address that was passed to the LM1O driver's NCB handler in ES:BX (and on the stack).
- The LM10 NetBIOS driver may use either PhysNCBDone or VirtINCBDone, but must only call ONE of the routines for any given NCB.
- For performance reasons, the LM1O NetBIOS driver should:
  - use the virtual address supplied in the NCB_NAME field when provided
  
  - support interrupt time submission of NCBs

Dec Offset	Hex Offset	Parameter Name	Byte Length	8086 Type	Description
0	0	NCB_COMMAND	1	DB	Command field
1	1	NCB_RETCODE	1	DB	Return Code
2	2	NCB_LSN	1	DB	Local Session number
3	3	NCB_NUM	1	DB	Number of application program name
4	4	NCB_BUFFER	4	DW	Pointer to message buffer address
8	8	NCB_LENGTH	2	DB	Buffer length in bytes
10	A	NCB_CALLNAME	16	DB	Name on local or remote NETBIOS. This field has a different use for the NCB.CHAIN.SEND command.
26	1A	NCB_NAME	16	DB	Name on the local NETBIOS session. This field has a different use for the NCB.RESET command.
42	2A	NCB_RTO	1	DB	Receive timeout
43	2B	NCB_STO	1	DB	Send timeout
44	2C	NCB_PRESERVE	4	DB	Reserved LM10 should preserve these bytes.
48	30	NCB_ADPTR_NUM	1	DB	The adapter number
49	31	NCB_PRESERVE	1	DB	Reserved LM10 should preserve this byte.
50	32	NCB_RESERVE	6	DB	Reserved
56	38	NCB_DD_ID	1	DB	Application id
57	39	NCB_FLAGS	1	DB	Flags (See description)
58	3A	NCB_PRESERVE	6	DB	Reserved LM10 should preserve these bytes.

NCB_COMMAND	Same As LAN Technical Reference for OS2 DD interface, minus NCB_POST paragraph.
NCB_RETCODE	Same As LAN Technical Reference for OS2DD interface
NCB_LSN	Same As LAN Technical Reference for OS2 DD interface
NCB_NUM	Same As LAN Technical Reference for OS2 DD interface
NCB_BUFFER	Same As LAN Technical Reference for OS2 DD interface
NCB_LENGTH	Same As LAN Technical Reference for OS2 DD interface
NCB_CALLNAME	Same As LAN Technical Reference for OS2 DD interface, minus 'This field is also used by the NCB.RESET command.'
NCB_NAME	Same As LAN Technical Reference for OS2 DD interface
NCB_RTO	Same As LAN Technical Reference for OS2 DD interface
NCB_STO	Same As LAN Technical Reference for OS2 DD interface
NCB_PRESERVE	Reserved. LM10 should preserve these bytes.
NCB_ADPTR_NUM	Same As LAN Technical Reference for OS2 DD interface
NCB_RESERVE	Reserved LM10 May modify this field
NCB_DDID	One byte field specifying the application id of the submitter. This field is specified on all NCBs except NCB.RESET. It is used to identify applications for NCB.ADD.GROUP.NAME, NCB.RECEIVE.ANY (any) and NCB.RECEIVE.DATAGRAM (any). The range will be 0x00 through 0xFF. Note that the LAN Redirector(NETWKSTA.200) will always set this field to 0x00. All other applications will use numbers 0x01 through 0xFF.
NCB_FLAGS	NCB Flag bits 0x08 - Used in NCB.CALL and NCB.LISTEN to indicate that the caller is Ring 3 and thus specifies to not use PiggyBackAck for this session. All other bits are undefined and set to 0.

1.6 NetBIOS Command Descriptions

NCB.ADD.GROUP.NAME
	Same as LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
NCB.ADD.NAME
	Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
	This NCB is also used to request Name#1.
	To request Name#1, NCB_NAME+0 must be 0x00 and NCB_NAME+1 must be 0x2A(*).
NCB.CALL
	Same as LAN Technical Reference for OS/2DD interface, minus supplied field of NCB_POST@
	plus supplied field of
	NCB_FLAGS If bit 0x08 is off, PiggyBackAck is requested.
	If bit 0x08 is on, no PiggyBackAck is requested.
NCB.CANCEL
	Same As LAN Technical Reference for OS/2 DD interface,
NCB.CHAIN.SEND
	Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
NCB.CHAIN.SEND.NO.ACK
	Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
NCBDELETE.NAME
	Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
	This NCB is also used to request Name#1.
	To request Name#1, NCB_NAME+0 must be 0x00 and NCB_NAME+1 must be 0x2A(*).
NCB.FIND.NAME
	Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
NCB.HANG.UP
	Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
	NCB_BUFF@ is set to 0xFFFFFFFF when an ncb.hang.up is issued as a result ncb.reset.
NCB.LAN.STATUS.ALERT
	Same As LAN Technical Reference for OS?2 DD interface, minus supplied field of NCB_POST@
NCB.LISTEN
	Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
	plus supplied field of
	NCB_FLAGS If bit 0x08 is off, PiggyBackAck is requested.
	If bit 0x08 is on, no PiggyBackAck is requested.
NCB.RECEIVE
	Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
NCB.RECEIVE.ANY
	Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
NCB.RECEIVE.BROADCAST.DATAGRAM
	Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
NCB.RECEIVE.DATAGRAM
	Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
NCB.RESET
	Supplied fields are
	NCB_ADPTR_NUM
	Returned fields are
	LOAD_SESSIONS at NCB_NAME+8 (1 byte field)
	The number of commands defined at LM10 load time.
	LOAD_COMMANDS at NCB_NAME+9 (1 byte field)
	The number of commands defined at LM10 load time.
	LOAD_NAMES at NCB_NAME + 10(1 byte field)
	The number of names defined at LM10 load time. This Number includes Name #1.
	Note: These are the only fields required for NCB.RESET.
NCB.SEND
	Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
NCB.SEND.BROADCAST.DATAGRAM
	Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
NCB.SEND.DATAGRAM
	Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
NCB.SEND.NO.ACK
	Same As LAN Technical Reference for OS/2 DD interface, minus supplied field of NCB_POST@
NCB.SESSIONS.STATUS
	Same As LAN Technical Reference for Os/2 DD interface, minus supplied field of NCB_POST@
NCB.TRACE
	Not supported
NCB.TRACE
	Not supported

2.0 Extensions to LM10 Specifications

2.1 DDID Support for LM10 Protocol Driver

IBM NetBIOS Netbeui LM10 protocol driver adds this DDID support. The LM10 interface specification does not include a Device Driver Identification Number concept(DDID). The NB30 NetBIOS driver identifies its applications with this DDID. The LM10 protocol stack assumes that only one application is running. Hence a NetBIOS application using LMl0 stack may end up getting another NetBIOS application's data when it uses NCB.RECEIVE.ANY for any name or NCB.RECEIVE.DATAGRAM for any name.

DDID is also associated with NetBIOS Group Name, so the same application cannot add the same group name twice. IBMs LM10 protocol stack Netbeui and TCPbeui have been enhanced to include the DDID concept. Netbeui identifies names, with DDID, so NetBIOS applications using netbeui or TCPbeui are guaranteed to get their own data. Any NetBIOS application running over OEM LM10 stack may not get the correct data if it uses NCB.RECEIVE.ANY for any name or NCB.RECEIVE.DATAGRAM for any name if LM10 stack does not use DDID concept.

2.2 Resource Consideration

Since the LM10 interface does not specify any NetBIOS resource related information in the NETBIOS LINKAGE structure, NB30 NetBIOS and LAN Redirector depend on the values configured in protocol.ini file. If an OEM LM10 protocol does not add a protocol section in protocol.ini, then the default values assigned by these drivers (NB30 NetBIOS, LAN Server and LAN Redirector) will be used for NetBIOS resources.

2.3 Implementation Specific Information

NetBIOS.OS2 driver uses some of the bytes in the NCB's reserve field. So LM10 protocol drivers are expected to preserve this field.

WORD PTR ncb_reserve + 0
WORD PTR ncb_reserve + 6
WORD PTR ncb_reserve + 8
WORD PTR ncb_reserve + 12

The first two bytes of the reserve field, four bytes starting from offset reserve + 6 and two bytes starting from offset reserve + 12 need to be preserved.

2.4 Reserved NCB Command Codes

The following NetBIOS Command Block codes are reserved by IBM:

NB30 NetBIOS supports the ATTACHDD Device Driver Interface defined in the IBM Local Area Network Technical Reference Manual.

Notices

August 1994

Issued by:

IBM Corporation
Personal Software Products
11400 Burnet Road
Austin, Texas 78758

First Edition (August 1994)

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

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

Disclaimers

References in this publication 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 IBM's intellectual property rights or other legally protectible rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility.

IBM may have patents or pending patent applications covering subject matter in 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.

Trademarks

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

IBM	OS/2	AT	Micro Channel
Operating System/2	LAN Server 2.0	Extended Services
LAN Adapter and Protocol Support

Chapter 1 - Introduction
Chapter 2 - Configuration and Binding
- Configuration and Binding Process
Chapter 3 - Protocol to MAC Interface Description
Chapter 4 - Data Structures
Chapter 5 - Specification of Primitives
Chapter 6 - Protocol Manager
Chapter 7 - VECTOR and Dynamic Binding
Appendix A - System Return Codes
Appendix B - Reference Material
Appendix C - NDIS 2.0.1 802.3
Appendix D - 802.5
Appendix E - Utilities Provided with the Protocol Manager
Notices
- Copyright Notices

[[[#Terms|next]]][[[#toc|parent]]][[[#toc|TOC]]]

Chapter 1 - Introduction

This document describes the LAN Manager network driver architecture and interfaces that let a DOS or OS/2 system support one or more network adapters and protocol stacks. This architecture provides a standardized way for writing drivers for network adapters and communications protocols. It also solves the problem of how to configure and bind multiple drivers into the desired set of layered protocol stacks.

Drivers written to the interfaces defined here will function concurrently in a system with other networking and protocol drivers, and will operate correctly with the LAN Manager software for DOS and OS/2.

Definition of Terms

To simplify the job of supporting multiple adapters and protocols, the architecture defines four kinds of drivers:

Media access control (MAC) drivers, which provide low-level access to network adapters. The main function of a MAC driver is to support transmitting and receiving packets, plus some basic adapter management functions. MAC drivers are device drivers that are loaded during system initialization and remain permanently in memory. Since they cannot be unloaded, they are called "static."
Protocol drivers, which provide higher-level communication services from data link to application (depending on the driver). An example is a NetBIOS driver that provides a NetBIOS interface at the top and communicates with a MAC driver at the bottom. Protocol drivers can be device drivers, TSRs, or transient DOS applications. A protocol driver is called "static" if it cannot be unloaded. A protocol driver is called "dynamic" if it can be loaded and unloaded on demand.
MAC-layer entities, which bind to real MAC drivers and expose a new MAC-like layer interface on top. Possible examples are MAC bridges, test tools, or interface mappings that change the NDIS interface to meet some environment-specific administrative requirement.
The Protocol Manager driver, which is a special driver that provides a standardized way for multiple MAC and protocol drivers to get configuration information and bind together into the desired protocol hierarchy. The Protocol Manager gets all configuration information from a central file, PROTOCOL.INI.

Scope of This Document

This document defines

Protocol Manager functions and interfaces for configuration and binding of MAC and protocol drivers
The software interface between MAC and protocol drivers

Separate documents will specify the configuration and interface for other kinds of protocol drivers, including data link and transport drivers.

Changes for This Version

The major highlights of this version compared to the last (1.0) are

Support for dynamic binding/unbinding of protocol modules, allowing protocols to be swapped in and out of memory as needed. No changes are required of MAC drivers to support the dynamic bind/unbind features. In particular, NDIS 1.0.1 conformant MACs will support dynamically binding protocol modules.
Additional Protocol Manager functions to support dynamic binding and future administrative requirements.
Some adjustments to the ResetMAC function, and to the StartReset and EndReset primitives, were made to correct some inconsistencies and keep the logic out of critical paths.
Additional fields was added to certain tables to provide additional information. The presence or absence of these fields can be determined by examining the length field in each table.
Some new recommendations and clarifications on issues such as double-word alignment of data blocks, the use of the permanent station address, the copying of DS and Entry points, the use of 80386 32-bit registers, the release of internal resources before confirmations, the handling of zero-length data blocks, the formatting of MAC headers, the use of zero handles, and new transmit error codes for Token-Ring to support source routing.
A standard for protocol service-specific characteristics tables.
The inclusion of additional 802.3 and 802.5 specific information and added statistics definitions.
Additional information and caveats to help developers.
The Protocol Manager now has a transient component (in some configurations) called PROTMAN.EXE. This is now described with certain restrictions imposed on Protocol Manager primitives.
Some new error response codes were defined.
Appendix E, "Utilities Provided with the Protocol Manager," was added to describe some helpful bind and configuration management utilizes.
Selected statistics designated as mandatory for both service-specific and media-specific statistics (802.3 and 802.5).
Extended 802.3 statistics to include Number_of_Underruns.
OpenAdapter function expanded to permit driver return of vendor-specified warning errors and/or hardware error codes.

It is not expected that any of these changes will result in incompatibilities with protocol and MAC drivers written to previous versions of this specification. Great care was taken to avoid creating incompatibilities. It is the protocol's responsibility to identify and interoperate with older NDIS version driver implementations that may not have implemented support for statistics Older network drivers will co-exist with network drivers written to this specification. However, to take advantage of new features (such as dynamic binding), developers may wish to update their protocol drivers to be NDIS 2.0.1 compliant.

Chapter 2 - Configuration and Binding

A network server or workstation includes at least one MAC and one protocol driver, plus the Protocol Manager driver. More complex configurations can have multiple MAC and protocol drivers.

The Protocol Manager is always defined in CONFIG.SYS to load before any MAC or protocol drivers. Its job is to read the configuration information out of the PROTOCOL.INI file and make this available to MAC and protocol drivers that load later.

MAC and protocol drivers use this information to set initialization parameters and allocate memory appropriately. For example, a NetBIOS driver may use the configuration information provided by the Protocol Manager to determine its maximum number of names and sessions.

As each driver configures and initializes itself, it identifies itself to the Protocol Manager using a driver- defined "module name" and "characteristics table." The module name defines a kind of logical name for the communication service provided by the driver. The characteristics table provides specific parameters about the service and the set of entry points the driver uses to communicate with other drivers. A single driver may identify itself to the Protocol Manager as multiple logical modules if, for example, it implements more than one layer of protocol interface (such as transport and data link).

Before two modules can communicate, they must be bound together. Binding is the process of two modules exchanging characteristics tables so that they can access each others entry points. This establishes the linkage they need to make requests of one another and indicate asynchronous request completion. Binding is controlled by the Protocol Manager based on information from PROTOCOL.INI. Binding can be either static or dynamic for protocol drivers. If a protocol driver is static, then its binding is static. If it is dynamic, then its binding is dynamic. A dynamic protocol driver can be unbound from its bound drivers prior to unloading itself from memory. This unbinding process is also controlled through the Protocol Manager.

Configuration and Binding Process

In the typical case of a system with one MAC driver and a NetBIOS driver, the set of drivers loads and initializes as follows:

Protocol Manager loads, initializes, and reads PROTOCOL.INI.
MAC driver loads and calls GetProtocolManagerInfo to get any needed configuration information, such as its DMA channel.
MAC driver initializes and calls RegisterModule to identify itself as the module named, for example, "ETHERCARD." This call passes ETHERCARD's characteristics table to the Protocol Manager.
NetBIOS driver loads and calls GetProtocolManagerInfo to get any needed configuration information, such as the maximum number of names, sessions, and commands to support.
NetBIOS driver initializes and calls RegisterModule to identify itself as the module named "NetBIOS." This call passes NetBIOS's characteristics table to the Protocol Manager and indicates that NetBIOS wants to bind to ETHERCARD.
After all device drivers have loaded, the Protocol Manager determines from the information supplied on previous RegisterModule requests that NetBIOS must bind to ETHERCARD. Using a defined dispatch address in the characteristics table for NetBIOS, the Protocol Manager calls NetBIOS and instructs it to bind to ETHERCARD. The call, InitiateBind, includes the characteristics table for ETHERCARD.
NetBIOS calls ETHERCARD requesting to bind. The modules exchange characteristics tables with each other. They now have each other's entry points and are bound.
NetBIOS may now call ETHERCARD at its defined entry points for transmitting and receiving packets.

If the example NetBIOS driver was dynamically loadable, the binding to the ETHERCARD MAC would be done through the Protocol Manager's VECTOR facility (see Chapter 7). The VECTOR shields the static MAC driver from the details of dynamic binding.

Chapter 3 - Protocol to MAC Interface Description

The interface between a protocol and MAC driver provides for the transmission and reception of network packets, called frames. The interface includes other functions for controlling and determining the status of the network adapter controlled by the MAC.

To allow for efficient use of memory and to minimize buffer copies, frames being transmitted and received are passed between protocol and MAC using a scatter/gather buffer description convention. This passes an array of pointers/lengths called a frame buffer descriptor. There are three types of these descriptors, one for describing frames being transmitted (TxBufDescr) and two for frames being received (RxBufDescr and TDBufDescr).

Overall, the calls at the protocol/MAC interface are grouped into categories of transmission, reception, indication control, status indications, and general requests. An additional category of function, system requests, is generic to all drivers.

Transmission

Transmitting data can work either synchronously or asynchronously, at the option of the MAC. Protocols must be able to handle both cases. Primitives are TransmitChain and TransmitConfirm.

Protocol

MAC

TransmitChain

CALL------>

Call passes TxBufDescr and unique handle. MAC can copy data now or later

<---RETURN---

Return indicates if data has been copied. If not, MAC now owns frame data blocks and will copy them asynchronously.

Later on, after data is copied by MAC:

TransmitConfirm

<-----CALL-----

Call supplies unique handle from TransmitChain.

---RETURN--->

Data block ownership returned to protocol.

NOTE: If the MAC transmits the frame synchronously, it indicates this on the return from TransmitChain and will not generate a TransmitConfirm.

Reception

Receiving data can work in either of two ways, depending on the MAC. Protocols must be able to handle both cases:

The MAC generates a ReceiveLookahead indication that points to part or all of the received frame in contiguous storage. This is called the "lookahead" data. The protocol may issue a TransferData call back to the MAC if it wants the MAC to copy all or part of the received frame to protocol storage. The protocol can, of course, copy the lookahead data itself. In some implementations, this can be the entire frame.
The MAC generates a ReceiveChain indication that points to a RxBufDescr that describes the entire frame received. The protocol can copy the data immediately or later. If later, it releases the frame buffer areas back to the MAC via a call to ReceiveRelease.

Generally, the first approach will be implemented by MAC drivers for non-host-buffered network adapters, while drivers for host-buffered network adapters will implement the second. Non-host-buffered adapters that use programmed I/O or DMA will generally provide a small leading portion of the received frame as lookahead data, whereas those that use a single memory mapped buffer will usually provide the whole frame.

In either case, the protocol must validate the received packet very rapidly (within a few instructions) and reject it if necessary. This is very important to performance in a multiprotocol environment.

The following sections illustrate the non-host-buffered adapter versus host-buffered adapter receive scenarios.

Non-Host-Buffered Adapter

MAC

Protocol

ReceiveLookAhead

CALL------>

Call passes pointer to lookahead data. Protocol examines this data.

If protocol wants the frame and lookahead wasn't the whole frame, the protocol can ask MAC to transfer the frame:

TransferData

<-----CALL-----

Passes TDBufDescr indicating where to put the received data.

---RETURN--->

<---RETURN---

Upon return from protocol, MAC reenables the hardware.

IndicationComplete

CALL----->

MAC calls protocol to allow interrupt-time post processing.

<---RETURN---

Host-Buffered Adapter

MAC

Protocol

ReceiveChain

CALL------>

Call passes pointer to RxDataDescr.

<---RETURN---

Return tells if protocol accepts the frame and, if so, whether it copied the data. If accepted but not copied, ownership of data blocks passes to the protocol that copies the data asynchronously.

IndicationComplete

CALL----->

MAC calls protocol to allow interrupt-time post processing.

<---RETURN---

Later, if protocol deferred copying the data (this may occur during IndicationComplete):

<-----CALL-----

ReceiveRelease. The call supplies the unique handle from ReceiveChain.

---RETURN--->

Data block ownership returned to MAC.

Indication Control

Two primitives let a protocol selectively control when it can be called with indications from the MAC. These primitives are IndicationOn and IndicationOff.

Before calling an indication routine, the MAC implicitly disables indications. This means, for example, that if another frame arrives while the protocol is processing the indication for the previous one, the protocol will not be reentered. Likewise, if the protocol issues a TransmitChain for loopback data from within the ReceiveLookahead indication routine, it will not be reentered to process the loopback data reception.

Protocols can reenable indications upon returning from ReceiveLookahead, ReceiveChain, or Status indications or by calling IndicationOn within the IndicationComplete routine.

Status Indication

Status indications are calls from a MAC to protocol that convey a change in adapter or network status.

A status indication works much like a reception indication. The status indication handler is catered with indications disabled, and there is a mechanism that will leave indications disabled.

MAC		Protocol
Status
Call passes status type and information.
	<---RETURN---
IndicationComplete
MAC calls protocol to allow interrupt-time post processing.
	<---RETURN---

General Requests

General requests are calls from a protocol to a MAC, asking it to do a general function such as open or close the network adapter or change the station address.

General requests work much like a TransmitChain request, except the primitives are Request and RequestConfirm.

MAC

Protocol

Request

CALL------>

Issue request to MAC with unique handle.

<---RETURN---

Return indicates if request completed.

Later, if request completed asynchronously:

<-----CALL-----

RequestConfirm. The call supplies unique handle from Request.

---RETURN--->

If the MAC satisfies the request synchronously, it indicates this on the return from Request and will not generate a RequestConfirm.

System Requests

System requests support module binding and management functions. They are usually made by the Protocol Manager to a MAC or protocol module, but can also be made by a protocol to another protocol or MAC module.

System requests work much like general requests except that all are synchronous and the requests are not module specific.

Upper Module		Lower Module
System
Issue request to lower module.
	<---RETURN---	Return indicates request completed.

Protocol Manager Primitives

Protocol Manager primitives are requests from protocol or MAC modules to the Protocol Manager for venous Protocol Manager services. These requests are always synchronous.

Protocol or MAC Module		Protocol Manager
Protocol Manager primitive
Issue request to Protocol Manager.
	<---RETURN---	Return indicates request completed.

Chapter 4 - Data Structures

Module Characteristics

Protocol and MAC modules are described by a data structure called a characteristics table. Each characteristics table consists of several sections: a master section called the common characteristics table, and four subtables. The common characteristics table contains module independent information, including a dispatch address for issuing system commands like InitiateBind to the module. The four module- specific subtables are chained off the common characteristics table. These subtables define module- specific parameters and the entry points used for inter- module communication (such as the MAC/protocol interface functions). When two modules bind together, they exchange pointers to their common characteristics tables, so that each gets access to the other's descriptive information and entry points.

NOTE: NDIS drivers must copy the module DS and entry point addresses (from the common characteristics and upper/lower dispatch tables) to their local data segment at bind time. In future versions of this specification, this information may be volatile. Having this information directly accessible will also improve performance. This information must not be copied prior to the bind call and must not be used unless the bind completes successfully.

NOTE: The information in the characteristics table for a module is primarily informational, in support of network management and configuration tools. Upper modules binding to lower ones will NOT need to parse this information to adapt their behavior at the interface. They will generally just use the information to validate that they have been bound to the correct type of module. Most of the other information is provided in the structure to support information utilities.

Some new fields have been added to some of the characteristics tables for version 2.0.1. The size/length fields at the start of the tables can be checked to see if the new fields are available in the table.

Common Characteristics

The format of this information is identical for all modules. Note that all information in this section of the table is static.

WORD	Size of common characteristics table (bytes)
BYTE	Major NDIS version (2 BCD digits - 02 for this version)
BYTE	Minor NDIS version (2 BCD digits - 00 for this version)
WORD	Reserved
BYTE	Major module version (2 BCD digits)
BYTE	Minor module version (2 BCD digits)
DWORD	Module function flags, a bitmask: 0 - Binding at upper boundary supported 1 - Binding at lower boundary supported 2 - Dynamically bound (that is, this module can be swapped out) 3-31 - Reserved, must be zero
BYTE[16]	Module name - ASCIIZ format
BYTE	Protocol level at upper boundary of module: 1 - MAC 2 - Data link 3 - Network 4 - Transport 5 - Session -1 - Not specified
BYTE	Type of interface at upper boundary of module: For MAC: 1=> MAC For Data link: To be defined For Transport: To be defined For Session: 1 => NCB For any level: 0 => private (ISV defined)
BYTE	Protocol level at lower boundary of module: 0 - Physical 1 - MAC 2 - Data link 3 - Network 4 - Transport 5 - Session -1 - Not specified
BYTE	Type of interface at lower boundary of module: For MAC: 1 => MAC For Data link: To be defined For Transport: To be defined For Session: 1 => NCB For any level: 0 => private (ISV defined)
WORD	Module ID filled in by the Protocol Manager on return from RegisterModule
WORD	Module DS
LPFUN	System request dispatch entry point
LPBUF	Pointer to service-specific characteristics (NULL if none)
LPBUF	Pointer to service-specific status (NULL if none)
LPBUF	Pointer to upper dispatch table (NULL if none)
LPBUF	Pointer to lower dispatch table (NULL if none)
LPBUF	Reserved for future expansion, must be NULL
LPBUF	Resaved for future expansion, must be NULL

NOTE:	LPSZ Long pointer to an ASCIIZ string LPBUF Long pointer to a data buffer LPFUN Long pointer to a function

In version 1.0.1, the two bytes after the first WORD were required to be set to zero. For compatibility with version 1.0.1, an NDIS spec major version number of 00 is interpreted the same as major version number 01.

The module function flags bitmask must accurately specify the capabilities of the module. The Protocol Manager uses these fields; for example, the dynamically bound (bit 2) flag when set indicates that this module is a dynamically loadable and unloadable module. Such a module can only be used in the Protocol Manager dynamic mode.

The upper and lower boundary protocol level and interface type bytes must accurately specify the protocol level and interface type. The Protocol Manager uses these fields. If an interface does not support NDIS bindings or a protocol level is undefined at the interface, a value at 0xFF must be used. In this case the corresponding interface type is undefined.

In addition to the preceding common characteristics table, a given module will typically have a set of subtables that are chained off the common table:

Service-specific characteristics table:
This table contains descriptive information and parameters about the module.
Service-specific status table:
This table contains run-time operating status and statistics for the module.
Upper dispatch table:
This table contains dispatch addresses for the upper boundary of the module - that is, the entry points it exports as a service provider.
Lower dispatch table:
This table contains dispatch addresses for the lower boundary of the module - that is, the entry points it exports as a service client.

NOTE: Under OS/2, dispatch addresses and data segments are Ring 0 selectors. This field is usually set at Ring 3 INIT time even though the selector set must be Ring 0.

MAC Service-Specific Characteristics

All MACs use the following format for the service-specific characteristics table. This table contains volatile information (like the current station address) that can be updated by the MAC during the course of operation. Other modules may read this table directly during execution.

WORD	Length of MAC service-specific characteristics table
table
BYTE [16]	Type name of MAC, ASCIIZ format: 802.3, 802.4, 802.S, 802.6, DIX, DIX+802.3, APPLETALK, ARCNET, FDDI, SDLC, BSC, HDLC, ISDN
WORD	Length of station addresses in bytes
BYTE [16]	Permanent station address
BYTE [16]	Current station address
DWORD	Current functional address of adapter (zero if none)
LPBUF	Multicast address list (structure defined below)
DWORD	Link speed (bits/sec)
DWORD	Service flags, a bitmask: 0 - Broadcast supported 1 - Multicast supported 2 - Functional/group addressing supported 3 - Promiscuous mode supported 4 - Software settable station address 5 - Statistics are always current in service-specific status table 6 - InitiateDiagnostics supported 7 - Loopback supported 8 - Type of receives: 0 - MAC does primarily ReceiveLookahead indications 1 - MAC does primarily ReceiveChain indications 9 - IBM source routing supported 10 - ResetMAC supported 11 - Open/CloseAdapter supported 12 - Interrupt request supported 13 - Source routing bridge supported 14 - GOT virtual addresses supported 15 - Multiple TransferDatas permitted during a single indication (version 2.0.1 or later) 16 - MAC normally sets FrameSize = 0 in ReceiveLookahead (version 2.0. 1 or later) 17-31 - Reserved, must be zero
WORD	Maximum frame size that can be both sent and received
DWORD	Total transmission buffer capacity in the driver (bytes)
WORD	Transmission buffer allocation block size (bytes)
DWORD	Total reception buffer capacity in the driver (bytes)
WORD	Reception buffer allocation block size (bytes)
CHAR[3]	IEEE vendor code
CHAR	Vendor adapter code
LPSZ	Vendor adapter description
WORD	IRQ interrupt level used by adapter (version 2.0.1 or later)
WORD	Transmit queue depth (version 2.0.1 or later)
WORD	Maximum number of data blocks in buffer descriptors supported (version 2.0.1 or later)

The remaining bytes in the table (based on length) are vendor specific.

In interpreting these tables, the implementor must always bear in mind that additional functions may be added to future MACs and that the support of functions that the protocol does not need must not prevent the protocol from accepting a bind for the MAC.

The type name describes to the protocol the type of MAC protocol header that the MAC driver supports. In general, protocol stacks must be prepared to support the types "802.3," "802.5," "DIX," and "DIX+802.3." If the native media of the MAC is not one of these types (for example, ARCNET), then it is recommended that the MAC developer consider claiming support for one of the above types and doing a transparent internal mapping between the private header format of the media and the public header format being claimed. Without support for one of the above header formats, general protocol compatibility cannot be guaranteed. The list specified above is not exhaustive. New names may be added in the future or a vendor may provide special MAC type names for use with protocols that interoperate with special MACs provided by that vendor. In the latter case it is recommended that a vendor use a MAC type name that does not start with an alphanumeric character to avoid conflicts with NDIS MAC type names that might be used in future versions of this specification.

In the various parts of this specification, all station and multicast addresses for a given MAC have the length specified in the "Length of station addresses" field.

The permanent station address must be obtained from the hardware if at all possible, as it may be used by LAN Manager for security or administrative purposes. If a PROTOCOL.INI entry is used to override the current station address, the permanent station address must not be affected. Only if there is no hardware-based addressing scheme will it be possible to override the permanent station address by configuration parameters. The current station address will always reflect the currant address as set via parameter or by calling Request SetStationAddress.

The functional address DWORD represents the functional address bit pattern present in the last four bytes of an IBM-compatible functional address. This excludes the first two bytes, 0xC0 and 0x00. The functional address DWORD represents the logical OR of all functional addresses currently registered to the adapters.

The multicast address list is a buffer formatted as follows:

WORD	Maximum number of multicast addresses
WORD	Current number of multicast addresses
BYTE[16]	Multicast address 1
BYTE[16]	Multicast address 2
. . .
BYTE[16]	Multicast address N

The multicast address list is kept packed by the MAC so that the current multicast addresses occur first in the list.

Service flags indicate which optional functions are supported by an NDIS driver. If a particular function bit is set, that function is supported. When attempts are made to invoke unsupported functions, NDIS MAC drivers must respond properly by returning INVALID_FUNCTION (0x0008).

If loopback is supported in the network adapter hardware, then bit 7 of the MAC service flags must be set.

If loopback is not supported in the hardware (bit 7 of the MAC service flags is not set), the protocol driver must handle this function itself by some loopback delivery of the frame to be transmitted.

The following criteria must be met for loopback:

The destination address is the same as the local station's current station address or the destination is a broadcast, multicast, or functional address that would have been received by this station if sent by another.
The frame must qualify for reception according to the current packet filter.

The loopback mechanism must cause the Receive indication to occur at interrupt time (and it must be delayed by IndicationOff.

If IBM source routing is used (bit 9 is set), it is the protocol module's responsibility to encode and interpret appropriate source routing information. This bit merely implies that the device is capable of sending packets with the source routing bit set in the source address so that a protocol can recognize such a packet.

While the ResetMAC function (bit 10) is optional, it is strongly recommended that those implementing the NDIS MAC driver support this function. Some protocol drivers may rely on this function to recover from hardware error conditions.

If the service flags indicate that OpenAdapter is supported (bit 11 is set), then the protocol driver must ensure that the adapter is open. The open status of an adapter can be determined by examining bit 4 of the MAC status in the MAC service-specific status table. If the adapter is not open, then the protocol must issue an OpenAdapter Request (normally during bind-time processing).

If source routing bridge is set (bit 13), it is implied that the MAC is capable of receiving all packets on the network that have the source routing bit set.

If GDT virtual addresses are supported (bit 14 is set), then Ring 0 GDT virtual addresses can be used to describe frames. All MACs must support the use of physical addresses to describe frames; however, for some MACs it is preferable to supply a GDT address if one is readily available. The GDT address must remain valid throughout the scope of its use by the MAC.

If bit 16 of She service flags field is set, She MAC driver does not normally provide the total frame size of received data. In dais case die MAC normally calls ReceiveLookahead with the FrameSize parameter equal to zero. Setting dais bit is optional. It is left to the MAC implementor to determine how frequency returning FrameSize equals zero constitutes sufficient grounds to set this bit. However, this bit must be reset if the MAC always calls ReceiveLookahead with She FrameSize parameter nonzero or if a zero FrameSize parameter is returned only for intermittent erroneous packet reception. For version 1.0.1 compatibility, bit 16 reset gives no indication whether the MAC will return a zero FrameSize parameter or not. Some MAC and higher layer protocols do not support "length" fields within Their encoding. Such protocols rely on knowing the size of valid frame data received at the MAC interface and then deduce the amount of data at their layer by stripping off the lower layer protocol headers. This bit warns such protocols that the required received frame size is not normally available at the MAC interface and that receive frames might not be able to be processed. Such protocol scan refuse to bind to such MACs.

The maximum frame size must reflect The maximum size packet chat can be both transmitted and received by the MAC client. This size must reflect only The bytes chat actually cross the NDIS boundary. For EtherNet, this value is typically 1514, since the client does not specify the CRC bytes. Token-Ring values vary but do not include The nondata SD, ED, and FS bytes or the FCS.

The network adapter RAM is characterized by four parameters. The first is the number of bytes available for storing packets to be transmitted, usually one or two full-size packets in size. The second parameter is the allocation granularity, typically about 256 bytes, indicating how much memory would be occupied by a one-byte packet pending transmission. The third and fourth parameters are the number of bytes available for storing received packets and the receive packet granularity. Often These parameters will be affected by PROTOCOL.INI keywords (for example, specifying two transmit buffers rather than one), and it is required that These numbers accurately reflect the current adapter configuration. Protocol drivers may use these numbers to determine reasonable window sizes, and incorrect values can impact performance.

The intent of the IEEE vendor and vendor adapter codes is that, when used in combination, they uniquely identify this MAC driver for this adapter. The IEEE vendor code uniquely defines the vendor providing the MAC driver. The use of the if vendor code avoids the need for any global registry of vendor adapter codes. The IEEE vendor code is assigned by the IEEE and becomes the first three bytes of a six-byte IEEE 802 address. The vendor adapter code specifies a particular MAC driver provided by the vendor for an adapter. If the IEEE vendor code is assigned to the vendor, the vendor assigns a unique vendor adapter code to each MAC driver provided. For those without an IEEE vendor code, a value of 0xFFFFFF is required. In this case, the vendor adapter code is undefined.

The vendor adapter description string is an ASCIIZ string containing a description of the adapter that could be used to format an error message (for example, "3Com EtherLink II adapter").

The transmit queue depth specifies the maximum number of TransmitChain requests the MAC can buffer internally. This number must be set to one if the TransmitChain implementation in the MAC is synchronous. Each queued TransmitChain request requires that the MAC driver copy at least the chain descriptor and immediate data, so this parameter is generally configurable through a PROTOCOL.INI keyword called MAXTRANSMITS. The protocol driver can use this queue depth to compute the amount of time a transmit might be queued up within the MAC.

The maximum number of data buffer blocks is the maximum number of blocks supported in Transmit, TransferData, and ReceiveChain buffer descriptors. For version 1.0.1 backward compatibility this must be a minimum of eight. For version 1.0.1 - compatible MACs for which this field is absent, the maximum number assumed is eight.

The size of the NDIS defined part of the MAC specific characteristics table may increase in subsequent versions of the specification. If vendor specific information follows the NDIS defined information, a protocol using it must check the NDIS spec version number in the common characteristics table to determine where the NDIS specified information ends and the vendor specified information begins.

MAC Service-Specific Status Table

The MAC service-specific status and media-specific statistics tables provide information about the status of and traffic through a MAC. Since these tables can be updated by the MAC driver at interrupt time, a protocol must ensure that these tables are read with interrupts disabled. The MAC must update this table (and the media-specific statistics table if present) atomically.

WORD	Length of status table
DWORD	Date/time when diagnostics last run (0xFFFFFFFF if not run), format is seconds since 12:00 midnight, January 1, 1970
DWORD	MAC status, a 32-bitmask: 0-2 - Opcoded as follows: 0 - Hardware not installed 1 - Hardware failed startup diagnostics 2 - Hardware failed due to configuration problem 3 - Hardware not operational due to hardware fault 4 - Hardware operating marginally due to soft faults 5-6 Reserved 7 - Hardware fully operational 3 - If set, MAC is bound, else not bound 4 - If set, MAC is open, else not open (if adapter doesn't support open/close function, set to 1 if hardware is functional) 5 - If set, adapter diagnostics are in progress (version 2.0.1 or later) 6-31 - Reserved, must be zero
WORD	Current packet filter, a bitmask: 0 - Directed and multicast or group and functional 1 - Broadcast 2 - Promiscuous 3 - All source routing 4-15 - Reserved, must be zero

Statistics for MACs

LPBUF	Pointer to media-specific statistics table (may be NULL)
DWORD	Date/time when last ClearStatistics issued (0xFFFFFFFF if not kept); format is seconds since 12:00 midnight, January 1, 1970
DWORD	Total frames received OK
DWORD	Total frames with CRC error
DWORD	Total bytes received
DWORD	Total frames discarded - no buffer space
DWORD	Total multicast frames received OK
DWORD	Total broadcast frames received OK
DWORD	Reserved (obsolete statistic)
DWORD	Reserved (obsolete statistic)
DWORD	Reserved (obsolete statistic)
DWORD	Reserved (obsolete statistic)
DWORD	Reserved (obsolete statistic)
DWORD	Total frames discarded - hardware error
DWORD	Total frames transmitted OK
DWORD	Total bytes transmitted OK
DWORD	Total multicast frames transmitted
DWORD	Total broadcast frames transmitted
DWORD	Reserved (obsolete statistic)
DWORD	Reserved (obsolete statistic)
DWORD	Total frames not transmitted - time-out
DWORD	Total frames not transmitted - hardware error

Remaining bytes (based on length) in the table are vendor specific.

All statistics counters are 32-bit unsigned integers that wrap to zero when the maximum count is reached, after which the counters will continue to count. When updating these counters, a frame is counted in all the supported counters that apply. The case of an unsupported counter (0xFFFFFFFF) can be distinguished from the situation whereby a county is about to wrap around if the values of the counters are checked at bind times. If the initial value of the counter is 0xFFFFFFFF, then the counter is not supported. Otherwise the counter is supported and 0xFFFFFFFF at a later time means the counter is about to wrap around.

Service-Specific Statistics Definitions

Total frames received OK
(NumberOfFramesReceivedOK)- corresponding 802.3 statistics

Total frames with CRC error
(NumberOfFramesReceivedWithFrameCheckSequenceErrors)

Total bytes received

Total frames discarded - no buffer space

Total multicast frames received OK
(NumberOfMulticastFramesReceivedOK)

Total broadcast frames received OK
(NumberOfBroadcastFramesReceivedOK)

Total frames discarded - hardware error

Total frames transmitted OK
(NumberOfFramesTransmittedOK)

Total bytes transmitted OK

Total multicast frames transmitted
(NumberOfMulticastFramesTransmittedOK)

Total broadcast frames transmitted
(NumberOfBroadcastFramesTransmittedOK)

Total broadcast bytes transmitted

Total frames not transmitted - time-out

Total frames not transmitted - hardware error

MAC Upper Dispatch Table

The number and meaning of dispatch addresses provided here apply to the boundary between a MAC and a protocol. This may differ at other protocol boundaries. Note that each upper/lower module binding may have its own unique set of dispatch addresses that is set up when the modules exchange characteristics tables. This can be achieved by exchanging copies of the common characteristics table, where the copy has the desired pointers to the specific dispatch tables for the binding.

LPBUF	Back pointer to common characteristics table
LPFUN	Request address
LPFUN	TransmitChain address
LPFUN	TransferData address
LPFUN	ReceiveRelease address
LPFUN	IndicationOn address
LPFUN	IndicationOff address

NOTE: No dispatch address is allowed to be NULL.

Protocol Service-Specific Characteristics Table

For compatibility with future versions of this specification, all protocols must provide a protocol service-specific characteristics table that starts with the following fields:

WORD	Length of protocol service-specific characteristics table
BYTE[16]	Type name of protocol, ASCIIZ format
WORD	Protocol type code

This can be followed by protocol-specific information.

The protocol type name will be used in future versions of this specification. Specific type names for different protocol types will be defined later. Protocol type codes will also be defined later. For now, these two fields are simple placeholders and must be set to null string and zero, respectively.

Protocol Lower Dispatch Table

The protocol lower dispatch table is specified in the characteristics table for the protocol binding to the MAC. The characteristics table for the MAC actually does not supply a lower dispatch table (the pointer to it is NULL).

LPBUF	Back pointer to common characteristics table
DWORD	Interface flags (used by VECTOR frame dispatch): 0 - Handles non-LLC frames 1 - Handles specific LSAP LLC frames 2 - Handles nonspecific LSAP LLC frames 3-31 - Reserved, must be zero
LPFUN	RequestConfirm address
LPFUN	TransmitConfirm address
LPFUN	ReceiveLookahead indication address
LPFUN	IndicationComplete address
LPFUN	ReceiveChain indication address
LPFUN	Status indication address

NOTE: No dispatch address is allowed to be NULL.

Characteristics Tables for NetBIOS Drivers

NetBIOS drivers written to the existing LAN Manager Ring 0 NetBIOS specification can be adapted to fit into the Protocol Manager structure by defining a common characteristics table for them. Note that such a NetBIOS driver must still respond to the existing LAN Manager NetBIOS linkage binding mechanism; these drivers will only use Protocol Manager binding at their lower boundary (to the MAC). A variant kind of NetBIOS module will be defined in the future that takes advantage of Protocol Manager binding at both boundaries.

Common characteristics for NetBIOS drivers:

WORD	Size of common characteristics table (bytes)
BYTE	Major NDIS version (2 BCD digits)
BY IN	Minor NDIS version (2 BCD digits)
WORD	Reserved
BY IF	Major module version (2 BCD digits)
BYTE	Minor module version (2 BCD digits)
DWORD	Module function flags, 0x00000002 (binds lower)
BYTE[16]	NetBIOS module name
BYTE	Protocol level at upper boundary of module: 5 = Session
BYTE	Type of interface at upper boundary of module: 1 = LAYMAN NCB
BYTE	Protocol level at lower boundary of module: 1 = MAC
BYTE	Type of interface at lower boundary of module: 1 = MAC
WORD	NetBIOS module ID
WORD	NetBIOS module DS
LPFUN	System request dispatch entry point
LPBUF	Pointer to service-specific characteristics (see the following lists)
LPBUF	Pointer to service-specific status, must be NULL
LPBUF	Pointer to upper dispatch table (see the following lists)
LPBUF	Pointer to lower dispatch table (see the following lists)
LPBUF	Reserved, must be NULL
LPBUF	Reserved, must be NULL

Upper dispatch table for a NetBIOS module:

LPBUF	Back pointer to common characteristics table
LPFUN	Request address
LPFUN	NetBIOS NCB handler (LAYMAN calling conventions)

Lower dispatch table for a NetBIOS module:

LPBUF	Back pointer to common characteristics table
DWORD	Interface flags (used by VECTOR frame dispatch): 0 - Handles non-LLC frames 1 - Handles specific LSAP LLC frames 2 - Handles nonspecific LSAP LLC frames 3-31 - Reserved, must be zero
LPFUN	RequestConfirm address
LPFUN	TransmitConfirm address
LPFUN	ReceiveLookahead indication address
LPFUN	IndicationComplete address
LPFUN	ReceiveChain indication address
LPFUN	Status indication address

Service-specific characteristics for a NetBIOS module:

WORD	Length of NetBIOS module service-specific characteristics table
BYTE [16]	Type name of NetBIOS module, ASCIIZ format
WORD	NetBIOS module type code

This can be followed by module-specific information.

The protocol type name will be used in future versions of this specification. Specific type names for different protocol types will be defined later. Protocol type codes will also be defined later. For now, these two fields are simple placeholders and must be set to null string and zero, respectively.

Frame Data Description

The MAC describes frame data with a data structure called a buffer descriptor. The descriptor is composed of pointers and lengths that describe a logical frame. Buffer descriptors are ephemeral objects. A descriptor is valid only during the scope of the call that references it as a parameter. The called routine must not modify the descriptor in any way. If the called routine needs to refer to the described data blocks after returning from the call, it must save the information contained in the descriptor.

Data blocks described by descriptors are long-lived. Ownership of the data blocks is implicitly passed to the module that is called with the descriptor. The called module relinquishes ownership back to the caller either via setting a return argument or by later issuing a call back to the supplying module. Under OS/2, some pointers may be either GDT virtual addresses or physical addresses. In this case, the pointer has an associated pointer type opcoded field. Defined values are zero for physical addresses and two for GDT virtual addresses. GDT virtual addresses can be supplied to the MAC only if bit 14 of the service flags in the MAC service-specific characteristics table is set. The GDT address must remain valid throughout the scope of its use by the MAC.

Under DOS, there is no distinction between physical and virtual addresses. All addresses in this case are segment:offset. Care must be taken to ensure that the segment offset plus data length do not exceed the 64K segment boundary. The pointer type field, if present, is always encoded as a zero.

For performance reasons, it is recommended that data blocks used for transmission and reception be double-word aligned where possible. Both MAC and protocol NDIS drivers may choose to perform byte, word, or dword memory movement without first ensuring proper alignment. This will result in reduced performance in combination with drivers that do not guarantee such alignment.

A buffer descriptor can contain one or more data blocks of length zero. In this case, the other fields in the data block (Data Ptr and Data Type) may not be valid and must be ignored.

Transmit Buffer Descriptor

All transmit data is passed using a far pointer to a transmit buffer descriptor, TxBufDescr. The format of transmit buffer descriptors is

WORD	TxImmedLen	Byte count of immediate data; max is 64
LPBUF	TxImmedPtr	Virtual address of immediate data
WORD	TxDataCount	Count of remaining data blocks; max is configurable

Followed by TxDataCount instances of

BYTE	TxPtrType	Type of pointer (0=physical, 2=GDT)
BYTE	TxResByte	Reserved byte (must be zero)
WORD	TxDataLen	Length of data block
LPBUF	TxDataPtr	Address of data block

In a TxBufDescr structure, the immediate data described by the first two fields is ephemeral and may be referenced only during the scope of the call that supplies it. Such immediate data is always transmitted before data described by TxDataLen and TxDataPtr pairs. If the called routine needs to refer to the immediate data after returning from the call, it must copy the data. The maximum size of immediate data is 64 bytes. For version 7.0.1 MACs or later, the maximum TxDataCount is specified in the MAC specific characteristics table. For version 1.0.1 MACs, the maximum count is eight.

Transfer Data Buffer Descriptor

Transfer data can be described by a far pointer to a transfer data buffer descriptor, TDBufDescr. The format of transfer data buffer descriptors is

WORD

TDDataCount

Count of transfer data blocks; max is configurable

Followed by TDDataCount instances of

BYTE	TDPtrType	Type of pointer (0=physical, 2=GDT)
BYTE	TDResByte	Reserved byte (must be zero)
WORD	TDDataLen	Length of data block
LPBUF	TDDataPtr	Address of data block

For version 2.0.1 MACs or later, the maximum TDDataCount is specified in the MAC specific characteristics table. For version 1.0.1 MACs, the maximum count is eight.

Receive Chain Buffer Descriptor

Receive chain data can be passed by a far pointer to a receive chain buffer descriptor,

RxBufDescr. The format of receive chain buffer descriptors is

WORD

RxDataCount

Count of receive data blocks; max is configurable

Followed by RxDataCount instances of

WORD	RxDataLen	Length of data block
LPBUF	RxDataPtr	Virtual address of data block

For version 2.0.1 MACs or later, the maximum receive data block count is specified in the MAC specific characteristics table. For version 1.0.1 MACs, the maximum count is eight.

For received frames that are larger than 256 bytes, the first data block of the frame must be at least 256 bytes long. Frames less than or equal to 256 bytes will be passed up with RxDataCount equal to one.

PROTOCOL.INI

The PROTOCOL.INI file stores configuration and binding information for all the protocol and MAC modules in the system. The file uses the same general format as the LANMAN.IN file. It consists of a series of named sections, where the section name is in fact the module name from a module characteristics table. Below the bracketed module name is a set of configuration settings for the module in name = value format. For example:

[MYNetBIOS]
Drivername = NetBIOS$
Bindings = ETHERCARD
MaxNCBs = 16
MaxSessions = 32
MaxNames = 16

The rules for PROTOCOL.INI contents are

Bracketed module name. This must be the name of a protocol or MAC module, for example, [MYNetBIOS]. This is the name of the module as defined in that module's characteristics table. The name must be 15 characters or less (not counting the brackets). Mixed case can be used, but the Protocol Manager will convert it to uppercase when it reads the file into memory.
Drivername = <device driver name>. This parameter is required for all device driver modules. It defines the name of the OS/2 or DOS device driver that the module is contained in. Note that a single device driver name can be mentioned by several sections of the PROTOCOL.INI file, if the driver contains multiple logical modules. The drivername parameter is the recommended method by which a module searches for its module section in the PROTOCOL.INI file to get its configuration parameters. This allows the module to find all relevant module sections based on a single name intrinsic to the module and independent of the particular bracketed module name used in the PROTOCOL.INI file. This keyword is also required for DOS dynamic modules like TSRs or transient application modules. Although there is no driver name intrinsically assigned to such modules, it is required that a unique name be assigned to this keyword for such modules anyway. In this way, the same search mechanism used by device drivers can be used by dynamic DOS modules to find their relevant module sections in PROTOCOL.
Bindings = <module name> | <module name>, <module name>, . . . This parameter is optional for protocol modules. It is not valid for MAC modules. If present, it is used by the protocol module to determine which MAC modules it will ask to bind to. (In other words, changing this parameter in the PROTOCOL.INI file can reconfigure a protocol to bind to a different MAC.) The bindings parameter can be omitted if the protocol driver software is preconfigured to bind to a particular MAC, or if the system will only contain one MAC and one static protocol module. In the latter case (only in static mode), the Protocol Manager by default will ask the one static protocol to bind to the one MAC.
Other keywords and parameters. Any other keyword = value statements are module specific. Keyword names must be 15 characters or less. They can be mixed case but are converted to uppercase when read by the Protocol Manager. Note that keyword names are unique within the scope of each <module name> section and can appear within the section In any order.
White space around the equal sign is not significant, nor is trailing white space on the line. Except for this leading and trailing white space, all other characters of the value string are taken verbatim.
A list of parameters can appear to the right of the equal sign. If there are no parameters, the equal sign can be optionally omitted. A parameter is terminated by a space, tab, comma, or semicolon. No parameters are interpreted by the Protocol Manager.
A parameter can either be up to a 31-bit signed numeric value or a string of any length.
A numeric parameter can be expressed either in decimal or hexadecimal format. All numeric parameters must start with the characters '0' through '9' or by a + or - followed by the '0' to '9' character. A hexadecimal parameter must start with '0x' or '0X' and use valid hexadecimal digits. A nonhexadecimal numeric parameter is treated as a decimal integer. A parameter not surrounded by quotes and starting with 0 to 9 or + or - followed by 0 to 9 will be assumed to be a numeric parameter.
A string is a parameter that either starts with a nonnumeric character or is surrounded with quotes ("...."). The string is preserved in the memory image as it appears in PROTOCOL.
A line starting with a semicolon in column one is a comment and is ignored. Blank lines are ignored too.
Lines can be as long as required. Continuation lines are not supported. Lines end with CR LF.
Tabs, formfeeds, and spaces are considered to be white space.

The Protocol Manager supports an optional section with optional keywords defined as follows:

[PROTMAN]
Drivername = PROTMAN$
Dynamic = YES or NO
PRIORITY = prot1, prot2, ...
Bindstatus = YES or NO

The bracketed module name can be any valid name as long as it is unique within this PROTOCOL.INI. Drivername is required and must be assigned PROTMAN$, identifying the section as belonging to the Protocol Manager. None of the entries are case sensitive.

The dynamic keyword is optional. It defaults to NO if not present. If set to NO, the Protocol Manager operates only in the static mode and does not support dynamic protocol drivers. If set to YES, the Protocol Manager operates in the dynamic mode and supports both static and dynamic binding.

The PRIORITY keyword is optional. If absent, the VECTOR uses default demultiplexing priority if multiple protocol drivers are bound to the same MAC (see the "VECTOR Demultiplexing" section in Chapter 7). If present, the parameters on the right-hand side are presumed to be a list of protocol module names, highest priority first. The VECTOR prioritizes protocol drivers for demultiplexing (if necessary) according to their order in the list, and packets are offered first to the first protocol driver listed. Protocol drivers not listed are assigned default priority AFTER those listed. It is not necessary that a protocol driver ever bind for it to be listed here.

The bindstatus keyword is optional. If absent, the BindStatus command is not supported by the Protocol Manager. If set to YES, BindStatus is supported by the Protocol Manager. The default disable condition is a memory optimization feature primarily for DOS environments.

When syntax errors are detected in processing the PROTOCOL.INI commands, by convention, all NDIS drivers should

Display an error message detailing the exact syntax problem
Assume some non-fatal value for the parameter associated with the error and complete processing

Configuration Memory Image

When the Protocol Manager initializes, it reads PROTOCOL.INI and parses it into a memory image that it makes available to MAC and protocol modules via the GetProtocolManagerInfo call. The parsed image is formatted to make it easy for run-time modules to interpret. All information contained in PROTOCOL.INI is present in the memory image in the same order as in the file. (Comments and white space are of course not present in the image.) Note that in static mode the image is only available during device driver initialization time. In dynamic mode the image may additionally be created by a utility that then registers it with the Protocol Manager.

The structure definitions defined in the following section do not conform rigorously to C language syntax They provide a pseudo C-like language to define the data structures encoded in the configuration memory Image.

ConfigMemorylmage

The ConfigMemoryImage data structure defines the complete memory image for all logical devices read from the PROTOCOL.INI configuration file. It is a doubly linked list of ModuleConfig structures. Each ModuleConfig structure corresponds to one module. The ConfigMemoryImage structure is defined as follows:

struct ConfigMemoryImage
{
        struct ModuleConfig(l) Module(l); 
        struct ModuleConfig(2) Module(2);
        . . .
        struct ModuleConfig(N) Module(N);
};

where

N = the number of modules encountered by the Protocol Manager when parsing the configuration file PROTOCOL.INI.

ModuleConfig

The ModuleConfig(i) structure defines the memory image for configuration parameters corresponding to one (bracketed name) module. The (i)th module specified in PROTOCOL.INI is defined as follows:

struct ModuleConfig(i)
{
        struct ModuleConfig(i+l) far *NextModule;
        struct ModuleConfig(i-1) far *PrevModule;
        unsigned char ModuleName [16];
        struct KeywordEntry(l) KeywordEntry(l);
        struct KeywordEntry(2) KeywordEntry(2);
        . . .
        struct KeywordEntry(N) KeywordEntry(N);
};

where

N = the number of keyword entries encountered in the PROTOCOL.INI file for this module.

NextModule = a FAR pointer to the next module configuration structure. This is NULL if it is the structure for the last module. For OS/2 the selector is a Ring 3 selector. For DOS the pointer is a segment:offset pair.

PrevModule = a FAR pointer to the previous module configuration structure. This is NULL if it is the structure for the first module. For OS/2 the selector is a Ring 3 selector. For DOS the pointer is a segment:offset pair.

ModuleName = an array containing the characters of the module name (given in brackets in the configuration file). This is an ASCIIZ string consisting of a maximum of 15 nonnull uppercase characters.

Keyword Entry

For each keyword line in the configuration file for the module, a memory image structure is created specifying the keyword and the parameter values. The (j)th keyword encountered in the PROTOCOL.INI file for the module is defined as follows:

struct KeywordEntry(j)
{
        struct KeywordEntry(j+1) far *NextKeywordEntry;
        struct KeywordEntry(j-1) far *PrevKeywordEntry;
        unsigned char Keyword[16]; 
        unsigned NumParams; 
        struct Param(1) Param(1); 
        struct Param(2) Param(2);
        . . . 
        struct Param(N) Param(N);
};

where

N = the number of parameters entered with the keyword. If N= 0, the parameters are not present.

NextKeywordEntry = a FAR pointer to the next keyword entry structure in the memory image. This is NULL if it is the last keyword entry. For OS/9 the selector is a Ring 3 selector. For DOS the pointer is a segment:offset pair.

PrevKeywordEntry = a FAR pointer to the previous keyword entry structure in the memory image. This is NULL if it is the first keyword entry. For OS/2 the selector is a Ring 3 selector. For DOS the pointer is a segment:offset pair.

Keyword = the array containing the characters of the keyword found in the configuration file. This is an ASCIIZ string consisting of a maximum of 15 nonnull characters. Alphabetic characters will be uppercase in the memory image.

NumParams = the number (N) of parameters entered with the keyword for each parameter described by a param structure. The value is zero if no parameters were present.

Param(k) = the (k)th parameter structure to specify the value of one parameter in a list of parameters for a keyword. Param(k+1) follows Param(k) in sequence within the memory image. Each parameter is delimited by a length field for the parameter. It is assumed that a keyword's fields will be parsed sequentially.

Param

For the (k)th parameter defined in a parameter list for a specific keyword, the following structure defines its value and attributes:

struct Param(k)
{
        unsigned ParamType; 
        unsigned ParamLen; 
        union ParamValue
        {
                long Numeric; 
                unsigned char String[STRINGLEN];
        };
};

where

STRINGLEN = the length of the ASCIIZ parameter string (including the terminating NULL) for string parameters.

ParamType = the type of parameter. The following types are supported:
= 0 a signed integer supporting up to 31-bit values with the least significant byte first
= 1 a string of characters

ParamLen = the length of the parameter value. The length could either be 4 for numeric parameters or STRINGLEN for string parameters, where STRINGLEN is the length of the string (including the terminating NULL).

Numeric = a 31-bit signed numeric value.

String = an ASCIIZ character string. The case of alphabetic characters in the string is preserved from that in PROTOCOL.INI.

The size of the Param(k) structure is thus ParamLen + 4.

BindingsList

For each module that registers with the Protocol Manager, a BindingsList structure may be given to the Protocol Manager specifying the set of modules that the given module wishes to bind to. The current module will require services from these other modules. This structure is defined as follows:

struct BindingsList
{
        unsigned NumBindings; 
        struct Module
        {
                char ModuleName[16];

        } BoundDriver[NUMBINDINGS];
};

where

NUMBINDINGS = the number of modules that the specified module wants to be bound to it from below. In the static default binding mode of one static protocol and one MAC, a value of zero in this field means for the protocol that it will bind to the MAC. Otherwise, in the nondefault binding mode, a value of zero in this field means that the module has no lower bindings.

ModuleName = an ASCIIZ string specifying the logical name of a module that the current module wishes to have bound to it from below. The string can be a maximum of 15 nonnull characters. The Protocol Manager will convert all alphabetic characters to uppercase.

BoundDriver = an array of NUMBINDINGS module names specifying the list of modules to which the current module wants to be bound.

The order of the modules in the list is significant in that InitiateBind requests will be issued to the protocol module in this order.

Specification of Primitives

Implementors should obey the following general guidelines:

All primitives specified in this section can be called in protected mode in either interrupt or task context under OS/2. Since any primitive can be called in interrupt context, it is illegal to block during the execution of a primitive.
All routines must run (as much as possible) with interrupts enabled. Interrupt handlers must dismiss the interrupt at the 8259 as soon as possible.
An indication handler will nominally be entered with interrupts enabled. The handle may enable or disable interrupts if it chooses, and on return the MAC must assume that the interrupt state may have been changed.
Under DOS, indication handlers must assume they have only 200 bytes of stack space. If more stack space is needed, then the handler must supply a stack.
Confirmation and IndicationComplete handlers must be fully reentrant and are always entered with interrupts enabled. Under DOS, Confirmation and IndicationComplete handlers must assume they are entered on whichever stack the interrupt occurred on.
A confirmation handler may be entered with the confirmation for a request before the request has resumed.
It is recommended that a MAC release the internal resources associated with either TransmitChain or a request before calling the confirmation handler. This allows the protocol to submit a new TransmitChain or request from the confirmation handler. Failing to do so may have a significant impact on performance.
A protocol must assume whenever it gives control to a MAC that interrupts may be enabled by the MAC unless otherwise explicitly specified.
When passing a virtual address to one of these primitives under OS/2, the address must be a Ring 0 GOT address unless otherwise specified. The interrupt service routine portion of the MAC must handle the fact that this address may not be valid if an interrupt occurs in real mode.
All primitives have a set of specific error codes defined. In general, MACs and protocols must return these specific codes. However, it is acceptable to return GENERAL_FAILURE for any nonrecoverable failure. NDIS developers must be aware that new error codes may be added in the future and must design their code to allow for this.
If a particular entry point or function is not supported by an NDIS protocol or MAC driver, the entry point must still be exposed and an error (INVALID FUNCTION 0x0008) resumed if it is called. Crashing when an unsupported request is made is unacceptable.
Parameters are passed on the stack compatible with Microsoft C FAR Pascal calling conventions. On entry to any routine the called module must save the caller's DS before setting its DS from the dataseg parameter. At exit the caller's DS must be restored. Furthermore, the called module must follow standard Microsoft C conventions about saving "register variable" SI and DI registers if these are used. Modules that use the 80386 registers EDI, ESI, and EBP must preserve these registers also. The direction bit is assumed to be clear on entry and must be clear upon exit. These conventions apply for calls in both directions across the NDIS MAC interface.
Direct calls return in AX a return code specifying the status of function invocation. Those functions specified as using IOCTLs return this in the status field of the request block.
Before calling a module in OS/2, it is the caller's responsibility to ensure that it is currently executing in protected mode. If it is running in real mode it must do an OS/2 RealToProt DevHlp call before calling the inter- module interface function. Furthermore, in OS/2 the inter-module call can only be made at post-CONFIG.SYS INIT time since all selectors are Ring 0 selectors.
A MAC starts with packet reception disabled. A protocol must call SetPacketFilter to enable reception of packets.
It is recommended that the number of request commands that can be simultaneously queued by the MAC be configurable. The suggested keyword in the configuration file is MaxRequests. The recommended default is 6. The suggested range is 1 through 10.
The number of TransmitChain commands that can be simultaneously queued by the MAC must be configurable. The suggested keyword in the configuration file is MaxTransmits. The recommended default is 6. The suggested range is 1 through 50.
On a DIX or 802.3 network, packet buffers received may have been padded to the minimum packet size for short packets. It is the responsibility of the MAC client to examine the length field if present and strip off the padding.
For DIX or 802.3 networks, the MAC client can transmit a buffer with packet length smaller than the minimum. It is the responsibility of the MAC to provide the required padding bytes before transmission to the wire. The content of the padding bytes is undefined.
Protocol drivers conforming to this specification are expected to format and interpret MAC headers for the MAC driver types supported. Generally, protocols are expected to support 802.3, DIN and 802.5 MAC headers. It is recommended that MAC drivers for other media types consider claiming to be one of the above types and doing a transparent internal mapping between that and its own private MAC header format. In doing so, the MAC will be able to claim interoperability (assuming the appropriate testing is done) with most protocol drivers developed for LAN Manager.
In the absence of any such conversion, the MAC header is passed protocol-to-MAC or MAC-to-protocol in exactly the format in which it exists on the medium. The CRC and nondata fields are not passed across this boundary. Therefore, the EtherNet CRC and the Token-Ring SD, FCS, ED, and FS fields are not passed and will not be included in the packet length. The protocol must convert header fields found in the header buffer passed up to whichever format is required to conveniently store them in local memory.
For example, multibyte fields (802.3 length, for instance) may not be received in the byte order that is normally used by the CPU for storing multibyte parameters. For exact format of the MAC header, refer to the appropriate standards document (see Appendix B).
For performance reasons, it is recommended that PhysToGDT be used whenever possible instead of PhysToVirt.
Commonly used parameters:

ProtID	The unique module ID of the protocol, assigned at bind time by the Protocol Manager.
MACID	The unique module ID of the MAC, assigned at bind time by the Protocol Manager.
ReqHandle	A handle assigned by the protocol to identify this request. If the request is implemented asynchronously by the MAC driver in question, this handle is returned on the confirmation call used to indicate completion of the request. A ReqHandle of zero indicates that the confirmation be unconditionally suppressed. For example, the request may still be handled asynchronously, but there will be no notification of completion. A ReqHandle of zero must not change the immediate return code.
ProtDS	DS value for the called protocol module, obtained from the module's dispatch table at bind time.
MACDS	DS value for the called MAC module, obtained from the module's dispatch table at bind time.

Direct Primitives

TransmitChain

Purpose: Initiate transmission of a frame.

PUSHWORD	ProtID;Module	ID of protocol
PUSHWORD	ReqHandle	Unique handle for this request or zero
PUSHLPBUF	TxBufDescr	Pointer to frame buffer descriptor
PUSHWORD	MACDS	DS of called MAC module
CALL TransmitChain
Returns:	0x0000 0x0002 0x0006 0x0007 0x0008 0x000A 0x000B 0x000C 0x00FF	SUCCESS REQUEST_QUEUED OUT_OF_RESOURCE INVALID_PARAMETER INVALID_FUNCTION HARDWARE_ERROR TRANSMIT_ERROR NO_SUCH_DESTINATION GENERAL_FAILURE

TxBufDescr Far pointer to the buffer descriptor for the frame.

Description:

This call asks the MAC to transmit data. The MAC can either copy the data described by TxBufDescr before resuming or queue the request for later (asynchronous) processing. The MAC indicates which option it is taking by setting the appropriate return code.

In the asynchronous case, ownership of the frame data blocks passes to the MAC until the transmission is complete; the protocol must not modify these areas until then. Ownership of the data blocks is resumed to the protocol when the MAC either returns a status code that implies completion of the original request or calls its TransmitConfirm entry with the ReqHandle from TransmitChain. If a request handle of zero is used and, therefore, TransmitConfirm is not called, then ownership must not be considered resumed until the protocol receives a message that implies the transmission has occurred (for example, receiving an ACK to the transmitted message).

Note that when doing asynchronous transmission the MAC must retain any needed information from TxBufDescr, since the pointer to that structure becomes invalid upon resuming from TransmitChain. Also, if the TxImmedLen of the descriptor is nonzero, the MAC must retain a copy of the immediate data at TxImmedPtr, since the immediate data area becomes invalid upon resuming from TransmitChain.

The MAC header must fit entirely in the immediate data, if present, or in the first nonimmediate element described in TxBufDescr if there is no immediate data.

A MAC must be prepared to handle a TransmitChain request at any time, including from within interrupt-time indication routines.

The return code REQUEST_QUEUED causes a TransmitConfirm to be called from the MAC back to the protocol if the ReqHandle on the TransmitChain call is not zero. All other return codes from TransmitChain imply that no TransmitConfirm will occur.

The TRANSMIT_ERROR and NO_SUCH_DESTINATION error codes are intended to allow a protocol to recreate the frame status byte on a Token-Ring network. Thus, NO_SUCH_DESTINATION implies that the address-recognized bits were not set (and therefore the frame was not copied), while TRANSMIT_ERROR merely means that the frame was not copied. Protocols that make use of source routing may need the NO_SUCH_DESTINATION error code to be completely conformant. Token-Ring MAC driver writers must make every attempt to return these error codes properly.

TransmitConfirm

Purpose: Imply the completion of transmitting a frame.

PUSH WORD	ProtID	Module ID of protocol
PUSH WORD	MACID	Module ID of MAC
PUSH WORD	ReqHandle	Unique handle from TransmitChain
PUSH WORD	Status	Status of original TransmitChain
PUSH WORD	ProtDS	DS of called protocol module
CALL TransmitChain
Returns:	0x0000 0x0007 0x00FF	SUCCESS

Description:

This routine is called by a MAC to indicate completion of a previous TransmitChain. The purpose of this is to return ownership to the protocol of the transmitted data blocks.

The ProtID parameter must be the value passed by the protocol on the previous TransmitChain that identifies the requester.

The ReqHandle is the value passed by the protocol on the previous TransmitChain that identifies the original request.

TransmitConfirm does not necessarily imply that the packet has been transmitted, though it generally will have been (with the exception of some intelligent adapter implementations). If the packet has been transmitted, Status must indicate the final transmit status:

0x0000	SUCCESS
0x000A	HARDWARE_ERROR
0x000B	TRANSMIT_ERROR
0x000C	NO SUCH_DESTINATION
0x00FF	GENERAL_FAILURE

For more details, see the preceding section, "TransmitChain."

ReceiveLookahead

Purpose: Indicate the arrival of a received frame and offer lookahead data.

PUSH WORD	MACID	Module ID of MAC
PUSH WORD	FrameSize	Total size of frame (zero if not known)
PUSH WORD	BytesAvail	Bytes of lookahead available in buffer
PUSH LPBUF	Buffer	Virtual address of lookahead data
PUSH LPBYTE	Indicate	Virtual address of indicate flag
PUSH WORD	ProtDS	DS of called protocol module
CALL ReceiveLookahead
Returns:	0x0000 0x0003 0x0004 0x0005 0x0006 0x0007 0x00FF	SUCCESS FRAME_NOT_RECOGNIZED FRAME_REJECTED FORWARD_FRAME OUT_OF_RESOURCE INVALID_PARAMETER GENERAL_FAILURE

FrameSize Total size, in bytes, of the received frame. A value of zero indicates that the MAC does not know the total frame size at this time.

BytesAvail Number of bytes available in the lookahead buffer. This is guaranteed to be at least as large as the lookahead size established with the SetLookahead request. For frames that are smaller than the lookahead size, the lookahead buffer will contain the whole frame.

BufferVirtual address of contiguous lookahead buffer. The buffer contains the leading BytesAvail octets of the frame. This buffer is ephemeral; it is addressable to the protocol only during the scope of the receive call.

Indicate Virtual address of indication flag byte. This byte is set to 0xFF by the MAC prior to this call. If the protocol clears the byte to zero prior to resuming, then indications will be left disabled until IndicationOn is called from IndicationComplete.

Description:

This routine is called by a MAC to indicate reception of a frame and to offer frame lookahead data. The protocol is expected to inspect this information very rapidly to determine whether or not it wants to accept the frame. If it wants to accept the frame, it may call TransferData to ask the MAC to copy the frame data to a specified buffer described by a TDBufDescr. The protocol can indicate that it is rejecting or does not recognize the frame by returning an appropriate error code. Note that the FRAME_NOT_RECOGNIZED error has special significance to the VECTOR function. If the protocol is accepting the frame and if the lookahead buffer contains the whole frame, the protocol can simply copy the data itself before returning from receive. The protocol can determine that it has the whole frame if BytesAvail equals FrameSize, or if the lookahead information includes a protocol header with die frame length, and this matches BytesAvail.

It is strongly recommended that MACs provide a nonzero FrameSize whenever possible. Some protocols might not be able to process frames unless the frame size given by this parameter is known. A MAC can optionally indicate that it does not normally provide a nonzero frame size by setting bit 16 of the service flags in the MAC specific characteristics table.

The MAC implicitly disables indications (IndicationOff) before calling ReceiveLookahead. The indicate flag byte instructs the MAC on whether to reenable indications or leave Hem disabled on the return. If the protocol chooses to leave indications disabled, it can enable Them within IndicationComplete by calling IndicationOn.

The protocol must absolutely minimize its processing time within the ReceiveLookahead handler. This is necessary to let certain MACs reenable the hardware to avoid loss of incoming frames. Shortly after returning from ReceiveLookahead, the MAC will call die protocol back at its IndicationComplete entry point. The protocol can do any needed post-processing of the received frame at diet time. The MAC does not guarantee to provide one IndicationComplete call for each indication. It can choose to issue a single IndicationComplete for several indications that have occurred.

TransferData

Purpose: Transfer frame data from the MAC to a protocol.

PUSH LPWORD	BytesCopied	Number of bytes copied
PUSH WORD	FrameOffset	Starting offset in frame for transfer
PUSH LPBUFTD	BufDescr	Virtual address of transfer data description
PUSH WORD	MACDS	DS of called MAC module
CALL TransferData
Returns:	0x0000 0x0007 0x0008 0x00FF	SUCCESS INVALID_PARAMETER INVALID_FUNCTION GENERAL_FAILURE

BytesCopied Virtual address of buffer for returning the number of bytes copied during transfer data operation.

FrameOffset Starting offset in received frame where data transfer must start. The value of FrameOffset must be less than or equal to the value of BytesAvail from the corresponding ReceiveLookahead.

TDBufDescr Virtual address of transfer descriptor describing where to store the frame data.

Description:

A protocol calls this synchronous routine from within its ReceiveLookahead handler before return, to ask the MAC to transfer data for a received frame to protocol storage. The protocol can specify any starting frame offset and byte count for the transfer, so long as these don't exceed the frame's length. If bit 15 of the MAC service flags is set, multiple TransferDatas can be called during a single ReceiveLookahead indication. If this bit is reset, only one TransferData per ReceiveLookahead indication is permitted. In the latter case, subsequent calls within the same indication will return an error.

For MACs with bit 15 of the MAC service flags reset, a protocol intending to call TransferData must do so only if it has decided to accept the incoming packet. Since the MAC drive may be shared by multiple protocols, a protocol's failure to follow this restriction in this case jeopardizes other coexisting protocol drivers from receiving these packets. When a protocol is bound to a MAC with bit 15 set, this restriction does not apply as a mandatory requirement. However, it is still recommended in such cases for performance reasons that a protocol call TransferData only if it has decided to accept the incoming packet. A protocol module must set the lookahead size large enough to determine if the packet is intended for it by examining only the lookahead bytes presented by ReceiveLookahead.

It is recommended that the multiple TransferData feature with bit 15 set be implemented in MAC drivers whenever it is reasonable to do so with the adapter hardware.

IndicationComplete

Purpose: Allow the protocol to do post-processing on indications.

PUSH WORD	MACID	Module ID of MAC
PUSH WORD	ProtDS	DS of called protocol module
CALL IndicationComplete
Returns:	0x0000 0x0007 0x00FF	SUCCESS INVALID_PARAMETER GENERAL_FAILURE

Description:

A MAC calls this entry point to enable a protocol to do post-processing after an indication. The MAC will always generate an IndicationComplete subsequent to an indication regardless of the return code of the indication. Although still in interrupt context and

subject to the normal OS/2 guidelines for interrupt processing, the protocol is not under the severe time constraints of the indication. The MAC must minimize stack usage before calling this routine and, under DOS, must have swapped off of any special "interrupt" stack.

This routine is always entered with interrupts enabled and with the network adapter interrupt dismissed from the interrupt controller. Therefore, it may be reentered at the completion of another indication. Also no one-to-one correspondence is guaranteed between indications and IndicationComplete. A MAC may generate one IndicationComplete for several indications. A protocol may enforce a ones one correspondence by leaving indications disabled until the return from IndicationComplete.

If indications are explicitly disabled by a protocol on return from an indication, it is the protocol's responsibility to invoke IndicationOn as soon as possible during IndicationComplete

MAC developers must avoid simply serializing each indication with IndicationComplete, as this can negatively affect performance. The MAC must be designed to allow an indication to occur during IndicationComplete processing. Of course, if this occurs, another IndicationComplete call Will be necessary.

ReceiveChain

Purpose: Indicate reception of a frame in MAC-managed buffers.

PUSH WORD

MACID

Module ID of MAC

PUSH WORD

FrameSize

Total size of frame Bytes)

PUSH WORD

ReqHandle

Unique handle for this request

PUSH LPBUF

RxBufDescr

Virtual address of receive descriptor

PUSH LPBYTE

Indicate

Virtual address of indicate flag

PUSH WORD

ProtDS

DS of called protocol module

CALL ReceiveChain

Returns:

0x0000
0x0001
0x0003
0x0004
0x0005
0x0006
0x0007
0x00FF

SUCCESS
WAIT_FOR_RELEASE
FRAME_NOT_RECOGNIZED
FRAME_REJECTED
FORWARD_FRAME
OUT_OF_RESOURCE
INVALID_PARAMETER
GENERAL_FAILURE

FrameSize

Total size of received frame, in bytes.

RxBufDescr

Virtual address of receive descriptor describing the received frame.

Indicate

Virtual address of indication flag byte. This byte is set to 0xFF by the MAC prior to this call. If the protocol clears the byte to zero prior to resuming, then indications will be left disabled until IndicationOn is called from IndicationComplete.

Description:

A MAC calls this routine to indicate the reception of a frame in MAC-managed storage. Ownership of this storage is implicitly passed to the protocol when this call is made. At its option, the protocol may copy the data right away and indicate this via the return code (in which case ownership reverts to the MAC); or the protocol may queue the request and copy the frame later (in which case it retains ownership of the frame's storage until it calls ReceiveRelease). Since the protocol may queue data received in this manner, it is possible that the MAC could run low on available frame buffers. The MAC may elect to call ReceiveLookahead instead of ReceiveChain while it is low on frame buffers. This allows the MAC to retain control of its remaining buffers until the protocol releases the buffers it is holding.

Note that for frames longer than 256 bytes, the MAC must guarantee that the first data block of the frame is at least 256 bytes long. Frames less than or equal to 256 bytes in length must be completely specified with a single data block. This allows the protocol to parse packet headers out of the first data block and greatly facilitates protocol processing efficiency.

Like ReceiveLookahead, a protocol's processing within ReceiveChain is time critical. At some point after return from ReceiveChain, the MAC will generate an IndicationComplete to allow post-processing of the indication.

The MAC implicitly disables indications (IndicationOff) before calling ReceiveChain. The indicate flag byte instructs the MAC on whether to reenable indications or leave them disabled on the return. If the protocol chooses to leave indications disabled, it can enable them within IndicationComplete by calling IndicationOn.

ReceiveRelease

Purpose: Return frame storage to the MAC that owns it.

PUSH WORD	ReqHandle	Unique handle from ReceiveChain
PUSH WORD	MACDS	DS of called MAC module
CALL ReceiveRelease
Returns:	0x0000 0x0007 0x0008 0x00FF	SUCCESS INVALID_PARAMETER NOT_SUPPORTED GENERAL_FAILURE

Description:

A protocol uses this call after it has copied frame data provided by a ReceiveChain call. ReceiveRelease returns ownership of the frame data blocks to the MAC.

IndicationOff

Purpose: Disable MAC indications.

PUSH WORD	MACDS	DS of called MAC module
CALL IndicationOff
Returns:	0x0000 0x0008 0x00FF	SUCCESS INVALID_FUNCTION GENERAL_FAILURE

Description:

A protocol can use this call to prevent the generation of ReceiveLookahead, ReceiveChain, and Status indications from the MAC. This is similar in concept to disabling interrupts. When indications are off, a MAC must queue events that would cause it to generate indications to the protocol. A MAC implicitly disables indications just before calling the ReceiveLookahead, ReceiveChain, or Status indication entry point of a protocol.

The only legal use of IndicationOff is to bracket a call or calls to the MAC. For example, the following sequence is valid:

IndicationOff
TransmitChain
IndicationOn

In this situation the protocol must not block while indications are off and must call IndicationOn as soon as possible. The protocol must ensure that all calls to IndicationOff are paired with a corresponding call to IndicationOn. If the protocol issues an IndicationOff call from a timer tick handle, or from a ReceiveLookahead, ReceiveChain, or Status indication handler, it must issue the IndicationOn call before resuming.

Note that IndicationComplete may still occur even though indications are disabled. Disabling indications has no effect on a MAC's ability to call IndicationComplete.

This function always returns with interrupts disabled. It is the responsibility of the caller to reenable them.

IndicationOn

Purpose: Enable MAC indications.

Called from protocol to MAC:

PUSH WORD	MACDS	DS of called MAC module
CALL IndicationOn
Returns:	0x0000 0x0008 0x00FF	SUCCESS INVALID_FUNCTION GENERAL_FAILURE

Description:

A protocol must use this call to reenable indications after having disabled them. Note that a MAC can optionally defer the actual reenabling of indications.

It is possible that IndicationOff and IndicationOn pairs will nest. Therefore, the MAC must maintain a reference count to enable it to determine when to actually reenable indications. The protocol must not assume that a call to IndicationOn will immediately enable indications.

IndicationOn may be called from an IndicationComplete handler after leaving indications disabled on return from an indication handler. IndicationOn may also be used, paired with IndicationOff, to bracket a call or calls to the MAC.

This function always returns with interrupts disabled. It is the responsibility of the caller to reenable them. No indications will be generated until after the call has returned.

General Requests

General requests are commands from a protocol to a MAC directing it to do adapter management operations like setting the station address, running diagnostics, and changing operating parameters or modes. A MAC may choose to implement any of the request functions synchronously or asynchronously. A MAC returns the REQUEST_QUEUED return code to inform the protocol that a given request will be processed asynchronously. When this is the case, the MAC will call back to the protocol's RequestConfirm entry point to indicate when processing of the request is complete. If a request handle of zero is used, then the RequestConfirm call is suppressed. It is the caller's responsibility to make certain that any data referenced by the request remains valid until the request is guaranteed to have completed. If a protocol makes a general MAC request when executing its InitiateBind startup function and the MAC returns REQUEST QUEUED, the protocol must wait for the corresponding RequestConfirm to be resumed before exiting from the InitiateBind function. Any other return code from a general request implies that no RequestConfirm will occur.

All general requests have the following common calling convention:

PUSH WORD	ProtID	Module ID of protocol or zero
PUSH WORD	ReqHandle	Unique handle for this request or zero
PUSH WORD	Param1	Request dependent word parameter or zero
PUSH DWORD	Param2	Request dependent dword parameter or zero
PUSH WORD	Opcode	Opcode of request
PUSH WORD	MACDS	DS of called MAC module
CALL Request

InitiateDiagnostics

Purpose: Start run-time diagnostics.

PUSH WORD	ProtID	Module ID of protocol
PUSH WORD	ReqHandle	Unique handle for this request or zero
PUSH WORD	0	Pad parameter - must be zero
PUSH DWORD	0	Pad parameter - must be zero
PUSH WORD	1	Initiate diagnostics request
PUSH WORD	MACDS	DS of called MAC module
CALL Request
Returns:	0x0000 0x0002 0x0006 0x0007 0x0008 0x0009 0x000A 0x00FF	SUCCESS REQUEST_QUEUED OUT_OF_RESOURCE INVALID_PARAMETER INVALID_FUNCTION NOT_SUPPORTED HARDWARE_ERROR GENERAL_FAILURE

Description:

This function causes a MAC to run hardware diagnostics and update its status information in the MAC-specific status section of the characteristics table. A MAC must return an error if it does not support run-time diagnostics. While the diagnostics are in progress, the MAC must set the diagnostics in progress bit (bit 5) in the MAC status field in the MAC service-specific status table. If HARDWARE_ERROR is resumed, the protocol can examine the various fields in the service-specific status table for an indication as to the cause of the problem.

ReadErrorLog

Purpose: Return the error log.

PUSH WORD	ProtID	Module ID of protocol
PUSH WORD	ReqHandle	Unique handle for this request or zero
PUSH WORD	LogLen	Length of log buffer
PUSH LPBUF	LogAddr	Buffer for returning log
PUSH WORD	2	ReadErrorLog request
PUSH WORD	MACDS	DS of called MAC module
CALL Request
Returns:	0x0000 0x0002 0x0006 0x0007 0x0008 0x0009 0x00FF	SUCCESS REQUEST_QUEUED OUT_OF_RESOURCE INVALID_PARAMETER INVALID_FUNCTION NOT_SUPPORTED GENERAL_FAILURE

Description:

This command causes a read error log to be issued to the adapter. This command is implemented on the IBM Token-Ring adapter and possibly other adapters. The format of the information returned is adapter specific and not specified here.

SetStationAddress

Purpose: Set the network address of the station.

PUSH WORD	ProtID	Module ID of protocol
PUSH WORD	ReqHandle	Unique handle for this request or zero
PUSH WORD	0	Pad parameter-must be zero
PUSH LPBUF	AdaptAddr	Buffer containing the adapter address
PUSH WORD	3	SetStationAddress request
PUSH WORD	MACDS	DS of called MAC module
CALL Request
Returns:	0x0000	SUCCESS
	0x0002	REQUEST_QUEUED
	0x0006	OUT_OF_RESOURCE
	0x0007	INVALID_PARAMETER
	0x0008	INVALID_FUNCTION
	0x0009	NOT_SUPPORTED
	0x00FF	GENERAL_FAILURE

Description:

There is only a single station address. Each time it replaces the current station address in the MAC service- specific characteristics table and reconfigures the hardware to receive on that address if required. The station is initially configured with the address specified in the permanent station address field of the MAC service-specific characteristics table (which this call does not modify).

The adapter address buffer contains only the bytes of the address to be set. The length of the address must be equal to the length specified in the MAC service characteristics table.

If the hardware does not support a mechanism to modify its station address, the current station address buffer is not updated and this function returns INVALID_FUNCTION. In this case the MAC continues to use the permanent station address to recognize incoming directed packets.

If a MAC does not support the OpenAdapter and CloseAdapter commands (bit 11 of the MAC service flags is reset), then the SetStationAddress command can be issued by the protocol at any time. However, if the MAC supports the OpenAdapter and CloseAdapter commands (bit 11 of the MAC service flags is set), then this command is valid either during system initialization time or while the MAC is in a closed state. The protocol driver must issue an OpenAdapter call after issuing the SetStationAddress call for the SetStationAddress command to take effect.

OpenAdapter

Purpose: Issue open request to the network adapter.

PUSH WORD	ProtID	Module ID of protocol
PUSH WORD	ReqHandle	Unique handle for this request or zero
PUSH WORD	OpenOptions	Adapter-specific open options
PUSH DWORD	ExtendedRet	Optional pointer to a DWORD extended return code (vendor specific or warning level)
PUSH WORD	4	OpenAdapter request
PUSH WORD	MACDS	DS of called MAC module
CALL Request
Returns:	0x0000 0x0002 0x0006 0x0007 0x0008 0x0009 0x0024 0x002A 0x00FF	SUCCESS REQUEST_QUEUED OUT_OF_RESOURCE INVALID_PARAMETER INVALID_FUNCTION NOT_SUPPORTED HARDWARE_FAILURE NETWORK_MAY_NOT_BE_CONNECTED GENERAL_FAILURE

Optional vendor-specific information can be resumed through the ExtendedRet pointer. A caller supporting this would push a pointer to a DWORD. The DWORD would have been initialized to 0xFFFFFFFF (unsupported). If there is any extended return information, this value would be changed. A caller not supporting this would simply push a NULL (0) pointer. The OpenAdapter routine that supports this would verify that the ExtendedRet pointer is not NULL and then write the information. The OpenAdapter routine that does not support this would simply ignore the pointer.

The purpose of ExtendedRet is to provide warning messages on a SUCCESS return without requiring additional testing for those callers not supporting warnings, to provide additional information about GENERAL_FAILURE and HARDWARE_FAILURE, and to pass vendor specific codes on any return to provide for active functional experimentation and evolution without inconveniencing other vendors' components.

Description:

The purpose of the OpenAdapter function is to activate an adapter's network connection. This may involve making an electrical connection for some adapters, such as Token-Ring adapters. This also implies that a considerable delay may occur between submittal of this request and its confirmation. If the MAC indicates that OpenAdapter is supported (by setting bit 11 of the service flags in the MAC service-specific characteristics table), then the protocol driver must ensure that the adapter is open during bind-time processing. Since OpenAdapter can only be called when the adapter is closed, even in a VECTOR configuration, the protocol must first check if the adapter is already open by examining bit 4 of the MAC status in the MAC service specific status table.

While an adapter is closed, the following functions are guaranteed to operate: SetLookahead, SetPacketFilter, SetStationAddress, Interrupt, IndicationOff, IndicationOn.

Since this function is adapter specific, it is expected that any necessary parameters are either known a priori by the MAC or can be recovered from the PROTOCOL.INI file. The format of the information is highly adapter specific and left up to the implementor to define.

The OpenOptions parameter is adapter specific. For IBM Token-Ring and compatible adapters, these are defined in the IBM Token-Ring Technical Reference Manual.

CloseAdapter

Purpose: Issue close request to the network adapter.

PUSH WORD	ProtID	Module ID of protocol
PUSH WORD	ReqHandle	Unique handle for this request or zero
PUSH WORD	0	Pad parameter- must be zero
PUSH DWORD	0	Pad parameter- must be zero
PUSH WORD	5	CloseAdapter request
PUSH WORD	MACDS	DS of called MAC module
CALL Request
Returns:	0x0000 0x0002 0x0006 0x0007 0x0008 0x0009 0x00FF	SUCCESS REQUEST_QUEUED OUT_OF_RESOURCE INVALID_PARAMETER INVALID_FUNCTION NOT_SUPPORTED GENERAL_FAILURE

Description:

This function closes an adapter. This causes it to decouple itself from a network so that packets cannot be sent or received. CloseAdapter resets the functional or multicast addresses currently set.

Since this function is adapter specific, it is expected that any necessary parameters are either already known by the MAC or can be recovered from the PROTOCOL.INI file. The format of the information is highly adapter specific and left up to the implementor to define.

ResetMAC

Purpose: Reset the MAC software and adapter hardware.

PUSH WORD	ProtID	Module ID of protocol
PUSH WORD	ReqHandle	Unique handle for this request or zero
PUSH WORD	0	Pad parameter- must be zero
PUSH DWORD	0	Pad parameter- must be zero
PUSH WORD	6	ResetMAC request
PUSH WORD	MACDS	DS of called MAC module
CALL Request
Returns:	0x0000	SUCCESS
	0x0006	OUT_OF_RESOURCE
	0x0007	INVALID_PARAMETER
	0x0008	INVALID_FUNCTION
	0x0009	NOT_SUPPORTED
	0x0074	HARDWARE_FAILURE
	0x009A	NETWORK_MAY_NOT_BE_CONNECTED
	0x00FF	GENERAL_FAILURE

Description:

This function causes the MAC to issue a hardware reset to the network adapter. The MAC may discard without confirmation any pending requests and abort operations in progress. For compatibility with some current protocols that do not properly handle resets, it is suggested that the MAC complete pending requests, returning INVALID_FUNCTION on all confirmations that result. The MAC must preserve the current station address, lookahead length, packet filter, multicast address list, functional address, and indication on/off state.

For MACs that support the OpenAdapter function, the ResetMAC command leaves the adapter in the opened state if it was opened prior to the reset. The adapter open parameters that were in effect prior to the reset must be the same ones in effect after the reset.

When the reset is initiated, the MAC must generate a StartReset status indication back to the protocol. For some MACs a considerable delay can elapse between the start of the reset and its completion. All MACs must subsequently issue an EndReset indication when the reset is complete. During the time between the StartReset indication and the corresponding EndReset indication, the MAC must return INVALID_FUNCTION for any request it receives while a reset is in progress. The EndReset indication notifies the protocol that the MAC can handle new requests. As always, an IndicationComplete follows these indications. MACs written to version 1.0.1. of this spec will not issue the EndReset indication. They must issue an IndicationComplete to signal the end of the reset.

Note that the completion (the return from this command or the request confirm) of the ResetMAC request itself does not signal the start or end of the reset.

There can be no guarantee that this function will succeed, though the NDIS MAC developer must make every attempt. An error return from this call can be considered fatal. If the reset fails, the adapter may no longer be in the same state. For example, if the adapter was open before a failed ResetMAC, it may now be closed.

ResetMac must not be queued.

SetPacketFilter

Purpose: Select received packet general filtering parameters.

PUSH WORD	ProtID	Module ID of protocol
PUSH WORD	ReqHandle	Unique handle for this request or zero
PUSH WORD	FilterMask	Bitmask for packet filter
PUSH DWORD	0	Pad parameter-must be zero
PUSH WORD	7	SetPacketFilter request
PUSH WORD	MACDS	DS of called MAC module
CALL Request
Returns:	0x0000	SUCCESS
	0x0002	REQUEST_QUEUED
	0x0006	OUT_OF_RESOURCE
	0x0007	INVALID_PARAMETER
	0x0008	INVALID_FUNCTION
	0x00FF	GENERAL_FAILURE

FilterMask:Bit

Description:

This command tells the MAC which kinds of received packets must generate indications to the protocol invoking this command. A FilterMask of zero indicates that the MAC must not indicate received packets to that protocol. If a FilterMask bit is set, this indicates that the MAC must indicate that type of packet to the protocol. Except for a zero FilterMask a filter bit of zero does not require the MAC to suppress indications for that type of packet. For example, the FilterMask used by the MAC may or may not correspond to the capabilities of the hardware adapter. A MAC can be designed to receive multicast frames by promiscuously receiving all frames and discarding those that do not match the filter. It is optional for the MAC to support such software filtering. If the MAC can suppress such indications, it is strongly recommended that it do so. However, if the MAC does not suppress such indications, then the protocol must be prepared to receive these and discard the incoming packet if necessary.

If this request returns SUCCESS, then the hardware is enabled to receive the types of packets requested and will generate indications to the protocol for those types of packets.

If the MAC does not support the receiving of packets of the type specified, then it will return GENERAL_FAILURE. In this case the FilterMask is left in its previous state.

AddMulticastAddress

Purpose: Allow the adapter to respond to a multicast address.

PUSH WORD	ProtID	Module ID of protocol
PUSH WORD	ReqHandle	Unique handle for this request or zero
PUSH WORD	0	Pad parameter- must be zero
PUSH LPBUF	MultiAddr	Buffer containing multicast address
PUSH WORD	8	AddMulticastAddress request
PUSH WORD	MACDS	DS of called MAC module
CALL Request
Returns:	0x0000	SUCCESS
	0x0002	REQUEST_QUEUED
	0x0006	OUT_OF_RESOURCE
	0x0007	INVALID_PARAMETER
	0x0008	INVALID_FUNCTION
	0x0009	NOT_SUPPORTED
	0x00FF	GENERAL_FAILURE

Description:

This function allows the addition of multicast addresses. The term multicast address also implies 802.5 group addresses. This function allows the addition of only one address at a time but can be repeated to add more multicasts.

It is the MAC's responsibility to return an error if too many multicast addresses have been added (OUT_OF_RESOURCE or INVALID_FUNCTION) or if an address of the wrong type has been added (INVALID_PARAMETER).

Multicast addresses are never overwritten and return an error (INVALID_PARAMETER) if they already exist, no matter what Their type. They must be explicitly deleted.

The multicast address buffer contains only the bytes of the multicast address to be added. The length of the multicast address must be equal to the length specified in the MAC service characteristics table.

DeleteMulticastAddress

Purpose: Forbid the adapter to respond to a multicast address.

PUSH WORD	ProtID	Module ID of protocol
PUSH WORD	ReqHandle	Unique handle for this request or zero
PUSH WORD	0	Pad parameter- must be zero
PUSH LPBUF	MultiAddr	Buffer containing multicast address
PUSH WORD	9	DeleteMulticastAddress request
PUSH WORD	MACDS	DS of called MAC module
CALL Request
Returns:	0x0000	SUCCESS
	0x0002	REQUEST_QUEUED
	0x0006	OUT_OF_RESOURCE
	0x0007	INVALID_PARAMETER
	0x0008	INVALID_FUNCTION
	0x0009	NOT_SUPPORTED
	0x00FF	GENERAL_FAILURE

Description:

This function removes a previously added multicast address. The term multicast address also implies 802.5 group addresses. INVALID_PARAMETER is returned if the address is not in the table.

The multicast address buffer has the same format as in the AddMulticastAddress command.

UpdateStatistics

Purpose: Cause MAC statistics to be updated.

PUSH WORD	ProtID	Module ID of protocol
PUSH WORD	ReqHandle	Unique handle for this request or zero
PUSH WORD	0	Pad parameter- must be zero
PUSH DWORD	0	Pad parameter - must be zero
PUSH WORD	10	UpdateStatistics request
PUSH WORD	MACDS	DS of called MAC module
CALL Request
Returns:	0x0000	SUCCESS
	0x0002	REQUEST_QUEUED
	0x0006	OUT_OF_RESOURCE
	0x0007	INVALID_PARAMETER
	0x0008	INVALID_FUNCTION
	0x00FF	GENERAL_FAILURE

Description:

This function causes the MAC to atomically update the statistics in its characteristics table. The requester can then read the table when this operation is complete. Those statistics that are not always current will remain the same until the next UpdateStatistics call is performed. If all of the statistics in the table are always current, this function must return SUCCESS.

ClearStatistics

Purpose: Cause MAC statistics to be cleared.

PUSH WORD	ProtID;	Module ID of protocol
PUSH WORD	ReqHandle	Unique handle for this request or zero
PUSH WORD	0	Pad parameter- must be zero
PUSH DWORD	0	Pad parameter - must be zero
PUSH WORD	11	ClearStatistics request
PUSH WORD	MACDS	DS of called MAC module
CALL Request
Returns:	0x0000	SUCCESS
	0x0002	REQUEST_QUEUED
	0x0006	OUT_OF_RESOURCE
	0x0007	INVALID_PARAMETER
	0x0008	INVALID_FUNCTION
	0x00FF	GENERAL_FAILURE

Description:

This function causes the MAC to reset its statistics counters. This implies that all statistics must be reset to zero in an atomic operation.

InterruptRequest

Purpose: Request asynchronous indication.

PUSH WORD	ProtID	Module ID of protocol
PUSH WORD	0	Pad parameter - must be zero
PUSH WORD	0	Pad parameter - must be zero
PUSH DWORD	0	Pad parameter - must be zero
PUSH WORD	12	InterruptRequest request
PUSH WORD	MACDS	DS of called MAC module
CALL Request
Returns:	0x0000	SUCCESS
	0x0006	OUT_OF_RESOURCE
	0x0008	INVALID_FUNCTION
	0x0009	NOT_SUPPORTED
	0x00FF	GENERAL_FAILURE

Description:

This function requests that the MAC generate an asynchronous interrupt status indication back to the protocol. The protocol may control the generation of this interrupt status indication by disabling and later enabling indications. The MAC may, at its discretion, suppress the generation of this indication if there is another indication pending that can be issued in place of the interrupt status indication. This request is intended to be used for MACs that can generate a hardware interrupt on demand. This function must be implemented if at all possible. InterruptRequest will substantially improve the performance of some protocols (particularly DLC).

SetFunctionalAddress

Purpose: Cause the adapter to change its functional address.

PUSH WORD	ProtID	Module ID of protocol
PUSH WORD	ReqHandle	Unique handle for this request or zero
PUSH WORD	0	Pad parameter- must be zero
PUSH LPBUF	FunctAddr	Buffer containing functional address
PUSH WORD	13	SetFunctionalAddress request
PUSH WORD	MACDS	DS of called MAC module
CALL Request
Returns:	0x0000	SUCCESS
	0x0002	REQUEST_QUEUED
	0x0006	OUT_OF_RESOURCE
	0x0007	INVALID_PARAMETER
	0x0008	INVALID_FUNCTION
	0x0009	NOT_SUPPORTED
	0x00FF	GENERAL_FAILURE

Description:

This function sets the IEEE 802.5 functional address to the passed functional address. The adapter will use the functional address to discern packets intended for it. For more information about functional addresses, see the IEEE 802.5 specification.

The functional address buffer contains only the bytes of the new functional address bit pattern. It represents the logical OR of all functional addresses to be registered with the adapter. The length of the functional address buffer is four bytes.

Multiple protocols can set or reset their functional address bit if required by each protocol by first reading the current functional address DWORD bit pattern from the MAC service characteristics table, then ORing in or ANDing out the required functional bit and passing the new functional address pattern in this command.

SetLookahead

Purpose: Set the length of lookahead information for ReceiveLookahead.

PUSH WORD	ProtID	Module ID of protocol
PUSH WORD	ReqHandle	Unique handle for this request or zero
PUSH WORD	Length	Minimum length of lookahead information
PUSH DWORD	0	Pad parameter- must be zero
PUSH WORD	14	SetLookahead request
PUSH WORD	MACDS	DS of called MAC module
CALL Request
Returns:	0x0000	SUCCESS
	0x0002	REQUEST_QUEUED
	0x0007	INVALID_PARAMETER
	0x00FF	GENERAL_FAILURE

Description:

This request sets the minimum length in bytes of lookahead information to be returned in a ReceiveLookahead indication. Until SetLookahead is initially called, a value of 64 bytes is assumed for the lookahead length. When first called, SetLookahead sets the lookahead length value equal to the length parameter of the request. After the first SetLookahead request, the lookahead length is changed only if the value of the length parameter is larger than the current lookahead length. If the length parameter value is smaller, the current lookahead length remains unchanged and SUCCESS is resumed. SetLookahead can be called at any time, and the lookahead length is preserved during a reset. The maximum value for the lookahead length is 256 bytes. MACs that never call ReceiveLookahead or always return lookahead information of length greater than or equal to 256 bytes can return SUCCESS without any internal action. MACs must support 256 bytes of lookahead data if requested.

General Request Confirmation

Purpose: Confirm the completion of a previous general request.

PUSH WORD	ProtID	Module ID of protocol
PUSH WORD	MACID	Module ID of MAC
PUSH WORD	ReqHandle	Unique handle for this request
PUSH WORD	Status	Final status of original request
PUSH WORD	Request	Original request opcode
PUSH WORD	ProtDS	DS of called protocol module
CALL RequestConfirm
Returns:	0x0000	SUCCESS
	0x0006	OUT_OF_RESOURCE
	0x0007	INVALID_PARAMETER
	0x0024	HARDWARE_FAILURE
	0x00FF	GENERAL_FAILURE

Description:

This function notifies a protocol that an asynchronous MAC control request has completed after the previous request had returned a REQUEST_QUEUED. It is possible that a RequestConfirm can be resumed to the protocol before the protocol's corresponding request function has completed.

The ProtID parameter must be the value passed by the protocol on the previous general request to identify the requester.

If a protocol had made a general MAC request when executing its InitiateBind startup function and the MAC resumed REQUEST_QUEUED, the protocol must wait for the corresponding RequestConfirm to be resumed before exiting from the InitiateBind function.

Status Indication

Status indications are spontaneous calls from a MAC to a protocol, typically at interrupt time. They inform the protocol of changes in MAC status.

All status indications have the following common calling convention:

PUSH WORD	MACID	Module ID of MAC
PUSH WORD	Param1	Opcode dependent word parameter or zero
PUSH LPBYTE	Indicate	Virtual address of indicate flag
PUSH WORD	Opcode	Opcode of status indication
PUSH WORD	ProtDS	DS of called protocol module
CALL Status

Indicate is the virtue address of the indication flag byte. This byte is set to 0xFF by the MAC prior to this call. If the protocol clears the byte to zero prior to resuming, then indications will be left disabled until IndicationOn is called from IndicationComplete.

RingStatus

Purpose: Return a change in ring status.

PUSH WORD	MACID	Module ID of MAC
PUSH WORD	Status	New ring status
PUSH LPBYTE	Indicate	Virtual address of indicate flag
PUSH WORD	1	RingStatus indication
PUSH WORD	ProtDS	DS of called protocol module
CALL Status
Returns:	0x0000	SUCCESS

Description:

This function is called by 802.5-style MAC drivers to indicate a change in ring status. The status codes for 802.5-style drivers are encoded as a 16-bit mask where the bits in the mask are defined as follows:

Bit	Meaning
15	Signal loss
14	Hard error
13	Soft error
12	Transmit beacon
11	Lobe wire fault
10	Auto-removal error 1
9	Reserved
8	Remove received
7	Counter overflow
6	Single station
5	Ring recovery
4-0	Reserved

For certain ring status changes, the adapter may already have been removed from the ring. The protocol driver must check whether the adapter has been closed (by examining bit 4 of the MAC status field in the MAC service-specific status table). For additional information, see the IBM Token-Ring Technical Reference Manual. If the status condition caused the adapter to close, the MAC must return confirmations with non-SUCCESS status codes for all pending TransmitChain and general requests.

AdapterCheck

Purpose: Return hardware status.

PUSH WORD	MACID	Module ID of MAC
PUSH WORD	Reason	Reason for adapter check
PUSH LPBYTE	Indicate	Virtual address of indicate flag
PUSH WORD	2	AdapterCheck indication
PUSH WORD	ProtDS	DS of called protocol module
CALL Status
Returns:	0x0000	SUCCESS

Description:

This function is called to indicate a fatal adapter error. If this function is called, the protocol must issue a ResetMAC call (if supported) before communications can resume. Note that a MAC may choose to tolerate some number of errors before issuing an AdapterCheck indication. For example, a MAC may want to accept the occasional receive DMA overrun, and only issue the AdapterCheck for this condition if it occurs excessively.

For 802.5 MACs the Reason code is defined as follows (NOT a bitmask):

0x8000	Adapter inoperative
0x1000	Illegal opcode
0x0800	Local bus parity error
0x0400	Parity error
0x0100	Internal parity error
0x0080	Parity error, ring transmit
0x0040	Parity error, ring receive
0x0020	Transmit overrun
0x0010	Receive overrun
0x0008	Unrecognized interrupt
0x0004	Unrecognized error interrupt
0x0003	Adapter detected no PC system service
0x0002	Unrecognized supervisory request
0x0001	Program request

All 802.5 values not defined in the preceding list are reserved.

The MAC must always return confirmations with non-SUCCESS status codes for all pending TransmitChain and general requests.

For 802.3 MACs the reason code is defined as follows (NOT a bitmask):

0x8000	Adapter inoperative (adapter did not respond to command or could not be found)
0x4000	Command timed out (adapter did not complete command within acceptable time interval)
0x2000	SQE test failure (no heartbeat detected on previous transmission)
0xl000	Excessive collisions (transmission failed due to excessive collisions)
0x0800	Lost carrier sense (adapter lost carrier during transmission)
0x0400	TDR failure (TDR test detected a short or open on the link)
0x0020	Transmit underrun (DMA underrun occurred on transmission)
0x0010	Receive overrun (DMA overrun occurred on reception)

All 802.3 values not defined in the preceding list are reserved.

StartReset

Purpose: Imply that the adapter has started a reset.

PUSH WORD	MACID	Module ID of MAC
PUSH WORD	0	Pad parameter - must be zero
PUSH LPBYTE	Indicate	Virtual address of indicate flag
PUSH WORD	3	StartReset indication
PUSH WORD	ProtDS	DS of called protocol module
CALL Status
Returns:	0x0000	SUCCESS

Description:

This function is called to indicate that the adapter has started a reset. This will generally be due to a call to ResetMAC (perhaps by another protocol driver in a VECTOR configuration) but can be unsolicited. The protocol must assume when it gets this indication that all requests outstanding to the MAC have been discarded without notification. The end of the reset will be signaled by an EndReset indication. The reset process may take a significant amount of time. While it is in progress, the MAC might reject any requests it cannot handle with INVALID_FUNCTION (0x0008 ). As with any other indication, StartReset is entered with indications implicitly disabled. To protect itself from other indications, the protocol may choose to modify the indicate flag to keep indications disabled on return. This will not prevent the EndReset indication from being generated, however StartReset is affected by IndicationOn and IndicationOff.

EndReset

Purpose: Imply that the adapter has finished a reset.

PUSH WORD	MACID	Module ID of MAC
PUSH WORD	Status	MAC error information
PUSH LPBYTE	Indicate	Virtual address of indicate flag
PUSH WORD	5	EndReset indication
PUSH WORD	ProtDS	DS of called protocol module
CALL Status	nbsp;	nbsp;>
Returns:	0x0000	SUCCESS
nbsp;	0x0008	INVALID_FUNCTION

Description:

This function is called to indicate that the adapter has finished a reset and follows the StartReset indication. The protocol may return INVALID_FUNCTION if it was written to version 1.0.1 of this specification, where it assumes end of reset on IndicationComplete. To ensure compatibility with version 1.0.1 protocol drivers, the MAC must ensure the IndicationComplete is called after EndReset and before any other indications.

EndReset will pass up a success/fail code for ResetMAC in the status parameter:

0x0000	SUCCESS
0x0024	HARDWARE_FAILURE
0x002A	NETWORK_MAY_NOT_BE_CONNECTED
0x00FF	GENERAL_FAILURE

As with any other indication, EndReset is entered with indications implicitly disabled. To protect itself from other indications, the protocol may choose to modify the indicate flag to keep indications disabled on return. MAC drivers must be prepared for the possibility that both StartReset and EndReset allow the protocol to modify this flag.

EndReset is NOT affected by IndicationOn/IndicationOff. In other words, if the protocol modifies the indicate flag during StartReset to disable indications, this will not prevent the EndReset indication from being generated.

If both StartReset and EndReset disable indications, the IndicationOff depth is two, requiring two calls to IndicationOn in order to enable indications. For example, if protocol A disables indications during StartReset and protocol B disables indications during EndReset, both protocols must issue IndicationOn before indications are reenabled. The same is true if the same protocol issues IndicationOff twice.

Interrupt

Purpose: Imply that an interrupt has occurred as the result of an interrupt request.

PUSH WORD	MACID	Module ID of MAC
PUSH WORD	0	Pad parameter - must be zero
PUSH LPBYTE	Indicate	Virtual address of indicate flag
PUSH WORD	4	Interrupt indication
PUSH WORD	ProtDS	DS of called protocol module
CALL Indication
Returns:	0x0000	SUCCESS

Description:

The MAC calls this function to indicate to a protocol that an interrupt requested by an interrupt request has occurred. Since this indication can be deferred by disabling indications, a protocol might use this mechanism to implement a simple scheduling schema to allow it to regain control once outside of a critical code region. The MAC may, at its discretion, suppress the generation of this indication if there is another indication pending that can be issued in place of the interrupt status indication.

[[[#Interrupt|previous]]][[[#InitiateBind|next]]] [[[#SpecificationPrimitives|parent]]][[[#toc|TOC]]]

System Requests

All MAC and protocol modules implement a set of system request functions that support module-independent functions such as binding. The caller of these functions is usually the Protocol Manager. The entry point for system requests is defined in the common characteristics table for the module. All system requests are implemented synchronously. Note that all pointers in system requests are Ring 0 GDT virtual addresses.

All system requests have the following common calling convention:

PUSH DWORD	Param1	Request-dependent dword parameter or zero
PUSH DWORD	Param2	Request-dependent dword parameter or zero
PUSH WORD	Param3	Request-dependent word parameter or zero
PUSH WORD	Opcode	Opcode of request
PUSH WORD	TargetDS	DS of called module
CALL System

InitiateBind

Purpose: Instruct a module to bind to another module.

PUSH DWORD	0	Pad parameter - must be zero
PUSH LPBUF	CharTab	Characteristics of module to bind
PUSH WORD	LastBind	Nonzero if last InitiateBind
PUSH WORD	1	InitiateBind request
PUSH WORD	ProtDS	DS of called protocol module
CALL System
Returns:	0x0000	SUCCESS
	0x0008	INVALID_FUNCTION
	0x0021	INCOMPLETE_BINDING
	0x0022	DRIVER_NOT_INITIALIZED
	0x0023	HARDWARE_NOT_FOUND
	0x0024	HARDWARE_FAILURE
	0x0025	CONFIGURATION_FAILURE
	0x0026	INTERRUPT_CONFLICT
	0x0027	INCOMPATIBLE_MAC
	0x0028	INITIALIZATION_FAILED
	0x002A	NETWORK_MAY NOT_BE CONNECTED
	0x002B	INCOMPATIBLE_OS_VERSION
	0x00FF	GENERAL_FAILURE

Description:

This call is issued by the Protocol Manager to an upper protocol module. It passes the address of the characteristics table of the lower module that the upper module must issue a bind call to. If the upper module specified a BindingsList including more than one lower module, then InitiateBinds will be issued for those modules in the order the lower modules are listed in the BindingsList structure. LastBind is used to indicate the last InitiateBind request so that the module can perform any final initialization prior to returning. In the static default binding case of one static protocol and one MAC, the Protocol Manager will issue an InitiateBind, passing the characteristics table of the MAC even if no bindings list was specified. In this case LastBind will be nonzero. In the nondefault case, if a module other than a MAC does not have lower bindings (having a BindingsList with a NumBindings count = 0), the Protocol Manager will still issue an InitiateBind to the module to allow final initialization. In this case CharTab will be NULL and LastBind will be nonzero.

If the bind operation fails, then the InitiateBind operation must also fail, returning the same return code as the failing bind call.

If a module returns a non-SUCCESS code on InitiateBind, in the dynamic mode the Protocol Manager will automatically deregister that module and remove all reference to it in its bind tables. In particular, any other module that had registered (via RegisterModule) its intention to bind with the failed module will get an InitiateBind call with the CharTab pointer FAR NULL and LastBind nonzero. A module that has lower bindings and receives an InitiateBind with a NULL bind CharTab must generate a non-SUCCESS return code in order to force the Protocol Manager to deregister it. In DOS it is recommended that a dynamic module that failed its bind uninstall itself. In OS/2 it is recommended that the dynamic driver that failed its bind leave its dynamic segments unlocked.

Bind

Purpose: Exchange module characteristics table information.

PUSH LPBUF	CharTab	Pointer to caller's table
PUSH LPBUF	TabAddr	Address where to return a pointer characteristics
PUSH WORD	0	Pad parameter- must be zero
PUSH WORD	2	Bind request
PUSH WORD	TargetDS	DS of called module
CALL System
Returns:	0x0000	SUCCESS
	0x0008	INVALID_FUNCTION
	0x0022	DRIVER_NOT_INITIALIZED
	0x0023	HARDWARE_NOT_FOUND
	0x0024	HARDWARE_FAILURE
	0x0025	CONFIGURATION_FAILURE
	0x0026	INTERRUPT_CONFLICT
	0x0027	INCOMPATIBLE_MAC
	0x0028	INITIALIZATION_FAILED
	0x002A	NETWORK_MAY NOT BE_CONNECTED
	0x002B	INCOMPATIBLE_OS_VERSION
	0x00FF	GENERAL_FAILURE

Description:

This function is used by one module to bind to another. It exchanges pointers to characteristics tables between the two modules. A MAC will accept only one bind and will not accept additional bind attempts.

For compatibility with remote initial program load, MAC drivers must not manipulate the network adapter at INIT time. The MAC driver is free to determine if the network adapter is present, but must leave any hardware manipulation to bind time processing.

InitiatePrebind (OS/2 only)

Purpose: In OS/2 dynamic bind mode, instruct a module to restart its prebind initialization.

PUSH DWORD	0	Pad parameter - must be zero
PUSH LPBUF	0	Pad parameter - must be zero
PUSH WORD	0	Pad parameter - must be zero
PUSH WORD	3	Bind request
PUSH WORD	ProtDS	DS of called protocol module
CALL System
Returns:	0x0000	SUCCESS
	0x00FF	GENERAL_FAILURE

Description:

In the OS/2 dynamic mode, this call is issued by the Protocol Manager to a dynamically loadable protocol driver when the Protocol Manager InitAndRegister is called. This function is available for the protocol driver to restart its prebind initialization when it is dynamically reloaded.

An OS/2 dynamic protocol driver is assumed to be made up of static and transient segments. When the protocol is not needed, the transient segments are unlocked (using the DevHlp Unlock command) to allow them to be swapped out. When the protocol is needed again, InitiatePrebind is issued. During InitiatePrebind, the driver needs to lock down its dynamic segments (using the DevHlp Lock command, type 1) to force them back into memory and make them addressable again. The protocol must save the lock handle resumed by this call to use Unlock later. Also, the prebind initialization sequence is initiated in this call and consists of rereading the PROTOCOL.INI memory image, configuration initialization, prebind memory allocations, and registration with the Protocol Manager. The protocol module typically carries out here the same functions that are performed by a static protocol module when a strategy routine INIT command is given.

InitiateUnbind

Purpose: Instruct a module to unbind from another module.

PUSH DWORD	0	Pad parameter - must be zero
PUSH LPBUF	CharTab	Characteristics of module to unbind
PUSH WORD	LastUnbind	Nonzero if last InitiateUnbind
PUSH WORD	4	InitiateUnbind request
PUSH WORD	ProtDS	DS of called protocol module
CALL System
Returns:	0x0000	SUCCESS
	0x00FF	GENERAL_FAILURE

Description:

This call is issued by the Protocol Manager in dynamic mode to an upper protocol module. It passes the address of the characteristics table of the lower module to which the upper module must issue an Unbind command (this would be an entry into the VECTOR if the lower module is a MAC). LastUnbind is used to indicate the last InitiateUnbind request, so the module can perform any final cleanup before resuming.

If a protocol module does not have lower bindings (having a BindingsList with a NumBindings count = 0), InitiateUnbind will still be issued with CharTab set to NULL and LastUnbind set to nonzero in order to allow the module to terminate.

Unbind

Purpose: An unbind request from an upper protocol module to a lower module.

PUSH LPBUF	CharTab	Callers characteristics table
PUSH DWORD	0	Pad parameter- must be zero
PUSH WORD	0	Pad parameter - must be zero
PUSH WORD	5	Unbind request
PUSH WORD	TargetDS	DS of called module
CALL System
Returns:	0x0000	SUCCESS
	0x0008	INVALID_FUNCTION
	0x00FF	GENERAL_FAILURE

Description:

This function is used by one protocol module to unbind from another. The caller's characteristics table is passed to permit the called module to identify the upper module. If the Unbind is to a MAC, the VECTOR does the Unbind cleanup on behalf of the MAC. Thus MAC drivers themselves do not need to support this call.

Protocol Manager Primitives

Since the Protocol Manager primitives can be accessed via an IOCTL in OS/9, a request block is defined as follows:

struct ReqBlock
{
        unsigned Opcode             /*Opcode for Protocol Manager request */
        unsigned Status             /*Status at completion of request*/
        char far *Pointer1              /*First parameter Ring 0 GDT pointer */
        char far *Pointer2              /*Second parameter Ring 0 GDT pointer */
        unsigned Word1              /*Parameter word */
};

Direct calls are made to the Protocol Manager with a pointer to the ReqBlock on the stack. For IOCTL requests, the parameter buffer contains a pointer to the ReqBlock. The direct calling sequence is as follows:

PUSH LPBUF	ReqBlock	Ring 0 GDT address of ReqBlock
PUSH WORD	TargetDS	DS of Protocol Manager
CALL ProtManEntry

Note that under OS/2 the direct entry cannot be used at CONFIG.SYS initialization time since the driver is still in Ring 3 context.

Note also that if the Protocol Manager is in dynamic mode, these primitives can be invoked by other modules after system initialization. Dynamic OS/2 Ring 0 device drivers issuing these primitives post-INIT time must use the direct entry interface since the IOCTL interface is illegal at this time.

GetProtocolManagerlnfo

Purpose: Retrieve the pointer to configuration image.

Opcode	1
Status	On return contains request status
Pointer1	On return contains a FAR pointer to structure memory image representing the parsed user configuration file PROTOCOL.INI. For static OS/2 device drivers, the selector of the pointer returned here is valid only at device INIT time. For dynamic OS/2 device drivers, the selector returned is always valid and will be a valid LDT selector for the process under which this primitive is called. For DOS this is a segment:offset pair.
Pointer2	Unused
Word1	On return contains the BCD-encoded major (low byte in memory) and minor (high byte in memory) version of the specification on which this Protocol Manager driver is based (version 2.0 for this specification).

Returns:	0x0000	SUCCESS
	0x0008	INVALID_FUNCTION
	0x0002	F INFO_NOT_FOUND
	0x00FF	GENERAL_FAILURE

Description:

This request is used by a module to the configuration information parsed from the user defined protocol configuration file PROTOCOL.INI. Modules invoke this function during device driver initialization to obtain this information for initializing configuration variables and making dynamic memory allocations and to determine their inter-module bindings.

In DOS dynamic mode, INFO_NOT_FOUND is returned if the Protocol Manager detects that the structured memory image is not valid. This can occur if, prior to loading a dynamic module, the structured configuration memory image was not registered with the Protocol Manager via a RegisterProtocolManagerInfo command or if the memory image got corrupted between registering it and getting it via the current primitive. The corruption might occur if another DOS program is loaded between the memory image registrations and the memory image read operation by a dynamic protocol invoking the GetProtocolManagerInfo primitive.

This request is valid in both the static and dynamic modes of Protocol Manager operation. In the static mode, this request is only valid prior to binding and starting. Invoking this primitive in static mode after all modules are bound and started will cause INVALID_FUNCTION to be resumed by the Protocol Manager.

RegisterModule

Purpose: Register a module and its bindings.

Opcode	2
Status	On return contains request status
Pointer1	Contains a FAR pointer to the module's common characteristics table. The module must have all information in that table filled in except for the module B), which is filled in by the Protocol Manager on return.
Pointer2	Contains a FAR pointer to a BindingsList structure of the modules to which this module wants to be bound. The Protocol Manager will use only the information passed in the BindingsList to determine the relevant module bindings. This pointer can be FAR NULL to indicate that this module will not currently bind to any module. This latter option is useful for dynamic OS/2 modules that need to register their module name with the Protocol Manager but do not want to remain fully resident (and therefore bind) at the current time. This nonbindable registration permits the dynamic driver to reregister with a BindingsList when it is later reloaded and made operational.
Word1	Unused

Returns:	0x0000	SUCCESS
	0x0008	INVALID_FUNCTION
	0x002C	ALREADY_REGISTERED
	0x00FF	GENERAL_FAILURE

Description:

This request is used by a driver or dynamically loadable executable to identify one of its contained modules to the Protocol Manager. After calling RegisterModule, a static driver must remain installed and respond to system requests. A dynamic OS/2 driver must leave its system entry function code permanently locked in memory. A dynamic DOS module must remain installed and respond to system requests until it is unbound and unloaded. This registration is accomplished by passing a pointer to the module's characteristics table to the Protocol Manager. The driver also passes a bindings list requested by the module. The bindings list contains the one or more module names that the module wants to bind to as a client. This bindings information is later used by the Protocol Manager to determine the necessary sequence of InitiateBind commands to issue. This bindings list must persist while the protocol is operational. In the static default bindings case of one static protocol and one MAC, the bindings list pointer provided in this request can be NULL, indicating that a protocol module by default will bind to the single underlying MAC. Otherwise, in the nondefault bindings case, a NULL bindings list pointer provided in this request will indicate that this module will not bind to any other module at the current time and is not ready to initialize. In this latter case the Protocol Manager will not call the module's InitiateBind system function. A NULL bindings list pointer is particularly useful for dynamic OS/2 drivers that register their module name at INIT time, but are not to remain fully resident at startup time. This is called a nonbindable registration. A protocol module can also pass a non-NULL bindings list with a zero number of bindings count. In the default bindings case, this is interpreted by the Protocol Manager to bind the protocol to the single underlying MAC. In the nondefault bindings configuration this means that a protocol is registering without any lower bindings, but is required to be initialized by an InitiateBind call.

A driver that contains multiple modules can call RegisterModule multiple times, once for each module. The Protocol Manager responds to each request by assigning each module a module ID. The module ID is resumed in the module's characteristics table on completion of the RegisterModule request.

If a module name is currently registered with the Protocol Manager, an attempt to register the same module name will fail and a status code of ALREADY REGISTERED will be resumed. A dynamic OS/2 driver is considered currently registered if it had previously registered with a non-NULL bindings list indicating a requirement to bind and/or start and it had not yet unbound. Thus, a dynamic OS/2 driver can reregister with the Protocol Manager under the same module names if it either had unbound or had not previously made a bindable registration.

This request is valid in both the static and dynamic modes of Protocol Manager operation. In the static mode, this request is only valid prior to binding and starting. Invoking this primitive in static mode after all modules are bound and started will cause INVALID_FUNCTION to be returned by the Protocol Manager. A registration of a dynamic module (bit 2 set of the module function flags in the common characteristics table) in static Protocol Manager mode is invalid and will generate INVALID_FUNCTION. It is mandatory that all static DOS and static and dynamic OS/2 device drivers invoke this function at least once at INIT time.

BindAndStart

Purpose: Initiate the binding process.

Opcode	3
Status	On return contains request status
Pointer1	Caller's virtual address of FailingModules structure. This structure in the caller's address space is filled in by the Protocol Manager prior to resuming from BindAndStart. If BindAndStart reports an error, it contains the module names in ASCIIZ format of the upper module and lower module (may be a NULL string) reporting the error. If BindAndStart is successful, then both are NULL strings. For example: struct FailingModules { char UpperModuleName[16] /* Upper failing module / char LowerModuleName{16} / Lower failing module */ };
Pointer2	Unused
Word1	Unused

Returns:	0x0000	SUCCESS
	0x0007	INVALID_PARAMETER
	0x0008	INVALID_FUNCTION
	0x0020	ALREADY_STARTED
	0x0021	INCOMPLETE_BINDING
	0x0022	DRIVER_NOT_INITIALIZED
	0x0023	HARDWARE_NOT_FOUND
	0x0024	HARDWARE_FAILURE
	0x0025	CONFIGURATION_FAILURE
	0x0026	INTERRUPT_CONFLICT
	0x0027	INCOMPATIBLE_MAC
	0x0028	INITIALIZATION_FAILED
	0x0029	NO_BINDING
	0x0002	D PATH_NOT_FOUND
	0x0002	E INSUFFICIENT_MEMORY
	0x00FF	GENERAL_FAILURE

Description:

This request is used to trigger the Protocol Manager bind and start sequence. This permits an application program (for example, executing from a DOS batch or OS/2 command file) to trigger the bind sequence. The bind sequence is invoked by the Protocol Managers calling each module's inter-module InitiateBind function. If an InitiateBind fails, then BindAndStart will fail with the same return code as the failing InitiateBind.

In the static mode of Protocol Manager operation, this request can be invoked only once to bind and start all static drivers. Successive invocations return INVALID_FUNCTION.

In the dynamic mode, this command tells the Protocol Manager to issue the InitiateBind primitive to all dynamically loaded protocol drivers that have registered since the last InitiateBind (or since the beginning of time for the first call)

In DOS, the caller is required to invoke this primitive via the direct entry point rather than the DOS IOCTL method. The Protocol Manager will generate an INVALID_FUNCTION error if this function is invoked by an IOCTL. This will permit the protocol modules to make DOS function calls during their bind and start sequence initiated by this primitive (when the Protocol Manager calls the InitiateBind system entry point of the protocol). If the IOCTL were used, the bind/start sequence would be carried out inside a DOS call, and protocols would not be able to make further DOS calls within their initialization sequence in order to prevent DOS reentry.

In DOS, the Protocol Manager loads PROTMAN.EXE to execute this command. The caller must have previously guaranteed that at least 20K of memory is available to load PROTMAN.EXE prior to invoking the BindAndStart primitive. In static VECTOR configurations (Chapter 7), PROTMAN.EXE will remain resident after BindAndStart completes. In such cases it is strongly recommended that the caller free as much memory as possible prior to calling BindAndStart so the PROTMAN.EXE will reside in the lowest memory possible. This will prevent large unusable gaps in DOS memory when the calling function terminates.

A utility, NETBIND.EXE, that invokes the BindAndStart primitive is provided with the Protocol Manager and is described in Appendix E.

GetProtocolManagerLinkage

Purpose: Retrieve Protocol Manager dispatch and DS value.

Opcode	4
Status	On return contains request status
Pointer1	On return contains the Protocol Manager dispatch point
Pointer2	Unused
Word1	On return contains the Protocol Manager DS

Returns:	0x0000	SUCCESS
	0x0008	INVALID_FUNCTION
	0x00FF	GENERAL_FAILURE

Description:

This request is used by a module to obtain the dispatch entry point and DS of the Protocol Manager. Direct calls can then be made by DOS and OS/2 Ring 0 drivers and DOS utilities to the dispatch entry point.

All dynamically reloaded OS/2 protocol drivers must issue this command to the Protocol Manager at CONFIG.SYS INIT time using the IOCTL mechanism and must save the Ring 0 Protocol Manager dispatch entry point and DS. When the driver subsequently reregisters with the Protocol Manager on reload at post-INIT time, it must do so via the direct entry interface using the saved entry point and DS (since an IOCTL would be illegal at that time).

Any DOS utility that intends to invoke the BindAndStart or UnbindAndStop Protocol Manager primitives must first invoke this primitive to get the Protocol Managers direct entry point.

This request is valid in both the static and dynamic modes of Protocol Manager operation. In the static mode, this request is only valid prior to binding and starting. Invoking this primitive in static mode after all modules are bound and started will cause INVALID_FUNCTION to be resumed by the Protocol Manager.

GetProtocollniPath

Purpose: A command to obtain the path to the PROTOCOL.INI file read by the Protocol Manager what it initialized.

Opcode	5
Status	On return contains request status
Pointer1	The virtual FAR pointer to a buffer, which will contain the returned PROTOCOL.INI pathname in ASCIIZ format on completion
Pointer2	Unused
Word1	The length of the provided buffer on input

Returns:	0x0000	SUCCESS
	0x0007	INVALID_PARAMETER
	0x0008	INVALID_FUNCTION

Description:

This primitive can be called by an application program or dynamically loadable protocol that will read and parse the PROTOCOL.INI file to obtain the original location of the PROTOCOL.INI file used by the Protocol Manager when it initialized. This permits such a program to use the same file read by the Protocol Manager. The Protocol Manager returns only the pathname to the subdirectory containing the PROTOCOL.INI file, excluding the string \PROTOCOL.INI, which may be up to 60 characters in length. This string will include the drive identifier and be fully qualified relative to the root. The buffer must be large enough to hold the resumed string. If not, the contents of the buffer are undefined and the INVALID_PARAMETER error is returned.

This request is valid in both the static and dynamic modes of Protocol Manager operation. In the static mode, this request is only valid prior to binding and starting. Invoking this primitive in static mode after all modules are bound and started will cause INVALID_FUNCTION to be returned by the Protocol Manager.

RegisterProtocolManagerlnfo

Purpose: A command valid only in the dynamic mode to register the current starting address of the PROTOCOL.INI memory image with the Protocol Manager.

Opcode	6
Status	On return contains request status
Pointer1	The virtual FAR pointer to the structured memory image representing the parsed user configuration file, PROTOCOL.INI
Pointer2	Unused
Word1	Length of structured memory image

Returns:	0x0000	SUCCESS
	0x0008	INVALID_FUNCTION

Description:

In dynamic mode, this command registers with the Protocol Manager the address of the PROTOCOL.INI memory image. It is assumed that prior to dynamically loading a protocol module, the PROTOCOL.INI file is reread and reparsed in some memory image. The pointer to the memory image is given to the Protocol Manager, so that it is available for the GetProtocolManagerInfo primitive of the dynamic initializing module that reads its configuration parameters.

In static mode, this command is illegal and the INVALID_FUNCTION error code is resumed.

A utility, READPRO.EXE, that reads and parses the PROTOCOL.INI file into a memory image and registers this with the Protocol Manager is provided with the Protocol Manager and is described in Appendix E.

InitAndRegister

Purpose: An optional dynamic OS/2 command to dynamically restart the prebind initialization of a dynamically reloadable protocol driver.

Opcode	7
Status	On return contains request status
Pointer1	Unused
Pointer2	FAR virtual pointer to an ASCIIZ buffer containing the name of the module to be prebind initialized
Word1	Unused

Returns:	0x0000	SUCCESS
	0x0007	INVALID_PARAMETER
	0x0008	INVALID_FUNCTION
	0x00FF	GENERAL_FAILURE

Description:

In OS/2 dynamic mode, this command reactivates the transient portions of a protocol driver previously statically loaded at system startup, but for which the transient portions of the driver were not locked down. The command causes the Protocol Manager to invoke the system entry point of the specified module with the InitiatePrebind function in order for the driver to restart its prebind initialization. The prebind initialization functions are driver specific. However, it is expected that such functions might include

Locking down its dynamic segments using the DevHlp Lock command (lock type 1) and saving the resumed lock handle
Getting its PROTOCOL.INI configuration information
Doing its prebind initialization
Registering with the Protocol Manager

In static mode, this command is illegal and the INVALID_FUNCTION error code is resumed.

UnbindAndStop

Purpose: A dynamic binding command to terminate a transient, previously dynamically bound protocol module and to terminate its bindings.

Opcode	8
Status	On return contains request status
Pointer1	Failing modules as for the BindAndStart command
Pointer2	If non-NULL, FAR virtual pointer to an ASCIIZ buffer containing the name of the module to be unbound If NULL, terminates a set of previously dynamically bound protocol modules as defined in the following section (valid only for DOS)
Word1	Unused

Returns:	0x0000	SUCCESS
	0x0007	INVALID_PARAMETER
	0x0008	INVALID_FUNCTION
	0x0002	D PATH_NOT_FOUND
	0x0002	E INSUFFICIENT_MEMORY

Description:

This command is used in the dynamic mode to terminate either a specific protocol module or a set of previously dynamically bound protocol modules and to terminate their binds. A "set" is the collection of protocol modules previously loaded or reloaded between two successive BindAndStart calls or between the last BindAndStart and this call. Successive UnbindAndStop commands with NULL Pointer2 arguments terminate protocol sets in the reverse order in which they were bound. The Protocol Manager removes references to the protocols from its VECTOR (for MAC unbindings) table and general bindings tables. The Protocol Manager issues an InitiateUnbind command to each protocol to be unbound so that the protocol can issue an Unbind command to the modules that it is bound to. For MAC unbindings, the Unbind is issued back to the Protocol Manager VECTOR. The NULL Pointer2 option is used in DOS environments for TSR protocol modules in which the unbind sequence usually proceeds in reverse order of the bind sequence. The non- NULL Pointer2 option must be used in OS/2 environments. The NULL Pointer2 option is invalid for OS/2.

In DOS, the caller is required to invoke this primitive via the direct entry point method rather than the DOS IOCTL method. The Protocol Manager will generate an INVALID_FUNCTION error if this function is invoked by an IOCTL. This will permit the protocol modules to be terminated to make DOS function calls during their unbind/stop sequence initiated by this primitive (when the Protocol Manager calls the InitiateUnbind system entry point of the protocol). If the IOCTL were used, the unbind/stop sequence would be carried out inside of a DOS call, and protocols would not be able to make further DOS calls within their termination sequence in order to prevent DOS reentry.

In DOS the Protocol Manager loads PROTMAN.EXE to execute this command. The caller must have previously guaranteed that at least 20K of memory is available to load PROTMAN.EXE prior to invoking the UnbindAndStop primitive.

A utility, UNBIND.EXE, that invokes the UnbindAndStop primitive is provided with the Protocol Manager and is described in Appendix E.

In static mode, this command is illegal and the INVALID_FUNCTION error code is resumed.

BindStatus

Purpose: A command to obtain information from the Protocol Manager about the current set of bound modules.

Opcode	9
Status	On return contains request status
Pointer1	On input, under OS/2 only, if the caller is in Ring 3, this must be a FAR virtual pointer to a buffer where the resumed information will be stored On input, under DOS or in OS/2, if the caller is in Ring 0, this pointer must be NULL On output, Pointer1 points to the root tree
Pointer2	NULL
Word1	Only used in OS/2 Length of buffer (input) and bytes copied (output)

Returns:	0x0000	SUCCESS
	0x0008	INVALID_FUNCTION
	0x000D	BUFFER_TOO_SMALL

Description:

If enabled by the Protocol Managers BINDSTATUS=YES parameter in PROTOCOL.INI, this command can be called at any time to obtain information from the Protocol Manager about the current set of bound modules. If this command is disabled, an attempt to invoke this command will return INVALID_FUNCTION.

The following characteristics tables are returned for the modules that qualify:

Common characteristics
Service-specific characteristics (including the multicast address list for MAC modules)
Service-specific status
Media-specific statistics (for MAC modules only)

The tables are linked together into a bind tree using a new structure:

struct BindNode
{
        struct cctable far *commonptr,
        struct BindNode far *down; 
        struct BindNode far *right;
};

NOTE: There may be additional fields added to BindNode in the future, so do not rely on its exact size.

A BindNode is linked to its common characteristics table (CCT) by the CommonPtr field. The CCTs are then linked into a bind tree using the right and down pointers. Down points to the first BindNode bound below this one, and right points to the next. At the top of the tree (the uppermost level), the right pointers also link together the BindNodes as if they are bound to a virtual root BindNode.

A simple example might help illustrate this better:

        protocol
       /      \
      MAC1    MAC2

This would be represented by the following bind tree:

     Protocol
            |
            V
           MAC1 --> MAC2

In the example, the BindNodes have been hidden to keep the diagram simple-only their down and right pointers are shown. The remaining down and right pointers would be NULL.

One option when making this call is to pass a NULL buffer pointer (in Pointer1), in which case the root BindNode pointer will be returned in Pointer1. The Protocol Manager uses BindNodes internally to build the bind tree. The caller can then run the current bind tree to obtain information. This is the only method supported under DOS. Under OS/2, this method will only work for Ring 0 drivers.

Under OS/2, Ring 3 programs must use a second method by providing a pointer to a buffer (in Pointer1) of a specified size (in Word1) to copy the characteristics tables into. In this case, the Protocol Manager will copy the qualifying tables into the buffer provided. The first entry in the buffer will be the root BindNode. The order of the remaining BindNodes and tables within the buffer is undefined. The BindNodes and their various tables are linked together by pointers that will be fixed by the Protocol Manager to use the same selector as the buffer itself (that is, Ring 3 if the buffer is Ring 3). Specifically, the Protocol Manager will fix the following entries:

BindNode:
CommonPtr
Down
Right
Common characteristics:
Pointer to service-specific characteristics
Pointer to service-specific status
Service-specific characteristics
Pointer to multicast address list (MACs only)
Service-specific status
Pointer to media-specific statistics (MACs only)

The remaining pointers (for example, dispatch tables and entry points) will be in an undefined state and must not be relied upon.

If the buffer is too small, BUFFER_TOO_SMALL will be resumed, the pointers to tables that were not copied will be NULL, and the bytes copied return parameter (Word1) will indicate where the information was truncated.

The information resumed is merely a snapshot at a particular point of time. The Protocol Manager will disable interrupts while copying individual status and media- specific statistics tables to guarantee their internal integrity. The caller cannot assume that all tables were copied in the same atomic operation, however.

In the case of OS/2, if two or more modules are bound to the same lower module, the lower module's table is duplicated in the tree. Therefore, the Ring 3 caller will have to provide a larger amount of buffer space for the returned information.

The number of nodes in the bind tree does not necessarily reflect the number of modules bound.

RegisterStatus

Purpose: A command to query whether a specific logical module is currently registered with the Protocol Manager.

Opcode	0x0A
Status	On return, contains request status
Pointer1	NULL
Pointer2	FAR virtual pointer to a byte ASCIIZ module name
Word1	NULL

Returns:	0x0000	SUCCESS
	0x0008	INVALID_FUNCTION
	0x002C	ALREADY_REGISTERED

Description:

This command can be called in either the static or dynamic mode to determine whether a specific logical module is currently registered with the Protocol Manager. This can be used by the caller to determine whether a specified module has already registered with the Protocol Manager to prevent duplicate registration. A SUCCESS status resumed means that the specified module is not currently registered with the Protocol Manager. An ALREADY_REGISTERED status means that the module is currently registered.

In the static mode, this request is only valid prior to binding and starting. Invoking this primitive in static mode after all modules are bound and started will cause INVALID_FUNCTION to be resumed by the Protocol Manager.

Chapter 6 - Protocol Manager

Protocol Manager Initialization

The Protocol Manager is loaded and initialized in both the OS/2 and DOS environments via the operating system CONFIG.SYS INIT sequence. It must be loaded before any protocol or MAC driver is loaded. In DOS, the Protocol Manager is provided in a file called PROTMAN.DOS. For OS/2, the file is PROTMAN.OS2. The device name for the Protocol Manager is PROTMAN$ under DOS and \DEV\PROTMAN$ under OS/2 (the \DEV format is required by versions 1.2 or later of OS/2).

In DOS, to save memory an additional dynamically readable component of the Protocol Manager called PROTMAN.EXE is provided. This file must reside in the same directory as the static device driver component, PROTMAN.DOS, itself. This file is called for execution by the Protocol Manager device driver component whenever the Protocol Manager primitives BindAndStart and UnbindAndStop are to be executed. In the static VECTOR mode (Chapter 7), PROTMAN.EXE will remain resident after BindAndStart executes.

The Protocol Manager reads the PROTOCOL.INI file at INIT time and parses it to create the configuration memory image passed to the protocol modules. The file is located in the \LANMAN directory of the boot drive or the directory given by the /I: parameter on the DEVICE=PROTMAN.xxx line in CONFIG.SYS. Under DOS, this image is relocated to just below the memory ceiling, where it must remain untouched until all binding has completed. The Protocol Manager computes a checksum of this image and checks it at bind time to guarantee that the image has not been modified in the interim. Note that this memory is not reserved by the Protocol Manager.

If the Protocol Manager CONFIG.SYS initialization is successful, it is ready to support the initialization of the other drivers. However, the initialization can be aborted for either of the following reasons:

The Protocol Manager did not have enough memory to hold the PROTOCOL.INI configuration memory image.
The Protocol Manager encountered a syntax error while parsing the PROTOCOL.INI file. This could have been an illegal hexadecimal or decimal parameter value, an overflow condition (numeric value could not fit into 32 bits) was encountered, or a string was encountered with missing end quotes.

These conditions are flagged as fatal errors to prevent erroneous configuration parameters from propagating to the drivers for their operation.

Static Binding Sequence

The Protocol Manager can be configured to operate either in the static binding mode or in the dynamic binding mode. In the static binding mode, only statically loadable device drivers can be loaded and bound once at system initialization time. In the dynamic binding mode, dynamically loadable protocol drivers can be loaded and dynamically bound and unbound during system operation on a demand basis. Static drivers can also be loaded at INIT time in dynamic mode. The static binding sequence is described in this section. The dynamic binding sequence is described in Chapter 7, "VECTOR and Dynamic Binding."

To determine the binding sequence, the Protocol Manager builds a tree representing the bindings for all the modules in the system. MAC drivers are at the bottom, and the highest level (for example, NetBIOS) protocol layers are at the top. It then binds pairs together from the bottom up. To do this, it issues an InitiateBind to the upper module in the pair, passing it the characteristics table of the lower module. The upper module is expected to issue a bind to the lower module (if it is acceptable) and return. This continues with the next higher-up module. If there is a module that is not bound to anything else, it receives an InitiateBind with a NULL characteristics table pointer.

To be more formal, the following definitions are required:

A MAC driver is a protocol module with an upper-layer interface level of one (MAC layer) and a lower-layer interface level of zero (physical). It must support binding at its upper boundary.
A MAC-layer entity is a protocol module with both upper- and lower-layer interface levels of one. It must support binding at its lower boundary.
A standalone protocol module is one that has a lower-layer interface levy of zero and that does not support binding at its upper boundary.

The Protocol Manager builds a tree with multiple branches. Each MAC driver is at the base of a branch, with the protocol layers bound to it above it. Standalone modules are also considered branches by themselves. The left-to- right order is defined by the order in which the modules register with the Protocol Manager. The Protocol Manager does a preorder transversal of the tree, issuing InitiateBinds to all of the nodes except the MAC drivers.

An important aspect of the binding scheme is that it allows for modules to specify that they only do binding from above or below. This is a requirement in cases where a monolithic module exposes several interfaces, such as a NetBIOS, TLI, and DLC. The TLI could be presented as a logical module that had an upper interface (the TLI) but no lower interface (since it uses a private internal interface to its DLC). Such a module would have a characteristics table with the following settings:

DWORD	Module function flags, a bitmask (hints only): Bit 0 - set (binds at upper boundary) Bit 1 - clear (doesn't bind at lower boundary)
BYTE	Protocol level at upper boundary of module: 4 - Transport
BYTE	Type of interface at upper boundary of module: 1 => TLI
BYTE	Protocol level at lower boundary of module: -1 - Not specified
BYTE	Type of interface at lower boundary of module, for any level: 0 => private (ISV defined)
LPBUF	Pointer to upper dispatch table
LPBUF	Pointer to lower dispatch table (NULL)

Sequence for non-VECTOR configurations:

Protocol Manager driver (PROTMAN.OS2 for OS/2 or PROTMAN.DOS for DOS) is loaded during CONFIG.SYS initialization. The Protocol Manager must be configured ahead of any MAC or protocol drivers in CONFIG.SYS.
Protocol Manager initializes and reads PROTOCOL.INI to build the configuration memory image.
MAC and protocol drivers are loaded by the operating system. During its initialization processing, each driver optionally does the following:
- Open the PROTMAN$ device.
- Invoke the GetProtocolManagerInfo primitive to PROTMAN$ to get a pointer to the configuration memory image.
- Read configuration parameters from the image and use these to finish initialization and build characteristics tables.
- Use the RegisterModule function once for each module to be defined to the Protocol Manager.
CONFIG.SYS processing ends and applications are started.
An application opens the PROTMAN$ device and issues the BindAndStart IOCTL. Such an application utility, called NETBIND.EXE, is provided with the Protocol Manager driver and is defined in Appendix E.
The Protocol Manager uses information passed on previous RegisterModule calls to determine the module binding hierarchy.
Proceeding from bottom to top of the binding hierarchy, the Protocol Manager uses InitiateBind to cause each module to bind to the module below it in the hierarchy. Each module getting this call responds by issuing a bind call to the module specified by the Protocol Manager on InitiateBind.
When all modules have been bound, the Protocol Manager returns from BindAndStart.

The system is now fully operational. VECTOR configurations are similar, with the VECTOR being automatically inserted between layers one and two, if necessary (on top of the MAC driver as well as any MAC-layer entities that are present).

OS/2 Calling Convention

All of the Protocol Manager requests are supported by a single OS/2 IOCTL function. The services are demultiplexed via a function code specified in the ReqBlock structure.

This IOCTL has the following IOCTL request packet parameters:

Block device unit code: Undefined since the Protocol Manager is a character device.
Command code: 16 for generic IOCTL.
Status: If the IOCTL corresponds to one of the Protocol Manager commands, then the status field is returned with the ERR bit cleared, signifying IOCTL successful completion. However, the final status of the command is returned in the status field of the ReqBlock buffer as defined below. Note that if the command is recognized the ERR bit is always cleared regardless of the status returned in the status field. However, if the command is not recognized, an IOCTL status UNKNOWN_COMMAND (3) is returned with the ERR bit set. Finally, all of the commands return with the status DON bit set.
Category code: 0x81, which is the LAN Manager category code.
Function code: 0x58 for Protocol Manager command type.
Parameter buffer: Pointer to ReqBlock structure.
Data buffer: Unused, therefore the pointer is NULL.

By using the GetProtocolManagerLinkage request, a module can obtain the Protocol Manager dispatch point and DS. Once a module obtains the Protocol Manager's entry point and data segment, it passes a request to the Protocol Manager via the following function call:

int (far Pascal *ProtManEntry)(ReqBlockPtr, DataSeg); 
struct ReqBlock far *ReqBlockPtr; 
unsigned DataSeg;

where
ReqBlockPtr = a FAR pointer to the request block.
DataSeg = the Protocol Manager's data segment base.

The Protocol Manager returns in AX the same return code that is returned in the ReqBlock status.

DOS Calling Convention

All of the Protocol Manager requests are supported by a single DOS IOCTL function. The services are demultiplexed via a function code specified in the ReqBlock. This IOCTL should be requested via interrupt 21 with general registers loaded with the following contents:

AH = 44H for IOCTL request
AL = 02H for device input
DS:DX = Pointer to ReqBlock structure
CX = 14 for the size of the ReqBlock structure
BX = Handle from DOS open of PROTMAN$

This IOCTL generates the following IOCTL request packet parameters:

Block device unit code: Undefined since the Protocol Manager is a character device.
Command code: 3 for IOCTL input.
Status: If the IOCTL corresponds to one of the Protocol Manager commands, then the status field is returned with the ERR bit cleared, signifying IOCTL successful completion. However, the final status of the command is resumed in the status field of the ReqBlock buffer as defined below. Note that if the command is recognized the ERR bit is always cleared regardless of the status resumed in the status field. However, if the command is not recognized an IOCTL status UNKNOWN COMMAND (3) is returned with the ERR bit set. Finally, all of the commands return with the status DON bit set.
Media descriptor byte: Unused.
Transfer address: Pointer to ReqBlock structure.
Byte/sector count: 14.
Starting sector number: unused.

By using the GetProtocolManagerLinkage request, a module or application can obtain the Protocol Manager dispatch point and DS. It then makes a request to the Protocol Manager via the same direct calling mechanism as OS/2.

Chapter 7 - VECTOR and Dynamic Binding

In static mode, the VECTOR is a function that is implemented within the Protocol Manager that allows more than one protocol stack to drive a single MAC. In this mode, the Protocol Manager uses the VECTOR function only if it detects that more than one protocol is using the same MAC. If more than one MAC is attached to multiple protocol stacks, then an instantiation of the VECTOR is created for each MAC so attached.

In dynamic mode, the VECTOR function is always present unconditionally for protocol/MAC intermodule communications. There can be zero, one, or more protocol stacks that bind to a MAC, but the VECTOR function is still present. There can be zero protocols if there is only one dynamic protocol stack being used in the system and that stack is not currently loaded. In the dynamic mode, the VECTOR shields all static binding MACs from the interactions of dynamic binding and unbinding protocol modules.

Static VECTOR Binding

The Protocol Manager will modify the normal binding process if it detects that multiple protocols have requested the use of the same MAC in the PROTOCOL.INI file.

At INIT time from RegisterModule the Protocol Manager has determined the bind hierarchy and has found some MACs that bind to two or more protocols, signaling the insertion of VECTOR
To a MAC that will support multiple protocol stacks, the Protocol Manager issues a bind, passing the Protocol Manager characteristics table with entry points into the VECTOR module. The MAC starts itself and returns, passing back to the Protocol Manager a pointer to the MAC's characteristics table.
For a protocol that is part of a multiple protocol stack binding to the single MAC that was issued the previous bind command, the Protocol Manager issues InitiateBind, passing as the bind intermodule entry point, an entry point within the VECTOR module inside of the Protocol Manager.
The protocol module responds by issuing a bind request back to the Protocol Manager through its VECTOR entry point. The protocol module passes its characteristics table to the Protocol Manager VECTOR. The Protocol Manager returns a characteristics table within the VECTOR that is copied from the associated MACs characteristics tables, substituting the VECTOR entry points for the real MACs entry points.
The protocol starts itself ant returns from InitiateBind.
The Protocol Manager then issues subsequent InitiateBinds to other protocol modules as described above. If these other protocols are bound to a MAC through the VECTOR, the VECTOR procedure is repeated. Otherwise the non- VECTOR procedure is used.

At the conclusion of the binding process the VECTOR is in a position to filter calls as appropriate, going in either direction across the MAC/protocol interface.

Dynamic VECTOR Binding

A dynamic module can be loaded and bound after system initialization time on a demand basis. This dynamic loading and binding takes place in three phases:

The PROTOCOL.INI file is reread.
The dynamic protocol module does some prebind initialization, including getting its PROTOCOL.INI configuration parameters ant registering with the Protocol Manager.
The dynamically loaded protocol module dynamically binds to other modules given in its bind specification. If these other modules are MACs, the bind takes place through the Protocol Manager VECTOR facility.

At some point the dynamic protocol module is no longer required. The protocol module unbinds itself, terminates, ant unloads itself from memory.

The mechanisms for dynamically binding and unbinding are carried out somewhat differently between DOS and OS/2. The procedures are briefly described in the following section.

Dynamic Binding/Unbinding in the DOS Environment

In dynamic mode, both static and dynamic protocol modules can be supported. At startup time, the Protocol Manager performs initialization and binding of static modules as described in the "Static Binding Sequence" section in Chapter 6. However, in the dynamic mode, the VECTOR function is always inserted.
At some point after system startup, a dynamic loadable protocol module (that can be a transient application program or a TSR) is demand loaded. For the dynamic protocol module to have its configuration parameters at initialization, the PROTOCOL.INI file must be reread. Either an application program or the protocol module itself reads ant parses the PROTOCOL.INI file into the configuration memory image. It is suggested that the application or protocol module obtain the location of the PROTOCOL.INI file using the GetProtocolIni primitive. A pointer to this memory image is passed to the Protocol Manager via the RegisterProtocolManagerInfo primitive. This is required since the configuration memory image created by the Protocol Manager at MT time is not valid at post-INIT time. An application utility, READPRO.EXE, that reads and parses PROTOCOL.INI is provided with the Protocol Manager ant is described in Appendix E.
After loading, the protocol module initializes. Minimally, the protocol gets its PROTOCOL.INI configuration information from the Protocol Manager via GetProtocolManager Info, does its prebind initialization, and registers with the Protocol Manager via RegisterModule.
Either an application or the dynamic protocol module itself requests that the Protocol Manager initiate the binding sequence via the BindAndStart primitive. This causes the bind sequence described in steps 3 through 5 of the "Static VECTOR Binding" section, earlier in this chapter, to be executed. After the bind, the dynamic protocol is ready for use. An application utility, NETBIND.EXE, to initiate the binding sequence is provided with the Protocol Manager ant is described in Appendix E.
During operation, all protocol commands to the MAC go through the VECTOR.
When the dynamic protocol module is ready terminate, either it or an application program issues the UnbindAndStop command to the Protocol Manager. This causes the Protocol Manager to call the protocol's InitiateUnbind system entry point. In turn, this allows the protocol to issue Unbinds to other modules it was bound to and to do final cleanup before terminating. On return from the UnbindAndStop command, the protocol can be removed from memory. An application utility, UNBIND.EXE, to initiate the unbinding sequence is provided with the Protocol Manager and is described in Appendix E.

Dynamic Binding/Unbinding in the OS/2 Environment

In OS/2, all dynamic protocol modules are multisegment OS/2 device drivers. A dynamic OS/2 protocol differs from a static one in that the dynamic module has code and/or data segments that can be swapped out of virtual memory when not needed. These extra code and data segments must be specified with IOPL in the module's .DEF file so that they me marked as movable/swappable and not discardable by OS/2. In a static protocol module all segments are permanently locked in memory. A dynamic protocol module uses the OS/2 DevHlp Lock and Unlock calls (using a lock type of 1) to lock and free its code and/or data segments as needed. A dynamic protocol module is able to reregister multiple times with the Protocol Manager ant to dynamically bind with other configured modules. When no longer required, the dynamic module can unbind ant the dynamic memory segments can be unlocked to free up the memory. Static OS/2 protocol modules register and bind only at system initialization time. They do not unbind.
Since all OS/2 dynamic protocol modules are OS/2 device drivers, they may perform some INIT time initialization. The protocol must always register at INIT time with the Protocol Manager via RegisterModule. A protocol that is not required at system startup must still register with the Protocol Manager at INIT time, passing a NULL BindingsList pointer in the RegisterModule primitive. This is called a nonbindable registration. In this case the protocol need not lock down its extra code and data segments. It does, however, need to save the selector values for its dynamic code and data segments. The device drives device header, strategy routine, and the NDIS system entry routine must reside in the driver's main code and data segments (the first ones in the driver), which are permanently locked down. A driver required at system startup must pass a non-NULL BindingsList pointer if it has modules it is required to bind to (a bindable registration). A driver required at system startup must go ahead and DevHlp Lock its other segments at INIT time, making sure to save the lock handle returned by the call. Also at INIT time, the protocol module must invoke the GetProtocolManagerLinkage primitive to get and save the Protocol Managers Ring 0 direct entry point and DS.
Assuming that the protocol was not required at system startup time, at some point in time later it needs to be dynamically bound. At this point the module needs to get its PROTOCOL.INI configuration parameters, lock down its code and data segments, and perform its bindings. lathe configuration parameters are not repined in the base data segment, the protocol must raced the PROTOCOL.INI file. This is tone in a similar fashion to that described for DOS. The InitAndRegister primitive is the standard facility that lets the Protocol Manager request the protocol to reload its dynamic segments and perform its prebind initialization. Upon receiving the InitAndRegister primitive, the Protocol Manager calls the protocol driver's system entry point with InitiatePrebind, allowing the protocol to perform its prebind initialization. The protocol module uses this opportunity to issue DevHlp Lock calls (lock type 1) on its dynamic segments to bring them back into memory. The handle returned from the Lock call must be saved for later unlocking. Also at this juncture, the protocol can get its PROTOCOL.INI memory image from the Protocol Manager via the direct entry point GetProtocolManagerInfo function. It may also do other prebind initialization and finally register with the Protocol Manager via the direct entry point RegisterModule function. If the protocol module had previously made a nonbindable registration at system startup, then the current registration affords it the opportunity to specify its bindings to the Protocol Manager.
The bind and postbind initialization step is similar to that described for DOS. Again, any protocol binds to MACs are performed through the VECTOR.
During protocol operation, any protocol commands to a MAC go through the VECTOR.
When the protocol is no longer required, an application or the protocol itself can issue the UnbindAndStop command to the Protocol Manager. The sequence is similar to that described for DOS. The OS/2 driver, however, issues DevHlp Unlock commands against all of its dynamic segments so that these can be swapped out from memory. The previously saved lock handle is required on this call.

VECTOR Demultiplexing

The VECTOR dispatches incoming frames to protocol stacks using either a preprogrammed default or user statically defined priority polling mechanism. The default mechanism is based on the InterfaceFlags variable in the protocol's lower dispatch table. These flags describe the protocol according to the kinds of frames it handles:

Non-LLC frames
LLC frames with specific LSAPs
LLC frames with nonspecific LSAPs

According to default dispatch priority, VECTOR polls protocols in that order (and within that order, in the order they registered) until it finds one that does not return FRAME_NOT_RECOGNIZED or FORWARD_FRAME in the indication. For specific protocols, this default can be overridden by specifying the bracketed name of the protocol with the Protocol Manager PROTOCOL.INI keyword PRIORITY. Protocols with static priorities specified in this manner are polled by the VECTOR before any protocol not so specified. Protocols with static priorities are themselves polled in the order in which their bracketed names appear in the PRIORITY keyword parameter list. Of course, a protocol appearing in the static list is only polled if it is registered with the Protocol Manager and has bound to the MAC offering up the frame.

Appendix A - System Return Codes

This appendix lists return codes used in this version of the NDIS specification. Note that new error codes may be added in the future. Both protocol and MAC driver developers must design their code to allow for this.

0x0000 SUCCESS: The function completed successfully.

0x0001 WAIT_FOR_RELEASE: The ReceiveChain completed successfully but the protocol has retained control of the data buffer. ReceiveRelease will be called to release the data buffers.

0x0002 REQUEST_QUEUED: The current request has been queued. If the request handle is nonzero, the module will call TransmitConfirm or RequestConfirm when the request completes.

0x0003 FRAME_NOT_RECOGNIZED: This error is returned from the protocol when a MAC does an Indication and the frame does not make sense to the protocol. This will be interpreted by the VECTOR to mean that the next protocol in line ought to be called with the Indication.

0x0004 FRAME_REJECTED: A received frame was recognized but it was discarded. The buffer may be immediately reused.

0x0005 FORWARD_FRAME: A protocol wants the received frame to be offered to other protocols but wants to receive an IndicationComplete. This will be interpreted by the VECTOR to mean that the next protocol in line ought to be called with the Indication.

0x0006 OUT_OF_RESOURCE: The module is in a transient out-of-resource condition. The current request was not completed.

0x0007 INVALID_PARAMETER: One or more parameters were invalid.

0x0008 INVALID FUNCTION: A command function was requested when it was not legal to do so or an invalid request was made.

0x0009 NOT_SUPPORTED: A valid request that is not supported by the module was issued.

0x000A HARDWARE_ERROR: A hardware error occurred during the execution of this request. The request was not completed successfully; this can be considered nonfatal.

0x000B TRANSMIT_ERROR: The packet was not transmitted. This error code may indicate a local resource problem, excessive collisions, or a remote resource problem. On Token-Ring networks, this would be returned if the destination address was recognized but the receiver was out of buffers. This is a nonfatal error and can be taken as a hint that the packet should be retransmitted.

0x000C NO_SUCH_DESTINATION: The destination address was not recognized by any adapter on the local ring. This error is Token-Ring specific and can be interpreted to mean that source routing must be invoked to reach the destination.

0x000D BUFFER_TOO_SMALL: The buffer provided was too small for the information being returned. Some commands may still return partial information.

0x0020 ALREADY_STARTED: The Protocol Manager has already started the network drivers. This error occurs when BindAndStart is called more than once.

0x0021 INCOMPLETE_BINDING: This bind-time error occurs when the Protocol Manager cannot complete all of the bindings described in the bindings list, most probably due to missing modules.

0x0022 DRIVER_NOT_INITIALIZED: This bind-time error occurs when the MAC does not initialize properly during system boot, and a subsequent request is made to the MAC.

0x0023 HARDWARE_NOT_FOUND: This bind-time error occurs when the network adapter is not found by the MAC.

0x0024 HARDWARE_FAILURE: This error occurs in the following cases: network adapter reset failed, network adapter diagnostics failed, network adapter is not responding, network adapter is not found by the MAC. This error can be considered fatal.

0x0025 CONFIGURATION_FAILURE: This bind-time error occurs when the configuration is unacceptable to the network adapter.

0x0026 INTERRUPT_CONFLICT: This bind-time error occurs in OS/2 only, when an interrupt from some other device in the computer conflicts with the network adapter's interrupt.

0x0027 INCOMPATIBLE_MAC: This bind-time error occurs when a protocol determines a MAC is not compatible for the binding operation. Thus, binding cannot proceed.

0x0028 INITIALIZATION_FAILED: This bind-time error occurs when a protocol fails its initialization.

0x0029 NO_BINDING: This bind-time error occurs to indicate that the binding was not performed. This error can occur if a protocol driver took an error exit during its initialization or if a protocol driver has its upper level incorrectly specified as a MAC.

0x002A NETWORK_MAY_NOT_BE_CONNECTED: This bind-time error indicates that the adapter may not be connected to a network. It is intended to be suggestive of corrective action by the user.

0x002B INCOMPATIBLE_OS_VERSION: This bind-time error indicates that a protocol or MAC driver does not support the version of DOS or OS/2 being used.

0x002C ALREADY_REGISTERED: This error is returned by the Protocol Manager if an attempt is made to register a module with a module name already registered with the Protocol Manager. It is also resumed from a RegisterStatus primitive to indicate that the name is already registered.

0x002D PATH_NOT_FOUND: This error is resumed by the DOS Protocol Manager if PROTMAN.EXE could not be found when attempting to execute a BindAndStart or UnbindAndStop command.

0x002E INSUFFICIENT_MEMORY: This error is resumed by the DOS Protocol Manager if PROTMAN.EXE could not be loaded due to insufficient DOS memory when attempting to execute a BindAndStart or UnbindAndStop command.

0x002F INFO_NOT_FOUND: This error is resumed by the DOS Protocol Manager in a GetProtocolManagerInfo command if the PROTOCOL.INI structured configuration memory image is not present or was previously invalidated due to being overwritten or corrupted.

0x00FF GENERAL_FAILURE: Unspecified failure during execution of the function. 0xF000-0xFFFF: Reserved for vendor-defined error returns. These errors are treated as GENERAL_FAILURE.

Appendix B - Reference Material

OS/2 Device Drivers Guide
DOS Technical Reference
ANSI/IEEE standard 802.2 - 1985 (ISO/DIS 8802/2) Logical link control standard.
ANSI/IEEE standard 802.3 - 1985 (ISO/DIS 8802/3) Carrier Sense Multiple Access with Collision Dection local area network standard.
ANSI/IEEE standard 802.5 - 1985 (ISO/DIS 8802/5) Token- Ring local area network standard.
The EtherNet. A Local Area Network. Data Link Layer and Physical Layer Specifications, version 2.0, November 1982. Also known as the "Ethernet Blue Book."
IBM Token-Ring Network PC Adapter Technical Reference (69X7830).
IBM Token-Ring Network Architecture Reference - November 1985 (6165877).
Information processing systems - Open Systems Interconnection - Basic Reference Model, (ISO 7498). The OSI reference model.

Appendix C - NDIS 2.0.1 802.3

The 802.3 media-specific statistics structure is defined as follows:

Statistics in bold are mandatory, all others are strongly recommended. Reserved slots should return as 0xFFFFFFFF (unsupported).

WORD          Length of 802.3 statistics structure, including this field
WORD          802.3 statistics structure version level (1)
DWORD       Total frames with alignment error
DWORD        Reserved (obsolete statistic)
DWORD        Total frames with overrun error
DWORD        Reserved (obsolete statistic)
DWORD        Total frames transmitted after deferring
DWORD        Total frames not transmitted - max (16) collisions
DWORD        Reserved (obsolete statistic)
DWORD        Total late (out of window) collisions
DWORD       Total frames transmitted after exactly one (1) collision
DWORD       Total frames transmitted after multiple collisions
DWORD        Total frames transmitted, CD heartbeat
DWORD        Reserved (obsolete statistic)
DWORD        Total carrier sense lost during transmission
DWORD        Reserved (obsolete statistic)
DWORD        Total number of underruns (version 2.0.1 or later)

When updating the statistics counters, a frame is counted in all the supported counters that apply.

Examples

A "Multicast flame received ok" is counted in the following statistics counters:
- Total multicast frames received ok
- Total frames received ok
A "Transmit broadcast frame with one collision" is counted in all the following statistics counters:
- Frames transmitted with only one collision
- Total broadcast frames transmitted
- Total frames transmitted ok

Definitions

Total frames with alignment error

(NumberOfFramesReceivedWithAlignmentErrors)

This contains a count of frames that are not an integral number of bytes in length and do not pass FCS check. It reports on alignment errors "as the station sees it."

Total frames with overrun error

This contains a count of frames that could not be accepted due to a DMA overrun error.

Total frames transmitted after deferring

(NumberOfFramesWithDeferredTransmission)

This counter does not include frames involved in collisions.

Total frames not transmitted - max (16) collisions

(NumberOfFramesAbortedDueToExcessiveCollision)

This contains a count of the frames that are not transmitted successfully due to excessive collisions.

Total late (out of window) collisions

(NumberOfLateCollisions)

This contains a count of frames that are involved in an out-of-window collision.

Total frames transmitted after exactly one (1) collision

(NumberOfSingleCollisionFrames)

This contains a count of frames that are transmitted after exactly one collision.

Total frames transmitted after multiple collisions

(NumberOfMultipleCollisionFrames)

This contains a count of frames that are transmitted after a multiple number of collisions.

Total frames transmitted, CD heartbeat

(NumberOfSQETestErrors)

This contains a count of frames transmitted with the CD (collision detection) signal missing.

Total carrier sense lost during transmission

(NumberOfCarrierSenseErrors)

This contains a count of frames that experienced carrier sense lost (carrier sense signal not present at the receive pair of the controller) during transmission.

Total number of underruns (version 2.0.1 or later)

This contains a count of frames that could not be transmitted due to a DMA underrun error.

Appendix D - 802.5
Media-Specific Statistics

The 802.5 media-specific statistics structure is defined as follows:

Statistics in bold are mandatory, all others are strongly recommended. Reserved slots should return as 0xFFFFFFFF (unsupported).

WORD          Length of 802.5 statistics structure, including this field
WORD          802.5 statistics structure version level (1)
DWORD        FCS or code violations detected in repeated frame
DWORD        Reserved (obsolete statistic)
DWORD        Number of 5 half-bit time transition absences detected
DWORD        A/C errors
DWORD        Frames transmitted with abort delimiter
DWORD        Frames transmitted that failed to return
DWORD        Frames recognized, no buffer available
DWORD        Frame copied errors
DWORD        Number of frequency errors detected
DWORD        Number of times active monitor regenerated
DWORD        Reserved
DWORD        Reserved
DWORD        Reserved
DWORD        Reserved (obsolete statistic)
DWORD        Number of underruns

When updating the statistics counters, a frame is counted in all the supported counters that apply.

Definitions

FCS or code violations detected in repeated frame

This counter is incremented for every repeated frame that has a code violation or fails the frame check sequence (FCS) cyclic redundancy check.

Number of 5 half-bit time transition absences detected

Also known as burst error, this counter is incremented every time 5 half-bit time transitions are not detected between SDEL and EDEL in a repeated flame.

A/C errors

Also known as ARI/FCI set error, this counter is incremented when a station receives more than one AMP or SMP MAC frame with AC (ARI/FCI) equal to zero without first receiving an intervening AMP MAC frame. This counter indicates that the upstream adapter is unable to set its AC (ARI/FCI) bits in a frame that it has copied.

Frames transmitted with abort delimiter

This counter is incremented each time the adapter transmits an abort delimiter. This indicates that the frame was aborted in mid-transmission.

Frames transmitted that failed to return

This counter is incremented when a transmitted frame fails to return from around the ring due to time-out or the reception of another frame.

Frames recognized, no buffer available

Also known as receiver congestion, this counter is incremented when a ring station is receiving/repeating a frame and recognizes a frame addressed to it, but has no buffer space available for the frame.

Frame copied errors

This counter is incremented when a ring station receives or repeats a frame from the ring with the ring station's individual address, but with A = C = 1, indicating a possible duplicate address.

Number of frequency errors detected

This counter is incremented when a ring station detects a signal frequency problem.

Number of times active monitor regenerated

This counter is incremented each time the active monitor is lost and regenerated.

Number of underruns

This counter is incremented each time a DMA underrun is detected.

Appendix E - Utilities Provided with the Protocol Manager

To save system integrators the effort to read and parse the PROTOCOL.INI file, to register it with the Protocol Manager, to invoke the binding and unbinding of Protocol Manager primitives, and to report various Protocol Manager error conditions, three utilities are provided with the Protocol Manager in both the DOS and OS/2 environments and one utility is provided exclusively for the OS/2 environment:

NETBIND.EXE	Initiates the binding and operational startup of a set of modules previously loaded. It issues to the Protocol Manager the BindAndStart primitive and reports to the console any binding/initialization errors detected by the modules bound. This utility can be used in either the static or dynamic Protocol Manager mode of operation. In the static mode it should be invoked after all device driver modules are loaded (for example, from AUTOEXEC.BAT in DOS or STARTUP.CMD in OS/2). In the dynamic mode it can be invoked either at system startup time as in static mode or after a set of dynamically loadable modules have been loaded and are ready to be run. There are no command line parameters associated with this utility.
UNBIND.EXE	Initiates the unbinding and termination sequence of a set of dynamically loadable modules previously loaded and bound. It issues to the Protocol Manager the UnbindAndStop primitive and reports to the console any unbinding/termination errors detected by the modules being unbound. The utility can be used only in the dynamic Protocol Manager mode of operation. Invocation in the static mode will generate an error. It should be invoked when it is desired to terminate (and release from memory) a set of dynamically loadable modules that have been previously loaded and bound. In DOS each invocation will terminate and unbind the last set of modules previously bound via the NETBIND.EXE utility. Modules can be bound and unbound in groups, if required, by invoking NETBIND.EXE for each group of modules to be bound together and later invoking UNBIND.EXE. UNBIND.EXE will unbind the groups only in the reverse order in which the groups were previously bound. If protocols are implemented so that they free themselves from memory at the end of the unbind sequence, then this utility will free up the memory of all such protocols unbound. This utility has no effect on MAC drivers that are always static device drivers. In OS/2 the utility takes an argument string specifying the name of the module being unbound. In DOS there are no command line parameters associated with this utility.
READPRO.EXE	Reads the PROTOCOL.INI file, parses it into a memory image, and registers this memory image with the Protocol Manager so that the image is available to dynamically loadable protocols when they request their configuration memory image information. By invoking the GetProtocolIniPath primitive, this utility assures that the PROTOCOL.INI file is read from the same subdirectory as that used by the Protocol Manager when it initialized. The memory Image is registered with the Protocol Manager via the RegisterProtocolManagerInfo primitive. This utility can be used only in the Protocol Manager dynamic mode of operation. The utility reports any detected error conditions on the console. It should be invoked prior to the loading of any dynamic modules. There are no command line parameters associated with this utility.
RELOAD.EXE	This utility applies only to OS/2. It initiates the prebind initialization of an OS/2 dynamically loadable module. It issues to the Protocol Manager the InitAndRegister primitive containing the module name that was given as a command line parameter. The Protocol Manager calls the system entry point of the named module with the InitiatePrebind system function. The module is required to reinitialize, which may include locking down swappable segments, requesting and parsing the PROTOCOL.INI image, and reregistering with the Protocol Manager in preparation for a subsequent NETBIND.EXE invocation. This utility reports any detected error to the console.

If the system integrator requires more functionality than that provided by these utilities, the integrator can write an application utility that performs the desired functionality and invokes the required Protocol Manager primitives described in Chapter 5. For example, if in DOS a more flexible unbind facility to unbind in a user-specified order is required, UNBIND.EXE can be replaced by a user- written utility that invokes the UnbindAndStop primitive, in which Pointer2 points to the name of the module to be unbound.

Notices

October 8, 1990

This specification is intended for use by those developing or using networking products. This specification may be copied freely for that purpose as long as copyright notice is preserved on all copies of the specification. No fee or royalty is required by either 3Com Corporation or Microsoft Corporation to develop products that use the information contained within this specification. Information contained in this specification can be included in documents, presentations, or products of third parties; however, authorship must be attributed jointly to 3Com Corporation and Microsoft Corporation, and appropriate copyright notices must be placed in any such documents or presentations. Additional copies of this specification can be obtained from 3Com Corporation or Microsoft Corporation.

Copyright Notices

Microsoft, the Microsoft logo, and MS are registered trademarks of Microsoft Corporation.

3Com is a registered trademark and EtherLink II is a trademark of 3Com Corporation.
AppleTalk is a registered trademark of Apple Computer, Inc.
ArcNet is a registered trademark of Datapoint Corporation.
IBM is a registered trademark of International Business Machines Corporation.
EtherNet is a registered trademark of Xerox Corporation.

NDIS Implementation Information
for IBM LAN Systems
OS/2 Messaging and National Language Support

About This Document
1.0 General Strategy
2.0 Standardized Services for Device Driver Message Display and Logging
2.1 Device Driver Initialization
2.2 Device Driver Strategy Time
3.0 Non-Device Interface to the LAN Transport Message Functions
3.1 Functional Description
3.2 Implementation
- 3.2.1 Input Parameters
- 3.2.2 Calling Conventions
  - 3.2.2.1 Linking Method:
  - 3.2.2.2 Parameter Passing on Calling Sequence
4.0 Data Structure Definitions and Return Codes
4.1 Message Parameter Block
4.2 DevIOCtl Returned Status Field: (DevIOClt Function 1)
4.3 IDCInformation Request Packet: (DevlOCtl Function's 2 & 3)
4.4 Default Path Information Request Packet: (DevlOCtl Function 7)
4.5 Possible Return Codes
5.0 Installation/Configuration
5.1 CONFIG.SYS Entries
5.2 Configuring the Override for the Default Path Name
- 5.2.1 Search Path Rules
5.3 Other Configuration Parameters to the Messaging Support Driver
Notices

[[[#Sec10|next]]][[[#toc|parent]]][[[#toc|TOC]]]

About This Document

This document describes the interface for device drivers ring-3 application, and information about the specific implementation as it pertains to the message strategy of and National Language Support (NLS) for an IBM* Network Driver Interface Specification (NDIS) 2.01 device driver, as implemented in IBM* LAN Adapter and Protocol Support*. This document is not meant to be a tutorial; it is assumed that the user has knowledge of the rules and procedures on calls made to device drivers using both the DosDevlOCtl interface and the InterDevice Driver Communications (IDC) entry point. The information on these topics is presented here in a reference or summary manner.

Note: NDIS 2.0.1 is jointly authored by the 3Com*** Corporation and the Microsoft** Corporation.

The following publications provide additional information:

3Com/Microsoft LAN Manager** Network Driver Interface Specification (NDlS), Version 2.0.1, October 8, 1990
Microsoft LAN Manager, Programmer's Guide for NDIS, Version 2.0. 1, June, 1990
NDIS Implementation Information for IBM LAN Systems, Extended NIF Format, May, 1993
NDIS implementation Information for IBM LAN Systems, NDIS Extensions, May, 1993

1.0 General Strategy

All messages will be kept in a file separate from the application. They are separated from the executable code to enable NLS translation of messages into different languages without altering the calling program. It is strongly recommended that a help message file be included as a companion for the message file.
Refer to the OS/2 Technical Reference for the format of message text and the output file of MKMSGF utility.
When errors are encountered by an NDIS driver during the IPLing of the machine, a message describing the error should be logged into a message log file and displayed to the console.
If the LAN message device driver (LANMSGDD.OS2) is installed, and its companion DLL file (LANMSGDL.DLL) is available, then messages describing any errors can be logged in the message log file (LANMSGDD.LOG) and displayed to the console. This message log display interface is compatible with First Failure Support Technology/2 (FFST/2) and can be used at both IPL and run time.
The detailed LAN message device driver interface is described in Chapter 2, and the interface for ring-3 applications is described in Chapter 3.
The message and log files are assumed to be in the \IBMCOM subdirectory, unless changed by the user.

2.0 Standardized Services for Device Driver Message Display and Logging

This section describes the input parameters and calling conventions for the LAN message device driver (LANMSGDD.OS2). This piece of the system runs at privilege level zero and can be accessed by other device drivers both during their initialization and strategy lifetime. The interface basically enables a message to be retrieved from an NLS translatable message file and written to a message log file, and optionally displayed to the console. This means ring-0 message logging is now possible. The intent of this ring-0 service is not to enforce a standardization upon device drivers needing messaging service but rather to offer an interface that facilitates problem solving at the device driver or system level.

The interface is written to be compatible with the First Failure Support Technology/2 (FFST/2) interface but will still provide messaging services if FFST/2 is not available on the system. Thus, some parameters that may seem redundant for an application running with ring-3 privilege level are nevertheless required input to FFST/2.

2.1 Device Driver Initialization

During a device driver initialization period, it runs as a pseudo ring-3 application. During this time, it has access to a subset of DOS calls, including DosOpen, DosWrite, DosGetMessage and DosPutMessage. Using these APIs at initialization time, a device driver can display and write its messages to a log without assistance. This is the method most device drivers are currently using. However, this ability is lost after the device completes initialization.

A ring-3 entry point to the messaging support driver is provided solely for the sake of standardization and convenience to the device drivers it services. It exists so that all messages in a system can be logged to the same file without requiring knowledge about the log file name or location. It also alleviates the need for a device driver to open, go to the end of the file, write the record, and close the file for every message logged. Thus, this ring-3 interface can eliminate redundant code that would otherwise be needed in each device driver.

In order for messaging services to be available to other device drivers at IPL time, it is required that the LANMSGDD.OS2 module load prior to the calling device. This is easily accomplished by placing the DEVICE= statement for LANMSGDD.OS2 before the calling device in CONFIG.SYS. This ensures that when a device driver enters it initialization period, the messaging support driver is already loaded. As such, the messaging support driver has already made its transition from ring-3 to ring-0. The DOS services to which the initializing device driver has access are now unavailable to the messaging support driver. Its only access to these functions is through its ring-3 thread started by LANMSGEX.EXE. This thread, however, is not available until all device drivers specified in CONFIG.SYS have completed loading. To handle this, LANMSGDD.OS2 uses a queue for incoming message requests until the ring-3 thread is ready.

When the messaging support driver is called, it queues the request until the ring-3 services provided by LANMSGDL.DLL are available. For message logging, this is not a problem since the user cannot view the log until after IPL. However, messages that are to be displayed to the console during device driver initialization will experience a delay until the queue is processed. Therefore, if a device driver has a banner or logo it wants displayed during its initialization period, it may be preferable to use an API such as DosWrite to generate standard output.

2.1.1 Implementation

The messaging support driver ring-3 entry point is implemented using a general DosDevIOCtl call. Before DosDevIOCtl call can be made, the calling device driver will need a file handle by issuing a DosOpen to the messaging device driver. The name to use on the DosOpen call is \LANMSG$$. Even though it is not currently required, it is suggested that the full path and file name, \DEV\LANMSG$$, be used on the DosOpen. There was once an OS/2 1.2 requirement that the \DEV path be used to open a device driver. This requirement was dropped, but use of the path does work and it may prevent a code modification in some future release.

2.1.2 Functions Provided

Several messaging functions are provided to device driver applications when they run at privilege-level 3. To invoke these functions, the DosDevIOCtl function category 90h (the message device category code) must be used. This category will generate a general DevIOCtl to the messaging support driver. Four message service requests are provided through this category depending upon the DosDevIOCtl function code passed. The functions provided are:

        Function 01 = Request messaging services.
        Function 02 = Request LANMSGDD IDC entry point.
        Function 03 = Combine requests 01 and 02 in one DevIOCtl call.
        Function 07 = Request Default Message Path.

2.1.2.1 Function 01: Message Service Request

Function 01 will generate a general request for messaging services. The specifics of the request are contained in the input parameters passed in the DosDevIOCtl parameter buffer. This field is a far pointer (DWORD) to the message parameter block. This parameter block contains the component name of the device driver requesting services, the message number to access, the type of message, a display option, the full path and file name of the message input file, the output log file, and any insertion strings required for the message. A detailed description of the message parameter block is contained in 4.0, "Data Structure Definitions and Return Codes". The only required input parameter in the message parameter block is the message number identifier. All others are optional.

Output parameters are passed back to the calling routine in the DosDevIOCtl data buffer field. This field is a far pointer (DWORD) to a status variable. This variable is a WORD and will contain the return code on the success of the request. This field is needed since AX will contain the return code of the DosDevIOCtl call itself and is required on all message DosDevIOCtl calls. Device driver return codes are detailed in 4.0, "Data Structure Definitions and Retum Codes".

2.1.2.2 Function 02: Message IDC Information Request

This function allows a device driver to gain access to the message device driver ring-0 protect mode code segment entry point and data segment. This function alleviates the need for a device driver to issue an AttachDD during its ring-0 strategy time. It is important to remember that although one has the ring-0 entry point at its initialization time, a device driver may not use it until it has made its ring-0 transition.

There are no input parameters other than the function code passed on the DosDevIOCtl. Thus, the DosDevIOCtl parameter buffer field is null. Output is passed back in the data buffer area of the DosDevIOCtl. The data buffer must point the IDC information request packet. The first WORD of the packet contains the required status of the request. This is followed by a DOUBLE WORD, which contains the code segment and offset of the message device driver ring-0 entry point. The last field is a WORD, which contains the data segment of the Messaging Support Driver. A description of the IDC information request packet is contained in 4.0, "Data Structure Definitions and Return Codes" .

2.1.2.3 Function 03: Combine Functions 01 and 02

This function is provide solely for the convenience of the calling device driver. It keeps the caller from having to make two separate IOCtl's. Required input and output parameters for this function are a combination of functions

2.1.2.4 Function 07: Request Default Path

There is a hard-coded path where the messaging support driver (LANMSGDD.OS2) expects to find the default input message file, LT0.MSG, and will create the default output file, LANTRAN.LOG. This default path is \IBMCOM. Although the names of the default message file and log files usually do not need to be changed, they can be overridden using the input parameters passed in the message parameter block. The default path can be overridden using an input parameter on the DEVICE = statement for LANMSGDD.OS2 in CONFIG.SYS. This function is provided to enable device drivers to access the current default path. Refer to 5.0, "Installation/Configuration" for details.

Like Function 02, this function has no input parameter except the DosDevIOCtl function number itself. The DosDevIOCtl parameter buffer field is, therefore, null. The output of the request, like the other functions, is resumed through the DosDevIOCtl data field which points to the default path information request packet. The first WORD of the packet contains the status of this request. The next field in the packet contains a 32-bit pointer to a buffer where it will copy the full path and filename. Even though the default file name, LT0.MSG, can not be changed, the message device driver returns the full path and file name of the default message file. The next WORD in the packet holds the length of the path portion of the name only. Currently the maximum path length that the messaging support driver uses is 250 bytes.

The usefulness of this function lies in its ability to allow applications that do not use the default message file to query the messaging support device driver to obtain the current default path. This path is where the device driver can expect to find its message file. The application can then replace the default message file name with its own message file name. Accordingly, applications can keep their own message and log files in a common directory other than \IBMCOM. It may also prevent a device driver from having to define its own input parameter for the same purpose.

2.1.3 Calling Conventions and Input Parameters for the DosDevIOCtl Entry Point

                          (OS/2 creates a general DevIOCtl)

Function category:  90h = Message device category code.

Function code:      01  = Request messaging services.
                          02 = Request LANMSGDD IDC entry point.
                          03 = Combine r;       Pass address if data packet,
push    OFFSET Msg_Status       ;         offset to status field
push    ds                      ;       PASS PARMLIST , offset to
push    OFFSET Msg_Params       ;         message parameter block.
push    1                       ;       Function code (message request)
push    90h                     ;       Messaging category
push    Msg_DDHand              ;       Handle to LANMSG$$ from DosOpen.
call    DOSDEVIOCTL
cmp     Ax,0                    ;       DevIOCTL SUCCESS?
jne     Out_Err                 ;       No.
cmp     Msg_Status,0            ;       Message request successful?
jne     Out_Err                 ;       No.

2.2 Device Driver Strategy Time

The ring-0 interface (IDC or device driver strategy entry point) can be obtained using an AttachDD call or through a DevIOCtl, function 2 or 3, call during a device driver initialization.

2.2.1 Implementation

Calls to this entry point give a device driver access to the general messaging services provided by the messaging support driver. This entry point provides the equivalent functionality as that obtained the DosDevIOCtl function 02 call. Once the IDC entry point is obtained, only two parameters are required. The first parameter is a WORD value of 1. This value signifies that a device driver is requesting messaging services. The second parameter is a far (32-bit) pointer to the message parameter block. This is the same input block passed in the parameter buffer on the DosDevIOCtl call for function 02. Finally, AX will contain the same returned status code as that recorded in the data buffer Area of the function 02 DosDevIOCtl call.

2.2.2 Calling Conventions and Input Parameters for the IDC Entry Point

A list of the IDC, (inter-device communication or ring-0) input parameters and return code follow:

IDC invocation code:        0x0001 = Messaging function code.

Message parameter block:        A far pointer to the message parameter 
                                  block
Return code:                On return, AX  contains the same code 
                                  as that logged in the IOCTL status 
                                  field located in the DevIOCTL's data 
                                  buffer Area.

2.2.3 IDC Entry Example

Note: If a DosDevIOCTl requesting the message device driver IDC entry point was not issued, an ATTACHDD is first required to get it. The calling application is also required to establish LANMSGDD DS before the call.

push    es                      ;       PASS PARMLIST, offset to
push    OFFSET Msg_Params       ;          message parameter block.
push    1                       ;       Pass message IDC invocation.
call    DWORD ptr es:"Msg_CS"   ;       Call the MessageDD
cmp     AX,0                    ;       Success?
jne     OutMsg_Err              ;       No.

Note: When calling to the IDC entry point, the calling routine is assumed to have set up LANMSGDD data selector into DS prior to the call.

3.0 Non-Device Interface to the LAN Transport Message Functions

Following are a functional description and an implementation of the non-device interface to the message functions.

3.1 Functional Description

An additional entry point into the LAN transport message services has been defined using a dynamic link library (DLL). This entry point is available only after device driver initialization at IPL time. A ring-3 thread holds the DLL in memory for quick access to the entry point. The file itself is LANMSGDL.DLL, and its thread is LANMSGEX.EXE. Functionally, this entry point (MRMSG) provides access to the same general messaging services as those provided by both the DevIOCtl Function 01 entry and the IDC entry. In fact, a ring-3 application could call the messaging support device driver DevIOCtl entry and thereby gain access to all of its defined IOCtl functions. This interface provides a more direct access to the messaging function and is implemented solely for the convenience of an application.

3.2 Implementation

The non-device driver entry point is provided for ring-3 applications as a direct interface into the message dynamic link routine, LANMSGDL.DLL. It is not dependent upon the messaging support driver or its ring-3 EXE file, LANMSGEX.EXE, for existence. It operates like any DLL, from the thread of the calling routine. Actually, it is the same interface the LANMSGEX.EXE routine uses to output its own messages. It has been externalized for the convenience of any ring-3 application wanting to use it.

The message DLL routine contains all the logic for outputting a message to the console/log file or to FFST/2. This routine also determines if FFST/2 is present and available. It reformats the input parameters according to the interface being accessed. If FFST/2 is installed but not initialized, a warning message is displayed and logged, but no further attempt is made to access FFST/2 until the next IPL.

3.2.1 Input Parameters

Input to the routine is very similar to the IDC entry point parameters. Its first input parameter is a FAR pointer to the same message parameter block defined for the other two interfaces. See the description of the message parameter block in 4.0, "Data Structure Definitions and Return Codes". The second parameter is a WORD value that acts as an FFST/2 option flag. It allows an application to specify whether output to FFST/2 is desired. If the value passed is zero, the DLL precludes the use of the FFST/2 interface. If the value is set to 1, the routine uses FFST/2 services if they are available. The final parameter is a DWORD and is reserved. As such it must be 0. A list of the input parameters follows:

Message parameter block:        A far pointer to the message parameter block.
FFST/2 Options Flag:        0x0000 = Do not use FFST/2      
                                0x0001 = Use FFST/2 interface if available.
Reserved:                       DWORD value of all 0's.

3.2.2 Calling Conventions

The entry point label name to the Non-DD ring-3 interface is MRMSG. Either of the following OS/2 DLL linking methods can be used to gain access to this entry point. Each method for linking to MRMSG is demonstrated.

3.2.2.1 Linking Method:

This first example has only a requirement to include an IMPORT statement for LANMSGDL.MRMSG in the link deflation file.

Example - Method 1:

MASM external reference in source program:
  EXTRN MRMSG : FAR ; DLL message output routine.
Linking example:
  LINK Appl.OBJ,Appl.exe,,Appl.MAP,doscalls,Appl.DEF /NOD/NOT/MAP;

Example OS/2 definition file:
 NAME APPL WINDOWCOMPAT
 PROTMODE
 DESCRIPTION 'APPL ANY RING-3 APPLICATION'
 STACKSIZE 4096
 IMPORTS
  LANMSGDL.MRMSG

The second method does not require any external reference definitions or DEPORT definition. It makes use of OS/2 DosLoadModule and DosGetProcAddr. For a discussion of this method see the 0S/2 Programmer's Reference. A sample of this method follows.

Example Method 2:

;;;     Now load DLL module     
push    SEG  ObjBuf     ;Addr to buffer for the failing module
push    OFFSET ObjBuf   
push    ObjLen          ;Above's buffer length
push    SEG LanMSgMod   ;Pointer to module name 'LAMSGDL'
push    OFFSET LanMsgMod        
push    Seg LanMsgHand  ;Pointer to word value for Handle
push    OFFSET LanMsgHand       
call    DosLOADMODULE
or      ax,ax
jnz     Error_End       ;Bad return; cannot call module

;;;     Now get module entry point
        
push    LanMsgHand      ;Handle to DLL module
push    SEG LanMsgProc  ;Pointer to procedure name 'MRMSG'
push    OFFSET LanMSGProc       
push    SEG MRMSG       ;Ptr to DWORD to contain entry point
push    OFFSET MRMSG    
call    DOSGETPROCADDR
or      ax,ax
jnz     Error_End       ;Bad RC; do not call module

3.2.2.2 Parameter Passing on Calling Sequence

An example of the calling sequence to the MRMSG interface follows:

;;;;    Call message DLL here   
push    SEG MsgData     ; Pass msg control block
push    OFFSET MsgData  
push    1               ; Use FFST/2 if available
push    0               ; First WORD of 0'st
push    0               ; Second WORD of 0's
call    MRMSG           ; Far call to output msg
or      ax,ax           ; Error?
jne     Error_End       ; Yes.

4.0 Data Structure Definitions and Return Codes

Data structure definitions are provided for the message parameter block, the DevIOCtl resumed status field, the IDC information request packet, and the default path information packet. Return codes are also listed.

4.1 Message Parameter Block

The message parameter block is the basic input parameter structure used to request messaging services using both the DevIOCtl and the IDC entry points for device drivers and the non-device driver entry point for ring-3 applications. It is composed of the following fields (in order).

COMPONENT_ID - Far pointer (double word) to an 8-byte string that identifies the calling component, for example, the name of the device driver requesting messaging services. If null, the message contains information about who originated the message. If FFST/2 is installed, this field is used as the subcomponent name. (OPTIONAL)
IV_ ARRAY - Far pointer to an array of far pointers, from 0-9, that point to a 0-terminated string text used as message text insertion data. (If null, no insertion data exists.) (OPTIONAL)
IV_Number - Word value indicating the number of text insertion pointers found in the IV_Array field. Values 0 - 9 (0 means no insertion data exists). (OPTIONAL)
MESSAGE_Num - Word value used to hold the message number ID of the desired message. (REQUIRED)
Message_File - Far pointer to a null-terminated string identifying the path and message file name that contains the message text. If null, the default is used. (OPTIONAL)

Message_Type - Afford value used for the following types. (OPTIONAL)

                   4500h - ('E'00) denotes an error message.
                   5700h - ('W'00) denotes a warning message.
                   4900h - ('I'00) denotes an informational message.
                   0000h - (''00) denotes an unclassified message.

Display_Flag - Word value indicating the console display option. (OPTIONAL)

                Possible values include:
                    False (0) - do not display, even if error type.
                    True (1) - display to console.

Log_File - Far pointer to an alternate message log path and file name where the messages will be written. If null, the default is used. (OPTIONAL)

4.2 DevIOCtl Returned Status Field: (DevIOClt Function 1)

When requesting message services of DosDevIOCtl function 1 to the message device driver, the data buffer field on the IOCTL call must point to a WORD value. This value contains the status of the request on IOCTL completion. This status field is required on all DevIOCtl calls to the messaging device driver.

Returned status of request - Word (REQUIRED for all DevIOCtl's)

4.3 IDC Information Request Packet: (DevIOCtl Function's 2 & 3)

The ring-0 Information Request Packet is used for DevIOCtl output, i.e., passed in the Data Buffer area on the DosDevIOCtl call. The packet's structure is defined below:

Returned status of request - Word (REQUIRED for all DevIOCtl's) 
IDC/ring-0 entry point     - Double word (REQUIRED for IOCTL functions 2 and 3)
Ring-0 data segment        - Word (REQUIRED for IOCTL functions 2 and 3)

4.4 Default Path Information Request Packet: (DevIOCtl Function 7)

The ring-0 path information request packet can be used to determine what the current default message path is. The packet is used as output, that is, output passed in the data buffer area on the DosDevIOCtl call. The request packet is defined as follows:

Returned status of request  - Word (REQUIRED) 
Default path buffer address - Double word pointer (REQUIRED) 
Length of path name         - Word (REQUIRED)

4.5 Possible Return Codes

Possible return codes for all message entry points follow.

Note: This list is not intended to be exhaustive. Other unexpected DevHelp or OS/2 system calls may also be received.

0x0000 - Request has been accepted.
0x0001 - ERROR INVALID FUNCTION (Bad IDC invocation)
0x0002 - ERROR FILE NOT FOUND
0x0008 - ERROR NOT ENOUGH_MEMORY (Not enough internal resources 
         to satisfy request)
0x013C - ERROR MR_MSG_TOO_LONG (Message too long for message buffer)
0x013D - ERROR MR_MID_NOT_FOUND (Message number not found)
0x013E - ERROR MR_UN_ ACC_MSGT (Unable to access message file)
0x013F - ERROR MR_INV_MSGT_FORMAT (Invalid message file format)
0x0140 - ERROR_MR_INV_IVCOUNT (Invalid insertion variable count)
0x0141 - ERROR_MR_UN_PERFORM (Unable to perform function)

5.0 Installation/Configuration

There are three separate modules required for messaging services. The ring-0 executable filename of the device driver is LANMSGDD.OS2. The device driver maintains a detached ring-3 thread, which it uses to gain access to DOS kernel services. The ring-3 executable file name is LANMSGEX.EXE. This ring-3 thread also requires the ring-3 message DLL file LANMSGDL.DLL.

5.1 CONFIG.SYS Entries

The messaging device driver is loaded by a DEVICE = statement in the CONFIG.SYS file. This statement should be inserted into the CONFIG.SYS before any other LAN related device driver statements.

In order to provide the detached ring-3 thread, a RUN = statement for the LANMSGEX.EXE file is a so required. Additionally, in order to gain access to the messaging DLL file, a path name where the LANMSGDL.DLL exists must be entered on the LIBPATH statement in the CONFIG.SYS file.

Assuming the Lan Transport Services reside in the \IBMCOM subdirectory, the entries in CONFIG.SYS should be the following:

LIBPATH=C:\OS2\DLL;C:\IBMCOM;
.
.
.
DEVICE=C:\IBMCOM\LANMSGDD.OS2
RUN=C:\IBMCOM\LANMSGEX.EXE

5.2 Configuring the Override for the Default Path Name

The default path where the messaging support driver expects to find the message file and where it will place the log file is the IBMCOM directory. The default path can be overridden by placing an optional /I parameter on the LANMSGDD's DEVICE = statement in the CONFIG.SYS file. An example follows:

DEVICE=C:\IBMCOM\LANMSGDD.0S2 /I :C:\IBMLAN

The /I parameter requires the drive and directory where the message file and message log reside. A terminating backlash on the override string must not be included. If the drive is omitted, the current root is assumed.

The default message and log file names are LT0.MSG and LANTRAN.LOG. These defaults can be overridden only by using the runtime interface input parameters to the messaging support driver. If the C:\IBMCOM default is desired, the /I parameter can be omitted.

5.2.1 Search Path Rules

Rules for message and log file search paths follow:

If the message file does not exist in the default path but the path exists, the device driver searches the root directory for the input message file but still logs all messages using the original default path.
If the default path does not exist, the root directory is searched for the message file. If found, the default path is changed to the root and the log file is also placed there.
If the message file cannot be found in the default or the root directory, the device driver fails to install, and the log file is created in the root directory.

5.3 Other Configuration Parameters to the Messaging Support Driver

There are two other parameters which can effect the messaging support driver functioning. Like the default path override, these too are placed on the DEVICE = statement of the LanMsgDD device driver. The /S parameter disables the display function, while the /P disables the pause-on-error function.

If the customer wants to disable all messaging display from the messaging support driver, the /S parameter can be inserted at the end of the DEVICE= statement for LANMSGDD.OS2 in the CONFIG.SYS file. This will not affect messages that are displayed independently by a device driver at initialization time but will disable any message sent to the messaging support driver with the display option on. The messages will continued to be logged.

Currently if a message is received by the messaging support driver with an error type set and the display option on, the message is displayed and with a pause-on-error message. This pause-on-error requires operator intervention to continue. By default the pause-on-error option is on. To disable pause-on-error in the messaging support driver, the /P option can be inserted at the end of the DEVICE= statement for LANMSGDD.OS2 in CONFIG.SYS.

These parameters can be inserted in any order and may be entered in either upper or lower case.

Notices

May, 1993

Issued by:

IBM Corporation

Personal Software Products

11400 Burnet Road

Austin, Texas 78758

First Edition (May 1992)

Second 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

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

Disclaimers

References in this publication 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 IBM's intellectual property rights or other legally protectible rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility.

IBM may have patents or pending patent applications covering subject matter in 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.

Trademarks

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

IBM

OS/2

The following terms, denoted by a double asterisk (**) in this publication, are trademarks of other companies as follows:

3Com	3Com Corporation
Microsoft LAN Manager	Microsoft Corporation

NDIS Driver Developer's Tool Kit
for OS/2 and DOS
Programmer's Guide

Preface

How to Use This Manual

Audience
Content
Result

How to Use This Manual

Audience

The principal audience for this manual is developers of NDIS Media Access Control (MAC) drivers for both DOS and OS/2. It is assumed that the reader is an experienced system programmer, familiar with the operating system, x86 programming, and system internals. Experience with networking and/or device drivers is highly recommended. Familiarity with NDIS, while helpful, is not assumed.

Content

This manual contains guidelines for writing an NDIS MAC driver. It is organized into four chapters. Chapter 1, Overview, contains general background information on device drivers, NDIS, and MAC drivers. Chapter 2, OS/2 Device Drivers, contains OS/2 specific information. Chapter 3, DOS Device Drivers, contains DOS specific information, from the point of view of the differences between DOS and OS/2 drivers. Finally Chapter 4, Writing a Media Access Control Driver, gives guidelines and examples useful for writing your MAC driver.

Result

The intended result of this manual is to aid your driver development.

Notational Conventions

The following notational conventions are used in this manual

Hexadecimal (base 16) numbers are given in the form 0xdd, 0xdddd, etc.
For example, 0x28 is hexadecimal for the decimal number 40.
File names are given in all capital letters. Hence CONFIG.SYS stands for the file named CONFIG.SYS.
Code examples are given in Courier type face.

NDIS

NDIS details an internal architecture for network drivers. Drivers are divided into two categories: Media Access Control (MAC) drivers and Protocol drivers. MAC drivers directly control network adapter cards, while protocol drivers interface with the operating system and/or applications. The NDIS details the responsibilities of both types of drivers as well as the interface between them. For more information on NDIS, see the publications: 3Com/Microsoft LAN Manager Network Driver Interface Specification 2.0.1 and NDIS Implementation Information for IBM LAN Systems, NDIS Extensions.

Finding Further Information

Further information can be found in the following document:

If you already have the LAN Technical Reference, you need to order the following document:

Note: Once the Supplement is available, it will ship with orders of the LAN Technical Reference.

Chapter 1. Overview

OS/2 and DOS use specialized software, known as device drivers, to manage input and output. Examples are screen display, keyboard or mouse input, printer output, floppy or hard drive file input/output, and network adapter input/output. Each device driver is responsible for the interface between the device (that is, its controller) and the operating system.

Types of Device Drivers

Each device driver falls into one of two distinct categories, character drivers or block drivers, depending upon its device. Block drivers manage random access devices, such as disc drives, that support logical units and a directory structure. Character drivers manage all other devices, including network adapter cards. We will be concerned with character drivers.

Device drivers are further authorized into base drivers and installable drivers. Base drivers handle the basic system input/output and are usually considered part of the operating system. We will not be concerned with base drivers. Installable drivers handle all other input/output functions.

Installable Device Drivers

Installable device drivers are loaded at system initiation time. The driver initialization thread reads the CONFIG.SYS file and loads and initializes the drivers specified in the "DEVICE=" statements on a first-read-first-loaded basis.

Drivers are loaded into low memory and must consist of a data segment followed by a code segment. Additional data or code segments, if present, will be loaded into high memory.

Parts of a Device Driver

Device drivers consist of from two to five components as follows:

Device Driver Header (required). The first item in the driver's initial data segment is the device driver header. The header specifies device attributes and driver entry points.
Strategy Routine (required). System communication with device drivers is accomplished by calling the driver's strategy routine. System requests include initialization and, for most device drivers, input/output requests.
(Hardware) Interrupt Routine (recommended). OS/2 device drivers usually service hardware requests by means of hardware interrupts.
Software Interrupt Handler (optional). DOS device drivers usually service hardware requests by means of software interrupts. OS/2 drivers may contain a software interrupt handle for backwards compatibility with DOS.
Timer Handler (optional). OS/2 device drivers may specify a timer entry point which will be called by the system every 31.25 milliseconds.

Real Versus Protected Mode

OS/2 can emulate DOS, running DOS applications in the "DOS Compatibility Box". While in this mode, the processor emulates the behavior of the 8088 and 8086 chips by running in real mode. Otherwise the processor runs in protected mode.

While in real mode, the processor interprets the CS, DS, ES, and SS registers as segment registers, in protected mode they are selector registers. That is to say, in real mode 20-bit physical addresses are split into an high-order, 16-bit segment and a low-order, 4-bit offset. While in protected mode, address are virtual and consist of a 16-bit selector (whose three low order bits are ignored) and a 16-bit offset. The selector references a position in the appropriate (local or global) descriptor table (LDT or GDT).

Privilege Levels

While OS/2 is in protected mode, processes (and their threads) have a privilege level or ring number. The privilege level of a process determines its access to descriptor tables. Applications run at Ring 3, and can only access their own local descriptor table. The operating system runs at Ring 0, or kernel mode and can access both local and global descriptor tables.

Device drivers, however, initialize at Ring 3 (as do most applications) and run at Ring 0, to have greater access to the kernel and to hardware.

Introduction to NDIS

Network device drivers were traditionally large, monolithic drivers, containing code for protocols (the language of the network) as well as network hardware. Traditional drivers were difficult to write, had less flexibility, were harder to upgrade, and didn't support multiple protocols. A fully functional monolithic network driver would have to have the ability to interface with every protocol available.

A modular approach to protocol handling (in which only those protocols required are loaded) is a much more efficient use of system memory. The Network Device Interface Specification (NDIS) was developed to eliminate the need for multiple protocols within a single driver. Under NDIS, protocol handling is completely separated from hardware manipulation. NDIS replaces the traditional network driver with two distinct types of installable character drivers: protocol drivers and Media Access Control (MAC) drivers.

NDIS protocol drivers do not manipulate network hardware - they handle the various network data formats. MAC drivers handle the hardware. Working together, these two driver types replace the large monolithic network driver. As a result, protocol and hardware handling drivers are modular and streamlined. Protocol and MAC drivers, as a group, are called NDIS device drivers

The NDIS describes the functionality that both protocol and MAC drivers must provide for each other. The specification also describes a standard network driver interface for the two types (MAC and protocol) of NDIS device drivers

The interface includes a Protocol Manager to help organize configuration data and to bind the various modules together.

NDIS device drivers may choose to run under both OS/2 and DOS. NDIS drivers provide access to many kinds of complex protocols under multiple hardware configurations.

NDIS and the OSI Reference Model

The International Standards Organization, in an effort to standardize networks created the Open Systems Interconnection (OSI) reference model. In the OSI model, network software is thought of as a system of layers with each layer representing a particular task. The OSI model defines seven layers of networking tasks as follows

File:Images\ndisp01.gif

The lower portion of an NDIS protocol driver functions in the upper portion of the data link layer, above the network device driver interface. The upper portion of an NDIS protocol driver may reside anywhere from the data link to the application layer of the OSI model.

The device driver interface described in the NDIS specification functions within the data link layer of the OSI reference model.

NDIS MAC drivers are implemented at the bottom portion of the data link layer. MAC drivers may work with any physical media: PC Network, Token-Ring, ArcNet, etc. IBM protocol drivers support 802.3 or DIX (EtherNet) and 802.5 (Token-Ring) networks.

The Protocol Manager

The network device driver interface is implemented through a Protocol Manager used to coordinate connections (bindings) between modules. When an NDIS protocol or MAC driver loads and initializes, it passes to the Protocol Manager a pointer to an internal characteristics table that includes the module's name and entry points. Protocol drivers also pass a list of MAC drivers with which they wish to bind. The Protocol Manager reads the protocol driver's bindings list and helps the protocol driver to exchange information with each MAC driver in the list. The information exchanged consists of pointers to each other's characteristics tables. The exchanged entry point information allows protocol and MAC drivers to exchange characteristics tables and communicate directly with one another.

VECTOR

While a protocol driver may bind to multiple MAC drivers, each MAC driver must bind to one, and only one, protocol driver. To allow a MAC driver to bind to multiple protocol drivers or to allow a protocol driver to be dynamically loaded and unloaded, the Protocol Manager provides an additional module known as VECTOR. The VECTOR module shields a MAC driver from these details, allowing the MAC driver to be written as if there were always a single protocol driver bound to it.

Media Access Control Drivers

MAC drivers provide low-level access to network adapters. MAC drivers are loaded at system initialization time and are static - that is, they may not be removed from memory. The primary function of a MAC driver is to transmit and receive packets. Secondarily, the MAC driver also provides some basic adapter management functions.

Parts of a MAC Device Driver

Like other device drivers. an NDIS MAC driver contains the following components:

Header
Strategy Routine
- Initialization Routine
Interrupt Routine

Additionally, an NDIS MAC driver must contain entry points for the following seven, NDIS-specific, entry points:

System Request Routine
General Request Routine
TransmitChain Routine
TransferData Routine
ReceiveRelease Routine
IndicationOff Routine
IndicationOn Routine

Finally, an NDIS MAC driver must contain the following data structures:

Common Characteristics Table
Service-Specific Characteristics Table
Service-Specific Status Table
Upper Dispatch Table

How a MAC Device Driver Works

The sole purpose of the Strategy Routine in an NDIS MAC driver is to handle load-time initialization of the driver. Later the Protocol Manager directs NDIS drivers to exchange common characteristics table addresses with the drivers they bind to. Chained off of the common characteristics table are the other tables as well as entry points to their NDIS-specific routines.

A MAC driver's Interrupt Routine handles notifications from the hardware to the MAC. These notifications will cover such matters as changes in adapter status, reception of frames, and the completion of previous transmissions.

The System Request Routine handles such matters as binding (during which characteristics tables are exchanged) and unbinding. The General Request Routine handles protocol requests of the MAC. These requests include opening and closing the adapter, setting the station address, updating statistics, and many others. Both system and general requests utilize a request packet and return a completion code in a manner similar to that of an OS/2 driver's Strategy Routine.

The TransmitChain, TransferData, and ReceiveRelease routines are used during the transmission and reception of frames in order to pass data buffers between a protocol and a MAC driver.

The IndicationOff and IndicationOn routines are used to control (turn on and off) status and reception indications. Indications are notifications from a MAC driver to a protocol driver of a change in adapter status or of a reception of a frame. A protocol driver reacts to an indication in a manner similar to a MAC driver reacting to an interrupt.

Chapter 2. OS/2 Device Drivers

As mentioned in the first chapter, OS/2 device drivers contain a device driver header and a strategy routine. As these components are common to all device drivers, they will be discussed here. For more detailed information on OS/2 device drivers, see the following publications from the OS/2 2.0 Technical Library: Control Program Programming Reference (S10G-6263-0), and Physical Device Driver Reference (S10G-6266-0). In this section, we provide a summary of that information.

The Device Driver Header

The first item in the driver's initial data segment is the device driver header. This twenty-six byte data structure is organized as follows:

Offset	Size (bytes}	Description
0x00	4	Pointer to next header
0x04	2	Device Attribute Field
0x06	2	Offset to Strategy Routine
0x08	2	Offset to IDC Routine
0x0A	8	Name
0x12	8	Reserved

In order to support multiple devices within a single driver, the device driver header is a linked list. This list is terminated by a pointer of - 1 (0xFFFFFFFF), so if your driver supports only a single device, you should fill this field with -1.

The Device Attribute Field contains descriptive information used by the system. Its structure is as follows:

Bit	Description
0	Keyboard bit: 1 = device is the standard input device, 0 = otherwise
1	Screen bit: 1 = device is the standard output device, 0 = otherwise
2	NULL attribute bit: 1 = device is the NULL device, 0 = otherwise
3	Clock device bit: 1 = device is the system clock device, 0 = otherwise
9-7	Function Level: 001 = 0S/2 device driver (hence will be initialized in protect mode), 000 = compatibility box driver (hence will be initialized in real mode)
11	Open/close bit: 1 = driver requires an OPEN and CLOSE call from the system, 0 = otherwise
12	Shared bit: 1 = system file sharing rules apply, 0 = file ownership contentions will be resolved by the driver
13	IBM bit: set to zero for character devices (for block devices: 1 = supports DOS 2.0 and above file formats, 0 = supports DOS 1.0 or 1.10 formats)
14	Inter-driver communication (IDC) bit: 1 = driver has an IDC entry, 0 = otherwise
15	Device type bit: 1 = character device, 0 = block device

The other bits are reserved, and should be set to zero.

Following the Device Attribute Field offsets into the main code segment to the entry points of the Strategy Routine and the Inter Device Communication Routine.

Character devices then have an eight byte, ASCII, blank-filled name of the device driver. This name must match the "DriverName=" keyword given in the PROTOCOL.INI file. As a device name takes precedence over a file name in a DosOpen function call, device names should contain some unusual character. A terminating "$" is traditional.

The final eight bytes of the header are reserved and should be zero filled.

The Strategy Routine

The Strategy Routine handles the system's requests of the device driver. For an OS/2 device driver, these requests include installation, normal I/O, character device-specific I/O, block device-specific I/O, and generic I/O control.

The Strategy Routine follows the far call/return mode and can be called in either real or protect mode. At entry, a pointer to a Request Packet is contained in the ES:BX register pair. This pointer is bi-modal and references the same address whether the processor is in real or in protect mode.

The Strategy Routine reads the Request Packet and takes the appropriate action. Upon completion of the request, a status field is set in the Request Packet to indicate the completion status of the request.

The Request Packet

The Request Packet consists of a thirteen byte header followed by a command specific data area. The structure of the request packet header is as follows:

Offset	Size (bytes)	Description
0x00	1	Total length of Request Packet
0x01	1	Unit code (block device)
0x02	1	Command code
0x03	2	Status field
0x05	4	Reserved
0x09	4	Queue linkage field

The first byte gives the total length of the packet, including the header and command-specific data area. The next byte is ignored for character devices. The third byte gives the command code, indicating which function (for example, 0 = driver initialization) has been requested of the driver.

The next two bytes contain the status field. This field should be set by the driver to indicate the request completion status. Errors are indicated by setting the high order bit of this field. In this case, an error code should be returned in the low order eight bits.

The next four bytes are reserved, and the final four bytes of the header can be used to maintain a linked list of queued request packets. Either DevHlp services or the driver's own queue management may be used.

The remainder of the request packet contains command-specific data. The type and amount of command-specific data varies with each command.

The Initialization Routine

Overview

Every device driver's Strategy Routine must accept the INIT initialization request (request code = 0). The driver's code which processes this request is known as the driver's Initialization Routine. The INIT request is generated by the system during driver loading and initialization. At this time, the driver initialization thread reads the CONFIG.SYS file and interprets the "DEVICE=" command lines.

For each driver referenced, the system loads the first two segments into low memory (and any remaining segments into high memory), resolves intersegment memory references, and interprets the device driver header. Then if the device driver is a DOS-compatible driver (function level = 000) that may only run in the compatibility box, the system switches the processor to real mode, otherwise it remains in protect mode. Finally the driver initialization thread formats an INIT request packet and makes a far call to the driver's Strategy Routine to allow the driver to initialize itself.

The INIT Request Packet

The INIT request packet is twenty-three (0x17) bytes long. It consists of the standard thirteen byte header, followed by ten bytes of INIT-specific data in the following format:

Offset	Size (bytes)	Description
0x0D	1	Data_1
0x0E	4	Pointer_1
0x12	4	Pointer_2
0x16	1	Data_2

On entry, Data_1 is unused. Pointer_1 contains a bi-modal pointer to the device helper (DevHlp) routine. Pointer_2 contains a far pointer to the device driver parameter string as defined in the "DEVICE=" command in the CONFIG.SYS file. This string consists of the driver file name, followed by blank-separated arguments and is null-terminated. Data_2 is set, for block drivers only, to the drive number of the next logical unit the file manager expects to install. Data_2 is unused for character drivers.

On exit, Data_1 will be set, by block drivers only, to the number of logical units supported by the device. Character drivers should set Data_1 to zero. Pointer_1 should be set to the lengths of the code and data segments after initialization time, with the high-order word giving the code segment length and the low-order word the data segment. This allows the system to free memory used only by the initialization routine. Pointer_2 will be set, by block drivers only, to a far pointer top the BIOS parameter block array. Data_2 is not used on exit.

Finally, on exit the driver should set the status field in the Request Packet header. Successful initialization is indicated by a status value of 0x0100 (only bit 8 set, indicating request done). General Failure is signaled by a status value of 0x810C (bit 15 set, indicating error, bit 8 set, indicating request done, and error code 0x0C, indicating General Failure).

OS/2 Functions Available at Initialization

There are over 200 Application Program Interface (API) function calls available under OS/2. These functions perform I/O, control processes, manage interprocess communication, and perform many other tasks. A subset of these API functions are available to a device driver at initialization time.

An OS/2 device driver's initialization routine is called at Ring 3 in protect mode, and a DOS compatibility box driver's initialization routine is called in real mode. Hence neither process management nor memory management API calls are permitted. However, at a device driver's initialization time, the system base drivers have loaded. Hence the following API calls are available at initialization time:

FileI/O:
	Randomly reposition file pointer
	Close a file
	Perform generic I/O control functions
	Open a file
	Read from a file
	Write to a file
Directory Management:
	Delete a file
	Terminate a pattern matching search
	Look for a file, using pattern matching
	Look for next file matching pattern
File System Information
	Get system configuration information
	Get current working directory
	Get current working disk
	Get file status
	Get file attribute bits
System Message Handling
	Retrieve message from system message file
	Write message to system message file
Base-Line I/O
	Produce system audio alert

DevHlp Service

As device drivers run at Ring 0, kernel mode, API calls are only available during initialization time. Hence an interface to the OS/2 operating services is provided to device drivers through the DevHlp Interface. A pointer to the entry point for DevHlp calls is passed to the driver with the INIT request packet.

There are a total of fifty-seven DevHlp services. The following subsets of these are available at driver initialization time:

System Clock Management: SchedClockAddr
Character Que Management: QueueInit
Memory Management: AllocGDTSelector, AllocPhys, FreePhys, Lock, PhysToGDTSelector, PhysToVirt, Unlock, UnPhysToVirt, VirtToPhys
Interrupt Management: EOI, SetIRQ, SetROMVector, UnSetIRQ
Timer Services: ResetTimer, SetTimer, TickCount
System Services: GetDOSVar
Advanced BIOS Services: ABIOSCall, ABIOSCommonEntry, FreeLIDEntry, GetLIDEntry

Chapter 3. DOS Device Drivers

There are several areas of difference between DOS and OS/2, mostly in the area of memory access and management. For real mode DOS, the driver's view of memory is straight-forward. A valid address is always valid whether operating in interrupt, system, or user context. Under OS/2 the validity of an address is entirely dependent upon its context. Extra care and planning is required to ensure that the driver's memory management strategy is correctly defined.

The Device Driver Header

The interfaces and entry points defined by NDIS are the same both for DOS and for OS/2. There are however, differences in the basic device driver structure in the two systems. These discrepancies are illustrated by the format of the driver's device header. The DOS driver's header contains two entry points referred to as Strategy and Interrupt and is eight bytes shorter than the OS/2 header. The eighteen byte DOS device header is organized as follows:

Offset	Size (bytes)	Description
0x00	4	Pointer to next header
0x04	2	Device Attribute Field
0x06	2	Offset to Strategy Routine
0x08	2	Offset to Software Interrupt Routine
0x0A	8	Name

See the section on the OS/2 device headerfor a detailed description of the Device Attribute Field.

The Strategy Routine

Under DOS when the system processes a request packet, it initially calls the driver's strategy entry point with the register pair ES:BX containing the address of the packet. The only function the DOS strategy routine performs is saving this address in local memory. Immediately after return from the driver strategy routine, DOS calls the driver at the Software Interrupt entry point. The Software Interrupt routine retrieves the pointer stored by the strategy handler and then proceeds to execute the requested task.

The Request Packet

The DOS Request Packet, like the OS/2 Request Packet, consists of a thirteen byte header followed by a command-specific data area. The structure of the request packet header is as follows:

Offset	Size (bytes)	Description
0x00	1	Total length of Request Packet
0x01	1	Unit code (block device)
0x02	1	Command code
0x03	2	Status field
0x05	8	Reserved

See the section on the OS/2 Request Packetfor a detailed description of these fields.

The Initialization Routine

Overview

Under DOS, the Strategy Routine will save the address of the INIT request packet and return. The initialization Routine will be accessed through the Software Interrupt Entry point.

The INIT Request Packet

The DOS INIT request packet is, like the OS/2 packet, twenty-three (Ox 17) bytes long. It consists of the standard thirteen byte header, followed by ten bytes of INIT-specific data in the following format

Offset	Size (bytes)	Description
0x0D	1	Data_1
0x0E	4	Pointer_1
0x12	4	Pointer_ 2
0x16	1	Data_ 2

The only difference between the DOS and OS/2 packet is in the usage of Pointer_1. On entry for a DOS device driver, Pointer_1 is unused. On exit for a DOS driver, Pointer_1 should be set to point to the first available byte of memory above the driver.

INT 21 Function Calls at Initialization Time

During system initialization, there are typically several functions which require interface with the underlying operating system. For example, the driver may wish to display a text message identifying itself, or it may wish to query the revision of the system to be sure that some piece of required functionality is present. Particularly, in the case of an NDIS driver, interaction with another driver that has already been loaded is required.

The two operating environments, DOS and OS/2, provide the means to accomplish these tasks. Under DOS, operating system functions are executed by loading parameter values into registers and executing a software interrupt. The system dispatcher fields such requests via vector X'21'. The DOS Technical Reference provides a comprehensive description of the functions available via this method.

The OS/2 driver accesses the system via far calls to API functions linked into the executable file in precisely the same manner as an application program would. This is possible because the OS/2 initialization process executes in Ring 3 just as if it were an ordinary application program.

For both DOS and for OS/2, this functionality is accessible only during system startup. Once the initialization process has returned, neither the INT 21 or the application APIs are available.

Interrupt Handlers

Hardware interrupts and the associated interrupt handlers are managed in a slightly different manner between DOS and OS/2. Please note that interrupt handler as used in this context is distinct from the Software Interrupt routine described in the preceding discussions. In the current context, the interrupt handler is the body of code that executes in response to a hardware event and not as part of system request processing.

In an OS/2 environment, the handler is called indirectly by the system's interrupt manager. At the point at which the handler begins execution, all of the system's registers have been saved and a special interrupt stack is in use. In addition, the system provides helper routines to aid in managing Process Interrupt Control (PIC) related tasks such as delivering the SetIRQ command.

Under DOS, the handler is executed directly when a hardware interrupt occurs. Preserving the processor context, switching stacks, and dismissing the interrupt through direct interaction with the PIC are tasks which the driver must perform on its own behalf.

Chapter 4. Writing a Media Access Control Driver

The Media Access Control driver bridges the gap between the physical components of the network and the logical elements contained in the protocol stack. Every network transaction is processed by the MAC driver. Great care must be taken during implementation to ensure that a highly performant and flexible interface is provided. See the NDIS Driver Developer's Tool Kit for OS/2 and DOS Programmer's Performance Guide for guidance on performance Issues.

Typical drivers contain an entry point for requests from the operating system and usually an interrupt handler as well. NDIS MAC drivers contain additional entry points to process the functions that are defined at the boundary with the protocol driver. The calling sequence for the NDIS functions differs from that used by the operating system. Normal system functions such as read, write, open, and close are passed to the driver via a parameter block. NDIS functions are executed across the boundary between the MAC and the protocol using direct calls to entry points defined by the specification. The calling sequence used is far Pascal. The calling routine pushes its parameters on the stack from left to right, and the called routine releases the stack space occupied by the parameters on exit. Return status is passed via register AX. Called routines are responsible for saving and restoring standard register variables DS, DI, SI, and BP.

The following sections of this chapter will provide detailed descriptions and code samples illustrating the process that must be implemented by a MAC driver. These samples are written in assembly language, although C could be used. These samples are examples intended to illustrate possible code structures. Where differences exist between DOS and OS/2 the code fragments contain conditionals to control the assembly time generation of a driver for one system or the other.

The Strategy and Initialization Routines

Standard operating system type functions are signaled to an OS/2 driver via a far call to the Strategy Routine entry point defined in the driver header. The argument to this call is a pointer to a parameter block containing a code that indicates the function to be executed as well as supplementary information to be used in processing the request. The only function that a MAC driver must implement is initialization. Other functions may be implemented at the developer's discretion. For example, read and write might be used to provide access to the MAC's internal structures during debug. But in all cases, whether a function is implemented or not, every request must return a completed status in order to prevent exhaustion of system resources.

The initialization function is signaled to the driver during the processing of the CONFIG.SYS file at system startup time. During initialization, the driver establishes its operating environment, locates its adapter, and allocates the resources necessary for operation.

The PROTOCOL.INI file contains the definition of the communications subsystem that will be built. The PROTOCOL.INI file contains an entry for each driver that is configured in the NDIS environment. As part of its initialization path, the Protocol Manager reads this file and parses its contents into a tree structure. Each node directly below the root of the tree describes a [module] section from this definitions file.

Opening the Protocol Manager

As each NDIS driver initializes, it interacts with the Protocol Manager to obtain its individual parameters and to register itself. Access to the Protocol Manager is via the file system APIs. This is possible because during startup, the driver initialization code executes in Ring 3, just as if it were a normal application. The first step required is to open the Protocol Manager. The format of the function should be similar to that given below.

;                               
;-- Get handle for Protocol Manager                             
;                               
if      OS2                     
        push    ds                 ;    Far pointer to name (input)
        push    offset ProtocolManagerName              
        push    ds                 ;    Far pointer to handle (output)
        push    offset ProtocolManagerHandle            
        push    ds                 ;    Far pointer (output)
        push    offset ActionTaken              
        push    0                  ;    Dword file size (output)
        push    0               
        push    1                  ;    Flag (input)
        push    0C2h               ;    Mode (input)
        push    0                  ;    Dword reserved
        push    0               
        call    DOSOPEN         
        or      ax, ax             ;    Return status?
        jnz     NoManager          ;    Display error and abort
else                               ;    DOS interface
        mov     dx, offset ProtocolManagerName          
        mov     ax, 3d00h          ;    DOS open function
        int     21h             
        jc      NoManager               
endif

Protocol Manager Requests

After the Protocol Manager open has succeeded and the file handle is obtained, requests are executed using IOCTL functions, passing a pointer to a parameter block which defines the function to be performed. Under OS/2 the generic IOCTL, function code 16, is used to provide access to all of the functionality provided by the Protocol Manager. The Category code used is 0x81 signifying LAN Manager, with a function code of 0x58, indicating Protocol Manager type command. The parameter buffer contains a far pointer to a common request block structure. The structure given below describes the Protocol Manager request block.

PMBlock         struc           ; Function code
PMCode          dw      ?       ; Status returned by
PMStatus        dw      ?        
                                ; ProtMan
PMPtrl          dd      ?       ; First parameter
PMPtr2          dd      ?       ; Second parameter
PMWord          dw      ?       ; Third parameter
PMBlock         ends

Getting Configuration Information

Typically, the next step is to gain access to the ConfigMemoryImage parsed from PROTOCOL.INI by the Protocol Manager. The code fragment provided below illustrates the correct procedure for filling in the request block and invoking the Protocol Manager.

;                               
;--     Fill in request block.  Only parameter required                 
;       is function code.                       
;                               
        mov     PMReqBlk.PMCode, GetProtManInfo         
if      OS2                     
        push    0               ;       Far null pointer
        push    0               
        push    ds              ;       Far pointer to ReqBlk 
        push    offset PMReqBlk         
        push    ProtManCode     ;       0x58
        push    LanManCat       ;       0x81
        mov     ax,[ProtoclManagerHandle]               
        push    ax              ;       Handle returned by open
        call    DOSDEVIOCTL     ;       System API
        or      ax, ax          ;       Return okay?
        jnz     NoConfigInfo    ;       Display error and abort
else                            ;       DOS
        mov     bx, [ProtocolManagerHandle]             
        mov     dx, offset PMReqBlk             
        mov     cx, 14          ;       size of block
        mov     ax, 4402h       ;       IOCTL function
        int     21h             
        jc      NoConfigInfo            
endif                           
                                
                                
                                
;                               
;--     Success.  First pointer contains address of                     
;       ConfigMemoryInfo structure. Word parameter                      
;       contains revision of Protocol Manager. Check                    
;       for acceptable values.                  
;                               
        mov     ax,  PMReqBlk.PMWord            
        cmp     ax, ProtManLevel                
        jne     InvalidProtMan      ;Display error and abort
        lds     si,PMReqBlk.PMPtrl  ;Get pointer to config tree

The driver must now traverse the list of ModuleConfig structures, seeking the one that contains its operational parameters. Note that although the nodes are based an the square-bracketed [ModuleName] sections contained in the PROTOCOL.INI file, ModuleName is not the correct key to be used for the search. The value of this field is user definable and may be installation specific. The search should be based on the "DriverName=" keyword. This entry is required within every ModuleName section and must accurately reflect the name used within the driver's device header. Other fields are optional in general, but may be required by specific drivers. Below is an example PROTOCOL.INI entry for the driver for the fictional BITHOSE card. This driver requires two additional parameters, namely the I/O base address of the card and the IRQ to be used.

[bithose_NIF]
  DriverName      = bithose$
  Base            = 0x300
  IntLevel        = 3

When the Protocol Manager builds the ConfigMemoryImage, lower case characters are converted to upper case and white space and comment lines are ignored. During initialization, the bithose driver searches for a ModuleName section with the correct DriverName value.

;-- The following structure definitions are used                                
;    by the parsing routine below.                              
;                               
ModuleConfig            struc           
ModuleNext      dd      0               ;       Next in chain or
                                        ;       Null
ModulePrev      dd      0               ;       Previous in chain
ModuleName      db      16 dup (0)      ;       Square bracket name
KeyWordList     dd      0               ;       First keyword
ModuleConfig            ends            
                                
                                
KeyWord         struc           
KeyWordNext     dd      0               ;       Next in chain or
                                        ;       NULL
KeyWordPrev     dd      0               ;       Previous in chain
KeyWordName     db      16 dup (0)      ;       Keyword text
NumParams       dw      0               ;       Count of parameters
;                               
;--  The next section repeats NumParams times                           
;                               
ParamType       dw      0               ;       Type of parameter
                                        ;       =0 then long
                                        ;       =1 then ASCIIZ
string                          
ParamValue      dd      0               ;       Variable depending
                                        ;       on type
Keyword                 ends            
;                               
;-- Find our ModuleName section.                                        
;  ds:si--> Head of ModuleConfig linked list.                           
;                               
CheckEndModules:                                
     mov        ax, ds                  ;       Check for end of
     or         ax, si                  ;       the line
     jz         NoDriverName            ;       Display error and
                                        ;       abort
;                               
     push       ds                      ;       Save our place
     push       si                      
     lds        si, [si].KeyWordList                    
;                               
CheckEndKeywords:
     mov    ax, ds                      
     or     ax, si                      ;       Null pointer?
     jz     EndKeywords                 ;       Yes - try next module
;   
     mov        bx, si                  ;       Save structure pointer
     mov        si, [si].KeyWordName                    
     mov        di, offset DriverKeyword                        
     mov        cx, 10                  ;       Length of "DRIVERNAME"
     cld                                
     rep        cmpsb                   
     jcxz       FoundDriverKeyword                      
;                               
NextKeyword:                            
     lds        si, [bx].NextKeyword                    
     jmp        CheckEndKeyWords                        
;                               
FoundDriverKeyword:                             
     cmp        [bx].NumParams, 1                       
     jne        NextKeyword             ;       Invalid entry
     lea        si, [bx].Param                  
     cmp        [si].ParamType, ASCIIZ                  
     jne        NextKeyword                     
     mov        cx, OurNameLen                  
     cmp        cx, [si].ParamLen                       
     jne        NextKeyWord                     
     lea        si, [si].ParamValue                     
     mov        di, offset OurName                      
     rep        cmpsb                   
     jcxz       FoundOurName                    
     jmp        NextKeyword                     
;                               
EndKeywords:                            
     pop        si                      
     pop        ds                      ;       Restore
                                        ;       ModuleConfig ptr
     lds        si, [si].NextModule                     
     jmp        CheckEndModules                         
;                               
FoundOurName:                           
     pop        si                      
     pop        ds                      ;       We have our section
                                        ;       now

Building the Characteristics Tables

After locating the correct ModuleName section, the driver should copy the Name specified by the user into its common characteristics table. The driver should scan the keywords linked to this module for any specific required parameters. In this example, the bithose driver would continue the scan for the two additional required parameters. If they are not present, the driver may choose to display an error message and abort its initialization. For each parameter encountered, the driver should check to ensure that the parameter is of the correct type and that the value given is within range.

After parsing its ModuleConfig section, the driver should have enough information to query its adapter and complete the initialization of its characteristics tables. NDIS defines a set of tables that are maintained by conformant drivers. These tables contain information describing the capabilities of the driver and adapter, as well as several entry points within the driver that are callable by external entities across the NDIS boundary. Most of the fields in the table may be initialized when the driver is coded, with the default values in selected fields overridden by information gained from PROTOCOL.INI parsing.

Several fields within these tables contain far pointers to be used by the protocol driver after binding. The values contained must be Ring 0 GDT selectors. They can not be established at initialization time because the driver is operating in Ring 3. The value for these pointer fields are properly established using the SEG assembler pseudo-op as illustrated in the example below, describing the NDIS System Request dispatch entry point as it might appear within the MAC's Common Characteristics Table.

          dw         offset System 
          dw         SEG System

Completing Initialization

After the Characteristics Tables have been completely built, the MAC driver can proceed to the final stages of initialization. Depending on the MAC, this may, under OS/2 require reserving GDT selectors and locking extra segments for use during operation. When the implementation-specific initialization functions have completed, the driver is ready to complete its start-up path by registering with the Protocol Manager. This function is executed as a generic IOCTL as described in the preceding section on obtaining the ConfigMemoryInfo. The format of the call is described below.

;                               
;--  Fill in request block.  Required parameters are                            
;     function code and far pointer to the Common                               
;     Characteristics Table.  Pointer 2 (bindings                               
;      list) must be null for MAC's.                            
;                               
       mov              PMReqBlk.PMCode, RegisterModule                 
       mov              word ptr PMReqBlk.PMPtrl, offset CCTable                        
       mov              word ptr PMReqBlk.PMPtrl + 2, SEG CCTable                       
       mov              word ptr PMReqBlk.PMPtr2, 0                     
       mov              word ptr PMReqBlk.PMPtr2 + 2, 0                 
;                               
if     OS2                              
       push     0                       ;       Far null pointer
       push     0                       
       push     ds                      ;       Far pointer to ReqBlk
       push     offset PMReqBlk
       push     ProtManCode             ;       0x58
       push     LanManCat               ;       0x81
       mov      ax, [ProtoclManagerHandle]
       push     ax                      ;       Handle returned by open
       call     DOSDEVIOCTL             ;       System API
       or       ax, ax                  ;       Return okay?
       jnz      RegisterFail            ;       Display error and abort
else                                    ;       DOS
       mov      bx, [ProtocolManagerHandle]                     
       mov      dx, offset PMReqblk                     
       mov      cx, 14                  
       mov      ax, 4402h               ;       DOS IOCTL
       int      21h                     
       jc       RegisterFail                    
endif

Initialization is now completed and no further interaction with the Protocol Manager is required. The file handle used for the interface may now be closed and the driver may exit back to the OS/2 configuration processor.

The System Request Routine

At some point after the system has completed boot up, an application program may request that the network interface be started. This is signaled to the Protocol Manager via a BindAndStart function. A typical source of this request is the NETBIND.EXE program. During the RegisterModule phase, the Protocol Manager built a binding tree describing the protocol driver to MAC linkages to be established in order to create the communications subsystem. Upon receipt of the BindAndStart command the Protocol Manager traverses this tree, requesting that the higher level entities (protocol drivers) bind to the lower (MAC drivers).

For the MAC driver, the end result of this activity will, if the system is correctly configured, generate one and only one bind request from an upper level routine. This request may be issued by a single protocol driver module or it may be issued by a sub-function of the Protocol Manager called VECTOR acting on behalf of multiple protocol driver modules that have specified a binding to the MAC driver. In either case, the interface to the MAC driver is identical. When the MAC is invoked, the stack contains the parameters passed by the protocol driver in the following format

stack   -->     dword   far return
        -->     word    MAC's data_seg
        -->     word    opcode for Bind (2)
        -->     word    pad (0)
        -->     dword   pointer where to return CCTable address
        -->     dword   callers CCTable address

The Bind System Request

Bind is the only System Request that MAC drivers implement. The MAC should be prepared to bind with no more than one upper lead module. Succeeding Bind requests should return an invalid status. The code fragment provided below demonstrates the Bind procedure.

System proc far                         
       push     bp                      ;       Save frame pointer
       mov      bp, sp                  ;       And establish
                                        ;       addressability
       push     ds                      ;       Save
       push     di                      
       push     si                      
       mov      ds, [bp].SysDs          ;       Our data_seg
       mov      ax, INVALID_FUNCTION                    
       cmp      [bp].SysFunc, BIND                      
       jne      SysExit                 ;       Nothing else
       mov      ax, [BindStatus]                        
       or       ax, ax                  ;       We update this when a
                                        ;       bind has occurred.
                                        ;       If 1=0 then
                                        ;       already bound.
       jnz      SysExit                 
;                               
;-- Take control of the adapter now.  It shouldn't be                           
;     done during bootup in case the adapter is being                           
;   used for remote boot.                               
;                               
      call GetAdapter                   ;       Do adapter specific stuff
      or        ax, ax                  ;       Make sure all went well
      jnz       SysExit                 ;       Some kind of hardware
                                        ;       problem - fail the bind
;                               
;--  Mark ourselves as bound and copy in some of the                            
;     Protocol's information for fast access.                           
;                               
      mov   [BindStatus], INVALID_FUNCTION                              
      or      SpecStatusTable.SpecStatus, MACBound                              
      mov       ax, ds                  
      mov       es, ax                  
      mov       di, offset ProtocolTable                        
      lds       si, [bp].SysProtTable                   
      mov       ax, [si].CCTableDS      ;       Save Protocol's DS
      mov       es: [ProtcolDS], ax                     
      lds       si, [si].CCTableLowerDispatch                   
      mov       cx, SizeLowerDispatch                   
      cld                               
      rep       movsb                   
      xor       ax, ax                  ;       Status cleared
SysExit:                                
      pop       si                      
      pop       di                      
      pop       ds                      
      pop       bp                      
      ret       SizeSysParms            ;       Clean up stack and exit
System endp

If the MAC driver has chosen not to implement Open and Close then, on exit from the System Request function after a successful Bind, the adapter and the MAC should be fully conditioned and ready to support network traffic.

The Indication Routines

An indication, as generated by the MAC to the protocol driver, is a higher level notification of an adapter-generated event. Indications may occur when a frame is received, when an adapter error condition occurs, or, if supported by the underlying hardware. as the result of an InterruptRequest Gall Request issued at some earlier point in time by the protocol driver MAC drivers implement two entry points, IndicationOn and IndicationOff, that provide the protocol driver with a logical mechanism for enabling and disabling these events.

The MAC driver maintains its indication level as a counter. IndicationOff increments the counter and IndicationOn decrements it. At any point if the value of the counter is non-zero, indications may not be signaled to the protocol drive. This correctly handles unwinding from the case where IndicationOff requests have been nested.

On entry to the indication routines, the stack holds the calling context as follows:

       Stack    -->     dword   far return
                -->     word    MAC's data_seg

IndicationOff

The code fragment below provides an example IndicationOff routine. As part of its process path, the routine calls an adapter specific routine to disable its interrupt generation. Depending on the hardware, it may be possible to execute a partial disable, allowing the driver to continue processing non-indication generating functions such as TransmitChain.

IndicationOff                   proc far                                
      push      bp                      ;       Standard preamble
      mov       bp, sp                  
      push      ds                      
      push      di                      
      push      si                      
      mov       ax, [bp].IndDS                  
 ;                              
      cli                               ;       Per NDIS we return disabled
      mov       al, [IndicationLevel]                   
      inc       [IndicationLevel]                       
      or        al, al                  ;       Enabled before?
      jnz       IOffExit                ;       Yes - HW already disabled
;                               
     call       AdapterDisable          ;       Specific to adapter
;                               
IOffExit                                
      xor       ax, ax                  ;       Return okay
      pop       si                      
      pop       di                      
      pop       ds                      
      pop       bp                      
      ret       IndParmSize                     
IndicationOff                   endp

IndicationOn

The IndicationOn procedure is the complement of the IndicationOff function. The MACs indication level is decremented and, if the count reaches zero, adapter interrupts are re-enabled.

IndicationOn                                    proc far
     push       bp                      ;       Standard preamble
     mov        bp, sp                  ;       Get stack addressability
     push       ds                      
     push       di                      
     push       si                      
     mov        ds, [bp].IndDS          ;       Our data_seg
;                               
     cli                                ;       Per NDIS we return disabled
     dec        [IndicationLevel]                       
     jnz        IOnExit                 ;       Still off
;                               
     call AdapterEnable                 ;       HW specific to restart
                                        ;       Must run disabled because
                                        ;       indications not allowed within
                                        ;       the context of this call
;                               
IOnExit                         
     xor        ax, ax                  ;       Status = okay
     pop        si                      
     pop        di                      
     pop        ds                      
     pop        bp                      
     ret        IndParmSize                     
IndicationOn                            endp

In addition to these two routines, the indication level is implicitly manipulated by the MAC driver whenever an indication is about to be signaled to the protocol drive. This will be described more fully in the following sections describing the specific indications.

The TransmitChain Routine

The MAC's TransmitChain entry point is called by the protocol driver when there is a frame ready to be dispatched to the network. MAC's may implement TransmitChain synchronously or asynchronously. If the transmission is completed successfully within the context of this call, a successful return status is provided to the calling protocol. If the adapter is currently unable to accept another frame for transmission, the MAC may queue the request and return immediately to the protocol with a status indicating that the request was pended. At some later point when adapter resources become available, probably within the context of the interrupt handler, the frame can be dequeued and transmitted.

If transmission is deferred, the MAC has two additional responsibilities. First, the TransmitChainBuffer Descriptor and any immediate data it describes are valid only during the execution of the original TransmitChain call. Therefore, these volatile portions of the frame description must be copied into the MAC's memory space before returning. Second, when the deferred frame is finally transmitted, it must be confirmed to the protocol driver via the TransmitConfirm function described below.

On entry to TransmitChain, the stack contains the arguments provided by the protocol driver to be used in processing this request.

       stack    -->     dword   far return
                -->     word    MAC's data_seg
                -->     dword   pointer to buffer descriptor
                -->     word    request handle
                -->     word    Protocol ID

TransmitChain                           proc far
     push       bp                      ;       Standard preamble
     mov        bp, sp                  
     push       ds                      
     push       es                      
     push       di                      
     push       si                      
;                               
;-- First check if we can start a transmit now.                         
;                               
     call       CheckResources          ;       Adapter specific
     or         ax, ax                  ;       ax=0 then all systems go
     jz         TxOkay                  
;                               
;-- Else we have to queue request.                              
;                               
     call       CopyChain               ;       Copy descriptor, immediate
                                        ;       data, handle, and protocol ID
                                        ;       ss:bp -->TxChain info
     mov        ax, REQUEST_QUEUED                      
     jmp        TxChainExit             ;       Return - xmit deferred
     ;                          
;--   We can send now.                          
;                               
     Call DoTransmit                    ;       Adapter specific
                                        ;       ss:bp-->Txchain info
                                        ;       Returns status of xmit.
;                               
TxChainExit:                            
     pop        si                      
     pop        di                      
     pop        es                      
     pop        ds                      
     pop        bp                      
     ret        TxChainParmSize                 
TransmitChain                           endp

The Interrupt Routine

In large part, the design of the interrupt routine is dictated by the functionality of the adapter. There are, however, certain common sense guidelines to which all drivers should adhere.

The Interrupt Routine should be divided into two major sections. The front end is responsible for time-critical functions that execute during initial processing with the adapter disabled. The back end, while still in interrupt context, handles the less critical tasks after the adapter has been reconditioned to process network traffic. It is recommended that nesting within the Interrupt Routine be kept to a minimum. One invocation of the Interrupt Routine can completely clear the adapter's interrupt queue, efficiently using system resources. If multiple invocations of the Interrupt Routine are allowed to occur, then the potential exists to exhaust finite system resources such as stack space.

A simple, workable methodology, that eliminates Interrupt Routine nesting, gates access to the two portions of the Interrupt Routine based on memory resident flags. On entry the front end Interrupt Routine dismisses the interrupt at the PIC and, while interrupts are disabled, the following code sequence guarantees exclusive access to the Interrupt Routine code. A similar mechanism can be used when the front end handler has completed his critical execution path and is ready to continue the back end processing if necessary.

;                               
;-- Get and set the exclusion flag.                             
;                               
    mov         ax, 1                   
    xchg        al, [Level1Flag]                        
    or          al, al                  
    jnz         IntlExit                        ;       Already running - bail out
;-- Execute front end code                              
;                               
       -                                
       -                                
       -                                
;                               
;-- Front end completed.  Clear semaphore and see                               
;    if tail is running.                                
;                               
     cli                                        ;       Tests must execute disabled
     xor        al, al                  
     xchg   [Level1Flag],       al              ;       Get/Clear level 1
     xchg   [Level2Flag],       al              ;       Get/Set level 2
     or         al, al                  
     jz     ExecLevel2                          ;       Not running - go execute
;                               
IntlExit:                               
if   DOS                                        ;       Restore registers and swap
                                                ;        back to original stack
     popa                               
     pop        es                      
     pop        ds                      
     mov        ss, cs: [savedss]                       
     mov        sp, cs: [savedsp]                       
     iret                               
                                
else                                            ;       OS/2
     ret                                
endif                           
                                
;                               
;-- Execute back end code.                              
;                               
ExecLevel2:                             
if   DOS                                        ;       Swap off of interrupt stack
     popa                               
     pop        es                      
     pop        ds                      
     mov        ss, cs: [savedss]                       
     mov        sp, cs: [savedsp]                       
end                             
     -                          
     -                          
     -                          
     cli                                        ;       Clear until we exit
     mov        [Level2Flag], 0                 
if   DOS                                
     iret                               
else                                            ;       OS/2
     ret

With this technique, at most one iteration of the front end handler and one iteration of the back end handler we be active at any one time

Time-Critical Tasks

On entry to the Interrupt Routine, there are several house-keeping functions that are required for all drivers. When the Interrupt Routine begins execution, interrupts are disabled. Several critical tasks must be performed before re-enabling. The adapter's interrupt should be masked, either at the PIC or at the adapter itself, whichever is more convenient, and an End-of-Interrupt command must be delivered to the PIC to re-enable normal hardware interrupt processing. If running under DOS, the driver must swap to a private interrupt stack. Finally, with the Interrupt Routine secure from recursion, the processor interrupt flag should be set to allow normal system operation.

Changing Mode

Before continuing further along its processing path, the driver must ensure that it is executing in protected mode. This is a requirement if any upcalls to the protocol are to be executed during interrupt handling. The procedure for ascertaining whether or not the Interrupt Routine is running in protected mode and, if necessary, executing the mode switch is given below.

if    OS2                               
      smsw      ax                      ;       Get machine status word
      mov   [ModeSwitch],       ax                      
      shr       ax, 1                   ;       Shift out Protected Mode bit
      jc        InProtMode              ;       Okay
;                               
      mov       dl, RealtoProt          ;       0x2F
      call      dword ptr [DevHelp]                     
      mov       [ModeSwitch], 1                 
;                               
InProtMode:                             
endif

Similarly, during the Interrupt Routine's exit procedure, the processor must be resumed to real mode if a switch has been executed at the driver's request.

;                               
;--  Ready to exit. See if we did mode switch.                          
;                               
if    OS2                               
      xor       al, al                  
      xchg      [ModeSwitch], al                        
      or        al, al                  ;       =0 then no switch
      jz        NoSwitch                        
;                               
      mov       dl, ProttoReal          ;       0x30
      call      dword ptr [DevHelp]                     
;                               
NoSwitch:                               
endif

Receiving Frames

There are two basic mechanisms provided for passing received frames up to the protocol. The choice is based primarily on the type of interface supported by the adapter. For adapters that support shared memory such that the MAC drive has complete visibility to the entire received frame, the ReceiveChain primitive provides the more efficient mechanism for conveying frames to the protocol driver. If, on the other hand, the adapter interfaces via programmed I/O, ReceiveLookahead offers a facility whereby the driver can input a relatively small leading portion of the received frame and advertise it to the protocol driver. Drivers that generally use ReceiveChain may occasionally revert to ReceiveLookahead in situations where adapter memory resources are running low. Both methods are described in more detail below.

ReceiveLookahead and ReceiveChain are both defined as indications, and may be suppressed based on the value of the indication level variable. The level of indication may be manipulated explicitly by the protocol driver via the IndicationOn and IndicationOff MAC entries. Additionally, the MAC explicitly disables indications before calling the protocol driver at an indication entry point. This ensures that the protocol driver will not be interrupted during indication processing by the arrival of another indication. Beside the other arguments passed to the protocol driver during an indication call, the MAC passes the address of a byte location called the IndicateFlag. Before the upcall, the MAC initializes this location with the value 0xFF. During indication processing the protocol driver may clear this location. On return, the MAC examines the value contained in the flag. If it has been cleared, then indications remain disabled. Otherwise, the MAC decrements the value of indication level potentially re-enabling indications.

ReceiveLookahead

The code fragment given below illustrates the sequence required to signal a ReceiveLookahead indication to the protocol driver. If the Protocol accepts the frame, it will call the MAC driver's TransferData entry within the context of the ReceiveLookahead call in order to receive a copy of the frame data.

;                               
;-- Execute a ReceiveLookahead upcall.  The assumption is                               
;     that if we have reached this point indications are                                
;     currently enabled.                                
;                               
      mov       byte ptr [IndicateFlag], -1                     
      inc   byte ptr [IndicationLevel1]                         
      push      [MacId]                 ;       Assigned by ProtMan
      push      [FrameSize]             ;       Total size of frame
      push      [LookAheadLen]          ;       Range of LookAhead
                                        ;       This could be entire frame
      push      ds                      ;       Far ptr to LookAhead buffer
      push      offset LookAheadBuff                    
      push      ds                      ;       Far ptr to action flag
      push      offset IndicateFlag                     
      push      [ProtocolDS]            ;       Obtained during bind
      push      dword ptr [ReceiveLookahead]                    
                                        ;       Address copied during bind
;                               
;-- If the Protocol wants the frame it will call our                            
;    TransferData entry from within the context of this call                            
;                               
      mov       dl [IndicateFlag]                       
                                        ;       On return either 0 or -1
      add       [IndicationLevel, dl                    
      inc       [NeedIndComplete]                       
                                        ;       Remember we need a complete

ReceiveChain

The process path for ReceiveChain is conceptually similar to that used by ReceiveLookahead. ReceiveChain is more appropriately used when the entire frame is available in memory visible to the MAC driver. The indication level is managed similarly for both calls. With ReceiveChain the protocol driver may elect to copy the frame immediately into its space or it may defer the copy and queue the frame for copy and process during back end interrupt processing. If the protocol driver chooses to defer, the MAC driver must maintain the data buffers until they are explicitly released.

;                               
;-- ReceiveChain upcall processing. On entry the                                
;    frame buffers have already been linked to the                              
;   BufDescr.                           
;                               
    mov         byte ptr [IndicateFlag], -1                     
    inc         byte ptr [IndicationLevel]                      
    inc         word ptr [RequestHandle]        ;       Generate a new handle
    push                                
    push        [MacId]                         ;       Assigned by ProtMan
    push        [FrameSize]                     ;       Total size of frame
    push        [RequestHandle]                 ;       Identify this request
    push        ds                              ;       Far ptr to BufDescr
    push        offset RxBufDescr               ;       These are volatile so we
                                                ;       we only need one
    push        ds                              ;       Far ptr to action flag
    push        offset IndicateFlag                     
    push        [ProtocolDS]                    ;       Obtained during bind
    call        dword ptr [ReceiveChain]        ;       Address copied
                                                ;       during bind
    mov     dl, [IndicateFlag]                  ;       On return either 0 or -1
    add         [IndicationLevel], dl                   
    inc         [NeedIndComplete]               ;       Remember that we need a
                                                ;       complete
    cmp         ax, REQUEST_QUEUED              ;       If no --
    jne         ReleaseBuf                      ;       then we can release
    call        QueuedRecv                      ;       Put buffers on a waiting
                                                ;       queue. The unique handle
                                                ;       generated before the
                                                ;       call will be used for ID
                                                ;       during release

Note that a MAC that normally uses ReceiveChain may switch temporarily to ReceiveLookahead if the protocol driver has deferred processing on several frames and the MAC is running low on resources. ReceiveLookahead forces the protocol driver to process or reject the frame synchronously within the context of the call.

Other Tasks

In addition to receive processing, there are several other tasks that the interrupt Interrupt Routine may be called upon to manage. Adapter errors should be monitored and if necessary AdapterCheck status indications may be generated to the protocol driver in response to serious failures. If a transmit completion occurs, the MAC must generate a confirmation to the protocol driver, using the request handle passed with the original TransmitChain. If another frame is queued, a new transmit request can be passed to the adapter.

Only those functions that are time critical should be processed during front end interrupt handling. Whenever possible, work should be deferred until post processing when the adapter is re-enabled. Before exiting its back end interrupt processing, the MAC driver should generate an IndicationComplete upcall to allow the protocol driver to complete any of the processing it has deferred during indication time.

The TransferData Routine

TransferData is used only in conjunction with ReceiveLookahead. It describes a service entry point within the MAC driver that the protocol driver may invoke in order to transfer a received frame into its space. This call is valid only within the context of a ReceiveLookahead upcall from the MAC.

The MAC driver processes the data from the network card into the buffers linked to the TransferData buffer descriptor. The actual method of interface, DMA, programmed I/O, etc., is specific to the adapter. The process completes until either the entire frame has been transferred or until the protocol driver's buffers have been completely filled. In either case, the actual number of bytes copied is returned to the protocol driver in the location pointed to by the BytesCopied argument.

Depending on the hardware, the MAC may be able to support multiple calls to TransferData within the context of a single ReceiveLookahead upcall. If at all possible, the MAC should support this feature to allow for the case where multiple protocols are bound, via Vector, to a single MAC.

The ReceiveRelease Routine

ReceiveRelease is a MAC entry point called by the protocol driver when a ReceiveChain indication has been deferred. The protocol driver must remember the handle passed with the original ReceiveChain upcall and pass it back to the MAC. The handle is used to uniquely identify the buffers that are to be released.

The General Request Routines

The General Requests provide the protocol driver with the ability to perform adapter administration operations. All of the requests are handled via a single entry point. Specific operations are demultiplexed by the MAC via a function code parameter.

The MAC may choose to either handle the requests synchronously or to queue the request for later processing. If the request is deferred, the MAC must remember the handle and protocol ID passed with the call to be used later when the request is confirmed.

Notices

January, 1996

Issued by:

IBM Corporation
Personal Software Products
11400 Burnet Road
Austin, Texas 78758

Second Edition (January 1996)

First Edition (May 1993)

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

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

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

Copyright Notices

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

Disclaimers

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

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

Trademarks

The following terms are trademarks of the International Business Machine Company:

IBM OS/2

The following terms are trademarks of the indicated companies:

Microsoft Microsoft Corporation

LAN Manager Microsoft Corporation

3Com 3Com Corporation

The performance that is important to focus on for an NDIS MAC device driver is the performance that the communications users see. Communications users are most sensitive to the time it takes to send their data across the communications network. From the performance point of view this suggests that we focus on making the data flow paths as fast as possible for any quantity of data. Accomplishing fast data transfer requires analysis of three areas:

fast data flow between the device driver and the protocol stack
fast data flow through the device driver
fast data flow between the device driver and the adapter card.

In addition to minimizing the latency of the data flow paths, minimizing the CPU utilization of the NDIS MAC device driver is also important. Optimizing CPU utilization is necessary in servers, since the performance of the server is often a bottleneck in client-server transactions.

The performance of the NDIS MAC device driver itself is important as well as how it interfaces with the rest of the hardware and software system.

This document:

explains the key measures used in evaluating NDIS MAC device driver performance
discusses overall design considerations
identifies NDIS verbs of particular performance importance
discusses interrupt processing
discusses OS/2 system usage
discusses programming practices.

This information may help NDIS MAC device driver creators understand the performance effects of the many choices available to them and result in better performing NDIS MAC device drivers.

Performance Criteria

Performance for a NDIS MAC device driver is evaluated by three quantities: latency, throughput and system processor utilization. Latency is a measure of how fast the transport can put data on, or get data off, the communication medium. Latency can be broken down into transmit latency and receive latency. Latency is often measured by the time used to send and receive a few bytes of data. Smaller latency is better.

Throughput is a measure of how well data can be kept flowing on to or off of the communication medium. Throughput is measured in units of work per unit time. The amount of data used in throughput evaluation is large so that the effects of data handling and buffer management are apparent. For communications applications, throughput is often measured in units of bytes per second, or units of frames per second (for a range of frame sizes). Larger throughput is better.

Finally, system processor utilization shows how much of the system processor is used for flowing data in a throughput environment. Smaller system processor utilization is better.

End users are interested in the performance of the entire communications stack. It is important to run the device driver with different protocol stacks and see how each protocol stack uses the device driver. We recommend using the IBM NetBIOS and IBM 802.2 protocol stacks.

In order to focus on NDIS MAC device driver performance independently of other communication media traffic, performance measurements should be made on an isolated communication network.

Good system performance is the real end goal. NDIS MAC device driver performance is one component of communication system performance. System needs or bottlenecks may suggest the best tuning for communication system components to achieve the best system performance. For example a system that depends on fast communication is likely to need the best latency and throughput. However a system that has big CPU demands and little communication may run best when communication system parameters are tuned for least CPU utilization. NDIS MAC device drivers need to perform well across the spectrum of communication system tuning.

Performance Issues In NDIS MAC Device Driver Design

The performance of an NDIS MAC device driver is a key determinant in communications performance and is often a major factor in overall system performance. Consequently, considerable effort should be expended to ensure that each NDIS MAC device driver is high performing. In this section, we discuss overall design issues which affect the performance of an NDIS MAC device driver.

First, though, one must keep in mind that the recommendations in this document are general in nature. Each of the recommendations in this document has been implemented in an NDIS MAC device driver and has been shown to improve its performance. However, the specifics of the adapter play a large role in determining how effective these suggestions will be in improving performance. These specifics include the communications medium to which the adapter interfaces, the hardware design of the adapter, and the software interface specification by which the MAC device driver talks to the adapter. How much each contributing factor affects performance varies from adapter to adapter. The key point is that it is crucial to understand in detail the adapter's design and specifications.

The first NDIS MAC device driver design issue is related to multiple adapter support. If multiple adapters which use the same MAC driver can be present in a single machine, then there are two basic design choices:

up a single device driver model
use the multiple device driver model i.e., load a copy of the device driver for each adapter.

The single device driver model is strongly recommended for best performance. It avoids two key drawbacks of the multiple driver model: one, the extra RAM used by multiple instantiations of the code segment; and, two, the need for process and/or context switches to change from servicing one adapter to servicing a different adapter. Using the single device driver model, there would be one code segment operating on multiple data segments, one for each adapter. To move from servicing one adapter to servicing another now requires only a segment register load. Segment register loads are considerably less expensive than (operating system dependent) context switches. Note also that in the default case of a single adapter in a machine, the single device driver model will be the same as the multiple device driver model.

If one adopts the single device driver model, then that device driver is responsible for ensuring that service to each adapter is fair. Fairness is provided by selecting the first adapter to check for a pending interrupt in a round robin order. After that, all work is done for each adapter before proceeding to the next adapter. This ensures that the processing will be interwoven for all adapters. When the device driver is entered, all interrupts for all adapters handled by that device driver should be masked. We note that fairness must be ensured both when multiple adapters present interrupts at the same time and when the processing for one adapter is completed before deciding whether or not to return control to the operating system. In particular, before returning control to the operating system, all adapters should be checked for additional work.

After fairness of service among adapters is ensured, two issues of fairness in the processing of work for a single adapter must be addressed. The first fairness issue relates to how the MAC driver learns of adapter events which require service. Either the adapter will notify the MAC driver via interrupt or the MAC driver will find out by checking the adapter's status. This issue will be revisited in the Interrupt Processing section. The basic idea is that once the interrupt handler is in control through an interrupt driven event, further interrupts from the adapter should be masked until all worked discoverable by checking adapter status has been completed. Each particular NDIS MAC device driver must decide for itself how to balance its own interrupt driven and adapter status checking natures.

The second fairness issue deals with the balance of processing between transmit and receive work. The balance that the device driver must strive to maintain is between keeping the adapter as busy as possible with data to be transmitted and keeping the protocol as busy as possible processing data that has been received.

This balance depends on whether the software interface to the adapter is via shared RAM or via direct memory access (DMA). For adapters which use DMA, the corresponding NDIS MAC device driver may have to allocate its own receive buffers into which the adapter will DMA received data. These buffers will become critical resources and may turn into performance bottlenecks if not handled properly.

Two key adapter events to which the MAC driver must give priority are the processing of receive frames and the completion of previously transmitted frames. Processing receive frames quickly improves protocol responsiveness and frees receive buffers for the next incoming frame. Early detection of the completion of previously transmitted frames keeps the adapter busy transmitting additional frames. This happens because the MAC driver can pass additional data to the adapter once it determines that a previous transmit request has been fulfilled. MAC driver handling of these two key events is dependent upon the software interface to the adapter.

The design of NDIS lends itself particularly well to the use of scatter lists on the receive path and gather lists on the transmit path. If the adapter supports such lists, then the high performing NDIS MAC device driver must take advantage of them. Doing so will eliminate the need to copy segmented, and possibly physically dispersed, frames into separate, contiguous, MAC allocated buffer space. The performance gains using this approach are clear:

fewer data copies and, hence, reduced CPU utilization
smaller data segments
less data buffer manipulation.

Finally, each procedure in an NDIS MAC device driver should be coded as efficiently as possible. Efficient coding translates directly into improved performance by reducing CPU usage. In addition, the device driver should take advantage of any special adapter capabilities which could optimize performance. An example of such a capability would be an adapter that allows the device driver to begin handling the start of received data before the entire transmission is received.

The next two sections, Performance Important NDIS Verbs and Interrupt Processing, describe two areas where special attention must be focused to produce a high performing driver. The sections System Service Usage and Programming Practices provide suggestions which should be followed throughout in the implementation of an NDIS MAC device driver.

Performance Important NDIS Verbs

An NDIS MAC device driver is responsible for supporting a large number of NDIS primitives. However, only those primitives in the 'Direct Primitives' class directly affect critical path transmit and receive performance. Primitives in the other three classes: 'General Requests', 'System Requests', and 'Protocol Manager Primitives' do not usually occur on performance critical paths. While developers should strive to implement each piece of code efficiently, special attention must be paid in coding 'Direct Primitives'.

The primitives which most affect critical path transmit and receive performance are part of the protocol to MAC interface described in Chapter 3 of the NDIS Specification. These primitives are:

Transmit Chain
TransferData

and, to a lesser extent, the remaining 'Direct Primitives':

TransmitConfirm
ReceiveRelease
ReceiveLookAhead
ReceiveChain
IndicationOn
IndicationOff
IndicationComplete

For DOS NDIS MAC device drivers, the InterruptRequest primitive must be supported, else the performance of protocol drivers (including the DOS LAN Support Program) will be severely degraded.

The two methods of handling received data merit some discussion. ReceiveChain should be used if all the data received is system addressable when the MAC device driver gets the interrupt. ReceiveLookAhead should be used if either of two conditions hold. First, ReceiveLookAhead should be used if not all of the data is system addressable when the MAC device driver is interrupted. In this case, the data will need to be copied and this is a situation ReceiveLookAhead and the associated TransferData handle well. Second, ReceiveLookAhead should be used if not all the data has been received by the adapter when the interrupt is raised. In this case, protocol drivers may inspect and process the head of the frame without waiting for the entire frame to be received.

MAC driver processing in support of the MAC to adapter interface is also crucial for best critical path performance and will be discussed in the next section, Interrupt Processing. Since much of the processing of direct primitives involves interrupt processing, these two sections are necessarily interrelated.

TransmitChain

TransmitChain is the NDIS primitive used by protocols to transmit data. The protocol passes a transmit buffer descriptor consisting of a pointer to up to 64 bytes of immediate data and a list of data blocks. Each data block contains a pointer to up to 64 kilobytes of data. The key to a high performing implementation of TransmitChain is to pass the data to the adapter as quickly as possible. The actual details will vary with the adapter's software interface, but certain ideas are common to all adapters. The key idea is to eliminate any activities on this critical path which could be done in advance, either in initialization or during other non-critical path processing. Hence, any device driver data areas should be allocated in advance, probably during initialization. The immediate data, which must be copied to device driver buffer space, should be copied using a double word copy. Additionally, the destination buffer for the immediate data should be double word aligned. The number of transmission commands to the adapter should be minimized, though achieving this goal is adapter dependent. There is a performance benefit when several TransmitChains in a row are issued to the MAC driver. Finally, as mentioned in the previous section, high priority must be given to detecting previously submitted frames have been transmitted. If this check is made, then these TransmitConfirms for these frames can be issued directly within the TransmitChain path.

The NDIS specification also provides a performance recommendation for TransmitChain. In the introduction to Chapter 5 of 3Com/Microsoft LAN Manager Network Driver Interface Specification, the following can be found. "It is recommended that a MAC release the internal resources associated with either TransmitChain or a request before calling the confirmation handler. This allows the protocol to submit a new TransmitChain or request from the confirmation handler. Failure to do so may have a significant impact on performance."

TransferData

The TransferData primitive is issued by the protocol to the MAC device driver during a ReceiveLookAhead. The protocol asks the MAC device driver to copy the received data into the buffer spaces specified in a list of data blocks. The key to this routine is setting up the source and destination selectors and deciding how much data to copy. This process may be repeated many times depending upon how many data buffers the received data is stored in and how many buffers it is being transferred to. Each copy should be done using a double word copy. If the received data is in device driver buffers, then they should be double word aligned for fastest copy time. Tied in with these techniques is a suggestion for use in the ReceiveLookAhead routine, which will occur on interrupt. The lookahead buffer that is passed to the protocol should be the actual buffer into which the adapter has placed the data. The idea is to avoid allocating separate lookahead data buffers and the subsequent need to copy data into them. Further, in this method the lookahead buffer can potentially contain the entire frame, eliminating the need for the protocol to issue a TransferData primitive call.

TransmitConfirm

The TransmitConfirm primitive is issued by the MAC device driver to the protocol to indicate completion of a previous TransmitChain. This call serves an important function as an asynchronous indication to the protocol that the MAC device driver is ready to process additional transmit requests. A possible pitfall in NDIS MAC device driver design is to try to eliminate the need for TransmitConfirm calls. This can the done by returning 'success' to the protocol upon TransmitChain. This approach seemingly saves MAC device driver to protocol interactions. However, it may backfire in the following manner. Since the MAC device driver is actually queuing transmit requests internally and not completing them, when it runs out of transmit resources it will be forced to return 'out_of_resource'. This, in turn, will force the protocol to poll the MAC device driver to find out when resources are available again. The protocol must poll since no asynchronous indication, i.e. TransmitConfirm, will be forthcoming from the MAC device driver. Choosing the right polling interval is an intractable problem. If the interval chosen is too short, too much CPU is utilized. If the interval chosen is too long, the protocol will lose synchronization with the MAC device driver and not be passing it data as often as it could. Either way, serious throughput and overall performance degradation may occur. As a result, we strongly recommend that NDIS MAC device drivers use the TransmitConfirm primitive.

Interrupt Processing

The interrupt routine is critical to NDIS MAC device driver performance. Any excessive time spent in the interrupt handler can adversely affect performance. The two goals for an efficient interrupt handler are to minimize the number of interrupts (i.e. the number of times the operating system calls the interrupt handler) and to minimize the time spent processing each interrupt.

The two most common reasons for entering the interrupt routine are the "reception of data and notification of a completed transmission. Adapters may also interrupt the device driver if needed system resources, such as buffer space for DMA, have been depleted. NDIS primitives which the MAC device driver may issue to the protocol on interrupt include TransmitConfirm, ReceiveLookAhead, ReceiveChain, and StatusIndication. The IndicationComplete may be issued on interrupt when running OS/2, but not when running DOS.

There are a few general performance guidelines for efficient interrupt processing. We list them here and then conclude this section with several more specific suggestions for improving performance. The interrupt handler is a time critical routine in and of itself. Interrupts should not remain masked for more than approximately 500 microseconds. This means that the End of Interrupt should be issued to the interrupt controller within 500 microseconds of entry into the device driver's interrupt handler. The MAC driver interrupt handler must perform the following actions before issuing the end of interrupt:

determining if the interrupt is for this MAC driver
masking the adapter to prevent further interrupts
reading any adapter unique status which may be overwritten, and hence lost, due to subsequent events.

Only useful and necessary processing should take place on interrupt. Necessary processing includes time critical adapter interfacing, such as rearming the adapter. In addition, to reduce the overhead inherent in processing interrupts, the interrupt handler should check for additional work before exiting. This decreases latency and reduces CPU utilization by lessening costly context switches back to the operating system.

As mentioned above in the Performance Issues in NDIS MAC Device Driver Design section, the interrupt handler must balance processing efficiently with the need to detect higher priority work. Once the interrupt handler is in control through an interrupt driven event, further interrupts from the adapter should be masked until all work discoverable by checking adapter status has been completed. This will minimize kernel interrupt processing overhead.

The interrupt handler must also balance its processing between handling transmit completes and handling received data. As indicated previously, the balance that must be maintained between keeping the adapter as busy as possible with data to be transmitted and keeping the protocol as busy as possible processing received data. One way to achieve this balance is to limit the number of transmit completes to process before checking for higher priority interrupt and receive frame processing.

OS/2 System Service Usage

Device drivers need to use OS/2 system services to access functions such as memory allocation and address translations. The high performing NDIS MAC device driver will need to limit the use of OS/2 system services, particularly on the critical transmit and receive paths. A discussion of these critical paths can be found in the previous two sections of this document. Limiting operating system usage to only necessary calls will both reduce path length and lessen CPU utilization. One way this may be achieved is to save useful results obtained via system calls, eliminating the need to repeat the call later. Address translations are a good example of calls to which this technique applies.

One specific piece of advice relating to use of system services comes from the OS/2 device driver reference manuals. It is stated there that a device driver strategy routine should be prepared to yield the CPU about every 3 milliseconds. Limiting system service call will help ensure adherence to this rule.

Programming Practices

This document has detailed a number of ideas which improve the performance of NDIS MAC device drivers. However, the fundamental method for producing high performing code is writing efficient code. In that sense, the tips and techniques which we will summarize in this section underlie every other section of this guide.

The ideas in this section all fall under the general heading of code tuning. The goals of code tuning are to:

decrease the number of processor cycles required by program
decrease the number of address calculations performed
decrease the number of memory fetches
decrease the size of object code.

The major way to eliminate address calculations and memory fetches is by alignment. With the Intel 80386 and successor architectures, the normal memory fetch is for a double word (four eight bit bytes) of data, aligned on a double word boundary. Hence, proper alignment of any memory will optimize fetch performance, while misalignment will degrade performance. The only exceptions to this rule are possible overrides by the memory management system of the processor for devices whose bus access is fewer than 32 bits wide. Even for those devices, access will almost surely be at a word granularity and following double word alignment guidelines would not degrade performance.

The most important items to align are data structures. The rules to follow are:

align the data structure on a double word boundary. This means that the starting (physical) address of the structure should be on a four byte boundary.
elements of the data structure containing four or more bytes should be started on double word boundaries.
elements of the data structure containing fewer than four bytes should not cross double word boundaries.

Achieving alignment for each element in a data structure may require reordering the elements and the addition of null elements.

Code itself may also be aligned. The most important instructions to align are the targets of jump instructions. These instructions may be double word aligned by using an assembler directive which will automatically generate any needed null, aligning, instructions.

Data copying is one of the most CPU intensive operations. The time to copy data depends upon three factors: the granularity of the move instruction (byte, word or double word), the alignment of the source buffer and the alignment of the target buffer. The fastest copy time is achieved when both buffers are double word aligned, and the double word move instruction (REP MOVSD) is used. If either buffer is not double word aligned, the following technique produces an efficient string move routine. First, copy up to three bytes until the destination address is double word aligned. Second, copy the remaining bytes using the double word string copy instruction. Use of the double word copy move instruction ensures the smallest overhead for data transfer.

Two other suggestions may also help speed up code execution. The first is to order tests so that jumps are to the least likely cases. This ensures that the less costly fan through case (no jump) is to the most likely case. This also assumes that the code can be structured so that there is no jump instruction at the end of the code for the most likely case. It may be difficult to structure the code in this manner. The second suggestion is to take advantage of the 32 bit nature of the Intel 80386 (and successor) chips. One major advantage of the 80386 architecture over the 80286 architecture is the inclusion of too additional segment registers. Careful use of these registers will eliminate unnecessary and costly segment register loads. The additional high order word provided in each general purpose registers may also be used to lessen accesses to secondary memory.

We conclude this section by summarizing a number of the points made in an invaluable book. The book is "Writing Efficient Programs" by Jon Louis Bentley (1982, Prentice-Hall). The rules in the book are general in nature and their indiscriminate application is strongly discouraged. In addition, always keep in mind that the efficiency of a program is secondary to its correctness. Once again, there are two main areas where modifications may improve the efficiency of a program: in the data structures and in the code.

Data structures can be either modified or completely replaced. The latter approach is a system design issue and is not germane to the current discussion. Simple modifications to data structures can help reduce a program's time and/or space. Bentley suggests four methods for trading off more space for less time.

Data Structure Augmentation This refers to either adding additional information in the structure to or to changing the structure so its components can be accessed more easily. Data structure alignment, discussed above, is an example of this method.
Store Precomputed Results This should be done to save the cost of recomputing an expensive function. Storage of results of OS/2 system service calls fall into this category.
Caching Data that is accessed most often should be cheapest to access. Proper use of the two extra segment registers found in the 80386 chip, as opposed to only using 80286 registers, would be an example of this rule.
Lazy Evaluation This idea is to only evaluate expressions when necessary, thereby avoiding unneeded work.

It is possible to speed up small pieces of code by making local transformations. These changes fall into four general categories: loops, logic, procedures, and expressions. The referenced book contains a clear and concise discussion of rules to apply in these categories; we shall not repeat it here. Rather, we close by listing four fundamental rules which underlie all of the suggestions for writing efficient programs. These fundamental rules are (excerpted from pages 104 and 105 of Bentley):

Code Simplification Most fast programs are simple. Therefore keep code simple to make it faster.
Problem Simplification To increase the efficiency of a program, simplify the problem it solves.
Relentless Suspicion Question the necessity of each instruction in a time-critical piece of code and each field in a space-critical data structure.
Early Binding Move work forward in time. Specifically, do work now just once in hopes of avoiding doing it many times later.

Notices

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

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

Disclaimers

References in this publication 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 IBM's intellectual property rights or other legally protectible rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility.

IBM may have patents or pending patent applications covering subject matter in 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.

[[[#Disclaimers|previous]]][[[#Notices|parent]]][[[#toc|TOC]]]

Trademarks

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

IBM

OS/2

Extended Services

The following terms, denoted by a double asterisk (**) in this publication, are trademarks of other companies as follows:

Microsoft	Microsoft Corporation
3Com	3Com Corporation
CompuServe	CompuServe Incorporated

All other company, brand, and product names are trademarks or registered trademarks of their respective owners.

NDIS Driver Developer's Tool Kit
For OS/2 and DOS
Random Redirected Transform Test User's Manual

Preface

Purpose of this Manual

This document is the user manual for the Random Redirected Transfer Test Tool (hereafter referred to as RRTT). All of the functions and features available with RRTT are described here in detail.

Prerequisite Knowledge

Although no previous knowledge is required to exercise an RRTT session, the information in this manual is intended for the experienced programmer who is involved in the development of NDIS drivers. The reader should have an understanding of the procedures needed to meaningfully test a network driver.

Chapter 1. Introduction

Overview

RRTT provides a means of verifying a network's file transfer integrity. It resides as a top-level application package capable of transferring files of various size and content to the network nodes of your choice. RRTT is generally used after the TestTool application (also supplied with the NDIS Driver Developer's Tool Kit) has thoroughly demonstrated your development driver's functionality.

RRTT uses a bi-directional copy and compare sequence to verify proper file transfers. As many as 100 unique session may be simultaneously active on one network.

Software Installation

RRTT is a stand alone application requiring no network specific installation.

System Requirements

RRTT can run under either DOS or OS/2*. The minimum hardware configuration is two AT or PS/2 or compatible PCs with at least 640 KB of RAM, either a monochrome or color monitor, a hard drive of at least 10 MB or larger capacity, and a LAN Adapter card. The LAN Adapter card may reside in either one or both of these machines.

Chapter 2. Using RRTT

The RRTT utility uses script files and/or a User Interface to configure and execute file transfer tests. This chapter will, by way of example, describe how to navigate the straight forward User Interface, run a simple test, and change default User Options. Script files will then be explained which can further simplify testing procedures.

User Interface

Part of the User Interface for RRTT is menu driven and part is command driven. At the top of the screen is a Menu Bar, enabling the user to display one or more of the User Options or receive help. Additionally, some status indications are displayed at the right of the Menu Bar. Underneath the Menu Bar is the Information Screen which holds all of RRTTs user option settings. There is a different screen for each entry on the Menu Bar. Below the Information Screen is a Command Line used for entering commands. The bottom half of the screen is a Monitor Screen used for displaying test progress. See Figure 2-1.

File:Images/ndisrrt1.gif

There are several keys which manipulate RRTTs user interface.

The <F10> key moves the cursor off the command line and down into the Monitor Screen. Once there, the up and down arrow keys can be used to scroll through the 50 lines of history information. The <F10> key is a toggle. When the cursor key is in the message area, the <F10> key will move the cursor back up tot he command line.

The <Up> and <Down> arrow keys scroll up and down the command line history. This allows previous commands to be edited and/or repeated. If the cursor is currently in the Monitor Screen (due to an <F10>, then the up/down arrow keys scroll through the screen's history and not through the command line history. An <F10> will restore the cursor to the command line and the arrow keys will again scroll through the command history.

The <Left> and <Right> arrow keys move the cursor left and right within the current command line.

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

The <TAB>and <Shift><TAB> keys will move the menu bar tot he next information screen. <TAB> moves the menu to the right while <Shift><TAB> moves the menu to the left.

The <Alt> key jumps to one of the Menu Bar items. Each of the menu items has a letter which is highlighted. When the <Alt> key is pressed with one of the highlighted letters, that Information Screen pops up. This method is not available while a test is running.

Information Screens

The Information Screens, selected by the Menu Bar, display all of the various User Options available for configuring an RRTT session. Using the interface keys described above, each of the parameters chosen can be displayed. In addition, a General Information Screen is available for monitoring overall test information while an RRTT test is running.

Help Screen

Help screens are available by entering the ? Or HELP command. A list of all the RRTT commands accompanied by a description of their usage is displayed. The up/down arrows allow for scrolling through the command list. Upon selecting the command of interest, you may type <ENTER> to automatically type that command onto the command line. To exit this help screen without having the command entered into the command line type <ESC>. In either case, RRTT will return to its previously displayed menu.

Testing with RRTT

RRTT has several User Options that can be adjusted by the user. These options come with reasonable default settings and only a few may require your attention. As an introduction to RRTT, the default settings for the User Options are acceptable. To run RRTT requires only that one or more destination drives be selected. You may wish to use your hard drive for initial running as a reality test for RRTT. The DRIVE command followed by a list of drives and/or network nodes can be achieved as follows.

         >DR C:

Any additional names should be separated by at least one space. To activate a test type RUN. At this point RRTT will begin running a copy and compare sequence to each of the destinations chosen. The default settings will cause RRTT to generate a dummy file of random size and contents. The file will be transferred to and received from the root directory of drive C: To observe the test in progress, display the General screen as noted on the menu bar. Test duration, average transfer times, and test iterations are all present with this screen.

The User Interface is altered slightly while a test is running. Figure 2-2 shows the layout when the General Information Screen is displayed.

File:Images/ndisrrt2.gif

Figure 2-2: RRTT Test Display

In the particular run shown here, a log file is active and denoted by the L in the upper right hand corner of the interface. The test start time and current time are displayed along with the operating system being run and the session number currently set. The drive chosen is \\server1\root and is shown on the General Information Screen as well as the Monitor Screen. The General screen keeps track of test execution with an average drive performance number in Kbytes per second. These are separate for transmit and receive and are denoted by Xmt Kb/ s and Rcv Kb/s respectively. The total number of bytes sent over the network is displayed for each destination drive along with any errors that have occurred.

During execution the command line is no longer at the user's disposal, instead the current state for the test is displayed. The test iteration count along with the operation under way are reported to this field. There are five tasks that RRTT may be executing during a test session: create, transfer, receive, compare, or report. Create is displayed while RRTT builds the next dummy transfer file. Transfer is displayed while RRTT builds the next dummy file from the destination drive. Receive is displayed while RRTT receives the dummy file from the destination. Compare is displayed each time RRTT compares files. This happens twice per destination, once after a transmit and once after a receive. Report is displayed only briefly while test reports are generated.

The Monitor Screen monitors operations during an RRTT session. Information, such as successful command execution and instantaneous test results, is tracked on this screen. The amount of information displayed may be adjusted by the MMODE command prior to starting a test. Figure 2-2 shows how the Monitor Screen looks in VERBOSE mode. The destination under test, the file size used, the block size used, and the block delay time used are all reported to the Monitor. The success or failure of each copy/compare sequence follows the transfer parameters along with transfer times in Kbytes per second. This sequence repeats for each test iteration.

Once an execution is under way, there are a different set of commands used to control program flow. These options are one letter commands displayed in square brackets on the right of the command line. The two basic commands used during run are <F10> and S.

To pause the RRTT test type <F10>. Upon completion of its current task, RRTT will toggle to the Monitor Screen and allow scrolling through past message lines. Typing a second <F10> will resume the copy and compare sequence.

To stop the test type S, which will return you to the command line interface. Another test may be run using the RUN command or the session may be exited by typing EXIT.

This is all that is required to run RRTT utility. Tailoring RRTTs file transfer parameters and test report modes is available from the command line or from script.

Changing User Options

Each User Option has a unique command string and may be altered by the user. Each option is explained in the help text displayed with the ? Or HELP command For most commands, only the first two letters need to be typed. The same two letters are displayed on the various Information Screens in square brackets along with its current setting. Some of the commands require a range or mode parameter. Here some of the basic commands will be described by example, leaving the more complete explanation for the Command Description Chapter.

The most common User Options to vary are the transfer file contents, the transfer file size, the block transfer size, and the block delay time. These variables control, to a great extent, how a network driver is being exercised. The following four commands demonstrate one way to set their parameters:

         >FPATTERN RAN 0X00 0X60

         >FSIZE INC 1 10000

         >BSIZE RAN 100 2000

         >BDELAY 100

FPATTERN STANDS FOR "file pattern" and changes the contents of the dummy transfer file to be a sequence of random numbers between 0x00 and 0x60. The string RAN is used to direct FPATTERN to use a random range. The Information Screen labeled File displays the current setting. After this command is entered, the values are displayed in square brackets to indicate a range of numbers.

FSIZE stands for "file size" and changes the size of the dummy transfer file. Here, RRTT is directed to increment the file size by one byte but not to exceed 10000 bytes. The file size changes once per pass. In this configuration, after 10000 test iterations, each file size will have been covered and the sequence will start over with a file size of one byte.

BSIZE is the command to alter the "block size" used in transferring a file. This command will set the block size generator to use sizes randomly between 100 bytes and 20000 bytes. Only one size is used per pass. Note that for some test iterations, the block size will be larger than the file size. The block sizes actually used will be the smaller of the two sizes and a true random range for block size will not be accomplished for every pass. It is the user's responsibility to avoid or at least be aware of this type of limit conflict.

BDELAY is the command to alter the "block delay time" used between individual block transfers. In this example, the delay time between each block transfer will be a fixed 100 milliseconds. The corresponding display for block delay time is found, along with block size, on the Transfer Information Screen.

At this point a copy and compare session may be inititiated with the RUN command and the above parameters will be incorporated. To return to the command's default values, use the RESET command, which resets all the User Options including the ones set above.

Changing Report Mode

RRTT is capable of generating reports for the Monitor Screen, a log file, or a printer. There are a few User Options that allow variations on the reports produced. The MMODE (monitor mode), the LMODE (log mode), and PMODE (printer mode) are the commands used. The most common report mode to alter is the log report.

         >LMODE SILENT

This command will turn the log file on and reduce its output from the default setting of TERSE to SILENT. Only the first three letters of SILENT needed to be entered. In this mode only error encountered will be entered into the log file. A red letter L is registered in the upper right-hand corner of the screen, indicating that a log file is being produced. If a log file already existed, then new information will be appended to it. The Information Screen labelled Report shows the mode settings for the log file.

Using Script Files

Script files give RRTT as much flexibility as needed for performing lengthy top-level network tests. A script file, which is an ASCII text file containing RRTT commands, may be entered while invoking RRTT, in which case no User Interface will appear. Instead, all the commands in the file will be automatically executed.

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. The JUMP command is described in detail in the command description portion of this manual.

Below is an example of an ASCII script file. You can generate this script file by entering these lines into a file using a text editor.

         # use file sizes randomly between 10000 and max
         FSIZE RAN 10000
         # turn off block delay
         BDELAY OFF
         # report all activity to a log file
         LMODE VERBOSE
         # erase any old log information
         LMODE RESET
         # repeat this test 2 times then stop
         TREPEAT 2
         # set a destination for testing
         DRIVE
         # run the test
         RUN

To run a script file from RRTTs command line type:

        
        >SCRIPT script_file_name

This same script file could also be entered on the command line as follows:

        [C:\]RRTT script-file-name

By invoking RRTT with a script file, the user interface is never engaged, and the Monitor Screen prints test progress to standard output.

User Command Lists

The User commands available by RRTT are divided into three categories: Static User Options, Executable User Options, and Run Time User Commands. Each specific command under one of these categories is listed here for a quick reference and described in detail in subsequent chapters.

Static User Options

Static User Options are commands that allow the user to configure the RRTT test as desired. They do not perform any action other than establish a parameter to be used during the next test execution.

The following are the Static User Options. These commands set various values that will be used during an RRTT test.

NAME	DESCRIPTION
`BDelay`	Set the block delay for file transfers
`BInter`	Turn on/off block transfer interleaving
`BSize`	Set the block size for file transfers
`DRive`	Set destination drive for testing
`ERror`	Set number of errors before test abort
`FDelay`	Set the file delay time between transfers
`FName`	Set the transfer file name if user defined
`FPattern`	Set the file contents to a specific pattern
`FRepeat`	Set the file repeat count per test pass
`FSize`	Set the transfer file size
`LMode`	Turn on/off log and set log report mode
`LName`	Change default log file name
`MMode`	Set Monitor Screen report mode
`PAusecopy`	Pause the test prior to comparing a file
`PMode`	Set printer report mode
`SEssion`	Set a unique session number
`TRepeat`	Set the number of test iterations

Executable User Options

The following are the Executable User Options. These commands are not displayed on any of the Information Screens. They perform tasks that require some type of execution.

NAME	DESCRIPTION
`HELP or ?`	Display on-line help screens
`EXit`	Exit the application
`LComment`	Write a comment into the log file
`LOAD`	Load a configuration file
`QUit`	Exit the application
`REset`	Reset all the User Options
`RUN`	Run a test
`SAve`	Save the current configuration
`SCRIPT`	Execute a script file from within the UI

Run Time User Commands

The following are the Run Time User Commands. These are the set of commands that are used during a test. Each takes effect after RRTT completes its current operation.

NAME	DESCRIPTION
`S`	Stop current test
`X`	Exit application
`F10`	Pause test and toggle to Monitor Screen
`TAB`	Move to next Information Screen

Each of these commands is described in detail in the Command Description Chapter of this manual.

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 field displays the command name with a brief label denoting its function.
Syntax	The Syntax section gives the format of the command and the type of operands allowed. The capitalized portion of the command must be typed while the lower case portion of the command may be left off. For example the command FSize may be abbreviated to FS. Operands enclosed in square brackets "[]" are option and only one operand in a list enclosed with arrow brackets "<>" may be used. In many cases if a parameter is left out, the default minimum or maximum is used. Numerical operands may be entered as hexadecimal as well as decimal. If a numeric parameter has a preceding 0x, then it is read as hexadecimal. The default interpretation is decimal. There are a few exceptions to this rule where noted. Some commands except the qualifying strings INCREMENT or RANDOM, which determine how to interpret the following hexadecimal or decimal values. Many commands accept the RESET, DEFAULT, VERBOSE, TERSE, SILENT, ON, and OFF strings. All of these strings require only that their first three characters be typed. The meaning of each string is explained in each command description.
Description	The Description section describes what the command does and how its operands are interpreted. It may also contain a usage suggestion when appropriate.
Example	The Example section gives one or more example of the command usage. The ">" preceding each command denotes the command line prompt and is not typed.
Limits	DEFAULT: This field indicates the default settings for the command. N/A is used for Not Applicable. MIN: This field indicates the minimum allowable value for the command. N/A is used for Not Applicable. MAX: This field indicates the maximum allowable value for the command. N/A is used for Not Applicable.

BDELAY - block delay time

Syntax BDelay [<DEF, INC, OFF, RAN, RES>] ms_time [max_time]

Description

BDELAY, displayed on the Transfer Information Screen, sets the delay time used after each individual block of data is transferred. The time is accepted in milliseconds, ranging from 0 to 1000 milliseconds. In addition to accepting a fixed time, this command may be entered with one of the following operand strings: DEF, INC, OFF, RAN or RES.

DEF (short for DEFAULT) may be used to return the settings back to their default values. No other values are accepted for this string.

INC (short for INCREMENT) directs RRTT to increase the delay time by a fixed step size for each new test pass. The first parameter (separated from INC by a space) is interpreted as the step size. If a second value is entered it is interpreted as the maximum size to use before repeating the sequence. The first step of an INCREMENT sequence is the command's minimum acceptable value. If no maximum is supplied then the maximum acceptable value is used.

The OFF string turns the block delay time off which is equivalent to setting the delay time to zero.

RAN (short for RANDOM) directs RRTT to use random numbers between the minimum and maximum supplied on the command line. The first value after the RAN string is the minimum random number. The second value is the maximum value. If the maximum or both values are left blank then the default minimum and maximum values are used.

RES (short for RESET) functions the same as the DEFAULT string and returns the command's parameters back to their original settings.

Example

>BD RAN 30 90

Sets the block delay time to be a random value between 30 and 90 milliseconds.

BINTER - turn on/off block interleaving

Syntax	`BInter <DEF, OFF, ON, RES>`
Description	Block Interleave, displayed on the Transfer Information Screen, turns on and off drive interleaving during a file transfer. If more than one destination is active and there is more than one block of data to transfer per file, the BInter will transfer one block of data to each destination before proceeding to the next block.
Example	`>BI ON` Turns on the interleave capability.
Limits	DEFAULT: OFF MIN: N/A MAX: N/A

BSIZE - block size for file transfers

Syntax	`BSize [<DEF, INC, RAN, RES>] size [max_size]`
Description	Block Size, displayed on the Transfer Information Screen, determines the size of the blocks, in bytes, used in transferring a file. Large files are divided into block sizes and then transferred from or to a destination. A block delay after each block transfer may be introduced via the BDELAY User Options. If the file size is small, large block sizes have no effect. DEF (short for DEFAULT) may be used to return the settings back to their default values. No other values are accepted for this string. INC (short for INCREMENT) directs RRTT to increase the block size by a fixed number of bytes for each new test pass. The first parameter (separated from INC by a space) is interpreted as the step size. If a second value is entered it is interpreted as the maximum size to use before repeating the sequence. The first step of an INCREMENT sequence is the command's minimum acceptable value is used. RAN (short for RANDOM) directs RRTT to use random numbers between the minimum and maximum supplied on the command line. The first value after the RAN string is the minimum random number. The second value is the maximum value. If the maximum or both values are left blank then the default minimum and maximum values are used. RES (short for RESET) functions the same are the DEFAULT string and returns the command's parameters back to their original settings. The block sizes used can greatly effect the network performance numbers displayed. For small block sizes the Kbytes/Second performance number will be low.
Example	`>BS INC 256 0x2000` Sets the block size to increment by decimal 256 for each new file transfer but not to exceed hexadecimal 2000.
Limits	DEFAULT: RANDOM 120480 Bytes MIN: 1 Byte MAX: 20480 Bytes

DRIVE - set the destination drive list

Syntax	`DRive [<-,RES>] drive_name [drive_name ...]`
Description	Drive sets or clears active destination drives. A list of destinations separated by spaces may be entered. If a destination can not be accessed the Monitor Screen will respond with an error and that destination will not be entered onto the list. The Information Screen labeled Dest displays a list of up to 50 unique destinations. Each name may be up to 30 characters long. To remove a drive from the list a "-" must be supplied before the drive list and separated by spaces. Each active drive on the list is then removed. RES (short for RESET) will clear the entire drive list. RRTT will not run unless at least one destination is active.
Example	`>DR - \\server1\root g:\tmp` Removes both the \\server1\root and g:\tmp destinations from drive list.
Limits	DEFAULT: no active net names MIN: 1 MAX: 50

ERROR - error count before test abort

Syntax	`ERror<DEF,OFF,RES,error_count>`
Description	Error, displayed on the Loop Information Screen, sets the number of errors allowable prior to terminating a test session. This command is effectively a "break on error" switch. If Error is set to 1, RRTT will stop the session if an error occurs. If Error is set to OFF, RRTT will continue if and error occurs. If Error is set to a value other than 1, RRTT will continue until the appropriate number of errors has occurred.
Example	`>ER OFF` Continue upon receiving an error.
Limits	DEFAULT: 1(break on error) MIN: OFF MAX: 999999999

EXIT - exit the RRTT utility

Syntax	`EXit`
Description	Exit exits the RRTT utility.
Example	`>EXIT` Exits the RRTT utility.
Limits	DEFAULT: N/A MIN: N/A MAX: N/A

FDELAY - file delay time

Syntax	`FDelay <DEF,OFF,RES,delay_time>`
Description	File Delay, displayed on the Transfer Information Screen, sets a delay time after each complete file transfer. The value is accepted in floating point seconds. This option can be used to throttle down the RRTT test by placing it in a sleep state after each file transfer. This is not the same as the block delay time which holds off back to back transfers a given block delay time. Here, File Delay simply waits the appropriate number of seconds before transferring another file. OFF sets the delay to zero. DEF and RES both return FDelay to the default setting. INC, RAN, or ON are not acceptable strings.
Example	`>FD 1.5` Sets a delay between files of 1.5 seconds.
Limits	DEFAULT: OFF MIN: 0 MAX: 30.0 seconds

FNAME - transfer file file name

Syntax	`FName <DEF,RES,transfer_file_name>`
Description	File Name, displayed on the File Information Screen, sets the name of a user created transfer file. If this command is used, all of the internal file attributes used for creating a dummy file are overridden and the named file is used instead. The named file must exist in the current directory for it to be accepted.
Example	`>FN USER.TST` Directs RRTT to use the file USER.TST for network transfers rather than create its own file.
Limits	DEFAULT: RRTTS00.JNK MIN: N/A MAX: N/A

FPATTERN - file pattern for transfer files

Syntax	`FPattern [<DEF,INC,RAN,RES>] value [max_value]`
Description	File Pattern, displayed on the File Information Screen, controls the contents of an internally generated transfer file. The pattern can be controlled a few different ways. DEF (short for DEFAULT) may be used to return the settings back to their default values. No other values are accepted for this string. INC (short for INCREMENT) directs RRTT to step by a fixed increment for each ASCII byte. The first parameter (separated from INC by a space) is interpreted as the step size. If a second value is entered it is interpreted as the maximum size to use before repeating the sequence. The first step of an INCREMENT sequence is the command's minimum acceptable value. If no maximum is supplied then the maximum acceptable value is used. RAN (short for RANDOM) directs RRTT to use random extended ASCII values between the minimum and maximum supplied on the command line. The first value after the RAN string is the minimum random number. The second value is the maximum value. If the maximum or both values are left blank then the default minimum and maximum values are used. RES (short for RESET) functions the same as the DEFAULT string and returns the commands parameters back to their original settings. A fixed input string may also be used extending up to 45 characters long.
Examples	`>FP 12345abcde` Fills the transfer file with repetitions of this string. `>FP RAN 0x20 0xE0` Fills the file with random bytes ranging in value from 32 to 224 decimal.
Limits	DEFAULT: RANDOM 0X00 0XFF MIN: 0 MAX: 0xFF or 45 character string

FREPEAT - transfer file repeat count

Syntax	`FRepeat <DEF,RES,count>`
Description	File Repeat count, displayed on the Loop Information Screen, sets a repeat counter allowing for the same dummy transfer file to be transmitted more than once to a destination without generating a new transfer file. This eliminates the time to create a transfer file. DEF (short for DEFAULT) and RES (short for RESET) both return the repeat count to its original setting. File Repeat is no the same as Test Repeat, which causes the entire RRTT test to be repeated a specific number of iterations. File Repeat simply runs copy and compares with the same file the set number of times and then generates a new dummy transfer file. An FREPEAT value of one means transfer the file once per destination, rather than repeat the file transfer once.
Example	`>FR 1000` Directs RRTT to use the file 1000 times per destination prior to creating a new transfer file.
Limits	DEFAULT: 1 (no repeat) MIN: 1 MAX: 999999999

FSIZE - file size for dummy transfer file

Syntax	`FSize [<DEF,INC,RAN,RES>] value [max-value]`
Description	File Size, displayed on the File Information Screen, sets the size in bytes for the transfer file. As with block size and block delays, RRTT may be directed to create file sizes a number of different ways. DEF (short for DEFAULT) may be used to return the settings back to their default values. No other values are accepted for this string. INC (short for INCREMENT) directs RRTT to step the file size by a fixed increment for each new test pass. The first parameter (separated from INC by a space) is interpreted as the step size. If a second value is entered, it is interpreted as the maximum size to use before repeating the sequence. The first step on an INCREMENT sequence is the command's minimum acceptable value. If no maximum is supplied then the maximum acceptable value is used. RAN (short for RANDOM) directs RRTT to use random numbers between the minimum and maximum supplied on the command line. The first value after the RAN string (separated by a space) is the minimum random number. The second value is the maximum value. If the maximum or both values are used. RES (short for RESET) functions the same as the DEFAULT string and returns the command's parameters back to their original settings. A fixed size may be entered, in which case RRTT will alter other test parameters while leaving the file size constant.
Example	`>FS RAN` Sets the dummy transfer file size to some random number between the default minimum and maximum for each new pass of an RRTT test.
Limits	DEFAULT: RANDOM 1 0X20000 MIN: 1 Byte MAX: 131072 Bytes

HELP - display on-line help screens

Syntax	`HElp`
Description	Pops up a detailed help list. On the left is a list of all the RRTT commands available. On the right is a 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 commands. Typing the <ENTER> or <RETURN> key will exit the help screen with the current command selection already typed into the command line. Typing the <ESC> key will exit the help screen without saving the currently selected command. The menu displayed prior to executing HELP will be restored. The first few screens of the HELP command explain how to interpret the syntax fields of the command descriptions. The JUMP command is not included in the help screens and is only applicable when running script files. Typing ? is identified to typing the HELP command.
Example	`>HELP` Displays the on-line help screen atop the Information Screen.
Limits	DEFAULT: N/A MIN: N/A MAX: N/A

JUMP - jump to a script file label

Syntax	`JUMP [[!]<condition_code>] [<label>]`
Description	JUMP will alter the otherwise sequential flow of a script file by either skipping over the next script entry or moving the script file's pointer to a label. A condition code may be used to dictate whether the jump should be taken. A '1' flag is available for inverting the meaning of the condition code. If used, no white space may exist between the "!" and the condition code. If the condition code 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. White space is not allowed in labels. If the label is not present on the command line, the JUMP merely skips the next non-blank script line. This command is valid only when RRTT is reading command input from a script file. The presently supported condition code for the JUMP command is DRIVE_ERROR. It must be typed in all upper case letters. If any of the active destinations sustained an error during the last RRTT execution then the DRIVE_ERROR condition code will cause the script file to make the jump. If the !DRIVE_ERROR condition code is used, the jump is taken if no errors occurred. If identical labels exist in a script file, a JUMP command will start execution at the first occurrence of these identical labels. Labels are not case sensitive.
Examples	`JUMP` Skips the execution of the next command. `JUMP !DRIVE_ERROR` Skips the execution of the next command if no errors occurred during the last RUN. `JUMP DRIVE_ERROR ExitScript` Continues execution of the script file from after the label :ExitScript if an error occurred during the last RUN. `:ExitScript` Label in a script file. Ignored during execution and searched for by the JUMP command.
Limits	DEFAULT: N/A MIN: N/A MAX: N/A

LCOMMENT - write user comment into log file

Syntax	`LComment text_string`
Description	Log Comment writes a string into the active log file. The string may be up to 45 characters long. If no log file is active, no action is taken. A comment may be useful for deciphering a test report. Note that when the log file made has been set to VERBOSE the actual command LCOMMENT text_string will also be entered into the log file preceded by the text_string. When the log mode is TERSE or SILENT only the text_string will be entered.
Example	`>LC start of test number 5` Writes "start of test number 5" into the active log file.
Limits	DEFAULT: N/A MIN: N/A MAX: N/A

LMODE - sets the log mode for test reporting

Syntax	`LMode <DEF,OFF,ON,RES,SIL,TER,VER,file_name>`
Description	The Log Mode command, displayed on the Report Information Screen, performs tasks to control the log file. Depending on the parameters given, LMODE will turn on/off the log file, rename and turn on a new log file, change the reporting mode of a log file, or erase an old log file. DEF (short for DEFAULT) will return the log mode back to its original state, turn off an active log, and reset the log name to the default name. The OFF parameter turns off an active log. The ON parameter turns on a log file with the name displayed on the Report Information Screen. All new logging is appended to the log file. The RES (short for RESET) will erase the contents of the existing log file and start a fresh log using the name displayed on the Report Information Screen. SIL, TER, VER (short for SILENT, TERSE, and VERBOSE respectively) altar the amount of information collected during an RRTT session. SILENT only records test error information collected during an RRTT session. SILENT only records test error information and test completion summaries into the log file. TERSE records all the SILENT does plus RRTT drive report information for each test iteration. The VERBOSE switch causes the logger to record all test activity along with all command line activity. Only one switch may be used at a time, and each will turn on the log file if there isn't one already active. When a log file is active, a red letter L is displayed in the upper right-hand corner of the screen. If there is no L then log information is not being captured.
Example	`>LMODE VERBOSE` `>LMODE RESET` Sets the logger to record all activity and start with a fresh log file.
Limits	DEFAULT: TERSE MIN: N/A MAX: N/A

LNAME - log name

Syntax	`LName <DEF,RES, file_name>`
Description	Log Name, displayed on the Report Information Screen, is a Static User Option used to change the log file name. The name may be any valid file name and extension. DEF and RES (short for DEFAULT and RESET respectively) will return the log file name to the default name. The command LMODE file_name can also be used to change the log file name making the change takes place immediately. LNAME file_name does not turn the log on or off, it only changes the log on or off, it only changes the log file name. The name change, using LNAME, takes effect the next time a log file is opened.
Example	`>LN USER.LOG` Redefines the log file name to USER.LOG.
Limits	DEFAULT: RRTT.LOG MIN: N/A MAX: N/A

LOAD - load a configuration file

Syntax	`LOAD [file_name]`
Description	LOAD scans a configuration or script file for RRTT User Options. This allows for test configurations stored with the SAVE command or created with a test editor to be automatically loaded into RRTT. If the file_name is a script file, then all non-static commands are ignored. If the file_name is left off, the default file name is used. LOAD does not abbreviate.
Example	`>LOAD TEST8.CFG` Executes the configuration file TEST8.CFG
Limits	DEFAULT: RRTT.CFG MIN: N/A MAX: N/A

MMODE - set the monitor screen mode for reporting

Syntax	`MMode <DEF,RES,SIL,TER,VER>`
Description	The Monitor Mode command, displayed on the Report Information Screen, controls the amount of information reported to the Monitor Screen during an RRTT test. DEF and RES (short for DEFAULT and RESET respectively) will return the monitor mode back to its original state. SIL, TER, VER (short for SILENT, TERSE, and VERBOSE respectively) alter the amount of information displayed on the Monitor Screen during an RRTT session. SILENT only reports test error information. TERSE records all that SILENT does plus RRTT drive report information for each test iteration. The VERBOSE switch causes the Monitor to record all test activity. The command line activity is always reported to the Monitor Screen. Only one switch may be used at a time.
Example	`>MMODE SILENT` Do not monitor the RRTT test with the Monitor Screen.
Limits	DEFAULT: VERBOSE MIN: N/A MAX: N/A

PAUSECOPY - pause after file copy

Syntax	`PAusecopy<ON,OFF>`
Description	Pause on Copy, displayed on the Transfer Information Screen, causes RRTT to pause after each file copy and prior to performing a file compare. The user may, if they wish, manually introduce file errors (outside the application). Doing so will verify proper error reporting. Typing any character will resume the test. This is a 'reality check' and is not intended for network testing.
Example	`>PA ON` Wait for a keyboard hit before comparing files.
Limits	DEFAULT: OFF MIN: N/A MAX: N/A

PMODE - set the printer mode for test reporting

Syntax	`PMode <DEF,OFF,ON,RES,SIL,TER,VER>`
Description	The Printer Mode command, displayed on the Report Information Screen, controls the amount of information captured on the printer. DEF (short for DEFAULT) will return the printer mode back to its original state. The OFF parameter turns off the active printer. The ON parameter turns on the printer with the mode displayed on the Report Information Screen. The RES (short for RESET) will open then close the printer port. This is similar to turning the printer On the OFF. SIL, TER, VER (short for SILENT, TERSE, and VERBOSE respectively) alter the amount of information collected during an RRTT session. SILENT records only test error information and test completion summaries to the printer. TERSE records all that SILENT does plus RRTT drive report information for each test iteration. The VERBOSE switch causes the printer to record all test activity. Only one switch may be used at a time and each will turn on the printer if it isn't already active. When the printer log is active, a red letter P is displayed in the upper right-hand corner of the screen. If there is no P then log information is not being captured on the printer.
Example	`>PM SIL` Activate the printer to record error information.
Limits	DEFAULT: SILENT MIN: N/A MAX: N/A

QUIT - exit the RRTT utility

Syntax	`QUit`
Description	QUIT exits the RRTT utility and is identical to EXIT.
Example	`>QUIT` Exit RRTT
Limits	DEFAULT: N/A MIN: N/A MAX: N/A

Notices

January, 1996

Issued by:

IBM Corporation
Personal Software Products
11400 Burnet Road
Austin, Texas 78758

Second Edition (January 1996)

First Edition (May 1993)

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

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

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

Copyright Notices

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

Disclaimers

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

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

Trademarks

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

IBM OS/2

LAN Adapter and Protocol Support
IBM Product Overview

About This Publication
1.0 NDIS Overview
2.0 LAN Adapter and Protocol Support Overview
3.0 IBM OS/2 LAN Server Version 2.0
3.1 Adapter Support for IBM OS/2 LAN Server Version 2.0
4.0 IBM Extended Services for OS/2
4.1 Adapter support for IBM Extended Services for OS/2
5.0 IBM LAN Enabler Version 2.0
5.1 Description
5.2 Adapter Support for IBM LAN Enabler Version 2.0
6.0 IBM TCP/IP for OS/2 V 1.2.1
6.1 Description
6.2 Adapter Support for TCP/IP for OS/2
7.0 DOS LAN Support Program
8.0 LAN Products Requiring DOS LAN Support Program
8.1 OS/2 Products
8.2 DOS Products
9.0 NDIS Network Driver Enablement Process
9.1 IBM Testing Overview
9.2 NDIS MAC Driver Enablement Overview
9.3 NDIS Driver Enablement Offering
- 9.3.1 DWB Functional Verification Test
- 9.3.2 National Software Testing Laboratories Compatibility Test
- 9.3.3 IBM Complementary Delivery of OEM NDIS MAC Drivers
  - 9.3.3.1 Prerequisites for Distribution
  - 9.3.3.2 NDIS Driver Availability For Customers
- 9.3.4 National Language Support
Notices
- Copyrights
- Disclaimers
- Trademarks

[[[#Sec10|next]]][[[#toc|parent]]][[[#toc|TOC]]]

About This Publication

The network Driver Interface Specification (NDIS) developed jointly by 3Com** and Microsoft** is a standardized interface for network adapter drivers and protocol drivers. This publication describes the implementation of NDIS support in IBM LAN products. In particular this publication describes the implementation of LAN Adapter and Protocol Support in OS/2 based products and LAN Support Program in DOS based products. As of this printing, LAN Adapter and Protocol Support (LAPS) is available in Extended Services for OS/2, LAN Server 2.0, TCP/IP for OS/2 1.2.1, LAN Enabler 2.0, LAN Server 3.0, and Network Transport Services/2 (NTS/2) Version 1.0. This publication has been updated to reflect changes made to LAPS in LAN Server 3.0 and NTS/2.

This document also provides an overview of the LAN adapter enablement process for NDIS network drivers, also known as NDIS media access control (MAC) drivers. This process is for supporting OEM and IBM NDIS network drivers during phases of development, testing, and distribution to end users.

Related Publications

IBM Network Transport Services/2 LAN Adapter and Protocol Support Configuration Guide
IBM OS/2 LAN Server Version 3.0 Network Administrator Reference Volume 1: Planning and Installation
IBM OS/2 LAN Server Version 3.0 Network Administrator Reference Volume 2: Performance Tuning Guide
IBM OS/2 LAN Server Version 3.0 Application Programmer's Reference
IBM Extended Services for OS/2 Network Administration Guide
IBM Extended Services for OS/2 Communications Manager Configuration Guide
IBM Extended Services for OS/2 LAN Adapter and Protocol Support Configuration Guide
IBM OS/2 LAN Server Version 2.0 Network Administrator Reference Volume 1: Planning and Installation
IBM OS/2 LAN Server Version 2.0 Network Administrator Reference Volume 2: Performance Tuning
IBM OS/2 LAN Server Version 2.0 Network Administrator Reference Supplement for OS/2 2.0
IBM Local Area Network Technical Reference
TCP/IP for OS/2: LAPS Introduction and Configuration Guide
3Com/Microsoft LAN Manager Network Driver Interface Specification Version 2.0.1 Final
NDIS Implementation Information for IBM LAN Systems, Extended NIF Format
NDIS Implementation Information for IBM LAN Systems, NDIS Extensions
NDIS implementation Information for IBM LAN Systems, OS/2 Messaging and National Language Support
NDIS Implementation Information for IBM LAN Systems, IBM OS/2 LAN Technical Reference Extensions

1.0 NDIS Overview

The Network Driver Interface Specification (NDIS) developed jointly by 3Com** and Microsoft** is a standardized interface for network adapter drivers and protocol drivers. NDIS separates protocol handling from hardware manipulation by defining functions that protocol drivers and network adapter drivers must provide to each other. It defines a configuration and binding process, which is handled by the protocol manager. NDIS has become an accepted industry standard, providing a common, open interface that enables different manufacturers of network adapters and LAN software to communicate. Figure 1 illustrates the major software components in the NDIS environment.

File:Images/overvie1.gif

A network adapter driver provides the communication between a network adapter and a protocol. The main function of the network adapter driver is to support network packet reception and transmission. A protocol driver provides the communication between an application and a network adapter driver. The main function of the protocol manager is to read configuration information from the configuration file, PROTOCOL.INI, and make it available to the network adapter drivers and protocol drivers. It also coordinates connections between protocol drivers and network adapter drivers. Before the protocol driver and the network adapter driver can communicate, they must be bound together (entry points are exchanged). NETBIND initiates the binding process based on information in PROTOCOL.INI.

2.0 LAN Adapter and Protocol Support Overview

LAN Adapter and Protocol Support is network communication software that consists of NDIS-compliant protocol drivers, NDIS-compliant network adapter drivers, API support software, and configuration and installation software for these drivers. LAN Adapter and Protocol Support is the network communication software necessary to support the LAN connectivity for OS/2 LAN products, and is a subsystem in IBM Extended Services for OS/2, IBM OS/2 LAN Server Version 2.0, and IBM LAN Enabler Version 2.0. A version of LAN Adapter and Protocol Support that contains only a TCP/IP protocol stack is included in TCP/IP for OS/2 1.2.1. A later release of LAN Adapter and Protocol Support is included in LAN Server 3.0 and NTS/2.

IEEE 802.2 and NETBIOS are the protocol drivers available with LAN Adapter and Protocol Support. A device driver interface API and a dynamic link interface API exist for both protocols. The IEEE 802.2 and NETBIOS APIs and the IEEE 802.2 and NETBIOS protocols are described in detail in the IBM Local Area Network Technical Reference. Refer to the NDIS Implementation Information for IBM LAN Systems OS/2 LAN Technical Reference Extensions for a list of network adapters supported by LAN Adapter and Protocol Support. The chapter on NDIS Driver Enablement Process in this document describes how to assist new driver support for OS/2 products to develop, test and distribute.

NDIS allows multiple protocols to bind to the same network adapter driver. Therefore, both the NETBIOS and 802.2 protocol drivers can bind to the same network adapter driver. Figure 2 shows the relationship between LAN adapters, network adapter drivers, protocol drivers, and applications.

File:Images/overvie2.gif

In addition to the OS/2 API support, LAN Adapter and Protocol Support provides OS/2 2.0 Manual LAN Support. This will enable existing DOS NETBIOS and IEEE 802.2 applications running in the OS/2 2.0 Virtual DOS Machine environment to share an adapter with other DOS, OS/2 NETBIOS, and IEEE 802/2 applications running on the same machine.

Configuration parameters for LAN Adapter and Protocol Support network adapter drivers and protocol drivers exist in the file PROTOCOL.INI, which also contain the binding information for each driver. For a detailed explanation of configuration parameters and PROTOCOL.INI see the Extended Services Communications Manager Configuration Guide, or the Extended Services LAN Adapter and Protocol Support Configuration Guide, or the OS/2 LAN Server Network Administrator Reference Volume 2: Performance Tuning. For the LAN Server 3.0 and NTS/2 release of LAN Adapter and Protocol Support, see the LAN Adapter and Protocol Support Configuration Guide for a detailed explanation of configuration parameters and PROTOCOL.INI. The network information file (NIF) supports the user interface in providing network driver information to the PROTOCOL.INI.

3.0 IBM OS/2 LAN Server Version 2.0

IBM OS/2 LAN Server Version 2.0 Entry supports either 16-bit or 32-bit operating systems, provides enhancements over the previous IBM LAN Server in the areas of system management, double byte character set (DBCS) support for DOS LAN Requester, Windows 3.0 support, and OEM (PCM) enabling. The entry product is designed for customers specializing in workgroup computing.

The LAN requesters distributed feature is offered to enable DOS and OS/2 workstations to access the OS/2 LAN Server in a client/server relationship. The function offered in the Distributed Feature is a subset of that provided by IBM OS/2 LAN Server Version 2.0.

In addition to the function described above, excluding 32-bit operating system support, IBM OS/2 LAN Server 2.0 Advanced provides additional performance enhancements by exploiting advanced functions of the Intel 386 architecture. Also provided are disk mirroring duplexing and local server security. These functions allow the IBM OS/2 LAN Server Version 2.0 Advanced to support customers with critical applications requiring higher performance and enhanced data integrity.

IBM OS/2 LAN Server Version 2.0 has the same APIs as well as most of the same functions as Microsoft's LAN Manager 2.0. By providing unique features, IBM OS/2 LAN Server Version 2.0 achieves competitive advantage in many marketing situations.

3.1 Adapter Support for IBM OS/2 LAN Server Version 2.0

LAN Adapter and Protocol Support is packaged as a subsystem of IBM OS/2 LAN Server Version 2.0. IBM OS/2 LAN Server Version 2.0 runs as an application written to the NETBIOS and 802.2 protocol driver APIs. Therefore, any NDIS network driver written and tested on LAN Adapter and Protocol Support should qualify for testing under IBM OS/2 LAN Server Version 2.0. IBM OS/2 LAN Server Version 2.0 contains a suite of IBM-tested NDIS network drivers. IBM also provides an enablement process whereby IBM and OEM owners of adapters for which drivers were not provided in the original suite, can develop, test and distribute them.

File:Images/overvie3.gif

4.0 IBM Extended Services for OS/2

Two new IBM program products provide database and communications function for OS/2 programs. Both programs also contain database administration tools, Query Manager, and enhanced communications support for local area network (LAN) and standalone workstations. The two programs are:

IBM Extended Services with Database Server for OS/2
IBM Extended Services for OS/2

Associated only with IBM Extended Services with Database Server for OS/2 program, is a distributed feature called Database Client Application Enablers. This feature enables DOS, Windows, and OS/2 clients to access Extended Services database servers on a LAN. This same client support can provide read and write access to IBM host servers supporting Distributed Relational Database Architecture (DRDA). The IBM Extended Services for OS/2 program includes DOS, Windows, and OS/2 client support similar to that in the distributed feature.

IBM Extended Services for OS/2 is designed to run on the IBM OS/2 Standard Edition Version 1.3 (Refresh Level 1.30.1) or to replace the communications and database manager functions of the IBM Extended Edition Version 1.3 when upgrading to Refresh Level 1.30.1. IBM Extended Services for OS/2 will also run on the IBM OS/2 2.0 32-bit operating system.

IBM Extended Services for OS/2 includes many function, performance and usability enhancements to the database and communications applications previously available on the IBM Extended Edition Version 1.3. The base OS/2 operating system, previously part of the Extended Edition Database and Communication Manager components, is now a separately packaged program. The LAN Requester is now provided with IBM OS/2 LAN Server Version 2.0.

4.1 Adapter support for IBM Extended Services for OS/2

LAN Adapter and Protocol Support is packaged as a subsystem within IBM Extended Services for OS/2. IBM Extended Services for OS/2 runs as an application written to the NETBIOS and 802.2 protocol driver APIs. Therefore any NDIS network driver written and tested on LAN Adapter and Protocol Support should qualify for testing under IBM Extended Services for OS/2. IBM Extended Services for OS/2 contains a suite of IBM-tested NDIS network drivers. IBM also provides an enablement process whereby IBM and OEM owners adapters for which drivers were not provided in the original suite, can develop, test and distribute them.

File:Images/overvie4.gif

5.0 IBM LAN Enabler Version 2.0

IBM LAN Enabler Version 2.0 offers the OS/2 Requester (both 286 and 386), LAN Support Program 1.2, and DOS LAN Requester (DLR) in a separate program package for a uses of OS/2 LAN Server 2.0 and OEM servers.

The IBM LAN Enabler Version 2.0 is a repackaging of the OS/2 and DOS requesters in the IBM OS/2 LAN Server Version 2.0 product. This program is for customers who want requesters only for a LAN server or for customers who want to use LAN Adapter and Protocol Support without requiring IBM Extended Services for OS/2 or IBM OS/2 LAN Server Version 2.0.

5.1 Description

The OS/2 LAN Requester consists of two components, the LAN Adapter and Protocol Support and the requester code. LAN Adapter and Protocol Support contains NETBIOS virtual device driver (VDD) support which allows DOS NETBIOS applications running in an OS/2 virtual DOS machine (VDM) environment to share an adapter with other DOS, DOS Windows, and OS/2 NETBIOS applications.

The DOS LAN Requester consists of two components also, the DOS LAN Support Program, which is roughly the DOS equivalent to LAN Adapter and Protocol Support, and the requester code.

On an OS/2 workstation, a customer can choose to configure LAN Adapter and Protocol Support only or LAN Adapter and Protocol Support along with the OS/2 requester code. The customer who installs LAN Adapter and Protocol Support only has an application need requiring OS/2 LAN connectivity, but without requiring either IBM Extended Services for OS/2 or IBM OS/2 LAN Server Version 2.0. The customer who installs the requester with LAN Adapter and Protocol Support does not require IBM OS/2 LAN Server Version 2.0 as a prerequisite for the requester code.

5.2 Adapter Support for IBM LAN Enabler Version 2.0

LAN Adapter and Protocol Support is packaged as a subsystem of IBM LAN Enabler Version 2.0. IBM LAN Enabler Version 2.0 runs as an application written to the NETBIOS and 802.2 protocol driver APIs. Therefore, any NDIS network driver written and tested on LAN Adapter and Protocol Support should qualify for testing under IBM LAN Enabler Version 2.0. IBM LAN Enabler Version 2.0 contains a suite of IBM-tested NDIS network drivers. IBM also provides an enablement process whereby IBM and OEM owners of adapters for which drivers were not provided in the original suite, can develop, test and distribute them.

6.0 IBM TCP/IP for OS/2 V 1.2.1

6.1 Description

IBM TCP/IP for OS/2 supports a full suite of TCP/IP protocols and applications on OS/2. Applications include TCP, IP, UDP, ARP, ICMP, RIP, TELNET, FTP, TFTP, SMTP, SNMP, NFS, X Windows, NETSTAT, RIP and PING among others. Both IEEE 802.3 and Ethernet V2 (DIX) are supported on Ethernet LANs. FDDI, Token-Ring X.25, and SLIP support is also available.

6.2 Adapter Support for TCP/IP for OS/2

LAN Adapter and Protocol Support is packaged as a subsystem of TCP/IP for OS/2. Therefore, any NDIS network driver written and tested on LAN Adapter and Protocol Support should qualify for testing under TCP/IP for OS/2. TCP/IP for OS/2 contains a suite of IBM-tested NDIS network drivers. IBM also provides an enablement process whereby IBM and OEM owners of adapters for which drivers were not provided in the original suite, can develop, test and distribute them.

7.0 DOS LAN Support Program

The IBM LAN Support Program (LSP) is a DOS program product that provides network communication software for DOS workstation attachment to the local area network (LAN). In the NDIS environment LSP provides protocol Support for Ethernet (IEEE 802.3 and DIX Version 2.0) and IEEE 802.5. LSP also provides native mode (non-NDIS) Support for access to IBM PC Network and IBM Token-Ring networks.

The IEEE 802.2 and NETBIOS interfaces are contained in LSP allowing LAN applications to provide end to end connectivity. LSP also contains an interrupt arbitrator module which provides management of the '5C'X interrupt used to access the IEEE 802.2 and NETBIOS interfaces. The following figure shows the LSP structure including interfaces and modules.

File:Images/overvi51.gif File:Images/overvi52.gif

8.0 LAN Products Requiring DOS LAN Support Program

The LAN Support Program provides support for applications that are written to the NETBIOS and IEEE 802.2 programming interfaces. Examples of applications written to these interfaces are server code, requester/client code, and terminal emulation code. The following sections list applications that have been tested to work with LAN Support Program.

8.1 OS/2 Products

IBM DOS Database Requester packaged with IBM OS/2 Extended Edition 1.3
IBM DOS Database Requester packaged with IBM Extended Services for OS/2
IBM DOS LAN Requester packaged with the IBM OS/2 LAN Server 1.3, 2.0 and 3.0
IBM DOS LAN Requester packaged with IBM LAN Enabler Version 2.0

8.2 DOS Products

IBM PC LAN Program 1.3
IBM Personal Communications/3270
IBM Applications System/400 PC Support

9.0 NDIS Network Driver Enablement Process

The Network Driver Interface Specification (NDIS) network driver enablement process supports the development, testing, and distribution of NDIS media access control (MAC) drivers on IBM of products for OEM vendors.

9.1 IBM Testing Overview

This section describes the testing procedures followed by IBM in generating NDIS MAC drivers. The development and testing are divided into three broad parts.

File:Images\overvie6.gif

The development phase consists of programming the NDIS MAC drivers and taking that code successfully through unit test.
Functional verification consists of running a suite of test cases on the MAC driver running under the NETBIOS and IEEE 802.2 protocol drivers provided by LAN Adapter and Protocol Support. In addition an NDIS interface test can be performed using an IBM test tool which tests the NDIS verbs and parameters on the MAC driver.
Product verification test consists of testing the MAC driver with a variety of other connectivities using Extended Services and LAN Server. This test optimizes a simulated real life scenario.

9.2 NDIS MAC Driver Enablement Overview

To encourage the development of NDIS MAC drivers of OEM adapters for IBM products, IBM and two independent testing agents will offer enablement tools and testing that is similar to the test strategy IBM uses.

Two independent testing agents provide test offerings for a fee. DWB Associates, Inc. provides functional verification testing, the NDIS interface test or the MAC driver function test under the IEEE 802.2 and NETBIOS protocol drivers in LAN Adapter and Protocol Support. National Software Testing Laboratories Inc. (NSTL), provides compatibility testing of IBM OS/2 LAN Server and IBM Extended Services for OS/2 under IBM OS/2 32-bit and 16-bit operating systems.

OEM NDIS MAC Drivers that have passed NSTL compatibility test and are accompanied by a signed agreement with IBM will be distributed by means of various bulletin boards and conference disks. In addition these drivers will be candidates for being placed in a suite of drivers delivered with potential future products.

9.3 NDIS Driver Enablement Offering

9.3.1 DWB Functional Verification Test

DWB Associates Inc., is an independent software company that offers services related to development and testing of NDIS MAC drivers for a variety of LAN products including IBM Extended Services for OS/2 and OS/2 LAN Server. For a fee DWB offers OEM LAN adapter NDIS MAC driver functional verification test of LAN Adapter and Protocol Support which contains the NDIS Protocol drivers used in Extended Services for OS/2 and LAN Server. DWB also provides for testing the NDIS interface of a MAC driver using the IBM NDIS MAC driver test tool program. According to DWB, these tests may be useful for newly developed NDIS drivers or drivers that have undergone extensive modifications in order to comply with implementation of NDIS in the IBM OS/2 products. Inquiries regarding these offerings should be directed to DWB at (503) 626-3081. Any claims of compatibility with OS/2 will be made by each OEM vendor or by DWB. DWB certification of OEM NDIS drivers and adapters is not meant in any way to constitute an endorsement of any OEM product by IBM, and IBM does not warrant, or provide technical or defect support for, claims made by any OEM or by DWB.

9.3.2 National Software Testing Laboratories Compatibility Test

National Software Testing Laboratories, Inc. (NSTL) is an independent laboratory that offers an OEM LAN adapter NDIS MAC driver compatibility testing service for IBM Extended Services for OS/2 and LAN Server. Manufacturers of NDIS-compliant LAN adapters will be able, for a fee, to submit their adapters and NDIS drivers along with a network information file (NIF) to NSTL for certification. Inquiries regarding this service should be directed to NSTL at (215) 941-9600. Any claims of compatibility with Extended Services for OS/2 or LAN Server will be made by each OEM LAN adapter manufacturer or by NSTL. NSTL certification of OEM NDIS drivers and adapters is not meant in any way to constitute an endorsement of the OEM's products by IBM, and IBM does not warrant or provide technical or defect support for, claims made by any OEM or by NSTL.

9.3.3 IBM Complementary Delivery of OEM NDIS MAC Drivers

Any OEM NDIS SAC driver which satisfies the requirements for distribution, as described in the following two sections, will be placed in selected IBM distribution channels.

9.3.3.1 Prerequisites for Distribution

An OEM adapter owner with an NDIS MAC driver has the option of certifying with NSTL as compatible with Extended Services for OS/2 and LAN Server. If the owner has been certified by NSTL as compatible with IBM Extended Services for OS/2 and IBM OS/2 LAN Server and signs an agreement to distribute with IBM, the NDIS MAC driver will be placed on selected IBM distribution channels such as the IBM National Support Center Bulletin Board System (NSC BBS) and on the IBM OS/2 Conference on CompuServe** (OS/2 Disk). Placing an OEM NDIS driver on the IBM BBS and on the IBM OS/2 Conference on CompuServe for distribution is not meant in any way to constitute an endorsement of the OEM products by IBM, and IBM does not warrant, or provide technical or defect support for, claims made by any OEM NDIS driver owner.

9.3.3.2 NDIS Driver Availability For Customers

As a primary means of delivering NDIS MAC drivers IBM ships with IBM Extended Services for OS/2, IBM OS/2 LAN Server Version 2.0, IBM LAN Enabler Version 2.0, IBM TCP/IP for OS/2 1.2.1, IBM LAN Server Version 3.0, and IBM Network Transport Services/2 Version 1.0 a suite of NDIS MAC drivers that are tested and supported by IBM. A list of the drivers and adapters supported are in the NDIS Implementation Information for IBM LAN Systems, IBM OS/2 LAN Technical Reference Extensions document. Also, these drivers have been uploaded into IBM secondary delivery channels, such as the IBM National Support Center bulletin board system and on the OS/2 forum of CompuServe. As future IBM drivers are tested and approved, they will be also added to the secondary channels. OEM driver owners who qualify their drivers through NSTL and sign an agreement to distribute with IBM, will have that driver added to selected IBM channels for distribution, such as the bulletin board and conference forum mention for IBM drivers above. In addition these OEM drivers will be candidates for being paced in a suite of drivers delivered with potential future products.

9.3.4 National Language Support

Use of the message and message help file for National Language Support is optional. The message file provides runtime messages for the users to report error conditions. The message help file provides help prompts to the user at key interactive decision points of the runtime process.

Since these files provide text to be displayed on a panel, they can be written in any language. If more than one language is to be supported, the naming convention must support that process. IBM suggests the following:

Use the IBM country code to specify the language the files are written in. For example, if you would normally name English files as ADPT.MSG and ADPTH.MSG for the message and message help files respectively, then the country name files for Germany would be ADPT.049 and ADPTH.049 where 049 is the country code for Germany. The following is a list of IBM country codes supported by IBM OS/2 2.0:

  785  Arabic speaking
  099  Asian English
  061  Australia
  032  Belgium
  002  Canada (French speaking)
  042  Czechoslovakia
  045  Denmark
  358  Finland
  033  France
  049  Germany
  972  Hebrew speaking
  036  Hungary
  354  Iceland
  039  Italy
  081  Japan
  082  Korea
  003  Latin America
  031  Netherlands
  047  Norway
  048  Poland
  351  Portugal
  088  Republic of China
  034  Spain
  046  Sweden
  041  Switzerland
  090  Turkey
  044  United Kingdom
  001  United States
  038  Yugoslavia

Notices

May, 1993

Issued by:

IBM Corporation
Personal Software Products
11400 Burnet Road
Austin, Texas 78758

First Edition (May 1992)

Second 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

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

Disclaimers

References in this publication 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 IBM's intellectual property rights or other legally protectible rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility.

IBM may have patents or pending patent applications covering subject matter in 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.

Trademarks

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

OS/2

IBM

Extended Services

The following terms, denoted by a double asterisk (**) in this publication, are trademarks of other companies as follows:

Microsoft	Microsoft Corporation
3Com	3Com Corporation
CompuServe	CompuServe Incorporated

All other company, brand, and product names are trademarks or registered trademarks of their respective owners.

IBM NDIS Driver Implementation Package

Description/Contents

The IBM LAN Adapter and Protocol Support (LAPS), Network Transport Services/2 (NTS/2), and the DOS LAN Support Program (LSP) are the communications subsystems for IBM OS/2 and DOS products that require LAN connectivity. LAPS is included in the following products: Extended Services 1.0 (with or without Database Manager); LAN Server 2.0 (Entry or Advanced); LAN Enabler 2.0; TCP/IP v. 1.2.1; LAN Server 3.0 (Entry or Advanced) and NTS/2 1.0. In LAPS, NTS/2 and LSP, the Network Driver Interface Specification (NDIS) architected interface has been implemented for enabling NDIS Media Access Control (MAC) Device Drivers. This will allow the support of IEEE 802.5, 802.3, and Ethernet DIX Version 2.0 NDIS MAC drivers. This includes support for Ethernet, Token-Ring, FDDI, PCnet, and other architected network technologies.

If your organization has an adapter that you want supported on a platform containing the IBM LAPS and LSP, you will have to provide the NDIS MAC Device Driver for that adapter, and a Network Information File (NIF) for the install process. For OS/2 it is strongly recommended that a message file and message help file also be included.

Enclosed in this package are documents that are designed to assist you in the implementation of a new NDIS MAC Device Driver, or the conversion of an existing NDIS MAC Device Driver. These documents include the following:

For more extensive assistance in developing an NDIS MAC driver for use with IBM LAPS and LSP, the DWB Associates NDIS Device Driver Toolkit for OS/2 and DOSis available from DWB Associates, Inc. In addition to the documents you receive in this Information Package, the Tool Kit contains additional programming guides for writing NDIS MAC drivers and diskettes containing a sample driver, testing tools, test tool scripts, and a trace tool for debugging.
For information regarding the price and availability of the Tool Kit, contact DWB Associates, Inc., 9360 SW Gemini Drive, Beaverton, OR 97005, 503-626-3081.

3Com is a registered trademark of the 3Com Corporation

- Microsoft LAN Manager is a registered trademark of the Microsoft Corporation

Any reference to the NDIS Specification in products or documentation developed from this Implementation Package must contain the appropriate copyright and trademark acknowledgements.

May 1995

NDIS Implementation Information
for IBM LAN Systems
NDIS Device Driver Requirements

About This Publication
1.0 NDIS Device Driver Requirements
1.1 Deliverables
1.2 File Naming Conventions
1.3 Installation and Configuration issues
1.4 Device driver message support
1.5 Copyright
1.6 National Language Support (NLS)
1.7 NDIS support
1.8 Functional requirements
2.0 LAN Adapter option diskette issues
2.1 Directory structure
2.2 Adapter-related files
2.3 Documentation file requirements
- 2.3.1 Documentation file alternatives
2.4 National Language Support (NLS) on option diskette
- 2.4.1 NLS alternatives
- 2.4.2 Verification and testing
Appendix A. NDIS driver driver checklists
- A.1 FVT checklist
- A.2 SVT checklist
Appendix B. IBM MAC device drivers
Appendix C. Reserved message prefixes
Notices

[[[#Sec10|next]]][[[#toc|parent]]][[[#toc|TOC]]]

About This Publication

This publication provides a description of requirements for device drivers written to the Network Driver Interface Specification (NDIS). The requirements identified are primarily product-related such as: installation, configuration and packaging. It is intended as a supplement to the functional requirements identified in the NDIS specification. The relationship of key NDIS functions to IBM* LAN software products using both DOS* and OS/2* are explained.

Related Publications

3Com**/Microsoft** LAN Manager Network Driver Interface Specification
IBM NTS/2* LAN Adapter and Protocol Support* Configuration Guide (96F8489)
IBM LAN Support Program Users' Guide (20G0988)
IBM LAN Technical Reference (SC30-3383)
IBM LAN Technical Reference Supplement (SD21-0049)
NDIS Implementation Information for IBM LAN Systems, OS/2 Messaging and National Language Support
NDIS Implementation Information for IBM LAN Systems, NDIS Extensions
NDIS Implementation Information for IBM LAN Systems, Extended NIF Format
PS/2 Hardware Interface Tech Ref - Architectures (S84F-9808)

1.0 NDIS Device Driver Requirements

1.1 Deliverables

The following items are required deliverables for an NDIS device driver.

Documentation file
The purpose of the documentation file(s) is to provide all the information necessary to use the NDIS device driver(s). For a detailed description of the documentation file refer to section 2.3, "Documentation file requirements".
DOS
- DOS device driver executable file
- Network Information File (NIF)
- Message file
The DOS message file is identical to the OS/2 message file. For a detailed description of message files refer to section 1.4, "Device driver message support".
OS/2
- OS/2 device driver executable file
- Network Information File (NIF)
- Message file
- Message help file

1.2 File Naming Conventions

1.2.1 Device driver executable file

The filenames of the DOS and OS/2 NDIS device drivers should indicate the type of LAN adapter supported. For example, IBMTOK, IBMFDDI and MACETH indicate Token-Ring, FDDI and Ethernet respectively. The extension should be "DOS" or "OS2" as in: IBMTOK.DOS, IBMFDDI.OS2 and MACETH.OS2. For a list of IBM NDIS device drivers see Appendix B. "IBM MAC device drivers".

1.2.2 Message tile

The DOS and OS/2 message files must have a 3 character filename and an extension of "MSG". For example, LT2.MSG, LT5.MSG and MAC.MSG are the message files for the IBMTOK, IBMFDDI and MACETH device drivers.

Note, the message filenames of "LTn" are a convention used by IBM generated device drivers. This naming convention came about because early versions of NDIS support in OS/2 were referred to as "LAN Transport". Even though LAN Transport existed only in the OS/2 environment, the naming convention has been carried over to DOS NDIS device drivers for consistency.

Note, the messages in the message file use the filename as a message prefix. For example, LT20033E, would be the 33rd message in the LT2.MSG file. Message numbers are considered essential in problem resolution. This topic will be discussed in section 1.4, "Device driver message support".

1.2.3 Message help file

Message help files have an "H" appended to the filename of the associated message file. For example, LT2H.MSG is the message help file for LT2.MSG. The message help files contain a detailed explanation of the message and a suggested user action. They are used in conjunction with the OS/2 Help Facility. This topic will be discussed in more detail in section 1.4, "Device driver message support".

1.2.4 NIF and other miscellaneous files

The network information file (NIF) should have the same filename as the executable device driver. This leads to the OS/2 and DOS NIF file (files with different contents) having the same filename and extension, for example IBMFDDI.NIF. However, this has never surfaced as a problem since they are isolated in separate directories and never used in the same installation process.

Miscellaneous files should also use the filename of the executable device driver when possible. For example, the file containing the downloadable microcode for the IBM FDDI Workstation adapters is named IBMFDDI.BIN.

1.3 Installation and Configuration issues

1.3.1 Network information files

NDIS device driver installation entails copying the necessary device driver files from the adapter's option diskette and modifying the configuration files so that the device driver can be started successfully. Device driver configuration allows users to alter attributes of the device driver such as: number of buffers, buffer sizes, timer values or other adapter specific options. Device driver installation and configuration are closely related since they are often done in the same procedure.

In DOS, the device driver installation and configuration can be done by the DXMAID program of LAN Support Program. In OS/2, the same results can be accomplished using the LAN Adapter and Protocol Support (LAPS) installation and configuration program. Both of these programs rely on the device driver's network information file (NIF) to define the installation and configuration framework for the driver.

A NIF file which is written according to the'''Extended NIF Format'''chapter must be supplied with every NDIS device driver.For installation, the NIF describes which files must be copied from the adapter's option diskette and how to modify the CONFIG.SYS and PROTOCOL.INI files. For configuration, the NIF provides parameter ranges, defaults and help information.

The SNIFFLE.EXE utility will verify the syntax of the NIF file. Some details about NIF file contents are in the next

1.3.2 Support of NETADDRESS keyword

If the NDIS device driver supports "software gettable station addresses" according to the service flags of the MAC Service-Specific Characteristics table, it should provide a NETADDRESS option in the NIF. This allows multiple protocol stacks to share the same adapter without requiring the protocols to be started in a certain order.

Note, inform the user that the MAC address should be specified in canonical form for any of the Ethernet MAC types and non-canonical form (or MSB, most significant bit first) for the 802.5 MAC type. This information can be provided in the NETADDRESS parameter help text.

The NDIS device driver must guarantee that the "group address" bit is not set via the NETADDRESS parameter. The "group address" bit is the most significant bit of the 48 bit destination address (in non-canonical form). This rule may actually be enforced by the adapter. If not, the NDIS device driver must prevent a group address from being assigned as a locally administered address.

It is also possible to set the locally administered address of an adapter from some protocol drivers. This support exists for those NDIS MAC drivers which do not support NETADDRESS. Unfortunately it is a source of confusion for NDIS MAC drivers which support NETADDRESS. If the locally administered address is set by both the NDIS MAC driver and the protocol driver, the protocol driver's address is set last and therefore overwrites the address set by the NDIS MAC driver.

1.3.3 DRIVERNAME string in OS/2 NIFs

The drivername string must not end with a decimal number(s) in order to circumvent a problem in an early version of the LAPS installation and configuration program. In this version of the program, a drivername string which ends with a decimal number will not have its DEVICE= statement automatically inserted into the CONFIG.SYS file. This problem was resolved in LAPS version 2.10. The level of LAPS can be queried with the OS/2 command, SYSLEVEL.

1.3.4 NIF Title

The DOS and OS/2 NIF titles should contain the name of the adapter followed by the filename of the device driver executable in parenthesis. An example of a DOS NIF title would be:

IBM Token-Ring Network 16/4 Adapter II (IBM16TR.DOS)

This is the format that the LAN Support Program uses and it seems to make sense to couple the adapter to a device driver filename.

1.3.5 OS-specific features

The NIF file is the appropriate place to introduce OS-specific installation and configuration alternatives. Since system memory is a more valuable resource in DOS than OS/2, the default configuration for the DOS NIF file may allocate less system memory than the OS/2 NIF file. For example, buffer-size defaults may be minimal on DOS, enough to accommodate the maximum frame size. But on OS/2 the buffer-size defaults may be larger.

1.3.6 Manual installation and configuration

When a user does not have the DXMAID or LAPS installation and configuration programs available, they will have to manually install and configure the device driver. Manual installation and configuration should be avoided whenever possible. The purpose of the installation and configuration programs is to protect the user from the unique installation and configuration features of each device driver.

When necessary, the user can manually install the device driver by copying the appropriate files off of the adapter's option diskette and updating the CONFIG.SYS and PROTOCOL.INI files. The device drivers can be manually configured by altering the device driver's section of the PROTOCOL.INI file. Manual installation and configuration must be addressed in the documentation file of the adapter's option diskette. Refer to section 2.3, "Documentation file requirements"for a detailed description of the documentation file guidelines.

1.4 Device driver message support

The NDIS device driver message support is described in detail in the OS/2 Messaging and National Language Support chapters. A brief summary of message support and the DOS and OS/2 differences is described in the following sections.

1.4.1 Message file utility

The OS/2 Programmer's Toolkit contains a Message file utility called MKMSGF.EXE. This utility must be used to create the message file and the message help file. The MKMSGF.EXE utility translates a flat ASCII file into a packed file with a header which describes the offset and length of each message. The DosGetMessage function call requires that the message file is prepared by the MKMSGF.EXE utility.

Messages can no longer be built internal to the device driver. The external message file is a feature common to both DOS and OS/2 device drivers.

1.4.2 Message numbers

Message numbers are considered essential in problem resolution. Message numbers are of the format: PPPnnnns. Where PPP is a message prefix, for example LT2 and nnnn is a decimal number. The last character is either an: "E" (error), "I" (informational) or "W" (warning) indicating the severity of the message.

Message numbering is a feature common to both DOS and OS/2 device drivers. For a list of the reserved message prefixes see Appendix C, "Reserved message prefixes".

1.4.3 OS/2 message device driver logging

The OS/2 message device driver provides a feature which will receive messages from other device drivers. These messages will be written to a log file (\...\LANTRAN.LOG). The log file can be checked for error or warning messages after the system has completed initialization. The log file is very useful for verifying the successful initialization and Binding of the device drivers in the system. The message device driver logging is available only on OS/2 systems.

1.4.4 OS/2 help facility

The OS/2 help facility allows a user to get a detailed explanation and suggested action for an error message. The help facility obtains the explanation and suggested action information from the device driver's message help file. The help facility is invoked by entering "help" followed by the message number at the OS/2 command prompt, for example, "HELP LT20033E". This feature is available only on OS/2 systems.

Note, the OS/2 help facility expects the message prefix to be only 3 characters in length.

1.5 Copyright

All device drivers must have the appropriate copyright information. This usually consists of displaying a copyright statement to the screen during system initialization as well as expanding the copyright statement in ASCII form in the beginning of the executable code. Make sure you consult your company's legal department for your specific product's requirements.

1.6 National Language Support (NLS)

1.6.1 Message and message help translation

The message file and message help file must be translated for every language supported. The translators must be instructed to NOT translate: filenames (eg. PROTOCOL.INI), keywords (eg. DRIVERNAME), or directories etc.

1.6.2 NIF translation

Everything within double quotes can be translated in the NIF file. The single exception is that default values are specified in double qoutes and these can't be translated. The items of the NIF which usually have to be translated are: the title of the common section, the display text and help text of each parameter section. This is very similar to the translation necessary for the adapter definition file (ADF).

Note, the name of each parameter in the parameter section of the NIF file is NOT translated. The device driver does not need to search for translated keywords in the PROTOCOL.INI file.

1.6.3 Documentation file translation

Each documentation file will have unique translation instructions. The translators must be instructed to NOT translate: filenames (eg. PROTOCOL.INI), keywords (eg. DRIVERNAME), or directories etc.

1.6.4 Verification and testing

It's very important that the implementation of the translated files be verified, especially double byte character sets (DBCS).

1.7 NDIS support

802.5 MAC types must support the IBM Extensions described in the NDIS Extensions chapter. These extensions are necessary for the NDIS implementation of the 802.2 protocol stack to be consistent with the native (before NDIS) 802.2 implementation.

Also, as stated in the NDIS specification, the NDIS device driver must provide a general MAC type of 802.5, 802.3, DIX or DIX + 802.3 to be a "generally available" MAC. If the adapter is not one of the general medias, an internal mapping between the actual media and a general MAC type must be made by the NDIS device driver.

1.8 Functional requirements

1.8.1 Addressing limitations

A 16-bit adapter has 24 address connections which allow it to use addresses less than 16 MB. When an address greater than or equal to 16 MB is given to the NDIS device driver, it should return INVALID_PARAMETER as the TransmitChain return code.

This limitation can also arise when a 32-bit adapter, which has 32 address connections, has the flexibility to reside in a 16-bit slot. In this case, the adapter must inform the NDIS device driver (or the "system" in general) of the slot's addressing characteristics. Again, when a 32-bit adapter is in a 16-bit slot and an address greater than or equal to 16 MB is given to the NDIS device driver, it should return INVALID_PARAMETER as the TransmitChain return code.

1.8.2 Device Driver clean up for unsolicited disconnects

When the device driver is notified that the adapter has abruptly disconnected from the segment, the device driver passes a RingStatus indication to the protocol driver. This most commonly occurs when the cable is disconnected and the device driver presents a RingStatus indication, signalling that a lobe wire fault has occurred. At this time the device driver also indicates that the "MAC is not open" in the MAC status flag of the MAC Service-Specific Status table.

Once this has occurred, it is the responsibility of the application or protocol driver to retry re-connecting to the segment for a period of time, in case the event which caused the abrupt disconnect no longer exists. Or at the very least, the protocol driver must be able to resume operations when another application is started (or restarted).

However, for the protocol driver to be able to resume operations, it must have all of it's resources available. For example, when the adapter abruptly disconnects from the segment, the device driver may have transmits outstanding. If the adapter does not "post" these transmits as complete (causing the device driver to return them to the protocol driver - as it normally would), the device driver must complete these transmits. This returns all the outstanding transmit resources to the protocol driver so that it can resume operations when necessary.

1.8.3 IndicationComplete reentrancy

DOS NDIS device drivers have historically (ie IBMFDDI.DOS, IBMENI.DOS) been initially implemented as non-reentrant in the IndicationComplete call to the protocol. This deviates from the NDIS specification for IndicationCompletewhich states, "This routine is always entered with interrupts enabled and with the network adapter interrupt dismissed from the interrupt controller. Therefore, it may be reentered at the completion of another indication".

This problem is most commonly manifested by issuing "NET SEND" commands with the PC LAN Program (PCLP) product. When a "NET SEND" is issued, the destination station has a pop-up window displayed. This is displayed during the NetBIOS appendage call, which is also the protocol driver's IndicationComplete routine. The pop-up window will remain displayed for 1 minute. If the device driver is not capable of performing the IndicationComplete in a reentrant fashion, the protocol will not be able to receive any frames while the pop-up is displayed because the IndicationComplete call is also used to complete frame reception.

To verify this feature, issue a "NET SEND" command to a PCLP station and copy files from the same PCLP station. If the other station which is copying files loses its session while the pop-up is displayed, the DOS NDIS driver is probably not reentrant in IndicationComplete.

1.8.4 Interrupt Sharing

Interrupt sharing must be implemented on DOS drivers. Interrupt sharing considerations and implementation information are described in the PS/2 BIOS Interface Technical Reference.

1.8.5 InterruptRequest implementation

The InterruptRequest NDIS general request must be implemented by all DOS NDIS device drivers in order for the LAN Support Program 802.2 protocol driver to perform optimally. The necessity for this command is brought out when running the PERFORM3 benchmark performance test.

The InterruptRequest command allows the protocol to request that it be called at the IndicationComplete entry point. This is necessary because transmits given to the LSP protocol driver are not immediately issued, they are queued to the protocol driver's dispatcher component. The dispatcher component can only be entered on timer interrupts, TransmitConfirm's and IndicationComplete's. Therefore, invoking the InterruptRequest command will invoke the dispatcher, where queued transmits can be issued to the device driver.

When InterruptRequest is not implemented there is a tell-tale 55 ms. delay between transmits while running PERFORM3. This uniform delay is a result of the DOS timer acting as the mechanism to invoke the protocol driver's dispatcher component. This is enough of a delay to adversely affect the operation of the network (eg. NetBIOS sessions get lost).

When InterruptRequest is implemented correctly; throughput improvements of approximately 1000% are visible for 64 byte messages (700% for 512 byte messages and 400% for 4K byte messages).

1.8.6 LAN Network Manager support

The IBM LAN Network Manager (LNM) product relies on access to the Adapter Status Parameter (ASP) table and the MAC Buffer to report the condition of the local Token-Ring segment. The ASP table is described in Appendix B of the LAN Technical Reference. LNM acquires (via the 802.2 protocol driver) the address of the ASP table and the MAC Buffer through the extended MAC Service-Specific Characteristics (SSC) table defined in the NDIS Extensions chapter.

The Token-Ring "shared RAM" adapters maintain the ASP table and MAC Buffer in the read-only area of shared RAM. The addresses of the ASP table and the MAC Buffer can be stored in the MAC SSC extension, giving all protocol drivers (and their associated applications) access to them.

The Token-Ring busmaster adapters maintain the ASP table and MAC Buffer in adapter memory, the device driver must "shadow" them into workstation memory. The workstation addresses of the shadowed ASP table and MAC Buffer are then stored in the MAC SSC extension. The device driver must periodically refresh the shadowed ASP table and MAC Buffer, the recommended refresh interval is once every second.

Maintaining the ASP table and MAC Buffer in this manner provides protocol drivers and applications with a consistent level of information across all types of Token-Ring adapters.

1.8.7 ModifyOpenParms implementation

The ModifyOpenParms is a new NTDIS general request described in the NDIS Extensions chapter. The purpose of this command is to allow applications to dynamically control low-level functions on the adapter. For example, after a Token-Ring adapter has been initialized and in use for a period of time, a user may choose to have the adapter "pass Beacon MAC frames" to the system. This would most likely be required by an application being started which performs LAN management type functions. A very similar situation could occur for FDDI adapters and the processing of SMT frames.

The ModifyOpenParms request is most commonly passed to the NDIS device driver by the 802.2 protocol drivers when a DIR.OPEN.DIRECT or DIR.MODIFY.OPEN.PARMS CCB is issued in OS/2 or DOS, respectively. The OPEN_OPTIONS parameter contains the low-level adapter functions to be modified.

1.8.8 ResetMAC implementation

The purpose of the ResetMAC NDIS general request is to dynamically "issue a hardware reset to the network adapter" in order to recover from a fatal adapter error. If it isn't supported (support is optional), re-booting the system is the common procedure for invoking the device driver initialization code and therefore resetting the adapter.

As serious as it sounds, the ResetMAC general request has not been implemented because the adapters seldom have spurious fatal errors and the initialization code which would have to remain resident, is a burden in the DOS environment.

The most common error which the NDIS device driver/adapter have to recover from involves lobe wire faults. Recovery from lobe wire fault errors can be accomplished by re-opening the adapter when the fault has been corrected. It's not necessary to "issue a hardware reset to the network adapter" via ResetMAC to recover from a lobe wire fault error.

Even though ResetMAC is optional, it's analogous command in Novell's Open Data-Link Interface (ODI) specification is not. According to the ODI Developer's s Guide for DOS Workstation HSMs and ODI Developer's Guide for OS/2 Workstation Driversthe HSM or Driver I/O control routine of DriverReset "issues a hardware reset to the physical board". This is a factor when using the ODI-to-NDIS mappers because the DriverReset routine relies on the ResetMAC NDIS general request in order to reset the "physical board".

1.8.9 Remote Program Load (RPL) support

The description of the NDIS Bind system request states, "For compatibility with remote initial program load, MAC drivers must not manipulate the adapter at Init-time. The MAC driver is free to determine if the network adapter is present, but must leave any hardware manipulation to Bind-time processing."

Some initial IBM device drivers violate the NDIS specification in this area. The IBM FDDI Workstation Adapter drivers and the IBM Token-Ring Busmaster Server Adapter/A driver initialize the adapter at Init-time. These drivers function successfully with their respective adapters because the adapters do not support RPL. However, since these were some of the early drivers to be completed they have been used as code examples. The IBM Token-Ring 16/4 Adapter II drivers and the IBM LANStreamer* Adapter drivers initialize the adapter at Bind-time.

If a device driver initializes the adapter at Init-time, the RPL procedure will not succeed. The RPL procedure relies on a NetBIOS link being active between the RPL client and the RPL server. This link is maintained by the (DOS) device driver contained in the RPL boot block. Moreover, one of the files "downloaded" over this link is another copy of the device driver (or the OS/2 copy). This copy is "downloaded" by the processing of a CONFIG.SYS file from a redirected disk drive. If the "downloaded" instance of the device driver initializes the adapter at Init-time, the NetBIOS link will be lost between the RPL client and RPL server.

2.0 LAN Adapter option diskette issues

2.1 Directory structure

The device driver related directories of a LAN Adapter option diskette are listed in the following table.

Table 1. Device driver directories on Adapter option diskette

Directory	Contents
\	Adapter-specific files: .ADF, .DGS, main documentation file, etc.
\	All files for OS/2 NDIS device driver in IBM environments
\	Misc device driver install files (eg. OEMSETUP.INF for WFW)
\DOS	All files for DOS NDIS device driver in IBM environments
\NOVELL\OS2	All files for ODI OS/2 workstation driver
\NOVELL\DOS	All files for ODI DOS workstation driver
\NOVELL\NETWARE\286SERV	All files for IPX Netware LAN driver
\NOVELL\NETWARE\386SERV	All files for ODI Netware LAN driver

The OS/2 NDIS files are stored in the root directory because "A:\" is the default source drive and directory for the LAPS installation and configuration program. The DOS NDIS files are stored in the \DOS directory because "A:\DOS" is the default source drive and directory for the LAN Support Program's installation aid DXMAID.

2.2 Adapter-related files

The adapter-related files are usually provided by adapter development. This information is contained here to explain as much of the basic adapter option diskette as possible.

2.2.1 MCA - Adapter definition files and diagnostics

Adapter definition files (ADF) are required for Micro Channel* systems. The ADF file is used as configuration input to the Setup program on the reference diskette. The naming convention of the ADF files requires the filename of the ADF to begin with an "@", followed by the adapter ID. The extension is "ADF". For example, @8FC8.ADF is the ADF file for the IBM Token-Ring 16/4 Busmaster Adapter/A. The adapter's diagnostics program uses the same filename as the ADF, the extension is "DGS". For example, @8FC8.DGS.

2.2.1.1 Arbitration level 4

Micro Channel arbitration level 4 should not be used as a choice for the arbitration level. There was an old version of the Setup program which did not flag arbitration level 4 as "in use". This would allow undetected conflicts to occur. There are plenty of available arbitration levels without using level 4.

2.2.1.2 Busmaster adapters

Busmaster adapters should code the NODMA keyword in the ADF file to indicate that a DMA channel is not used by the adapter.

2.2.2 ISA

An ISA adapter may be shipped with a configuration program in place of an ADF file, since ADF files do not exist in an ISA system. Some ISA adapter's still have switches and are not software configurable.

2.2.3 EISA - Configuration files

EISA adapters are shipped with a configuration file, similar in function to an ADF file. The EISA configuration files begin with an "!" and have an extension of "CFG".

2.3 Documentation file requirements

The purpose of the documentation file is to provide all the information necessary to use the NDIS device driver. Therefore, the NDIS device driver doesn't have to be documented in the adapter's Installation and Testing manual. The Installation and Testing manual should direct the user to a documentation file on the option diskette, for device driver information. This file is usually a README-type file and it should reside in the root directory of the option diskette.

The documentation file can also be used to accommodate any adapter related information which wasn't available when hen the Installation and Testing manual was created. The softcopy form of the documentation file is meant to replace the distribution of a device driver hardcopy document.

2.3.1 Documentation file alternatives

Documentation files which address specific topics can be located in the appropriate directories. For example, a README file about LAN Support Program (eg. README.LSP) could be in the \NDIS\DOS directory. The main README file in the root directory should indicate where all the other documentation files are located.

The documentation scheme above does not guarantee that the documentation files will be copied off the adapter option diskette. If they are, they may be overwritten with another adapter's README files later. In order to provide documentation files that are installed along with device driver executables and not overwritten unintentionally, a documentation file should have the same filename as the executable and a "DOC" extension. For example, IBMFDDI.DOC This file could be added to the COPYFILE statement of the NIF to guarantee that it gets installed from the option diskette. Since it has a specific filename, it won't get overwritten as easily as a README-type file. Again, the main README file in the root directory should itemize all the documentation files on the adapter option diskette.

2.4 National Language Support (NLS) on option diskette

The adapter definition files and diagnostic program messages must be translated. The ADF translation guidelines are described in the Setup section of the PS/2 Hardware Interface Tech Ref - Architectures. For example, a prompt string can not exceed 38 characters. Usually the translators are aware of these guidelines. The translation rules for the diagnostic program are unique for each diagnostic program.

2.4.1 NLS alternatives

An option diskette is usually created to support either one language or all languages for a product. If the option diskette supports only one language, multiple language-specific option diskettes must be made. Otherwise, one option diskette contains all versions of the translated files.

For example, each IBM FDDI Workstation adapter's option diskette supports one language. The LT5.MSG file is a common file among all of the diskettes, but its contents are language-specific. The IBM FDDI Workstation adapter was translated for German, Italian and Japanese.

If one option diskette were created to contain all translated fries, "instructions" need to be supplied in order to use the correct translation of each file. These "instructions" could be manual directions or part of an automated procedure. The language-specific files might reside in unique directories, or they might all be in one directory with unique extension names. A common extension used to bring attention to language-specific files is the country code (eg. .049 for German or .001 for U.S. English). The list of available country codes is commonly documented in the operating system's command reference. The country codes supported by OS/2 2.0 are listed in the IBM Product Overview chapter.

2.4.2 Verification and testing

It's very important that the implementation of the translated files be verified, especially double byte character sets (DBCS).

Appendix A. NDIS driver driver checklists

The NDIS device driver checklists below should be the first items verified upon entering Functional Verification Test (FVT) and System Verification Test (SVT). Some of the "feature to verify" descriptions are abbreviated. Refer to the description of the feature earlier in the document for further details.

A.1 FVT checklist

Table 2. NDIS device driver deliverables

Feature to verify

DOS comments

OS/2 comments

Does driver executable have correct name?

Does external message file exist?

Does external msg file have correct name? (eg LTx.MSG)

Does external message help file exist?

NA, for now.

Does msg help file have correct name? (eg LTxH.MSG)

NA, for now.

Does Network Information file (NIF) exist?

Does NIF have correct name?

Do miscellaneous file(s) have correct name(s)?

Table 3. NDIS device driver Installation and Configuration

Feature to verify

DOS comments

OS/2 comments

Does SNIFFLE parse the NIF successfully?

Does NIF have executable filename in title?

Does DRIVERNAME match filename of executable?

Does DRIVERNAME string NOT end with a number?

Is NETADDRESS a PROTOCOL.INI keyword?

Is Group bit prevented from being set by NETADDRESS?

If Ethernet, is NETADDRESS in canonical form?

Configurable parms match across: .ADF, .NIF, README, etc?

Table 4. NDIS device driver message support

Feature to verify

DOS comments

OS/2 comments

Is copyright statement accurate?

Is copyright statement expanded in code?

Is copyright in code accurate?

Do the message prefix identifiers exist?

Are the message prefix identifiers correct? (eg LTxnnnnS)

Are the messages displayed to the console?

Are the messages logged to LANTRAN.LOG?

NA, for now.

Does help facility work with the external msg help file?

NA, for now.

Table 5. NDIS device driver Initialization

Feature to verify

DOS comments

OS/2 comments

Does each PROTOCOL.INI parm have accurate error msg?

Does each parameter have a syntax error msg?

Is the default for each parameter successful?

Is the maximum for each parameter successful?

Is the (maximum+ 1) for each parameter successful?

Is the minimum for each parameter successful?

Is the (minimum-l) for each parameter successful?

Does each parm function at the default value?

If init errors, does NETBIND fail?

Do multiple adapters initialize successfully?

Table 6. ADF file (for Micro Channel adapters only)

Feature to verify

DOS comments

OS/2 comments

Is arbitration level 4 for Busmasters omitted?

Is the NODMA keyword coded for Busmasters?

Is the help text for each choice accurate?

Is the default for each parameter successful?

Is the maximum for each parameter successful?

Is the (maximum+ 1) for each parameter unsuccessful?

Is the minimum for each parameter successful?

Is the (minimum-l) for each parameter unsuccessful?

A.2 SVT checklist

Table 7. NDIS device driver run-time functions

Feature to verify

DOS comments

OS/2 comments

Is InterruptRequest supported for DOS?

NA.

Is interrupt sharing supported?

Is the 16MB boundary checked?

Is IndicationComplete re-entrant?

Do multiple adapters operate successfully?

Is IndicationComplete call re-entrant?

Does the device driver recover if cable pulled?

Can LNM access the Adapter Status Parms table (TR only)?

Appendix B. IBM MAC device drivers

Table 8. NDIS device drivers

DOS device driver

OS/2 device driver

Adapter product

IBMTRDB.DOS

IBMTRDB.OS2

LANStreamer Adapter

IBM16TR.DOS

IBM16TR.OS2

Token-Ring Network 16/4 Adapter II

IBMFDDI.DOX

IBMFDDI.OS2

FDDI Workstation Adapters

IBMENI.DOS

IBMENI.OS2

LAN Adapter for Ethernet

IBMENII.DOS

IBMENII.OS2

LAN Adapter/A for Ethernet

IBMTOK.DOS

IBMTOK.OS2

Token-Ring Network Adapter II, Token-Ring Network 16/4 Adapter, Token-Ring Adapter II/A, Token-Ring Network 16/4 Adapter/A, Token-Ring Network PS/2 Model P70 386 Adapter/A

IBMNET.OS2

PC Network Broadband Adapter II, PC Network Adapter II Frequency 2, PC Network Adapter II Frequency 3, PC Network Baseband Adapter II

IBMNETA.OS2

PC Network Broadband Adapter II/A, PC Network Adapter II/A Frequency 2, PC Network Adapter II/A Frequency 3, PC Network Baseband Adapter II/A

IBMTRBM.OS2

Token-Ring Network 16/4 Busmaster Server Adapter/A

IBMXLN.DOS

IBMXLN.OS2

3174 Peer Communications

Table 9. Novell device drivers

DOS Workstn

OS/2 Workstn

286 Server

386 Server

Adapter product

IBMTRDBO.LAN

LANStreamer Adapter

TOKENBM.COM

TOKENBM.SYS

TOKEN.LAN
TOKENBM.LAN

TOKENBM.LAN

Token-Ring Network 16/4 Adapter II

IBMFDDIO.COM

IBMFDDIO.OS2

IBMFDDIO.LAN

FDDI Workstation Adapters

IBMENIO.COM

IBMENIOP.SYS
IBMENIOS.SYS

NE2000A1.LAN
NE2000A2.LAN

IBMENIO.LAN

LAN Adapter for Ethernet

IBMENIIO.COM

IBMENIIO.SYS

IBMENIIO.LAN

LAN Adapter/A for Ethernet

Appendix B. IBM MAC device drivers

Table 10. Defined IBM message prefixes

Prefix

Device Driver

LT0

802.2 and NetBIOS protocol drivers (LANDD.OS2 and NETBEUI.OS2)

LT1

IBM PC Network MAC drivers

LT2

IBM Token-Ring Network driver

LT3

IBM 3174 Peer Communication Network driver

LT4

IBM Token-Ring Network 16/4 Busmaster Server Adapter/A driver

LT5

IBM FDDI Workstation Adapter driver

LT6

IBM LANStreamer Adapter

LT7

LT8

IBM ODI2NDI Enablers

LT9

LTA

IBM LAN Adapter for Ethernet driver

LTB

IBM LAN Adapter/A for Ethernet driver

LTC

In development

LTD

In development

LTE

In development

LTF

In development

LTG

In development

Table 11. Other message prefixes

Prefix

Device Driver

PRO

Protocol Manager

BRZ

IBM Token-Ring Network 16/4 Adapter II

UBI

Ungermann-Bass** NUIpc** and NUIps/2**

ETH

IBM Adapter/A for Ethernet Networks driver

MAC

SMC EtherCard PLUS** and PLUS/A**

MAC

3Com** Etherlink II** and EtherLink/MC** (Note, no external message file)

Notices

May, 1993

Issued by:

IBM Corporation
Personal Software Products
11400 Burnet Road
Austin, Texas 78758

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.

Requests for copies of this publication and for technical information about IBM products should be made to your IBM Authorized Dealer or your IBM Marketing Representative.

Copyright Notices

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

Disclaimers

References in this publication 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 IBM's intellectual property rights or other legally protectible rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility.

IBM may have patents or pending patent applications covering subject matter in 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.

Trademarks

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

IBM	OS/2	LAN Adapter and Protocol Support
DOS	NTS/2	Micro Channel
Extended Edition	LANStreamer

The following terms, denoted by a double asterisk (**) in this publication, are trademarks of other companies as follows:

3Com	3Com Corporation
EtherLink II	3Com Corporation
EtherLink/MC	3Com Corporation
LAN Manager	Microsoft Corporation
Microsoft	Microsoft Corporation
EtherCard PLUS	Standard Microsystems Corporation
EtherCard PLUS/A	Standard Microsystems Corporation
NUIpc	Ungermann-Bass Corporation
NUlps/2	Ungermann-Bass Corporation
Ungermann-Bass	Ungermann-Bass Corporation

IBM OS/2 LAN Server 3.0 Product Overview

Preface
1.0 Introduction
2.0 IBM OS/2 LAN Server Version 3.0
2.1 Technical Update
2.2 Highlights
2.3 New Features Common to Entry and Advanced
- 2.3.1 Network Transport Services/2
- 2.3.2 Redirected Installation enablement
- 2.3.3 Peer Service
- 2.3.4 Optional Client Full-Screen Interface
- 2.3.5 System Management
- 2.3.6 DOS LAN Requester Virtual DOS LAN API Support
- 2.3.7 DOS LAN Requester Support of DOS 5.0 Task Switching
- 2.3.8 TCP/IP Coexistence
2.4 Features Unique to the Advanced Server
- 2.4.1 386 HPFS on OS/2 2.0
- 2.4.2 Greater than 16MB Support
- 2.4.3 Fault Tolerance
- 2.4.4 Local Security
3.0 Standard Features
3.1 Administration
- 3.1.1 Single System Image
- 3.1.2 Remote Administration
- 3.1.3 Server Monitoring
- 3.1.4 Remote Initial Program Load (IPL)
- 3.1.5 Operators
- 3.1.6 Timesource
- 3.1.7 Replicator Service
3.2 Installation
- 3.2.1 OS/2 (Server/Requester)
- 3.2.2 DOS LAN Requester
3.3 Security
- 3.3.1 User Profile Management
- 3.3.2 Password Encryption
- 3.3.3 Access Control Profiles
- 3.3.4 Local Security
- 3.3.5 Audit Trail
- 3.3.6 Alert Support
3.4 Fault Tolerance
- 3.4.1 UPS Support
- 3.4.2 Disk Mirroring and Duplexing
3.5 DOS Requester Functions
3.6 Application Coexistence
- 3.6.1 LAN Server Applications
- 3.6.2 Microsoft LAN Manager
4.0 Machine Requirements
4.1 LAN Server 3.0 - Entry or LAN Server 3.0 - Advanced
4.2 OS/2 LAN Requester
4.3 DOS LAN Requester
4.4 OEM Systems
4.5 OS/2 LAN Server for Macintosh Version 1.0
4.6 Hardware Adapter Support
- 4.6.1 PC Network and Token-Ring Support
- 4.6.2 Ethernet Support
- 4.6.3 3174 Peer Communications
- 4.6.4 Remote IPL Support
- 4.6.5 Device Driver Support of Additional LAN Adapters
5.0 Migration Considerations
5.1 Coexistence of LAN Servers in a Single Domain
5.2 Interoperability between LAN Servers and LAN Requesters
5.3 Logon and Administrative Capabilities
5.4 Access to External Resources
6.0 Product Direction
6.1 Distributed LAN System Evolution
6.2 The Future
Notices
- Copyrights
- Disclaimers
- Trademarks

Preface

This document provides information concerning the latest version of IBM* OS/2* LAN Server from the Personal Software Products organization in Austin, Texas USA. The Technical Update section covers items to be announced in this release of the product.

This release of IBM OS/2 LAN Server Version 3.0 delivers functions and features that have been gathered from customers, industry experts, and shaped by keen competition in the LAN industry. This release confirms IBM's commitment to be the leader in LAN systems. IBM OS/2 LAN Server Version 3.0 is the first LAN system to exploit the power of OS/2 2.0 and take advantage of the evolving processor technology. With this release IBM becomes the industry leader in network operating system (NOS) performance on DOS, Windows**, and OS/2.

The Austin Personal Software Products organization has been involved with LAN systems from the PC LAN Program (PCLP) to LAN Server 3.0. IBM has the technology, skills, and strategy required to provide world class LAN solutions that fit users' needs today and guarantee their investment in the future.

1.0 Introduction

IBM OS/2 LAN Server Version 3.0 is the first network server product to fully exploit the power of OS/2 2.0. With the advent of OS/2 2.0, the client-server model of networked workstations changed dramatically. OS/2 2.0 provides a true preemptive multiprocessing environment that benefits both client and server. No longer are you limited to a single client on a workstation, a dedicated server, or fragile communications. On top of this solid base is a user interface that allows transparent network access - no more groping on that foreign command-line interface.

When combined with Extended Services for OS/2* (Communications Manager and Database Manager), IBM OS/2 LAN Server Version 3.0 provides the most comprehensive integrated network solution in the industry. Allowing a single workstation to access a wealth of resources including files, printers, serial devices, applications, relational databases, and communications with the largest of mainframes. At the same time, while operating flawlessly with IBM solutions, IBM OS/2 LAN Server Version 3.0 provides interoperability with industry solutions (Novell NetWare**, Microsoft LAN Manager**, Bayan VINES**, and Artisoft Lantastic**).

IBM OS/2 LAN Server Version 3.0 release is available in two separate packages. The Entry server is a price competitive offering that includes new system management features and redirected installation support. This version is an ideal choice if you are just entering the world of networking. The next step is the Advanced server. It contains all the features available in the Entry server, plus the 386 high performance file system and enhanced Fault Tolerance. The Advanced server provides industry performance leadership, rated highly overall in a recent LANQuest survey (LAN Server, NetWare and LAN Manager, Performance Benchmark Comparison, LANQuest, June 1992). The fault tolerance capabilities provide comprehensive protection for mission-critical applications and data.

IBM OS/2 LAN Server Version 3.0 is a single byte character set (SBCS) / double byte character set (DBCS) converged product. That means there is a single source and single object code for the worldwide product. This allows rapid delivery of the product throughout the world and delivers the strongest national language support in the server business. National Language Versions (NLVs) of IBM OS/2 LAN Server Version 3.0 are provided to support the user's native language.

Note: When the term DBCS is used in this document, the intent is to address the DBCS considerations of the product in the Japanese (Japan), traditional Chinese (Taiwan), and the Korean (Korea) versions of the product.

2.0 IBM OS/2 LAN Server Version 3.0

2.1 Technical Update

The following new features are included in both the Entry and Advanced versions: NTS/2, Enhanced multi-adapter, Redirected installation enablement, Full domain control database API, Peer service, Optional client full-screen interface, and OS/2 TCP/IP coexistence.

The Advanced server product now running on the OS/2 2.0 base, provides the benefits of the 386 high performance file system, includes improved disk fault tolerance, and, combined with the IBM PS/2* Server 295, provides an asymmetrical multiprocessing environment.

Available with OS/2 LAN Server Version 3.0 are the DOS LAN Requester (DLR) and the OS/2 Requester. DOS LAN Requester and the IBM LAN Support Program Version 1.31, offer significant performance improvements over the previous DOS LAN Requester. The OS/2 Requester has been enabled for redirected installation and has numerous performance improvements.

Both DOS LAN Requester (DLR) and OS/2 Requester are available separately as Distributed Features. Distributed Features allow the purchase of a client license without regard to the number of of servers accessed and purchase of the exact number of licenses required. A distributed feature only provides the license to copy the client in your LAN Server package, no additional diskettes or publications are provided.

OS/2 LAN Server for Macintosh** Version 1.0 broadens the scope of support for the IBM OS/2 LAN Server product. With LAN Server for Macintosh, DOS, OS/2 and Mac clients can access files created by each other. LAN Server for Macintosh will provide the AppleTalk** File Server, Print Server functions, and Macintosh Print Monitor (over Token-Ring or Ethernet), which may be integrated into the OS/2 LAN Server environment.

2.1 Technical Update

OS/2 LAN Server Version 3.0 Entry and Advanced share numerous new features over previous versions of OS/2 LAN Server. These features are as follows:

Network Transport Services/2
Redirected installation enabled
Peer service
Enhanced multi-adapter support
Optional client full-screen interface
System management enhancements
DOS LAN Requester Virtual DOS LAN API support
DOS LAN Requester Support of DOS 5.0 task switching
DOS LAN Requester Windows DBCS-enabled user interface
DOS LAN Requester performance enhancements
TCP/IP coexistence

OS/2 LAN Server Version 3.0-Advanced has the following unique features

386 high performance file system
Supports greater than 16MB of memory
Improved disk fault tolerance (mirroring and duplexing)
- Remirror without format
- Mirror of the boot drive
Local security

2.3 New Features Common to Entry and Advanced

2.3.1 Network Transport Services/2

NTS/2 is an IBM product that provides network support for IBM 1.3 and IBM OS/2 2.0 operating systems and is included with IBM OS/2 LAN Server Version 3.0. The network support is based on the NDIS 2.01 specification. This product supplies the NETBIOS and IEEE 802.2, protocol NETBIOS VDD, and many network adapter drivers to support, networking applications. In addition to NETBIOS and 802.2 protocol support two additional features, which were not previously available, are supplied. This includes Novell ODI interface support and 802.2 VDD support. By supplying the ODI compatible protocol, Novell requesters, can be integrated on a hardware platform giving the Novell requester, the IBM LAN requester, and other applications the ability to share adapters with no difficulty.

802.2 VDD support eliminates the need for a dedicated network adapter for 802.2 DOS and Windows applications. This support allows sharing of adapters between 802.2 DOS and Windows applications, DOS and Windows NETBIOS applications, and OS/2 2.0 networking applications.

Other features of NTS/2 include a configuration utility, enhanced multi-adapter support, and remote installation support.

The configuration utility, called LAN Adapter and Protocol Support, (LAPS) has a simple-to-use Presentation Manager interface to aid in the configuration of adapters and protocols. The LAPS eliminates the need for manual, update of the PROTOCOL.INI and CONFIG.SYS files.

The LAN Configuration Installation Distribution Utility (LAN CID Utility) provides for the redirected (network) installation of OS/2 2.0, Extended Services, OS/2 LAN Server, and other applications. The redirected installation supports unattended modes for installation and configuration.

The enhanced multi-adapter support, when combined with the support in IBM OS/2 LAN Server Version 3.0, enables up to 1016 LAN Requesters to connect to a LAN Server across multiple adapters.

2.3.2 Redirected Installation enablement

The IBM OS/2 LAN Server Version 3.0 product makes possible the installation of requesters and servers in a remote and unattended manner. Remote installation is a form of redirected installation which supports the loading of code on workstations over the LAN from a designated code server. The code server can use the existing transport or can use the Service Installable File System (SRVIFS) provided by Network Transport Services/2 and can be either an OS/2 LAN Server or an OS/2 workstation with a Server Installable File System (SRVIFS). This second option can be achieved by installing:

NetView Distribution Manager/2 Version 2.0, which provides the unattended installation of OS/2 and DOS system and application software on standalone and host-connected LANs. In host connected LANs, when used with NetView Distribution Manager for MVS, the distribution and installation can be initiated from the host.

- or

Network Transport Services/2, which provides the lightly attended installation of OS/2 software on the LAN.

2.3.3 Peer Service

The Peer service feature gives a requester some of the capabilities of a server. This feature may be used with the server or in a standalone environment.

Once the Peer service is running, use of requester resources is no longer limited to the owner of the requester. The owner can create shares for the requester, just as a network administrator creates shares for a server. Other users can NET USE the peer server resources just as with a full server (the peer server name is the same as the requester name). The server code is not required to be present on the requester to benefit from the Peer service function.

The Peer service allows the owner to share directories, one printer, and one communication-device queue with other users on the network. It lets one user at a time connect to (that is, create a session with) the peer server. This differs from an OS/2 LAN Server, which allows sessions with multiple requesters. Peer named pipes are also supported, but are not limited to a single session.

The NET SESSION command has been enhanced to allow users to see who is connected to a server. This allows a user who is denied access to a peer server because of the session limit to find out who is currently connected to the peer server.

2.3.4 Optional Client Full-Screen Interface

Often, workstations are used by general users who have no need to perform server administrator tasks. In this case, there is no need for users to install the LAN Requester full screen interface (FSI) on the hard disk. These users may load the full-screen interface from a server. This allows the users to conserve approximately 2.5MB of disk space on their workstation.

2.3.5 System Management

2.3.5.1 First Failure Support Technology/2* (FFST/2)*

FFST/2 provides superior and consistent RAS functions to the customer. In the event of an error, error data can be captured and reported.

The intent is to migrate the current detection points to FFST/2. OS/2 LAN Server 3.0 contains software detection points that interrogate return codes, and if an error condition is indicated, an entry is made in the LAN error log. The code has been modified so each current detection point will write the error information into an FFST/2 structured error log. This enables LAN Server to comply with the standard IBM RAS structure.

2.3.5.2 Performance Hooks to Support PERFVIEW

OS/2 2.0 supports an architected performance hook technology and collection mechanism known as "Perfview". The Perfview performance hook types consist of counters, timers, and queues. A set of APIs are supported that allow applications, device drivers, and file system drivers to register information with the kernel. System Performance Monitor/2 (SPM/2) relies on this capability to monitor and manage system performance. This allows the administrator to tune a LAN system.

2.3.5.3 Softcopy Publications

The publications for IBM OS/2 LAN Server Version 3.0 are offered separately in displayable softcopy form. The files are shipped on the same media type as the basic machine-readable material.

These displayable manuals can be used with the BookManager* READ licensed programs in any of the supported environments.

2.3.5.4 SNAP DUMP Facility

The SNAP DUMP facility enables a customer having a software problem to easily capture all the related information requested by the support personnel. This information is typically dispersed throughout the system and require. Many steps to capture completely. A generic ASCII file will define what should be dumped and allow the system data to be captured in a single file.

2.3.5.5 All Domain Control Database (DCDB) Access via Remote API

This API allows application developers to use published interfaces to manipulate user information on the domain Controller. This API simplifies the migration of OS/2 LAN Server into the Distributed Computing Environment (DCE). It also allows application developers to create system management tools.

2.3.6 DOS LAN Requester Virtual DOS LAN API Support

The DOS LAN Requester Virtual DOS LAN API Support enables DOS applications running in the Virtual DOS Machine environments of OS/2 2.0 (including WIN-OS/2)* to call the LAN APIs without having to load the DOS LAN Requester code.

2.3.7 DOS LAN Requester Support of DOS 5.0 Task Switching

One of the features of the IBM DOS Shell is the ability to run two or more application programs at one time. A limited (Suspend/Resume) application task switcher called Task Swapper is provided in the shell, which allows the customer to switch from one application to another without closing applications. DOS LAN Requester supports this application task-swapping.

The Active Task List displays the names of programs that have been started. Programs are added to the Active Task List by starting the program from the IBM DOS Shell. Switching to active programs is done through the Active Task List or by cycling through the programs in the Active Task List using the ALT and TAB keys. To remove a program from the Active Task List, the user must exit the program.

2.3.8 TCP/IP Coexistence

OS/2 LAN Server 3.0 coexists with the existing IBM TCP/IP product. In addition the LAN Server can use the IP network to communicate. In this environment, both the sever and requester are required to use the IP protocol provided by TCP/IP for OS/2 and NETBIOS for TCP/IP products from IBM.

The current release of TCP/IP from IBM shares the common LAN Adapter and Protocol Support with the LAN Server. In the past, customers have used this Support, provided by the NETBIOS for TCP/IP program with the IBM TCP/IP program. In this release, the environment is supported.

NETBIOS is a programming interface used in a large inventory of PC-based local area network (LAN) customer application programs. TCP/IP is a networking protocol used in LAN and wide area networks (WANs) to facilitate communications among heterogeneous, multi-vendor system environments. The TCP/IP protocol has standards defined, specifically request for comments (RFC) 1001 and RFC 1002, which provide the ability to encapsulate NETBIOS application traffic and send it over the TCP/IP network.

Installing this module onto the workstation effectively replaces the native NETBIOS module normally used for NETBIOS-to-NETBIOS traffic on the LAN. Therefore, once installed, only the TCP/IP path is used for communication.

Note: Remote IPL is not supported in this environment.

2.4 Features Unique to the Advanced Server

2.4.1 386 HPFS on OS/2 2.0

The Advanced product runs on an OS/2 2.0 operating system and is a highly optimized network server designed for advanced 386/486-based platforms with very large hard drives. It consists of an optimized Ring 0 server tightly coupled with bootable installable high performance file system (386 HPFS) and customized device drivers to accelerate network file I/O.

2.4.2 Greater than 16MB Support

OS/2 2.0 allows access to greater than 16MB of memory. OS/2 1.3 allowed a maximum of 16MB. Because the 386 HPFS is capable of using massive amounts of memory for its cache, its performance is greatly improved by allowing access to memory beyond 16MB.

2.4.3 Fault Tolerance

Fault Tolerance now provides two new key features: remirror without format and the capability to mirror the boot drive. Remirror without format simplifies the recovery of a detached secondary drive. The process is as simple as using the FTSETUP program to recover the drive and rebooting the system, saving time and steps required to back up and restore the complete drive.

2.4.4 Local Security

The Local Security feature of the 386 high performance file system (HPFS) provides file protection against unauthorized access to any server file. This protection cannot be evaded by rebooting the server and is functional even when the LAN Server code is not running. This protection applies to all files stored on the 386 HPFS file partition.

3.0 Standard Features

3.1 Administration

3.1.1 Single System Image

A domain is the logical grouping of one or more servers in a local area network. This grouping is referred to as a Domain and is defined by a network administrator. This association allows a user to log on to a domain and gain access to resources on the individual servers. The single systems image allows the user, when logged on, to view both local and remote resources as if the resources were all part of the local workstation.

3.1.2 Remote Administration

The network administrator can perform administrative tasks on a given domain from an OS/2 requester on the LAN. The network administrator creates and maintains the domain definitions centrally stored in the domain control database on the domain controller, a role given to one of the senders in the domain at server installation time.

3.1.3 Server Monitoring

Extensive capabilities allow the network administrator to determine the status of server resources, list utilization statistics, view error logs, identify logged-on users, monitor attempts to log on with an invalid password, or invalid attempts to access resources, receive alerts (informative messages) when events of interest occur, and so on. 0S/2 LAN Server provides not only security related information but also diagnostic and resource usage information to the network administrator.

3.1.4 Remote Initial Program Load (IPL)

Remote IPL supports workstations with or without local media in both a DOS and an OS/2 environment. The remote IPL feature mimics the normal boot process of a PC Booting from a local drive with several slight variations, which allow the boot information to come from the network, rather than from the computer's hard disk or diskette drive. Remote IPL for both DOS and OS/2 is supported over Token Ring, PC Net, and Ethernet. A single server can provide this Remote IPL service to workstations connected to the network via IBM bridges. A full screen interface is provided to support the remote IPL function. The remote IPL function supports DOS 3.3, 5.0, and OS/2 2.0. This remote IPL facility allows the Remote IPLing of additional functions, such as Extended Services features, via network administrator manipulation of the product-provided standard IPL definitions. The requesters shipped with OS/2 LAN Server 3.0 are supported as part of the remote IPL process, as are the DOS and OS/2 LAN Transports and adapter drivers.

In the remote IPL environment, the user-selected boot configuration function provides, via a Presentation Manager application, a means to request an alternate boot to an OS/2 remote IPL requester. For example, the function provides the capability of remote IPLing a different version of OS/2 than is installed at the remote IPL server, a PS/2 reference diskette, or an occasionally used DOS application that does not run in the OS/2 MVDM.

3.1.5 Operators

There are three basic user types: USER, GUEST, and ADMINISTRATOR. A USER can access LAN resources as defined by the ADMINISTRATOR. The GUEST is a special user type that permits USER IDs not explicitly defined in the domain to have access to a specified set of LAN resources. The ADMINISTRATOR type is the network administrator and has overall control of domains on the LAN. The ADMINISTRATOR can delegate management of any of the following areas to an OPERATOR (e.g. any USER ID) by specifying (via the /OPERATOR parameter of the NET USER command) the appropriate sub-level of authority:

Server	Lets a user control shared resources on a server, read and clear the errorlog, and close sessions and files that are open. User control is through the command-line interface.
Accounts	Lets a user control user and group accounts (for example add, delete, and modify user accounts, and update logon requirements for the user accounts database). This operator privilege does not allow a user to grant administrative privilege or assign operator privilege. User control is through the command-line interface and User Profile Management.
Print Queues	Lets a user control shared serial communication devices. User control is through the command-line.
Communications Queues	Lets a user control shared serial communication devices. User control is through the command-line interface.

3.1.6 Timesource

This feature allows a domain controller to be designated as the network time server. This function is provided for use by applications that need to synchronize their time with a designated time source server. A bit is set (SV_TYPE_TIME_SOURCE) that identifies a server as the time source. This bit can be queried through use of either the NetServerEnum or NetServerGetlnfo APIs. NetServerEnum2 can be used to obtain a list of the time servers in up to four other domains by specifying these domains on the /OTHDOMAINS line in the IBMLAN.INI file or in the /OTHDOMAINS parameter on the NET START REQUESTER command. NetRemoteTOD can be used to obtain the time and date information from the time server.

3.1.7 Replicator Service

LAN Server provides a powerful Replicator service that helps make network administration easier and more efficient. This service allows a set of files stored on one server to be selectively replicated to other servers or OS/2 LAN requesters on the network. Replication can be used to distribute any administrative or application-related files.

3.2 Installation

3.2.1 OS/2 (Server/Requester)

A Presentation Manager application provides the capability to install, configure, and remove the LAN Server and OS/2 LAN Requester on all supported hardware platforms.

Installation of the LAN Server 3.0 product requires the OS/2 2.0 operating system.

3.2.2 DOS LAN Requester

An installation program is also provided for the installation of DOS LAN Requester.

3.3 Security

3.3.1 User Profile Management

User Profile Management (UPM) performs the user ID and password validation function at logon time. UPON also provides facilities for the management of user IDs and Groups within the domain.

A network administrator has a wide range of mechanisms with which to control and manage user access to the network. A network administrator has the ability to define:

Valid logon times	Permitted logon times can be specified in weekly intervals, such as Monday, Wednesday and Friday between 9 A.M. And 7 P.M.
Valid workstations	By default, a user can log on from any workstation on the network; however, the administrator can specify one to eight workstations to which a user is restricted.
Account expiration date	Individual accounts can be set to expire on specified dates. This is useful for temporary employees and classroom environments.
Forced logoff	When a user's account expires or the limits of a valid logon time are reached, the system can be set to force the user to logoff immediately, grant the user a specified grace period before an automatic logoff occurs or ignore the expiration and let the user continue working.

3.3.2 Password Encryption

OS/2 LAN Server uses the U.S. Government Data Encryption Standard (DES) encryption algorithm to encrypt passwords. Network administrators can also use the following system-wide settings to control the use of passwords:

Minimum password length	Specifies the required number of characters.
Maximum password age	Forces users to change their password at specified intervals.
Minimum password age	Stop users from altering their passwords until a specified interval has passed.
Unique password history	Ensures that a password chosen by a user is different from as many as eight of the user's previous passwords.

3.3.3 Access Control Profiles

Once a user is logged on to a domain, the user's access to a given resource is controlled by the access control profile for that given resource. The permissions which follow can be specified in an access control profile allowing flexibility in that combinations of appropriate permissions may be constructed to give very specific control to a user:

None	No access to the resource.
Execute	Use the resource (an application program), but not able to copy to your diskette or hard disk.
Read	Read Only.
Write	Write Only.
Create	Create a file or directory.
Delete	Delete a file or directory.
Attribute	Change the attributes of a file.
Permission	Gives a User the ability to grant other users access to this resource.

By default, all resources are protected. A network administrator can grant permissions to groups as well as individual users. Creating groups of users with similar resource needs makes it easier to grant access permissions. New users added to an existing group inherit the permissions previously given to the group. An administrator can effectively manage the resources in the network by using a combination of group designations and permissions.

3.3.4 Local Security

There are several facilities available to secure an OS/2 LAN Server that may not be locked away in a room of its own. The PS/2 hardware provides a power-on password facility, which disables the machine on startup until the correct password is provided. Another password facility allows the locking of the keyboard for those times when the operator is temporarily away. A Server Mode function is also available, which automatically disables input at startup but allows the machine to come to full readiness without operator interaction. The 386 high performance file system (HPFS) provides file protection against unauthorized access to any server file. This protection cannot be evaded by rebooting the server and is functional even when the LAN Server code is not running. This protection applies to all files stored on the 386 HPFS file partition. The 386 HPFS is available with-the Advanced server only.

3.3.5 Audit Trail

A comprehensive audit trail facility enhances security by enabling administrators to keep track of selected server resources. Any network resource, such as a directory, individual file, a named pipe, or a printer queue, can be designated to audit resources. Resource audit can provide data on the type of access (open, close, read, write, and so on), user name, accessing workstation, date and time of occurrence, outcome of the access, and descriptive information about the event. Server audit can keep track of when the sender is started, stopped, paused, or continued; all logons and logoffs; and all remote administration connections. The administrator also has the ability to audit changes to the user and group accounts database and to audit changes to the access control list.

3.3.6 Alert Support

Detailed, informative messages (alerts) are sent to designated users or administrators on the LAN when events of interest occur. Alerts are sent for printer or disk problems (printer out of paper, server disk is almost full); security problems, such as attempts to violate security (excessive password violations); or excessive entries in the error log (error log nearly full). When alerts are sent, all pertinent data is recorded, including the server name, date and time of alert, a description of the problem, and the recommended action.

First Failure Support Technology (FFST/2) provides superior and consistent reliability and serviceability (RAS) functions to the customer. If an error occurs, FFST/2 Supports the capturing and recording of error data and reporting of the error. This facility removes the necessity of having to recreate problems in the defect correction process. FFST/2 functions include:

Error logging
Message logging
Dump process
Generic alert building

Generic alerts are generated, formatted in Network Management Vector Transport (NMVT) format, and then sent to IBM LAN Network Manager or NetView when critical system situations occur. Generic alert supports detection points to detect the critical situations, generates and builds the NMVT formatted alert, and transports the alert to a host system or focal point.

3.4 Fault Tolerance

3.4.1 UPS Support

The Uninterruptible Power Supply (UPS) support provides warning and orderly server shutdown facilities when used with a compatible uninterruptible power supply available from a variety of vendors. The power supply signals the software through the serial port.

3.4.2 Disk Mirroring and Duplexing

Disk mirroring allows the duplication of data on another drive attached to the same disk controller. Disk duplexing allows this duplication on a drive attached to another disk controller. This feature also provides error logging, alerting, and monitoring of disk activity in a mirrored, duplexed, or standard server disk subsystem. Both mirroring and duplexing are available with the Advanced product only. This is in addition to the HOTFIX service available on both products, which provides for an automatic attempt to recover from an initial data write error by transferring data from flawed disk areas to writable disk space.

3.5 DOS Requester Functions

An improved synergy between DOS LAN Requester (DLR) and Microsoft Windows is provided. This allows users of Windows to access network files, printers, applications, and other services available on a LAN Server domain through the graphical user interface of Windows. The DLR user can do the following through Windows:

Log on and log off a LAN Server domain and modify logon assignments.
View, connect, and disconnect available LAN Server shared filesets.
View, connect, and disconnect available LAN Server shared printers.
View, install, and use available LANT Server shared applications.
Send messages to other network users.

DOS LAN Requester is able to accept double byte character set (DBCS) characters in command-line parameter strings.

The DBCS printer support makes possible the use of those printers unique to the DBCS environment.

3.6 Application Coexistence

3.6.1 LAN Server Applications

Applications written to the OS/2 LAN Server 2.0 APIs will be compatible with the LAN Server 3.0 product. The OS/2 LAN Server 2.0 command line commands are compatible with those in the LAN Server 3.0 product.

A Domain Control Database (DCDB) Migration Utility is provided to assist in the Migration of a PC LAN Program Version 1.3 environment to a LAN Server 3.0 environment. The Migration Utility preserves the data integrity and consistency of the definitions in the domain. A migration guide provides scenarios with step-by-step procedures for completing the migration. Upgrading from LAN Server 1.3 or LAN Server 2.0 does not require the execution of the migration utility.

3.6.2 Microsoft LAN Manager

LAN Server 3.0 will interoperate with the requesters from Microsoft LAN Manager 2.1. The requesters from LAN- Server 3.0 will interoperate with Microsoft LAN Manager 2.1.

Note: Names are restricted to eight characters on LAST Server.

4.0 Machine Requirements

4.1 LAN Server 3.0 - Entry or LAN Server 3.0- Advanced

IBM OS/2 LAN Server 3.0-Entry and Advanced support the appropriately configured hardware platforms that are supported by OS/2 2.0. Besides supporting appropriately configured IBM hardware, the Entry and Advanced products also support selected OEM equivalent hardware that has passed the OS/2 compatibility test. The approved platforms are listed in numerous forums and publications.

4.2 OS/2 LAN Requester

OS/2 LAN Requester supports the appropriately configured hardware platforms supported by OS/2 2.0.

4.3 DOS LAN Requester

DOS LAN Requester supports the appropriately configured hardware required to support the DOS 3.3 or 5.0 operating systems, or approved equivalents.

4.4 OEM Systems

IBM certification testing has been completed on various OEM hardware. LAN Server 3.0 is supported on those OEM platforms that are listed in Prodigy, CompuServ,, and under OS/2 forums.

4.5 OS/2 LAN Server for Macintosh Version 1.0

OS/2 LAN Server for Macintosh Version 1.0 supports the appropriately configured hardware platforms supported by LAN Server 3.0- Entry or LAN Server 3.0 - Advanced. The Macintosh workstations must be configured to support AppleTalk.

4.6 Hardware Adapter Support

Multiple adapter support consists of the ability to manage four logical networks concurrently. Token-Ring, Ethernet, and PC Network adapters are supported. The multiple adapter support is expected to be used primarily on servers; however, this support is available on requesters as well. A maximum of 254 NETBIOS sessions is supported per adapter card.

OS/2 LAN Server's support of the Network Driver Interface Specification (NDIS) makes it possible to support LAN adapter cards with NDIS compliant device drivers. Drivers for the OS/2 environment are shipped with the OS/2 LAN Server 3.0 products for the currently supported LAN adapters. The NDIS interface is publicly documented and supported. In addition to support of NDIS compliant adapters, a loop back driver is included for communication back to the same system.

4.6.1 PC Network and Token-Ring Support

The IBM PC Network adapter must be the primary network adapter if it is the only adapter on the workstation.

A workstation equipped with one of the following combinations of IBM PC Network and IBM Token-Ring Network adapters cannot have any other IBM PC Network adapter or IBM Token-Ring Network adapter:

Two IBM Token-Ring Network adapters
Two IBM PC Network adapters
One IBM PC Network adapter and one IBM Token-Ring Network adapter
One IBM PC Network adapter and one IBM Token-Ring Network adapter (the IBM PC Network adapter must be the primary adapter)

Note: Only four instances of the IBM Token-Ring Network 16/4 Busmaster Server Adapter/A can be installed on the same workstation.

4.6.2 Ethernet Support

A workstation cannot have more than two SMC (formerly Western Digital) adapters, two Ungermann-Bass* adapters, or two instances of the IBM PS/2 Adapter for Ethernet Networks.

4.6.3 3174 Peer Communications

The 3174 Peer Communications function provides peer-to-peer communication for programmable workstations connected to an IBM 3174 Control Unit through IBM 3270 communication adapters using coaxial cable or telephone twisted-pair wire. An OS/2 LAN Server or OS/2 LAN Requester workstation can support up to two 3270 communication adapters configured for 3174 Peer Communications at a time.

4.6.4 Remote IPL Support

Servers providing the Remote IPL service can be equipped with any adapter supported by OS/2 LAN Server 3.0. that has Remote IPL capability.

Remote IPL requesters must be equipped with at least one of the following network adapter types (assuming that the adapter has a RIPL** ROM chip or diskette drive to remote IPL from a diskette);

IBM Token-Ring Network adapter
IBM PC Network baseband adapter
IBM PC Network broadband adapter
IBM PS/2 Adapter (Micro Channel only) for Ethemet Networks

4.6.5 Device Driver Support of Additional LAN Adapters

In OS/2 LAN Server Version 3.0, IBM has implemented the 3Com*/Microsoft LAN Manager Network Driver Interface Specification (NDIS) for support of adapters. In addition, IBM has extended the NDIS specification in its implementation of NDIS drivers. The specific details of IBM's implementation of NDIS media access control (MAC) driver development is available on request to:

IBM Corporation

Department 483 Zip 9131

11400 Burnet Road

Austin, Texas 78758

5.0 Migration Considerations

This section describes the compatibility among various IBM server and requester products on a LAN. For a complete detailed summary of the steps required to migrate from any previous release to LAN Server 3.0, refer to the IBM OS/2 LAN Server Version 3.0 Network Administrator Reference Volume I: Planning and Installation (S96F-8428-00).

5.1 Coexistence of LAN Servers in a Single Domain

Servers with different OS/2 LAN Server 3.0 packages installed can coexist in a single domain. For example, a domain could have an OS/2 LAN Server - Advanced domain controller and two OS/2 LAN Servers - Entry additional servers.

OS/2 LAN Server 2.0 and 3.0 servers can coexist with OS/2 LAN Server 1.3 servers on the same domain (with either as the domain controller), provided the OS/2 LAN Server 1.3 servers are at Corrective Service diskette (CSD) level , WR05050 or greater.

5.2 Interoperability between LAN Servers and LAN Requesters

Table 1 and Table 2 describe access capabilities of various IBM LAN Requester products to resources on IBM LAN Server domains. the following three areas are covered:

Logging on to a domain
Administering a domain
Accessing external resources across domains.

The IBM LAN Server domains illustrated are:

PC LAN Program 1.31 (or later) Extended Services
OS/2 LAN Server 1.3
OS/2 LAN Server 2.0
OS/2 LAN Server 3.0.

The IBM LAN Requester products addressed are:

PC LAN Program 1.31 (or later) Base Services Requester (also requires IBM LAN Support Program)
PC LAN Program 1.31 (or later) Extended Services Requester (also requires IBM LAN Support Program)
OS/2 LAN Requester shipped with OS/2 Extended Edition 1.3
OS/2 LAN Requester shipped with LAN Server 2.0 and LAN Server 3.0
DOS LAN Requester shipped with OS/2 LAN Server 1.3, 2.0, and 3.0 (also requires IBM LAN SupportProgram).
LAN Enabler 2.0 (includes OS/2 LAN Requester and DOS LAN Requester).

5.3 Logon and Administrative Capabilities

Table 1 illustrates the logon (L) and administrative (A) capabilities of various requester products.

For example, a user can use a PC LAN Program 1.31 (or later) Base Services requester to log on to a domain controlled by an OS/2 LAN Server 3.0 server and can access domain resources available to that user ID. However, this user is not able to perform any administrative tasks in that domain.

TABLE 1. LOGON AND ADMINISTRATIVE CAPABILITIES

LAN Server Domains
LAN Requesters	PCLP 1.31 (or later) (ES)	OS/2 LAN Server 1.3 (on EE 1.3)	OS/2 LAN Server 2.0(on SE 1.3¹ or OS/2 2.0²)	OS/2 LAN Server 3.0 (on OS/2 2.0)
PCLP 1.31 (or later) (BS) running on a DOS or an OS/2 workstation	L³	L^3,4	L^3,4	L^3,4
PCLP 1.31 (or later) (ES) running on a DOS or an OS/2 workstation	L, A OS/2 LAN Requester (shipped with EE 1.3)	L,A⁵	L,A⁶	L,A⁶
OS/2 LAN Requester (shipped with LAN Server 2.0)running on OS/2 1.3 or OS/2 2.0		L,A⁵	L,A	L,A^6,7
OS/2 LAN Requester (shipped with LAN Enabler 2.0)		L,A⁵	L,A	L,A⁶
OS/2 LAN Requester (shipped with Lan Server 3.0) running on OS/2 2.0		L,A⁵	L,A	L,A
DOS LAN Requester (shipped with OS/2 LAN Server 1.3, 2.0, or 3.0 or LAN Enabler 2.0) running on a DOS or an OS/2 workstation.		L,A^4,8	L,A^4,8	L,A^4,8

Abbreviations:

A = administrative capabilities
BS = Base Services
EE = OS/2 Extended Services
L = logon capability
PCLP = PC LAN Program
SE = Standard Edition

Notes:

OS/2 Standard Edition 1.3 must be at CSD level XR5050 (or greater).
LAN Server 2.0-Advanced runs only on OS/2 Standard Edition 1.3.
The network administrator defines a user ID that matches the machine name of the PC LAN Program Base Services workstation. When the workstation issues a NET USE command, the machine name is validated against the defined user IDs.
Access to serial devices is not supported.
LAN Server 1.3 must be at CSD level WR05050 (or greater).
Administration of new functions, such as Fault Tolerance, is not supported.
LAN Server 3.0 does not support the remote IPL of OS/2 1.3 requesters.
You have administrative capability from a DOS LAN Requester workstation only if you have loaded an API that performs the desired administrative task. A large number of API categories that support remote network administration are supported. For detailed information, refer to the LAN Server Application Programmer's Reference. To load the APIs, run DOS LAN Requester with the/API parameter set in the DOSLAN.INI file.

5.4 Access to External Resources

Table 2 illustrates the access capabilities of various IBM LAN Requester products to resources on domains other than the logged-on domain. Access to resources across domains is accomplished through an external resource-definition function, through the use of appropriate APIs, or by using explicit NET SHARE and NET USE commands. Once a user's ID and password are validated, that user can access resources in another domain provided the network administrator of that domain has shared the resources and granted the appropriate access permissions.

For example, if a user of OS/2 LAN Requester is logged on to an OS/2 LAN Server 1.3 domain and requires access to resources in an OS/2 LAN Server 3.0 domain, the following resource definition must exist:

The desired resource in the OS/2 LAN Server 3.0 domain must be defined as shared.
The resource must be defined as an external resource in the OS/2 LAN Server 1.3 domain.
The user ID and password, if applicable, must be defined in the OS/2 LAN Server 3.0 domain.

Setting up a guest account is an alternative method of providing access to external resources.

TABLE 2. ACCESS TO EXTERNAL RESOURCES ACROSS DOMAINS

External Resource Domain to Be Accessed	Requester	Domain	PCLP 1.31 (or later) (ES)	OS/2 LAN Server 1.3	OS/2 LAN Server 2.0¹
PCLP 1.31 (or later) (BS)	Not applicable	X	X²	X²	X²
PCLP 1.31 (or later) (ES)	PCLP 1.31 (or later)	X	X²	X²	X²
OS/2 LAN Requester	OS/2 LAN Server 1.3, 2.0, or 3.0	X	X	X	X
DOS LAN Requester	OS/2 Lan Server 1.3, 2.0, or 3.0	X	X²	X²	X²

Abbreviations:

BS = Base Services
ES = Extended Services
PCLP = PC Lan Program

Notes:

X indicates access capability.

Applies to both LAN Server-Entry and LAN Server-Advanced.
Access to serial devices is not supported.

6.0 Product Direction

The following details IBM's directions for the OS/2 LAN Server product.

Server function on other platforms: for example, resource sharing for OS/2 and DOS clients extended to other systems such as IBM hosts that have certain performance and capacity advantages.
Merge and exploit other future security subsystems.
Evolve OS/2 LAN Server from using its native protocols and technologies to using Distributed Computing Environment (DCE) protocols and exploiting DCE technologies.

As IBM pursues these directions, we intend to fully protect current customer investments in client server applications by maintaining compatibility with current application interfaces and by providing interoperability between existing clients and new servers and new clients with existing servers.

6.1 Distributed LAN System Evolution

IBM's strategy is to upgrade, migrate, and evolve all IBM LAN solutions to a distributed LAN System environment based on the DCE and Distributed Management Environment (DME) technologies selected by the Open Software Foundation (OSF).

This migration will affect all of the key functions of OS/2 LAN Server including remote file, remote print, access control, DOS file system namespace support, and distributed application support via remote application interfaces and remote interprocess communications. The DCE technologies that LAN Server will exploit include the DCE Directory and the DCE User Registry; and LAN Server win migrate to the protocols that define the DCE Distributed File System (DSF) and the DCE Distributed Print implementation. Since some of these technologies are not completely defined or implemented, OS/2 LAN Server will migrate in a stepwise fashion, continuing to utilize its current native facilities until the new facilities are available. For example, OS/2 LAN Server will continue to provide remote file support with its current protocols until the DCE DFS technology is fully available for inclusion in an IBM product. If the DCE User Registry is available sooner, OS/2 LAN Sender will migrate to this technology in the appropriate OS/2 LAN Server release. The eventual target is to continue the stepwise migration until OS/2 LAN Server is entirely based on OSF DCE technologies.

6.2 The Future

In the future, a majority of IBM's customers will have the need for simple workgroup computing - sharing LAN resources, accessing host data and applications, and transferring files between desktop computers and hosts.

Some businesses are currently implementing LAN distributed solutions based on the level of client-server computing currently available in the market. In the case of LAN Server 3.0 a rich set of remote file and print capabilities are available to multiple servers working together as a workgroup. However, there is a need for workgroups of servers to participate in enterprise-wide management domains that include common user management and definition, enterprise-wide (and beyond) navigation to remote resources including distributed application services and interfaces, and data storage facilities featuring location independence that enables data replication and redundancy. There is also a very strong need for distributed system and network management tools that provide performance, configuration, and distribution services for the enterprise-wide LAN system. IBM is actively participating in the definition of the technology base for both DCE and DME to address these requirements.

There are several factors that will effect the movement from the current level of client-server participation and implementation in the enterprise.

Increased reliance on PC LANs will require LAN distributed solutions to be demanded earlier than expected.
The downsizing of host-based applications to LAN implementations will require that centralized management and host-based tools be provide in the LAN environment.
A desire to take advantage of the LAN's capabilities and the power of the PC to improve productivity will require that additional functionality be provided for workstation-based LAN solutions.

IBM will be an active participant in all phases of this movement with OS/2 LAN Server 3.0 and future releases based on OSF technologies as the strategic product for achieving the desired enterprise LAN solutions.

Notices

May, 1993

Issued by:

IBM Corporation
Personal Software Products
11400 Burnet Road
Austin, Texas 78758

First Edition (September 1992)

Second 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

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

Disclaimers

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

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 inquire, in writing, to the IBM Director of Commercial Relations, IBM Corporation, Purchase, NY 10577 - USA.

Trademarks

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

OS/2	Operating System/2
PS/2	Personal System/2
AT	Personal Computer AT
IBM	Extended Services
Presentation Manager	NetView
FFST/2	First Failure Support Technology/2
WIN-OS/2

The following terms, denoted by a double asterisk (**) in this publication, are trademarks of other companies as follows:

BootWare	Lanworks Technologies Inc.
EtherCard PLUS	Standard Microsystems Corporation
EtherLink Intel	3Com Corporation
Intel	Intel Corporation
Lotus	Lotus Development Corporation
Microsoft	Microsoft Corporation
MS-DOS	Microsoft Corporation
NetWare	Novell, Inc.
Novell	Novell, Inc.
NIU	Ungermann-Bass Corporation
RIPL	CTA Incorporated
Ungermann-Bass	Ungermann-Bass Corporation
Weitek	Weitek Corporation
Windows	Microsoft Corporation
XEROX	XEROX Corporation
3Com	3Com Corporation

Documents

IBM Network Transport Services/2 Version 1.0 Product Overview

Revision as of 17:14, 24 April 2016

About This Document

1.0 New General Request to Modify OPEN Parms

1.0 New General Request to Modify OPEN Parms

1.2 Change to Service Flags to Support ModifyOpenParms

2.0 Proposed Changes to the MAC SSC

3.0 Proposed Changes to the MAC 802.5 Media Specific Statistics

4.0 Proposed Changes to the Status Indication General Request

Notices

Copyright Notices

Disclaimers

Trademarks

NDIS Implementation Information for IBM LAN Systems Extended NIF Format

Table of Contents

About This Document

1.0 NDIS NIF File Definition

2.0 NIF Format Definition and Description

2.1 Common Sections

2.2 Parameter Section

2.3 Multiple NIF Files per Driver

3.0 NIF File Example

4.0 SNIFFLE - A NIF validator

Notices

Copyright Notices

Disclaimers

Trademarks

White Paper on NetBIOS Applications Interoperability

Table of Contents

1.0 NetBIOS Applications Interoperability

1.1 Configuration

1.2 Initialization

1.3 NetBIOS Linkage

1.4 NCB Handler

1.5 NCB Completion

1.6 NetBIOS Command Descriptions

2.0 Extensions to LM10 Specifications

2.1 DDID Support for LM10 Protocol Driver

2.2 Resource Consideration

2.3 Implementation Specific Information

2.4 Reserved NCB Command Codes

Notices

Copyright Notices

Disclaimers

Trademarks

Table of Contents

Chapter 1 - Introduction

Definition of Terms

Scope of This Document

Changes for This Version

Chapter 2 - Configuration and Binding

Configuration and Binding Process

Chapter 3 - Protocol to MAC Interface Description

Transmission

Reception

Non-Host-Buffered Adapter

Host-Buffered Adapter

Indication Control

Status Indication

General Requests

System Requests

Protocol Manager Primitives

Chapter 4 - Data Structures

Module Characteristics

Common Characteristics

MAC Service-Specific Characteristics

MAC Service-Specific Status Table

Service-Specific Statistics Definitions

MAC Upper Dispatch Table

Protocol Service-Specific Characteristics Table

Protocol Lower Dispatch Table

Characteristics Tables for NetBIOS Drivers

Frame Data Description

Transmit Buffer Descriptor

Transfer Data Buffer Descriptor

Receive Chain Buffer Descriptor

PROTOCOL.INI

Configuration Memory Image

ConfigMemorylmage

ModuleConfig

Keyword Entry

NDIS Implementation Information
for IBM LAN Systems
Extended NIF Format

White Paper on
NetBIOS Applications Interoperability

Appendix D - 802.5
Media-Specific Statistics