Jump to content

LAN Device Driver Documentation: Difference between revisions

From EDM2
← Older edit
Ak120 (talk | contribs)
35,819 edits
Ak120 (talk | contribs)
35,819 edits
mNo edit summary
 
(14 intermediate revisions by the same user not shown)
Line 1: Line 1:
By [[IBM]]
{{IBM-Reprint}}


'''Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation'''
*[[IBM NDIS Driver Implementation Package]]
 
**[[3Com/Microsoft LAN Manager Network Driver Interface Specification Version 2.0.1 Final]]
== About This Document ==
**[[LAN Adapter and Protocol Support - IBM Product Overview]]
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.
**[[IBM OS/2 LAN Server 3.0 Product Overview]]
 
**[[IBM Network Transport Services/2 Version 1.0 Product Overview]]
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.
**[[NDIS Implementation Information for IBM LAN Systems - NDIS Device Driver Requirements]]
 
**[[NDIS Implementation Information for IBM LAN Systems - Extended NIF Format]]
'''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.
**[[NDIS Implementation Information for IBM LAN Systems - NDIS Extensions]]
 
**[[NDIS Implementation Information for IBM LAN Systems - OS/2 Messaging and National Language Support]]
This document refers to the following publications for additional information:
**[[NDIS Implementation Information for IBM LAN Systems - IBM OS/2 LAN Technical Reference Extensions]]
* ''Microsoft/3Com LAN Manager** Network Driver Interface Specification (NDIS), Version 2.0.1, October 8, 1990.''
**[[White Paper on NetBIOS Applications Interoperability]]
* ''Microsoft LAN Manager Programmer's Guide for NDIS, Version 2.0.1, June 1990''
*[[NDIS Driver Developer's Tool Kit for OS/2 and DOS - Programmer's Guide]]
* ''IBM LAN Technical Reference''
*[[NDIS Driver Developer's Tool Kit for OS/2 and DOS Programmer's Performance Guide]]
 
*[[NDIS Driver Developer's Tool Kit for OS/2 and DOS - Random Redirected Transform Test User's Manual]]
==1.0 New General Request to Modify OPEN Parms==
 
=== 1.0 New General Request to Modify OPEN Parms ===
<pre class="western">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</pre>
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:
<pre>        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)</pre>
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:
{|
|width="50%"|'''Previous Value'''
|width="50%"|'''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:
 
<pre class="western">    WORD        RingUtilizationMeasurement (DIR.STATUS)</pre>
'''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:
 
<pre class="western">RingUtilizationMeasurement is ring utilization measurement in (DIR.STATUS)</pre>
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.
 
<pre class="western">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</pre>
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:
 
{|
|width="50%"|'''Bit'''
|width="50%"|'''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 &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
 
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or program(s) described in this publication at any time.
 
It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.
 
=== Copyright Notices ===
© '''Copyright International Business Machines Corporation 1992, 1995. All rights reserved.'''
 
Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
 
=== Disclaimers ===
References in this 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:
 
{|
|width="50%"|IBM
|width="50%"|OS/2
|}
 
The following terms, denoted by a double asterisk (**) in this publication, are trademarks of other companies as follows:
 
{|
|width="50%"|Microsoft
|width="50%"|Microsoft Corporation
|-
|Microsoft LAN Manager
|Microsoft Corporation
|-
|3Com
|3Com Corporation
|}
 
= NDIS Implementation Information <br />for IBM LAN Systems <br />Extended NIF Format =
== Table of Contents ==
* [[#AboutThisDocument|About This Document]]
* [[#Sec10|1.0 NDIS NIF File Definition]]
* [[#Sec20|2.0 NIF Format Definition and Description]]
* [[#Sec21|2.1 Common Sections]]
* [[#Sec22|2.2 Parameter Section]]
* [[#Sec23|2.3 Multiple NIF Files per Driver]]
* [[#Sec30|3.0 NIF File Example]]
* [[#Sec40|4.0 SNIFFLE - A NIF validator]]
* [[#Notices|Notices]]
** [[#Copyright|Copyrights]]
** [[#Disclaimers|Disclaimers]]
** [[#Trademarks|Trademarks]]
 
== 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:
 
<pre class="western">[common_section]
keyword = value
keyword = value
  .
  .
  .
[parameter section]
keyword = value
keyword = value
  .
  .
  .
[parameter section]
keyword = value
&lt;E0F&gt;</pre>
 
== 2.1 Common Sections ==
'''Note:''' Entries enclosed in braces {} are optional. Text surrounded by less than and greater than symbols &lt; &gt; is not significant and is used for information purposes only.
 
<pre class="western">[component name]
Type = &lt;Driver type&gt;
Title = &lt;Component name displayed to the user&gt;
Version= Component version number&gt;
Drivername= &lt;Driver name for PROTOCOL.INI&gt;
{Xports= &lt;Transport name&gt; {,&lt;transport name&gt;,...,&lt;Transport name&gt;}}
{Exec = &lt;Executable expression&gt;}
{Copyfile = &lt;8.3 File name&gt; {,&lt;8.3 File name&gt;,...,&lt;8.3 File name&gt;}}
 
[File]
Name = Filename&gt; {,&lt;Filename&gt;,...,&lt;FileName&gt;}
{Path = &lt;Location of above files&gt;}</pre>
'''Definitions:'''
 
'''[component_name]''' <br />                This can be anything although it is recommended that this be the NIF file name without the file extension.
 
{|
|width="33%"|'''Type'''
|width="33%"|Defines the driver type as follows:
|width="33%"| 
|-
| 
|'''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 ''n''th 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 ''n''th 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 &quot;roll your own&quot; keywords). Configuration code ignores unrecognized keywords. The format of the parameter section is as follows:
 
<pre class="western">[parameter_name]
Tag =  &lt; Interrupt | IOAddress | DMA Channel | RamAddress | RamAddrSize | RomAddress |
                RomAddrSize &gt;
Display =      &lt; &quot;display text&quot; &gt;
Type =  &lt; DecNum | Hexadecimal | HexNum | String | HexString | None | Decimal&gt;
StrLength = &lt; X &gt; (where X is a Decimal value)
Default =      &lt; Default Value &gt;
Range = &lt; 1 - X | X &gt;
Step =  &lt;X&gt;
Set =  &lt; Value1, Value2,...,ValueX &gt;
NlsSet =        &lt; Value1, Value2,...,ValueX &gt;
Scope = &lt; Global | Local &gt;
Optional =      &lt; Yes | No &gt;
Editable =      &lt; Yes | No &gt;
Virtual =      &lt; Yes | No &gt;
Help =  &lt; &quot;help text&quot; &gt;</pre>
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.
 
<pre class="western">[IBMTRBM]
Type = NDIS_SNGL
Title = &quot;IBM Token-Ring Network Busmaster Server Adapter&quot;
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 = &quot;Network adapter address&quot;
Type= HexString
Range = 400000000000- 7FFFFFFFFFFF
Optional= Yes
Editable= Yes
Virtual = No
Help = &quot;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.&quot;
 
[AdapBuffSize]
Display = &quot;Adapter card buffer size&quot;
Type= Decimal
Default = &quot;1032&quot;
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.&quot;
 
[AdapMinTran]
Display= &quot;Minimum adapter card transmit buffers&quot;
Type = Decimal
Default = &quot;4&quot;
Range = 4 - 676
Optional = Yes
Editable= Yes
Virtual= No
Help = &quot;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.&quot;
 
[AdapMaxTran]
Display = &quot;Maximum adapter card transmit buffers&quot;
Type = Decimal
Default = &quot;48&quot;
Range = 6 - 676
Optional= Yes
Editable = Yes
Virtual = No
Help = &quot;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.&quot;
 
[MaxTransmits]
Display = &quot;Maximum number of queued transmits&quot;
Type = Decimal
Default = &quot;31&quot;
Range = 1 - 459
Optional = Yes
Editable = Yes
Virtual = No
Help = &quot;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.&quot;
 
[MinRcvBuffs]
Display = &quot;Minimum number of adapter driver receive buffers&quot;
Type = Decimal
Default = &quot;20&quot;
Range = 1 - 3260
Optional = Yes
Editable = Yes
Virtual = No
Help = &quot;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) &gt; size of the largest frame on the network.
This value must be &gt; 4500 bytes on a 4MB network, and &gt; 18000 bytes on
a 16MB network&quot;
 
[SizWorkBuf]
Display = &quot;Size of adapter driver receive buffer&quot;
Type = Decimal
Default = &quot;2048&quot;
Range = 96 - 18000
Optional = Yes
Editable= Yes
Virtual= No
Help = &quot;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.&quot;</pre>
 
== 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 &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
 
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or program(s) described in this publication at any time.
 
It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.
 
=== Copyright Notices ===
© '''Copyright International Business Machines Corporation 1992, 1993. All rights reserved.'''
 
Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
 
=== Disclaimers ===
References in this products to IBM products, programs or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of 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:
 
{|
|width="25%"|Microsoft
|width="25%"|Microsoft Corporation
|width="25%"| 
|width="25%"| 
|-
|LAN Manager
|Microsoft Corporation
| 
| 
|-
|3Com
|3Com Corporation
| 
| 
|}
 
= White Paper on <br />NetBIOS Applications Interoperability =
 
== Table of Contents ==
* [[#Sec10|1.0 NetBIOS Applications Interoperability]]
* [[#Sec11|1.1 Configuration]]
* [[#Sec12|1.2 Initialization]]
* [[#Sec13|1.3 NetBIOS Linkage]]
* [[#Sec14|1.4 NCB Handler]]
* [[#Sec15|1.5 NCB Completion]]
* [[#Sec16|1.6 NetBIOS Command Descriptions]]
* [[#Sec20|2.0 Extensions to LM10 Specifications]]
* [[#Sec21|2.1 DDID Support for LM10 Protocol Driver]]
* [[#Sec22|2.2 Resource Consideration]]
* [[#Sec23|2.3 Implementation Specific Information]]
* [[#Sec24|2.4 Reserved NCB Command Codes]]
* [[#Notices|Notices]]
** [[#Copyright|Copyrights]]
** [[#Disclaimers|Disclaimers]]
** [[#Trademarks|Trademarks]]
 
== 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:
 
&lt; adapter# &gt; = &lt; driver name &gt;, &lt; lana number &gt;
 
where,
 
{|
|width="50%"|&lt; driver name &gt;
|width="50%"|is the OS/2 driver name for the LM10 NetBIOS driver.
|-
|&lt;lana number &gt;
|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 &quot;virtual network&quot; adapter. The format of each LMl0 NetBIOS network definition is:
 
&lt; network name &gt; = &lt; driver name &gt;, &lt; lana number &gt;, &lt; type &gt;, &lt; #sessions &gt;, &lt; #ncbs &gt;, &lt; #name &gt;
 
where,
 
{|
|width="50%"|&lt; driver name &gt;
|width="50%"|is the OS/2 driver name for the NetBIOS driver.
|-
|&lt; lana number &gt;
|is the LAN adapter number for the NetBI0S network represented by this statement. Default is 0.
|-
|&lt; type &gt;
|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.
|-
|&lt; #sessions &gt;
|is the number of session resources that LAN Manager will request from the NetBIOS driver at init time. The default is driver dependent.
|-
|&lt; #ncbs &gt;
|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.
|-
|&lt;#names &gt;
|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 &quot;SRVNETS=NET1, NET2&quot; 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:
<ol>
<li><p>Respond to the device Init command at driver load time by allocating packet buffers, setting up tables, and running start-up diagnostics as appropriate.</p></li>
<li><p>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.</p>
<p>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.</p></li></ol>
 
=== '''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.
 
{|
|width="33%"|Request Packet
|width="33%"| 
|width="33%"| 
|-
| 
|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.
 
{|
|width="50%"|DWORD
|width="50%"|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 <br />       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.
 
{|
|width="33%"|Entry
|width="33%"| 
|width="33%"| 
|-
| 
|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:
<ol>
<li>The LM10 NetBIOS driver must always call the given NCBDone routine in protected mode.</li>
<li>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.</li>
<li>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
|}
</li>
<li>The NCB_RETCODE field must have been completed with a suitable return code value.</li>
<li>NCBs_POST and NCB_CMD_CPLT fields must contain the values that they had at NCB submission time.</li>
<li>All NetBI0S processing of this NCB must be complete. The internals of NCBDone reserve the right to modify the NCB in any way.</li>
<li>Common Problems, Hints and Suggestions
<ul>
<li>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.</li>
<li>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.</li>
<li>For performance reasons, it is recommended that PhysToGDT be used whenever possible instead of PhysToVirt.</li>
<li>The NCB handler MUST NOT block at any time.</li>
<li>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.</li>
<li>LAN Server or LAN Redirector or NETBIOS NB30 driver needs this information for its session handling.</li>
<li>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).</li>
<li>The LM10 NetBIOS driver may use either PhysNCBDone or VirtINCBDone, but must only call ONE of the routines for any given NCB.</li>
<li>For performance reasons, the LM1O NetBIOS driver should:
<p>- use the virtual address supplied in the NCB_NAME field when provided</p>
<p>- support interrupt time submission of NCBs</p></li></ul>
</li></ol>
 
{|
|width="16%"|'''Dec'''
 
'''Offset'''
|width="16%"|'''Hex'''
 
'''Offset'''
|width="16%"|'''Parameter Name'''
|width="16%"|'''Byte'''
 
'''Length'''
|width="16%"|'''8086'''
 
'''Type'''
|width="16%"|'''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.
|}
 
{|
|width="50%"|NCB_COMMAND
|width="50%"|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 ===
{|
|width="50%"|NCB.ADD.GROUP.NAME
|width="50%"| 
|-
| 
|Same as LAN Technical Reference for OS/2 DD interface, <br />minus supplied field of <br />       NCB_POST@
|-
|NCB.ADD.NAME
| 
|-
| 
|Same As LAN Technical Reference for OS/2 DD interface, <br />minus supplied field of <br />       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, <br />minus supplied field of <br />      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, <br />minus supplied field of <br />       NCB_POST@
|-
|NCB.CHAIN.SEND.NO.ACK
| 
|-
| 
|Same As LAN Technical Reference for OS/2 DD interface, <br />minus supplied field of <br />       NCB_POST@
|-
|NCBDELETE.NAME
| 
|-
| 
|Same As LAN Technical Reference for OS/2 DD interface, <br />minus supplied field of <br />       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, <br />minus supplied field of <br />       NCB_POST@
|-
|NCB.HANG.UP
| 
|-
| 
|Same As LAN Technical Reference for OS/2 DD interface, <br />minus supplied field of <br />       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, <br />minus supplied field of <br />       NCB_POST@
|-
|NCB.LISTEN
| 
|-
| 
|Same As LAN Technical Reference for OS/2 DD interface, <br />minus supplied field of <br />       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, <br />minus supplied field of <br />       NCB_POST@
|-
|NCB.RECEIVE.ANY
| 
|-
| 
|Same As LAN Technical Reference for OS/2 DD interface, <br />minus supplied field of <br />       NCB_POST@
|-
|NCB.RECEIVE.BROADCAST.DATAGRAM
| 
|-
| 
|Same As LAN Technical Reference for OS/2 DD interface, <br />minus supplied field of <br />       NCB_POST@
|-
|NCB.RECEIVE.DATAGRAM
| 
|-
| 
|Same As LAN Technical Reference for OS/2 DD interface, <br />minus supplied field of <br />       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, <br />minus supplied field of <br />       NCB_POST@
|-
|NCB.SEND.BROADCAST.DATAGRAM
| 
|-
| 
|Same As LAN Technical Reference for OS/2 DD interface, <br />minus supplied field of <br />       NCB_POST@
|-
|NCB.SEND.DATAGRAM
| 
|-
| 
|Same As LAN Technical Reference for OS/2 DD interface, <br />minus supplied field of <br />       NCB_POST@
|-
|NCB.SEND.NO.ACK
| 
|-
| 
|Same As LAN Technical Reference for OS/2 DD interface, <br />minus supplied field of <br />       NCB_POST@
|-
|NCB.SESSIONS.STATUS
| 
|-
| 
|Same As LAN Technical Reference for Os/2 DD interface, <br />minus supplied field of <br />       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 <br />WORD PTR ncb_reserve + 6 <br />WORD PTR ncb_reserve + 8 <br />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''' <br />'''Personal Software Products''' <br />'''11400 Burnet Road''' <br />'''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 &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
 
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or program(s) described in this publication at any time.
 
It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.
 
=== Copyright Notices ===
 
© '''Copyright International Business Machines Corporation 1994. All rights reserved.'''
 
Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
 
=== Disclaimers ===
References in this 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:
 
{|
|width="25%"|IBM
|width="25%"|OS/2
|width="25%"|AT
|width="25%"|Micro Channel
|-
|Operating System/2
|LAN Server 2.0
|Extended Services
| 
|-
|LAN Adapter and Protocol Support
| 
| 
| 
|}
 
== Table of Contents ==
 
* [[#Introduction|Chapter 1 - Introduction]]
** [[#Terms|Definition of Terms]]
** [[#Scope|Scope of This Document]]
** [[#Changes|Changes for This Version]]
* [[#Configuration|Chapter 2 - Configuration and Binding]]
** [[#Configurationprocess|Configuration and Binding Process]]
* [[#Protocol|Chapter 3 - Protocol to MAC Interface Description]]
** [[#Transmission|Transmission]]
** [[#Reception|Reception]]
** [[#NonHostBufferedAdapter|Non-Host-Buffered Adapter]]
** [[#HostBufferedAdapter|Host-Buffered Adapter]]
** [[#IndicationControl|Indication Control]]
** [[#StatusIndication|Status Indication]]
** [[#GeneralRequests|General Requests]]
** [[#SystemRequests|System Requests]]
** [[#ProtocolManagerPrimitives|Protocol Manager Primitives]]
* [[#DataStructures|Chapter 4 - Data Structures]]
** [[#ModuleCharacteristics|Module Characteristics]]
** [[#CommonCharacteristics|Common Characteristics]]
** [[#MACServiceSpecificCharacteristics|MAC Service-Specific Characteristics]]
** [[#MACServiceSpecificStatusTable|MAC Service-Specific Status Table]]
** [[#ServiceSpecificStatisticsDefinitions|Service-Specific Statistics Definitions]]
** [[#MACUpperDispatchTable|MAC Upper Dispatch Table]]
** [[#ProtocolServiceSpecificCharacteristicsTable|Protocol Service-Specific Characteristics Table]]
** [[#ProtocolLowerDispatchTable|Protocol Lower Dispatch Table]]
** [[#CharacteristicsTablesforNetBIOSDrivers|Characteristics Tables for NetBIOS Drivers]]
** [[#FrameDataDescription|Frame Data Description]]
** [[#TransmitBufferDescriptor|Transmit Buffer Descriptor]]
** [[#TransferDataBufferDescriptor|Transfer Data Buffer Descriptor]]
** [[#ReceiveChainBufferDescriptor|Receive Chain Buffer Descriptor]]
** [[#ProtocolIni|PROTOCOL.INI]]
** [[#ConfigurationMemoryImage|Configuration Memory Image]]
** [[#ConfigMemorylmage|ConfigMemorylmage]]
** [[#ModuleConfig|ModuleConfig]]
** [[#KeywordEntry|Keyword Entry]]
** [[#Param|Param]]
** [[#BindingsList|BindingsList]]
* [[#SpecificationPrimitives|Chapter 5 - Specification of Primitives]]
** [[#DirectPrimitives|Direct Primitives]]
*** [[#TransmitChain|TransmitChain]]
*** [[#TransmitConfirm|TransmitConfirm]]
*** [[#ReceiveLookahead|ReceiveLookahead]]
*** [[#TransferData|TransferData]]
*** [[#IndicationComplete|IndicationComplete]]
*** [[#ReceiveChain|ReceiveChain]]
*** [[#ReceiveRelease|ReceiveRelease]]
*** [[#IndicationOff|IndicationOff]]
*** [[#IndicationOn|IndicationOn]]
** [[#GeneralRequests5|General Requests]]
*** [[#InitiateDiagnostics|InitiateDiagnostics]]
*** [[#ReadErrorLog|ReadErrorLog]]
*** [[#SetStationAddress|SetStationAddress]]
*** [[#OpenAdapter|OpenAdapter]]
*** [[#CloseAdapter|CloseAdapter]]
*** [[#ResetMAC|ResetMAC]]
*** [[#SetPacketFilter|SetPacketFilter]]
*** [[#AddMulticastAddress|AddMulticastAddress]]
*** [[#DeleteMulticastAddress|DeleteMulticastAddress]]
*** [[#UpdateStatistics|UpdateStatistics]]
*** [[#ClearStatistics|ClearStatistics]]
*** [[#InterruptRequest|InterruptRequest]]
*** [[#SetFunctionalAddress|SetFunctionalAddress]]
*** [[#SetLookahead|SetLookahead]]
*** [[#GeneralRequestConfirmation|General Request Confirmation]]
*** [[#StatusIndication|Status Indication]]
*** [[#RingStatus|RingStatus]]
*** [[#AdapterCheck|AdapterCheck]]
*** [[#StartReset|StartReset]]
*** [[#EndReset|EndReset]]
*** [[#Interrupt|Interrupt]]
** [[#SystemRequests5|System Requests]]
*** [[#InitiateBind|InitiateBind]]
*** [[#Bind|Bind]]
*** [[#InitiatePrebind|InitiatePrebind (OS/2 only)]]
*** [[#InitiateUnbind|InitiateUnbind]]
*** [[#Unbind|Unbind]]
** [[#ProtocolManagerPrimitives5|Protocol Manager Primitives]]
*** [[#GetProtocolManagerlnfo|GetProtocolManagerlnfo]]
*** [[#RegisterModule|RegisterModule]]
*** [[#BindAndStart|BindAndStart]]
*** [[#GetProtocolManagerLinkage|GetProtocolManagerLinkage]]
*** [[#GetProtocollniPath|GetProtocollniPath]]
*** [[#RegisterProtocolManagerlnfo|RegisterProtocolManagerlnfo]]
*** [[#InitAndRegister|InitAndRegister]]
*** [[#UnbindAndStop|UnbindAndStop]]
*** [[#BindStatus|BindStatus]]
*** [[#RegisterStatus|RegisterStatus]]
* [[#ProtocolManager6|Chapter 6 - Protocol Manager]]
** [[#ProtocolManagerInitialization|Protocol Manager Initialization]]
** [[#StaticBindingSequence|Static Binding Sequence]]
** [[#OSCallingConvention|OS/2 Calling Convention]]
** [[#DOSCallingConvention|DOS Calling Convention]]
* [[#Vector|Chapter 7 - VECTOR and Dynamic Binding]]
** [[#StaticVECTORBinding|Static VECTOR Binding]]
** [[#DynamicVECTORBinding|Dynamic VECTOR Binding]]
** [[#DynamicBindingUnbindingDOS|Dynamic Binding/Unbinding in the DOS Environment]]
** [[#DynamicBindingUnbindingOS|Dynamic Binding/Unbinding in the OS/2 Environment]]
** [[#VECTORDemultiplexing|VECTOR Demultiplexing]]
* [[#AppendixA|Appendix A - System Return Codes]]
* [[#AppendixB|Appendix B - Reference Material]]
* [[#AppendixC|Appendix C - NDIS 2.0.1 802.3]]
* [[#AppendixD|Appendix D - 802.5]]
* [[#AppendixE|Appendix E - Utilities Provided with the Protocol Manager]]
* [[#Notices|Notices]]
** [[#Copyright|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 &quot;static.&quot;
* 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 &quot;static&quot; if it cannot be unloaded. A protocol driver is called &quot;dynamic&quot; 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, &quot;Utilities Provided with the Protocol Manager,&quot; 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 &quot;module name&quot; and &quot;characteristics table.&quot; 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, &quot;ETHERCARD.&quot; 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 &quot;NetBIOS.&quot; 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 [[#Vector|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------&gt;
 
Call passes TxBufDescr and unique handle. MAC can copy data now or later
 
&lt;---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
 
&lt;-----CALL-----
 
Call supplies unique handle from TransmitChain.
 
---RETURN---&gt;
 
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 &quot;lookahead&quot; 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------&gt;
 
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
 
&lt;-----CALL-----
 
Passes TDBufDescr indicating where to put the received data.
 
---RETURN---&gt;
 
&lt;---RETURN---
 
Upon return from protocol, MAC reenables the hardware.
 
IndicationComplete
 
-----CALL-----&gt;
 
MAC calls protocol to allow interrupt-time post processing.
 
&lt;---RETURN---
 
=== Host-Buffered Adapter ===
 
MAC
 
Protocol
 
ReceiveChain
 
------CALL------&gt;
 
Call passes pointer to RxDataDescr.
 
&lt;---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-----&gt;
 
MAC calls protocol to allow interrupt-time post processing.
 
&lt;---RETURN---
 
Later, if protocol deferred copying the data (this may occur during IndicationComplete):
 
&lt;-----CALL-----
 
ReceiveRelease. The call supplies the unique handle from ReceiveChain.
 
---RETURN---&gt;
 
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.
 
{|
|width="33%"|MAC
|width="33%"|
|width="33%"|Protocol
|-
|Status
|------CALL------&gt;
|Call passes status type and information.
|-
|
|&lt;---RETURN---
|
|-
|IndicationComplete
|-----CALL-----&gt;
|MAC calls protocol to allow interrupt-time post processing.
|-
|
|&lt;---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------&gt;
 
Issue request to MAC with unique handle.
 
&lt;---RETURN---
 
Return indicates if request completed.
 
Later, if request completed asynchronously:
 
&lt;-----CALL-----
 
RequestConfirm. The call supplies unique handle from Request.
 
---RETURN---&gt;
 
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.
 
{|
|width="33%"|Upper Module
|width="33%"|
|width="33%"|Lower Module
|-
|System
|------CALL------&gt;
|Issue request to lower module.
|-
|
|&lt;---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.
 
{|
|width="33%"|'''Protocol or MAC Module'''
|width="33%"|
|width="33%"|'''Protocol Manager'''
|-
|Protocol Manager primitive
|------CALL------&gt;
|Issue request to Protocol Manager.
|-
|
|&lt;---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.
 
{|
|width="50%"|WORD
|width="50%"|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: <br />0 - Binding at upper boundary supported <br />1 - Binding at lower boundary supported <br />2 - Dynamically bound (that is, this module can be swapped out) <br />3-31 - Reserved, must be zero
|-
|BYTE[16]
|Module name - ASCIIZ format
|-
|BYTE
|Protocol level at upper boundary of module: <br />1 - MAC <br />2 - Data link <br />3 - Network <br />4 - Transport <br />5 - Session <br />-1 - Not specified
|-
|BYTE
|Type of interface at upper boundary of module: <br />For MAC: 1=&gt; MAC <br />For Data link: To be defined <br />For Transport: To be defined <br />For Session: 1 =&gt; NCB <br />For any level: 0 =&gt; private (ISV defined)
|-
|BYTE
|Protocol level at lower boundary of module: <br />0 - Physical <br />1 - MAC <br />2 - Data link <br />3 - Network <br />4 - Transport <br />5 - Session <br />-1 - Not specified
|-
|BYTE
|Type of interface at lower boundary of module: <br />For MAC: 1 =&gt; MAC <br />For Data link: To be defined <br />For Transport: To be defined <br />For Session: 1 =&gt; NCB <br />For any level: 0 =&gt; private (ISV defined)
|-
|WORD
|Module ID filled in by the Protocol Manager <br />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 <br />LPBUF Long pointer to a data buffer <br />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: <br />This table contains descriptive information and parameters about the module.
* Service-specific status table: <br />This table contains run-time operating status and statistics for the module.
* Upper dispatch table: <br />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: <br />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.
 
{|
|width="50%"|WORD
|width="50%"|Length of MAC service-specific characteristics table
|-
|table
| 
|-
|BYTE [16]
|Type name of MAC, ASCIIZ format: <br />                                 802.3, 802.4, 802.S, 802.6, DIX, DIX+802.3, <br />                                 APPLETALK, ARCNET, FDDI, SDLC, <br />                                 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: <br />0 - Broadcast supported <br />1 - Multicast supported <br />2 - Functional/group addressing supported <br />3 - Promiscuous mode supported <br />4 - Software settable station address <br />5 - Statistics are always current in service-specific status table <br />6 - InitiateDiagnostics supported <br />7 - Loopback supported <br />8 - Type of receives: <br />                              0 - MAC does primarily ReceiveLookahead indications <br />                              1 - MAC does primarily ReceiveChain indications <br />9 - IBM source routing supported <br />10 - ResetMAC supported <br />11 - Open/CloseAdapter supported <br />12 - Interrupt request supported <br />13 - Source routing bridge supported <br />14 - GOT virtual addresses supported <br />15 - Multiple TransferDatas permitted during a single indication (version 2.0.1 or later) <br />16 - MAC normally sets FrameSize = 0 in ReceiveLookahead (version 2.0. 1 or later) <br />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 &quot;802.3,&quot; &quot;802.5,&quot; &quot;DIX,&quot; and &quot;DIX+802.3.&quot; 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 &quot;Length of station addresses&quot; 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:
 
{|
|width="50%"|WORD
|width="50%"|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 &quot;length&quot; 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, &quot;3Com EtherLink II adapter&quot;).
 
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.
 
{|
|width="50%"|WORD
|width="50%"|Length of status table
|-
|DWORD
|Date/time when diagnostics last run (0xFFFFFFFF if not run), format<br />is seconds since 12:00 midnight, January 1, 1970
|-
|DWORD
|MAC status, a 32-bitmask: <br />0-2 - Opcoded as follows: <br />0 - Hardware not installed <br />1 - Hardware failed startup diagnostics <br />2 - Hardware failed due to configuration problem <br />3 - Hardware not operational due to hardware fault <br />4 - Hardware operating marginally due to soft faults <br />5-6 Reserved <br />7 - Hardware fully operational <br />3 - If set, MAC is bound, else not bound <br />4 - If set, MAC is open, else not open (if adapter doesn't support open/close function, set to 1 if hardware is functional) <br />5 - If set, adapter diagnostics are in progress (version 2.0.1 or later) <br />6-31 - Reserved, must be zero
|-
|WORD
|Current packet filter, a bitmask: <br />0 - Directed and multicast or group and functional <br />1 - Broadcast <br />2 - Promiscuous <br />3 - All source routing <br />4-15 - Reserved, must be zero
|}
 
Statistics for MACs
 
{|
|width="50%"|LPBUF
|width="50%"|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''' <br />(NumberOfFramesReceivedOK)- corresponding 802.3 statistics
 
'''Total frames with CRC error''' <br />(NumberOfFramesReceivedWithFrameCheckSequenceErrors)
 
'''Total bytes received'''
 
'''Total frames discarded - no buffer space'''
 
'''Total multicast frames received OK''' <br />(NumberOfMulticastFramesReceivedOK)
 
 
'''Total broadcast frames received OK''' <br />(NumberOfBroadcastFramesReceivedOK)
 
'''Total frames discarded - hardware error'''
 
'''Total frames transmitted OK''' <br />(NumberOfFramesTransmittedOK)
 
'''Total bytes transmitted OK'''
 
'''Total multicast frames transmitted''' <br />(NumberOfMulticastFramesTransmittedOK)
 
'''Total broadcast frames transmitted''' <br />(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.
 
{|
|width="50%"|LPBUF
|width="50%"|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:
 
{|
|width="50%"|WORD
|width="50%"|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).
 
{|
|width="50%"|LPBUF
|width="50%"|Back pointer to common characteristics table
|-
|DWORD
|Interface flags (used by VECTOR frame dispatch): <br />0 - Handles non-LLC frames <br />1 - Handles specific LSAP LLC frames <br />2 - Handles nonspecific LSAP LLC frames <br />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:
 
{|
|width="50%"|WORD
|width="50%"|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:
 
{|
|width="50%"|LPBUF
|width="50%"|Back pointer to common characteristics table
|-
|LPFUN
|Request address
|-
|LPFUN
|NetBIOS NCB handler (LAYMAN calling conventions)
|}
 
Lower dispatch table for a NetBIOS module:
 
{|
|width="50%"|LPBUF
|width="50%"|Back pointer to common characteristics table
|-
|DWORD
|Interface flags (used by VECTOR frame dispatch): <br />0 - Handles non-LLC frames <br />1 - Handles specific LSAP LLC frames <br />2 - Handles nonspecific LSAP LLC frames <br />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:
 
{|
|width="50%"|WORD
|width="50%"|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
 
{|
|width="33%"|WORD
|width="33%"|TxImmedLen
|width="33%"|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
 
{|
|width="33%"|BYTE
|width="33%"|TxPtrType
|width="33%"|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
 
{|
|width="33%"|WORD
|width="33%"|TDDataCount
|width="33%"|Count of transfer data blocks; max is configurable
|}
 
Followed by TDDataCount instances of
 
{|
|width="33%"|BYTE
|width="33%"|TDPtrType
|width="33%"|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
 
{|
|width="33%"|WORD
|width="33%"|RxDataCount
|width="33%"|Count of receive data blocks; max is configurable
|}
 
Followed by RxDataCount instances of
 
{|
|width="33%"|WORD
|width="33%"|RxDataLen
|width="33%"|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:
 
<pre class="western">[MYNetBIOS]
Drivername = NetBIOS$
Bindings = ETHERCARD
MaxNCBs = 16
MaxSessions = 32
MaxNames = 16</pre>
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 = &lt;device driver name&gt;. 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 = &lt;module name&gt; | &lt;module name&gt;, &lt;module name&gt;, . . . 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 &lt;module name&gt; 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 (&quot;....&quot;). 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:
 
<pre class="western">[PROTMAN]
Drivername = PROTMAN$
Dynamic = YES or NO
PRIORITY = prot1, prot2, ...
Bindstatus = YES or NO</pre>
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 &quot;VECTOR Demultiplexing&quot; 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:
 
<pre class="western">struct ConfigMemoryImage
{
        struct ModuleConfig(l) Module(l);
        struct ModuleConfig(2) Module(2);
        . . .
        struct ModuleConfig(N) Module(N);
};</pre>
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:
 
<pre class="western">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);
};</pre>
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:
 
<pre class="western">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);
};</pre>
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:
 
<pre class="western">struct Param(k)
{
        unsigned ParamType;
        unsigned ParamLen;
        union ParamValue
        {
                long Numeric;
                unsigned char String[STRINGLEN];
        };
};</pre>
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: <br />     = 0 a signed integer supporting up to 31-bit values with the least significant byte first <br />     = 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:
 
<pre class="western">struct BindingsList
{
        unsigned NumBindings;
        struct Module
        {
                char ModuleName[16];
 
        } BoundDriver[NUMBINDINGS];
};</pre>
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 &quot;register variable&quot; 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.<br />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 [[#AppendixB|Appendix B]]).
* For performance reasons, it is recommended that PhysToGDT be used whenever possible instead of PhysToVirt.
* Commonly used parameters:
 
{|
|width="50%"|ProtID
|width="50%"|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.
 
{|
|width="33%"|PUSHWORD
|width="33%"|ProtID;Module
|width="33%"|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 <br />0x0002 <br />0x0006 <br />0x0007 <br />0x0008 <br />0x000A <br />0x000B <br />0x000C <br />0x00FF
|SUCCESS <br />REQUEST_QUEUED <br />OUT_OF_RESOURCE <br />INVALID_PARAMETER <br />INVALID_FUNCTION <br />HARDWARE_ERROR <br />TRANSMIT_ERROR <br />NO_SUCH_DESTINATION <br />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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID
|width="33%"|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 <br />0x0007 <br />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:
 
{|
|width="50%"|0x0000
|width="50%"|SUCCESS
|-
|0x000A
|HARDWARE_ERROR
|-
|0x000B
|TRANSMIT_ERROR
|-
|0x000C
|NO SUCH_DESTINATION
|-
|0x00FF
|GENERAL_FAILURE
|}
 
For more details, see the preceding section, [[#TransmitChain|&quot;TransmitChain.&quot;]]
 
==== ReceiveLookahead ====
Purpose: Indicate the arrival of a received frame and offer lookahead data.
 
{|
|width="33%"|PUSH WORD
|width="33%"|MACID
|width="33%"|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 <br />0x0003 <br />0x0004 <br />0x0005 <br />0x0006 <br />0x0007 <br />0x00FF
|SUCCESS <br />FRAME_NOT_RECOGNIZED <br />FRAME_REJECTED <br />FORWARD_FRAME <br />OUT_OF_RESOURCE <br />INVALID_PARAMETER <br />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.
 
{|
|width="33%"|PUSH LPWORD
|width="33%"|BytesCopied
|width="33%"|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 <br />0x0007 <br />0x0008 <br />0x00FF
|SUCCESS <br />INVALID_PARAMETER <br />INVALID_FUNCTION <br />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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|MACID
|width="33%"|Module ID of MAC
|-
|PUSH WORD
|ProtDS
|DS of called protocol module
|-
|CALL IndicationComplete
| 
| 
|-
|Returns:
|0x0000 <br />0x0007 <br />0x00FF
|SUCCESS <br />INVALID_PARAMETER <br />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 &quot;interrupt&quot; 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 <br />0x0001 <br />0x0003 <br />0x0004 <br />0x0005 <br />0x0006 <br />0x0007 <br />0x00FF
 
SUCCESS <br />WAIT_FOR_RELEASE <br />FRAME_NOT_RECOGNIZED <br />FRAME_REJECTED <br />FORWARD_FRAME <br />OUT_OF_RESOURCE <br />INVALID_PARAMETER <br />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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ReqHandle
|width="33%"|Unique handle from ReceiveChain
|-
|PUSH WORD
|MACDS
|DS of called MAC module
|-
|CALL ReceiveRelease
| 
| 
|-
|Returns:
|0x0000 <br />0x0007 <br />0x0008 <br />0x00FF
|SUCCESS <br />INVALID_PARAMETER <br />NOT_SUPPORTED <br />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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|MACDS
|width="33%"|DS of called MAC module
|-
|CALL IndicationOff
| 
| 
|-
|Returns:
|0x0000 <br />0x0008 <br />0x00FF
|SUCCESS <br />INVALID_FUNCTION <br />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 <br />TransmitChain <br />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:
 
{|
|width="33%"|PUSH WORD
|width="33%"|MACDS
|width="33%"|DS of called MAC module
|-
|CALL IndicationOn
| 
| 
|-
|Returns:
|0x0000 <br />0x0008 <br />0x00FF
|SUCCESS <br />INVALID_FUNCTION <br />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:
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID
|width="33%"|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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID
|width="33%"|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 <br />0x0002 <br />0x0006 <br />0x0007 <br />0x0008 <br />0x0009 <br />0x000A <br />0x00FF
|SUCCESS <br />REQUEST_QUEUED <br />OUT_OF_RESOURCE <br />INVALID_PARAMETER <br />INVALID_FUNCTION <br />NOT_SUPPORTED <br />HARDWARE_ERROR <br />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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID
|width="33%"|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 <br />0x0002 <br />0x0006 <br />0x0007 <br />0x0008 <br />0x0009 <br />0x00FF
|SUCCESS <br />REQUEST_QUEUED <br />OUT_OF_RESOURCE <br />INVALID_PARAMETER <br />INVALID_FUNCTION <br />NOT_SUPPORTED <br />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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID
|width="33%"|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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID
|width="33%"|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 <br />0x0002 <br />0x0006 <br />0x0007 <br />0x0008 <br />0x0009 <br />0x0024 <br />0x002A <br />0x00FF
|SUCCESS <br />REQUEST_QUEUED <br />OUT_OF_RESOURCE <br />INVALID_PARAMETER <br />INVALID_FUNCTION <br />NOT_SUPPORTED <br />HARDWARE_FAILURE <br />NETWORK_MAY_NOT_BE_CONNECTED <br />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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID
|width="33%"|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 <br />0x0002 <br />0x0006 <br />0x0007 <br />0x0008 <br />0x0009 <br />0x00FF
|SUCCESS <br />REQUEST_QUEUED <br />OUT_OF_RESOURCE <br />INVALID_PARAMETER <br />INVALID_FUNCTION <br />NOT_SUPPORTED <br />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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID
|width="33%"|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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID
|width="33%"|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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID
|width="33%"|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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID
|width="33%"|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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID
|width="33%"|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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID;
|width="33%"|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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID
|width="33%"|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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID
|width="33%"|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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID
|width="33%"|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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|ProtID
|width="33%"|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:
 
{|
|width="33%"|PUSH WORD
|width="33%"|MACID
|width="33%"|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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|MACID
|width="33%"|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:
 
{|
|width="50%"|Bit
|width="50%"|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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|MACID
|width="33%"|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):
 
{|
|width="50%"|0x8000
|width="50%"|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):
 
{|
|width="50%"|0x8000
|width="50%"|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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|MACID
|width="33%"|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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|MACID
|width="33%"|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;&gt;
|-
|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:
 
{|
|width="50%"|0x0000
|width="50%"|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.
 
{|
|width="33%"|PUSH WORD
|width="33%"|MACID
|width="33%"|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:
 
{|
|width="33%"|PUSH DWORD
|width="33%"|Param1
|width="33%"|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.
 
{|
|width="33%"|PUSH DWORD
|width="33%"|0
|width="33%"|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.
 
{|
|width="33%"|PUSH LPBUF
|width="33%"|CharTab
|width="33%"|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.
 
{|
|width="33%"|PUSH DWORD
|width="33%"|0
|width="33%"|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.
 
{|
|width="33%"|PUSH DWORD
|width="33%"|0
|width="33%"|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.
 
{|
|width="33%"|PUSH LPBUF
|width="33%"|CharTab
|width="33%"|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:
 
<pre class="western">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 */
};</pre>
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:
 
{|
|width="33%"|PUSH LPBUF
|width="33%"|ReqBlock
|width="33%"|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.
 
{|
|width="50%"|Opcode
|width="50%"|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).
|}
 
{|
|width="33%"|Returns:
|width="33%"|0x0000
|width="33%"|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.
 
{|
|width="50%"|Opcode
|width="50%"|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
|}
 
{|
|width="33%"|Returns:
|width="33%"|0x0000
|width="33%"|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.
 
{|
|width="50%"|Opcode
|width="50%"|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:
 
<pre class="western">struct FailingModules
                {
                    char UpperModuleName[16]    /* Upper failing module */
                    char LowerModuleName{16}    /* Lower failing module */
                };
                </pre>
|-
|Pointer2
|Unused
|-
|Word1
|Unused
|}
 
{|
|width="33%"|Returns:
|width="33%"|0x0000
|width="33%"|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 ([[#Vector|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 [[#AppendixE|Appendix E]].
 
==== GetProtocolManagerLinkage ====
Purpose: Retrieve Protocol Manager dispatch and DS value.
 
{|
|width="50%"|Opcode
|width="50%"|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
|}
 
{|
|width="33%"|Returns:
|width="33%"|0x0000
|width="33%"|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.
 
{|
|width="50%"|Opcode
|width="50%"|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
|}
 
{|
|width="33%"|Returns:
|width="33%"|0x0000
|width="33%"|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.
 
{|
|width="50%"|Opcode
|width="50%"|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
|}
 
{|
|width="33%"|Returns:
|width="33%"|0x0000
|width="33%"|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 [[#AppendixE|Appendix E]].
 
==== InitAndRegister ====
Purpose: An optional dynamic OS/2 command to dynamically restart the prebind initialization of a dynamically reloadable protocol driver.
 
{|
|width="50%"|Opcode
|width="50%"|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
|}
 
{|
|width="33%"|Returns:
|width="33%"|0x0000
|width="33%"|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.
 
{|
|width="50%"|Opcode
|width="50%"|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 <br />If NULL, terminates a set of previously dynamically bound protocol modules as defined in the following section (valid only for DOS)
|-
|Word1
|Unused
|}
 
{|
|width="33%"|Returns:
|width="33%"|0x0000
|width="33%"|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 &quot;set&quot; 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 [[#AppendixE|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.
 
{|
|width="50%"|Opcode
|width="50%"|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 <br />On input, under DOS or in OS/2, if the caller is in Ring 0, this pointer must be NULL <br />On output, Pointer1 points to the root tree
|-
|Pointer2
|NULL
|-
|Word1
|Only used in OS/2 <br />Length of buffer (input) and bytes copied (output)
|}
 
{|
|width="33%"|Returns:
|width="33%"|0x0000
|width="33%"|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:
 
<pre class="western">struct BindNode
{
        struct cctable far *commonptr,
        struct BindNode far *down;
        struct BindNode far *right;
};</pre>
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:
 
<pre class="western">        protocol
      /      \
      MAC1    MAC2</pre>
This would be represented by the following bind tree:
 
<pre class="western">    Protocol
            |
            V
          MAC1 --&gt; MAC2</pre>
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:
 
<br />BindNode: <br />CommonPtr <br />Down <br />Right <br />Common characteristics: <br />Pointer to service-specific characteristics <br />Pointer to service-specific status <br />Service-specific characteristics <br />Pointer to multicast address list (MACs only) <br />Service-specific status <br />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.
 
{|
|width="50%"|Opcode
|width="50%"|0x0A
|-
|Status
|On return, contains request status
|-
|Pointer1
|NULL
|-
|Pointer2
|FAR virtual pointer to a byte ASCIIZ module name
|-
|Word1
|NULL
|}
 
{|
|width="33%"|Returns:
|width="33%"|0x0000
|width="33%"|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 ([[#Vector|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 [[#Vector|Chapter 7]], &quot;VECTOR and Dynamic Binding.&quot;
 
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:
 
{|
|width="50%"|DWORD
|width="50%"|Module function flags, a bitmask (hints only): <br />Bit 0 - set (binds at upper boundary) <br />Bit 1 - clear (doesn't bind at lower boundary)
|-
|BYTE
|Protocol level at upper boundary of module: <br />4 - Transport
|-
|BYTE
|Type of interface at upper boundary of module: <br />1 =&gt; TLI
|-
|BYTE
|Protocol level at lower boundary of module: <br />-1 - Not specified
|-
|BYTE
|Type of interface at lower boundary of module, for any level: <br />0 =&gt; 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 [[#AppendixE|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:
 
<pre class="western">int (far Pascal *ProtManEntry)(ReqBlockPtr, DataSeg);
struct ReqBlock far *ReqBlockPtr;
unsigned DataSeg;</pre>
where <br />ReqBlockPtr = a FAR pointer to the request block. <br />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 [[#DynamicBindingUnbindingDOS|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 [[#StaticBindingSequence|&quot;Static Binding Sequence&quot; 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 [[#AppendixE|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 [[#StaticVECTORBinding|&quot;Static VECTOR Binding&quot; 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 [[#AppendixE|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 [[#AppendixE|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 &quot;Ethernet Blue Book.&quot;
* 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).
 
<br />WORD          Length of 802.3 statistics structure, including this field <br />WORD          802.3 statistics structure version level (1) <br />'''DWORD       Total frames with alignment error''' <br />DWORD        Reserved (obsolete statistic) <br />DWORD        Total frames with overrun error <br />DWORD        Reserved (obsolete statistic) <br />DWORD        Total frames transmitted after deferring <br />DWORD        Total frames not transmitted - max (16) collisions <br />DWORD        Reserved (obsolete statistic) <br />DWORD        Total late (out of window) collisions <br />'''DWORD       Total frames transmitted after exactly one (1) collision''' <br />'''DWORD       Total frames transmitted after multiple collisions''' <br />DWORD        Total frames transmitted, CD heartbeat <br />DWORD        Reserved (obsolete statistic) <br />DWORD        Total carrier sense lost during transmission <br />DWORD        Reserved (obsolete statistic) <br />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 &quot;Multicast flame received ok&quot; is counted in the following statistics counters:
#* Total multicast frames received ok
#* Total frames received ok
# A &quot;Transmit broadcast frame with one collision&quot; 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 &quot;as the station sees it.&quot;
 
'''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 <br />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).
 
<br />WORD          Length of 802.5 statistics structure, including this field <br />WORD          802.5 statistics structure version level (1) <br />DWORD        FCS or code violations detected in repeated frame <br />DWORD        Reserved (obsolete statistic) <br />DWORD        Number of 5 half-bit time transition absences detected <br />DWORD        A/C errors <br />DWORD        Frames transmitted with abort delimiter <br />DWORD        Frames transmitted that failed to return <br />DWORD        Frames recognized, no buffer available <br />DWORD        Frame copied errors <br />DWORD        Number of frequency errors detected <br />DWORD        Number of times active monitor regenerated <br />DWORD        Reserved <br />DWORD        Reserved <br />DWORD        Reserved <br />DWORD        Reserved (obsolete statistic) <br />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:
 
{|
|width="50%"|NETBIND.EXE
|width="50%"|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 ====
 
'''Copyright 1988, 1989, 1990 3Com Corporation/Microsoft Corporation'''
 
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. <br />AppleTalk is a registered trademark of Apple Computer, Inc. <br />ArcNet is a registered trademark of Datapoint Corporation. <br />IBM is a registered trademark of International Business Machines Corporation. <br />EtherNet is a registered trademark of Xerox Corporation.
 
= NDIS Implementation Information <br />for IBM LAN Systems <br />OS/2 Messaging and National Language Support =
 
== Table of Contents ==
 
* [[#About|'''About This Document''']]
* [[#Sec10|'''1.0 General Strategy''']]
* [[#Sec20|'''2.0 Standardized Services for Device Driver Message Display and Logging''']]
* [[#Sec21|2.1 Device Driver Initialization]]
** [[#Sec211|2.1.1 Implementation]]
** [[#Sec212|2.1.2 Functions Provided]]
*** [[#Sec2121|2.1.2.1 Function 01: Message Service Request]]
*** [[#Sec2122|2.1.2.2 Function 02: Message IDC Information Request]]
*** [[#Sec2123|2.1.2.3 Function 03: Combine Functions 01 and 02]]
*** [[#Sec2124|2.1.2.4 Function 07: Request Default Path]]
** [[#Sec213|2.1.3 Calling Conventions and Input Parameters for the DosDevIOCtl Entry Point]]
** [[#Sec214|2.1.4 Example DevIOCtl]]
* [[#Sec22|2.2 Device Driver Strategy Time]]
** [[#Sec221|2.2.1 Implementation]]
** [[#Sec222|2.2.2 Calling Conventions and Input Parameters for the IDC Entry Point]]
** [[#Sec223|2.2.3 IDC Entry Example]]
* [[#Sec30|'''3.0 Non-Device Interface to the LAN Transport Message Functions''']]
* [[#Sec31|3.1 Functional Description]]
* [[#Sec32|3.2 Implementation]]
** [[#Sec321|3.2.1 Input Parameters]]
** [[#Sec322|3.2.2 Calling Conventions]]
*** [[#Sec3221|3.2.2.1 Linking Method:]]
*** [[#Sec3222|3.2.2.2 Parameter Passing on Calling Sequence]]
* [[#Sec40|'''4.0 Data Structure Definitions and Return Codes''']]
* [[#Sec41|4.1 Message Parameter Block]]
* [[#Sec42|4.2 DevIOCtl Returned Status Field: (DevIOClt Function 1)]]
* [[#Sec43|4.3 IDCInformation Request Packet: (DevlOCtl Function's 2 &amp; 3)]]
* [[#Sec44|4.4 Default Path Information Request Packet: (DevlOCtl Function 7)]]
* [[#Sec45|4.5 Possible Return Codes]]
* [[#Sec50|'''5.0 Installation/Configuration''']]
* [[#Sec51|5.1 CONFIG.SYS Entries]]
* [[#Sec52|5.2 Configuring the Override for the Default Path Name]]
** [[#Sec521|5.2.1 Search Path Rules]]
* [[#Sec53|5.3 Other Configuration Parameters to the Messaging Support Driver]]
* [[#Notices|Notices]]
** [[#Copyright|Copyrights]]
** [[#Disclaimers|Disclaimers]]
** [[#Trademarks|Trademarks]]
 
 
 
[[[#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. <br />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. <br />The detailed LAN message device driver interface is described in [[#Sec20|Chapter 2]], and the interface for ring-3 applications is described in [[#Sec30|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:
 
<pre class="western">        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.</pre>
 
==== 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, [[#Sec40|&quot;Data Structure Definitions and Return Codes&quot;.]] 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 [[#Sec40|4.0, &quot;Data Structure Definitions and Retum Codes&quot;.]]
 
==== 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 [[#Sec40|4.0, &quot;Data Structure Definitions and Return Codes&quot; .]]
 
==== '''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 [[#Sec50|5.0, &quot;Installation/Configuration&quot; 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''' ===
 
<pre class="western">                          (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.</pre>
 
 
== '''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:
 
<pre class="western">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. </pre>
 
 
 
 
=== '''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.
 
<pre class="western">push    es                      ;      PASS PARMLIST, offset to
push    OFFSET Msg_Params      ;          message parameter block.
push    1                      ;      Pass message IDC invocation.
call    DWORD ptr es:&quot;Msg_CS&quot;  ;      Call the MessageDD
cmp    AX,0                    ;      Success?
jne    OutMsg_Err              ;      No.</pre>
'''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 [[#Sec40|4.0, &quot;Data Structure Definitions and Return Codes&quot;.]] 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:
 
<pre class="western">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.</pre>
 
 
 
 
=== '''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:
 
<pre class="western">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</pre>
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:
 
<pre class="western">;;;    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</pre>
 
 
 
 
==== '''3.2.2.2 Parameter Passing on Calling Sequence''' ====
 
An example of the calling sequence to the MRMSG interface follows:
 
<pre class="western">;;;;    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.</pre>
 
 
 
 
== '''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).
 
<ul>
<li><p>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)</p></li>
<li><p>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)</p></li>
<li><p>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)</p></li>
<li><p>MESSAGE_Num - Word value used to hold the message number ID of the desired message. (REQUIRED)</p></li>
<li><p>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)</p></li>
<li><p>Message_Type - Afford value used for the following types. (OPTIONAL)</p>
<pre class="western">                  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.</pre></li>
<li><p>Display_Flag - Word value indicating the console display option. (OPTIONAL)</p>
<pre class="western">                Possible values include:
                    False (0) - do not display, even if error type.
                    True (1) - display to console.</pre></li>
<li><p>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)</p></li></ul>
 
 
 
 
 
== '''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.
 
<pre class="western">Returned status of request - Word (REQUIRED for all DevIOCtl's)</pre>
 
 
 
 
== '''4.3 IDC Information Request Packet: (DevIOCtl Function's 2 &amp; 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:
 
<pre class="western">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)</pre>
 
 
 
 
== '''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:
 
<pre class="western">Returned status of request  - Word (REQUIRED)
Default path buffer address - Double word pointer (REQUIRED)
Length of path name        - Word (REQUIRED)</pre>
 
 
 
 
== '''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.
 
<pre class="western">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)</pre>
 
== 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:
 
<pre class="western">LIBPATH=C:\OS2\DLL;C:\IBMCOM;
.
.
.
DEVICE=C:\IBMCOM\LANMSGDD.OS2
RUN=C:\IBMCOM\LANMSGEX.EXE</pre>
 
== 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 &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
 
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or program(s) described in this publication at any time.
 
It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.
 
 
-----
 
 
 
=== Copyright Notices ===
 
© '''Copyright International Business Machines Corporation 1992, 1993. All rights reserved.'''
 
Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
 
 
-----
 
 
 
=== Disclaimers ===
 
References in this 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:
 
{|
|width="50%"|IBM
|width="50%"|OS/2
|}
 
The following terms, denoted by a double asterisk (**) in this publication, are trademarks of other companies as follows:
 
{|
|width="50%"|3Com
|width="50%"|3Com Corporation
|-
|Microsoft LAN Manager
|Microsoft Corporation
|}
 
= NDIS Driver Developer's Tool Kit <br />for OS/2 and DOS <br />Programmer's Guide =
 
== Table of Contents ==
 
* [[#Preface|Preface]]
** [[#HowUseThisManual|How to Use This Manual]]
*** [[#Audience|Audience]]
*** [[#Content|Content]]
*** [[#Result|Result]]
** [[#NotationalConventions|Notational Conventions]]
** [[#NDIS|NDIS]]
** [[#FindingFurtherInformation|Finding Further Information]]
* [[#Chapter1|Chapter1. Overview]]
** [[#TypesofDeviceDrivers|Types of Device Drivers]]
** [[#InstallableDeviceDrivers|Installable Device Drivers]]
*** [[#PartsofDeviceDriver|Parts of a Device Driver]]
*** [[#RealVersusProtectedMode|Real Versus Protected Mode]]
*** [[#PrivilegeLevels|Privilege Levels]]
** [[#IntroductiontoNDIS|Introduction to NDIS]]
*** [[#NDISandOSIReferenceModel|NDIS and the OSI Reference Model]]
*** [[#ProtocolManager|The Protocol Manager]]
*** [[#VECTOR|VECTOR]]
** [[#MediaAccessControlDrivers|Media Access Control Drivers]]
*** [[#PartsMACDeviceDriver|Parts of a MAC Device Driver]]
*** [[#HowMACDeviceDriverWorks|How a MAC Device Driver Works]]
* [[#Chapter2|Chapter 2. OS/2 Device Drivers]]
** [[#OSDeviceDriverHeader|The Device Driver Header]]
** [[#OSStrategyRoutine|The Strategy Routine]]
*** [[#OSRequestPacket|The Request Packet]]
** [[#OSInitializationRoutine|The Initialization Routine]]
*** [[#OSOverview|Overview]]
*** [[#OSINITRequestPacket|The INIT Request Packet]]
*** [[#OSFunctionsInitialization|OS/2 Functions Available at Initialization]]
*** [[#OSDevHlpService|DevHlp Service]]
* [[#Chapter3|Chapter 3. DOS Device Drivers]]
** [[#DOSDeviceDriverHeader|The Device Driver Header]]
** [[#DOSStrategyRoutine|The Strategy Routine]]
*** [[#DOSRequestPacket|The Request Packet]]
** [[#DOSInitializationRoutine|The Initialization Routine]]
*** [[#DOSOverview|Overview]]
*** [[#DOSINITRequestPacket|The INIT Request Packet]]
*** [[#DOSINT21|INT 21 Function Calls at Initialization Time]]
** [[#InterruptHandlers|Interrupt Handlers]]
* [[#Chapter4|Chapter 4. Writing a Media Access Control Driver]]
** [[#StrategyInitializationRoutines|The Strategy and Initialization Routines]]
*** [[#OpeningProtocolManager|Opening the Protocol Manager]]
*** [[#ProtocolManagerRequests|Protocol Manager Requests]]
*** [[#GettingConfigurationInformation|Getting Configuration Information]]
*** [[#BuildingCharacteristicsTables|Building the Characteristics Tables]]
*** [[#CompletingInitialization|Completing Initialization]]
** [[#SystemRequestRoutine|The System Request Routine]]
*** [[#BindSystemRequest|The Bind System Request]]
** [[#IndicationRoutines|The Indication Routines]]
*** [[#IndicationOff|IndicationOff]]
*** [[#IndicationOn|IndicationOn]]
** [[#TransmitChainRoutine|The TransmitChain Routine]]
** [[#InterruptRoutine|The Interrupt Routine]]
*** [[#TimeCriticalTasks|Time - Critical Tasks]]
*** [[#ChangingMode|Changing Mode]]
*** [[#ReceivingFrames|Receiving Frames]]
*** [[#ReceiveLookahead|ReceiveLookahead]]
*** [[#ReceiveChain|ReceiveChain]]
*** [[#OtherTasks|Other Tasks]]
** [[#TransferDataRoutine|The TransferData Routine]]
** [[#ReceiveReleaseRoutine|The ReceiveRelease Routine]]
** [[#GeneralRequestRoutines|The General Request Routines]]
* [[#Notices|Notices]]
** [[#Copyright|Copyrights]]
** [[#Disclaimers|Disclaimers]]
** [[#Trademarks|Trademarks]]
 
[[[#HowUseThisManual|next]]][[[#toc|parent]]][[[#toc|TOC]]]
 
== Preface ==
How to Use This Manual
* [[#Audience|Audience]]
* [[#Content|Content]]
* [[#Result|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. <br />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 &quot;DEVICE=&quot; 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
 
[[Image:images%5Cndisp01.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:
 
{|
|width="33%"|Offset
|width="33%"|Size (bytes}
|width="33%"|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:
 
{|
|width="50%"|Bit
|width="50%"|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 &quot;DriverName=&quot; 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 &quot;$&quot; 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:
 
{|
|width="33%"|Offset
|width="33%"|Size (bytes)
|width="33%"|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 &quot;DEVICE=&quot; 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:
 
{|
|width="33%"|Offset
|width="33%"|Size (bytes)
|width="33%"|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 &quot;DEVICE=&quot; 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:
 
{|
|width="50%"|FileI/O:
|width="50%"| 
|-
|
|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:
 
{|
|width="33%"|Offset
|width="33%"|Size (bytes)
|width="33%"|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 [[#OSDeviceDriverHeader|the section on the OS/2 device header]]for 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:
 
{|
|width="33%"|Offset
|width="33%"|Size (bytes)
|width="33%"|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 [[#OSINITRequestPacket|the section on the OS/2 Request Packet]]for 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
 
{|
|width="33%"|Offset
|width="33%"|Size (bytes)
|width="33%"|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 [[ndisppg.htm|''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.
 
<pre class="western">;                             
;-- 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                         
        </pre>
 
==== 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.
 
<pre class="western">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            </pre>
 
==== 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.
 
<pre class="western">;                             
;--    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        </pre>
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 &quot;DriverName=&quot; 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.
 
<pre class="western">[bithose_NIF]
  DriverName      = bithose$
  Base            = 0x300
  IntLevel        = 3</pre>
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.
 
<pre class="western">;-- 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--&gt; 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 &quot;DRIVERNAME&quot;
    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</pre>
 
 
 
 
==== 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.
 
<pre class="western">          dw        offset System
          dw        SEG System</pre>
 
==== 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.
 
<pre class="western">;                             
;--  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                          </pre>
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
 
<pre class="western">stack  --&gt;    dword  far return
        --&gt;    word    MAC's data_seg
        --&gt;    word    opcode for Bind (2)
        --&gt;    word    pad (0)
        --&gt;    dword  pointer where to return CCTable address
        --&gt;    dword  callers CCTable address</pre>
 
==== 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.
 
<pre class="western">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                            </pre>
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:
 
<pre class="western">      Stack    --&gt;    dword  far return
                --&gt;    word    MAC's data_seg</pre>
 
==== 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.
 
<pre class="western">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    </pre>
 
==== 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.
 
<pre class="western">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</pre>
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.
 
<pre class="western">      stack    --&gt;    dword  far return
                --&gt;    word    MAC's data_seg
                --&gt;    dword  pointer to buffer descriptor
                --&gt;    word    request handle
                --&gt;    word    Protocol ID</pre>
 
 
<pre class="western">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 --&gt;TxChain info
    mov        ax, REQUEST_QUEUED                     
    jmp        TxChainExit            ;      Return - xmit deferred
    ;                         
;--  We can send now.                         
;                             
    Call DoTransmit                    ;      Adapter specific
                                        ;      ss:bp--&gt;Txchain info
                                        ;      Returns status of xmit.
;                             
TxChainExit:                           
    pop        si                     
    pop        di                     
    pop        es                     
    pop        ds                     
    pop        bp                     
    ret        TxChainParmSize               
TransmitChain                          endp</pre>
 
=== 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.
 
<pre class="western">;                             
;-- 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                                </pre>
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.
 
<pre class="western">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                          </pre>
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.
 
<pre class="western">;                             
;--  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                          </pre>
 
==== 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.
 
<pre class="western">;                             
;-- 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</pre>
 
==== 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.
 
<pre class="western">;                             
;-- 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</pre>
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''' <br />'''Personal Software Products''' <br />'''11400 Burnet Road''' <br />'''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 &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
 
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or program(s) described in this publication at any time.
 
It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.
 
=== Copyright Notices ===
 
© '''Copyright International Business Machines Corporation 1993. All rights reserved.'''
 
Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
 
=== Disclaimers ===
References in this products to IBM products, programs or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of the intellectual property rights of IBM may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products except those expressly designated by IBM, are the responsibility of the user.
 
IBM may have patents or pending patent applications covering subject matter this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries in writing to the IBM Director of Commercial relations IBM Corporation Purchase NY 10577 - USA.
 
=== Trademarks ===
The following terms 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
 
== Table of Contents ==
 
* [[#Introduction|Introduction]]
* [[#PerformanceCriteria|Performance Criteria]]
* [[#PerformanceIssues|Performance Issues in NDIS MAC Device Driver Design]]
* [[#PerformanceImportant|Performance Important NDIS Verbs]]
** [[#TransmitChain|TransmitChain]]
** [[#TransferData|TransferData]]
** [[#TransmitConfirm|TransmitConfirm]]
* [[#InterruptProcessing|Interrupt Processing]]
* [[#SystemServiceUsage|OS/2 System Service Usage]]
* [[#ProgrammingPractices|Programming Practices]]
* [[#Notices|Notices]]
** [[#Copyright|Copyright Notices]]
** [[#Disclaimers|Disclaimers]]
** [[#Trademarks|Trademarks]]
 
[[[#PerformanceCriteria|next]]][[[#toc|parent]]][[[#toc|TOC]]]
 
=== Introduction ===
 
A Network Driver Interface Specification (NDIS) Media Access Control (MAC) device driver provides the software interface with a Specific communication adapter and makes that communication adapter system resources available to communications protocol stacks through the NDIS programming interface.
 
This document provides guidance to the creators of NDIS MAC device drivers to help them achieve good performance from their device driver implementations.
 
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 [[#InterruptProcessing|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, [[#PerformanceImportant|Performance Important NDIS Verbs]] and [[#InterruptProcessing|Interrupt Processing]], describe two areas where special attention must be focused to produce a high performing driver. The sections [[#SystemServiceUsage|System Service Usage]] and [[#ProgrammingPractices|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, [[#InterruptProcessing|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 [[lanmang.htm#SpecificationPrimitives|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 &quot;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 [[#PerformanceIssues|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 &quot;Writing Efficient Programs&quot; 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 &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
 
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or program(s) described in this publication at any time.
 
It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.
 
==== Copyright Notices ====
© '''Copyright International Business Machines Corporation 1993. All rights reserved.'''
 
Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
 
==== Disclaimers ====
References in this 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, <br />IBM Corporation, <br />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:
{|
|width="33%"|IBM
|width="33%"|OS/2
|width="33%"|Extended Services
|}
 
The following terms, denoted by a double asterisk (**) in this publication, are trademarks of other companies as follows:
{|
|width="50%"|Microsoft
|width="50%"|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 <br />For OS/2 and DOS <br />Random Redirected Transform Test User's Manual =
== Table of Contents ==
 
* [[#Preface|Preface]]
** [[#Purpose|Purpose of this Manual]]
** [[#PrerequisiteKnowledge|Prerequisite Knowledge]]
* [[#Chapter1|Chapter 1. Introduction]]
** [[#Overview|Overview]]
** [[#SoftwareInstallation|Software Installation]]
** [[#SystemRequirements|System Requirements]]
* [[#Chapter2|Chapter 2. Using RRTT]]
** [[#UserInterface|User Interface]]
*** [[#InformationScreens|Information Screens]]
*** [[#HelpScreen|Help Screen]]
** [[#TestingwithRRTT|Testing with RRTT]]
** [[#ChangingUserOptions|Changing User Options]]
** [[#ChangingReportMode|Changing Report Mode]]
** [[#UsingScriptFiles|Using Script Files]]
** [[#UserCommandLists|User Command Lists]]
*** [[#StaticUserOptions|Static User Options]]
*** [[#ExecutableUserOptions|Executable User Options]]
*** [[#RunTimeUserCommands|Run Time User Commands]]
* [[#Chapter3|Chapter 3. Command Descriptions]]
** [[#Name|Name]]
*** [[#Syntax|Syntax]]
*** [[#Description|Description]]
*** [[#Example|Example]]
*** [[#Limits|Limits]]
** [[#BDELAY|BDELAY- block delay time]]
** [[#BINTER|BINTER - turn on/off block interleaving]]
** [[#BSIZE|BSIZE - block size for file transfers]]
** [[#DRIVE|DRIVE - set the destination drive list]]
** [[#ERROR|ERROR - error count before test abort]]
** [[#EXIT|EXIT - exit the RRTT utility]]
** [[#FDELAY|FDELAY - file delay time]]
** [[#FNAME|FNAME - transfer file file name]]
** [[#FPATTERN|FPATTERN - file pattern for transfer files]]
** [[#FREPEAT|FREPEAT - transfer file repeat count]]
** [[#FSIZE|FSIZE - file size for dummy transfer file]]
** [[#HELP|HELP - display on-line help screens]]
** [[#JUMP|JUMP - jump to a script file label]]
** [[#LCOMMENT|LCOMMENT - write user comment into log file]]
** [[#LMODE|LMODE - sets the log mode for test reporting]]
** [[#LNAME|LNAME - log name]]
** [[#LOAD|LOAD - load a configuration file]]
** [[#MMODE|MMODE - set the monitor screen mode for reporting]]
** [[#PAUSECOPY|PAUSECOPY - pause after file copy]]
** [[#PMODE|PMODE - set the printer mode for test reporting]]
** [[#QUIT|QUIT - exit the RRTT utility]]
** [[#RESET|RESET - reset RRTT utility]]
** [[#RUN|RUN - run an RRTT test]]
** [[#SAVE|SAVE - save the current configuration]]
** [[#SCRIPT|SCRIPT - run a script file]]
** [[#SESSION|SESSION - set the session tag]]
** [[#TREPEAT|TREPEAT - test repeat count]]
* [[#Notices|Notices]]
** [[#Copyright|Copyrights]]
** [[#Disclaimers|Disclaimers]]
** [[#Trademarks|Trademarks]]
 
[[[#Purpose|next]]][[[#toc|parent]]][[[#toc|TOC]]]
 
== 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.
 
[[Image:images/ndisrrt1.gif]]
 
There are several keys which manipulate RRTTs user interface.
 
The &lt;F10&gt; 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 &lt;F10&gt; key is a toggle. When the cursor key is in the message area, the &lt;F10&gt; key will move the cursor back up tot he command line.
 
The &lt;Up&gt; and &lt;Down&gt; 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 &lt;F10&gt;, then the up/down arrow keys scroll through the screen's history and not through the command line history. An &lt;F10&gt; will restore the cursor to the command line and the arrow keys will again scroll through the command history.
 
The &lt;Left&gt; and &lt;Right&gt; arrow keys move the cursor left and right within the current command line.
 
The &lt;Insert&gt; 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 &lt;TAB&gt;and &lt;Shift&gt;&lt;TAB&gt; keys will move the menu bar tot he next information screen. &lt;TAB&gt; moves the menu to the right while &lt;Shift&gt;&lt;TAB&gt; moves the menu to the left.
 
The &lt;Alt&gt; key jumps to one of the Menu Bar items. Each of the menu items has a letter which is highlighted. When the &lt;Alt&gt; 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 &lt;ENTER&gt; to automatically type that command onto the command line. To exit this help screen without having the command entered into the command line type &lt;ESC&gt;. 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.
 
<pre class="western">        &gt;DR C:</pre>
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.
 
[[Image: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 &lt;F10&gt; and S.
 
To pause the RRTT test type &lt;F10&gt;. Upon completion of its current task, RRTT will toggle to the Monitor Screen and allow scrolling through past message lines. Typing a second &lt;F10&gt; 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:
 
<pre class="western">        &gt;FPATTERN RAN 0X00 0X60
 
        &gt;FSIZE INC 1 10000
 
        &gt;BSIZE RAN 100 2000
 
        &gt;BDELAY 100</pre>
FPATTERN STANDS FOR &quot;file pattern&quot; 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 &quot;file size&quot; 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 &quot;block size&quot; 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 &quot;block delay time&quot; 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.
 
<pre class="western">        &gt;LMODE SILENT</pre>
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|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.
 
<pre class="western">        # 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</pre>
To run a script file from RRTTs command line type:
 
<pre class="western">       
        &gt;SCRIPT script_file_name</pre>
This same script file could also be entered on the command line as follows:
 
<pre class="western">        [C:\]RRTT script-file-name</pre>
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.
 
{|
|width="50%"|'''NAME'''
|width="50%"|'''DESCRIPTION'''
|-
|<code>BDelay</code>
|Set the block delay for file transfers
|-
|<code>BInter</code>
|Turn on/off block transfer interleaving
|-
|<code>BSize</code>
|Set the block size for file transfers
|-
|<code>DRive</code>
|Set destination drive for testing
|-
|<code>ERror</code>
|Set number of errors before test abort
|-
|<code>FDelay</code>
|Set the file delay time between transfers
|-
|<code>FName</code>
|Set the transfer file name if user defined
|-
|<code>FPattern</code>
|Set the file contents to a specific pattern
|-
|<code>FRepeat</code>
|Set the file repeat count per test pass
|-
|<code>FSize</code>
|Set the transfer file size
|-
|<code>LMode</code>
|Turn on/off log and set log report mode
|-
|<code>LName</code>
|Change default log file name
|-
|<code>MMode</code>
|Set Monitor Screen report mode
|-
|<code>PAusecopy</code>
|Pause the test prior to comparing a file
|-
|<code>PMode</code>
|Set printer report mode
|-
|<code>SEssion</code>
|Set a unique session number
|-
|<code>TRepeat</code>
|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.
 
{|
|width="50%"|'''NAME'''
|width="50%"|'''DESCRIPTION'''
|-
|<code>HELP or ?</code>
|Display on-line help screens
|-
|<code>EXit</code>
|Exit the application
|-
|<code>LComment</code>
|Write a comment into the log file
|-
|<code>LOAD</code>
|Load a configuration file
|-
|<code>QUit</code>
|Exit the application
|-
|<code>REset</code>
|Reset all the User Options
|-
|<code>RUN</code>
|Run a test
|-
|<code>SAve</code>
|Save the current configuration
|-
|<code>SCRIPT</code>
|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.
 
{|
|width="50%"|'''NAME'''
|width="50%"|'''DESCRIPTION'''
|-
|<code>S</code>
|Stop current test
|-
|<code>X</code>
|Exit application
|-
|<code>F10</code>
|Pause test and toggle to Monitor Screen
|-
|<code>TAB</code>
|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:
 
{|
|width="50%"|'''Name'''
|width="50%"|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 &quot;[]&quot; are option and only one operand in a list enclosed with arrow brackets &quot;&lt;&gt;&quot; 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 &quot;&gt;&quot; 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 ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>BDelay [&lt;DEF, INC, OFF, RAN,            RES&gt;] ms_time [max_time]</code>
|-
|'''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'''
|<code>&gt;BD RAN 30 90</code>
 
Sets the block delay time to be a random value between 30 and 90 milliseconds.
|}
 
=== BINTER - turn on/off block interleaving ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>BInter &lt;DEF, OFF, ON, RES&gt;</code>
|-
|'''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'''
|<code>&gt;BI ON</code>
 
Turns on the interleave capability.
|-
|'''Limits'''
|DEFAULT: OFF
 
MIN: N/A
 
MAX: N/A
|}
 
=== BSIZE - block size for file transfers ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>BSize [&lt;DEF, INC, RAN, RES&gt;]            size [max_size]</code>
|-
|'''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'''
|<code>&gt;BS INC 256 0x2000</code>
 
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 ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>DRive [&lt;-,RES&gt;] drive_name            [drive_name ...]</code>
|-
|'''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 &quot;-&quot; 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'''
|<code>&gt;DR - \\server1\root g:\tmp</code>
 
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 ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>ERror&lt;DEF,OFF,RES,error_count&gt;</code>
|-
|'''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 &quot;break on error&quot; 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'''
|<code>&gt;ER OFF</code>
 
Continue upon receiving an error.
|-
|'''Limits'''
|DEFAULT: 1(break on error)
 
MIN: OFF
 
MAX: 999999999
|}
 
=== EXIT - exit the RRTT utility ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>EXit</code>
|-
|'''Description'''
|Exit exits the RRTT utility.
|-
|'''Example'''
|<code>&gt;EXIT</code>
 
Exits the RRTT utility.
|-
|'''Limits'''
|DEFAULT: N/A
 
MIN: N/A
 
MAX: N/A
|}
 
=== FDELAY - file delay time ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>FDelay &lt;DEF,OFF,RES,delay_time&gt;</code>
|-
|'''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'''
|<code>&gt;FD 1.5</code>
 
Sets a delay between files of 1.5 seconds.
|-
|'''Limits'''
|DEFAULT: OFF
 
MIN: 0
 
MAX: 30.0 seconds
|}
 
=== FNAME - transfer file file name ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>FName            &lt;DEF,RES,transfer_file_name&gt;</code>
|-
|'''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'''
|<code>&gt;FN USER.TST</code>
 
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 ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>FPattern [&lt;DEF,INC,RAN,RES&gt;]            value [max_value]</code>
|-
|'''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'''
|<code>&gt;FP 12345abcde</code>
 
Fills the transfer file with repetitions of this string.
 
<code>&gt;FP RAN 0x20 0xE0</code>
 
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 ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>FRepeat &lt;DEF,RES,count&gt;</code>
|-
|'''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'''
|<code>&gt;FR 1000</code>
 
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 ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>FSize [&lt;DEF,INC,RAN,RES&gt;]            value [max-value]</code>
|-
|'''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'''
|<code>&gt;FS RAN</code>
 
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 ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>HElp</code>
|-
|'''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 &lt;ENTER&gt; or &lt;RETURN&gt; key will exit the help screen with the current command selection already typed into the command line. Typing the &lt;ESC&gt; 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'''
|<code>&gt;HELP</code>
 
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 ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>JUMP [[!]&lt;condition_code&gt;]            [&lt;label&gt;]</code>
|-
|'''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 &quot;!&quot; 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'''
|<code>JUMP</code>
 
Skips the execution of the next command.
 
<code>JUMP !DRIVE_ERROR</code>
 
Skips the execution of the next command if no errors occurred during the last RUN.
 
<code>JUMP DRIVE_ERROR ExitScript</code>
 
Continues execution of the script file from after the label :ExitScript if an error occurred during the last RUN.
 
<code>:ExitScript</code>
 
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 ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>LComment text_string</code>
|-
|'''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'''
|<code>&gt;LC start of test number 5</code>
 
Writes &quot;start of test number 5&quot; into the active log file.
|-
|'''Limits'''
|DEFAULT: N/A
 
MIN: N/A
 
MAX: N/A
|}
 
=== LMODE - sets the log mode for test reporting ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>LMode            &lt;DEF,OFF,ON,RES,SIL,TER,VER,file_name&gt;</code>
|-
|'''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'''
|<code>&gt;LMODE VERBOSE</code> <br /><code>&gt;LMODE            RESET</code>
 
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 ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>LName &lt;DEF,RES, file_name&gt;</code>
|-
|'''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'''
|<code>&gt;LN USER.LOG</code>
 
Redefines the log file name to USER.LOG.
|-
|'''Limits'''
|DEFAULT: RRTT.LOG
 
MIN: N/A
 
MAX: N/A
|}
 
=== LOAD - load a configuration file ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>LOAD [file_name]</code>
|-
|'''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'''
|<code>&gt;LOAD TEST8.CFG</code>
 
Executes the configuration file TEST8.CFG
|-
|'''Limits'''
|DEFAULT: RRTT.CFG
 
MIN: N/A
 
MAX: N/A
|}
 
=== MMODE - set the monitor screen mode for reporting ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>MMode &lt;DEF,RES,SIL,TER,VER&gt;</code>
|-
|'''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'''
|<code>&gt;MMODE SILENT</code>
 
Do not monitor the RRTT test with the Monitor Screen.
|-
|'''Limits'''
|DEFAULT: VERBOSE
 
MIN: N/A
 
MAX: N/A
|}
 
=== PAUSECOPY - pause after file copy ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>PAusecopy&lt;ON,OFF&gt;</code>
|-
|'''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'''
|<code>&gt;PA ON</code>
 
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 ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>PMode            &lt;DEF,OFF,ON,RES,SIL,TER,VER&gt;</code>
|-
|'''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'''
|<code>&gt;PM SIL</code>
 
Activate the printer to record error information.
|-
|'''Limits'''
|DEFAULT: SILENT
 
MIN: N/A
 
MAX: N/A
|}
 
=== QUIT - exit the RRTT utility ===
{|
|width="50%"|'''Syntax'''
|width="50%"|<code>QUit</code>
|-
|'''Description'''
|QUIT exits the RRTT utility and is identical to EXIT.
|-
|'''Example'''
|<code>&gt;QUIT</code>
 
Exit RRTT
|-
|'''Limits'''
|DEFAULT: N/A
 
MIN: N/A
 
MAX: N/A
|}
 
== Notices ==
January, 1996
 
Issued by:
 
'''IBM Corporation''' <br />'''Personal Software Products''' <br />'''11400 Burnet Road''' <br />'''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 &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
 
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or program(s) described in this publication at any time.
 
It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.
 
=== Copyright Notices ===
© '''Copyright International Business Machines Corporation 1993. All rights reserved.'''
 
Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
 
=== Disclaimers ===
References in this products to IBM products, programs or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of the intellectual property rights of IBM may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products except those expressly designated by IBM, are the responsibility of the user.
 
IBM may have patents or pending patent applications covering subject matter this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries in writing to the IBM Director of Commercial relations IBM Corporation Purchase, NY 10577, 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 <br />IBM Product Overview =
== Table of Contents ==
 
* [[#About|'''About This Publication''']]
* [[#Sec10|'''1.0 NDIS Overview''']]
* [[#Sec20|'''2.0 LAN Adapter and Protocol Support Overview''']]
* [[#Sec30|'''3.0 IBM OS/2 LAN Server Version 2.0''']]
* [[#Sec31|3.1 Adapter Support for IBM OS/2 LAN Server Version 2.0]]
* [[#Sec40|'''4.0 IBM Extended Services for OS/2''']]
* [[#Sec41|4.1 Adapter support for IBM Extended Services for OS/2]]
* [[#Sec50|'''5.0 IBM LAN Enabler Version 2.0''']]
* [[#Sec51|5.1 Description]]
* [[#Sec52|5.2 Adapter Support for IBM LAN Enabler Version 2.0]]
* [[#Sec60|'''6.0 IBM TCP/IP for OS/2 V 1.2.1''']]
* [[#Sec61|6.1 Description]]
* [[#Sec62|6.2 Adapter Support for TCP/IP for OS/2]]
* [[#Sec70|'''7.0 DOS LAN Support Program''']]
* [[#Sec80|'''8.0 LAN Products Requiring DOS LAN Support Program''']]
* [[#Sec81|8.1 OS/2 Products]]
* [[#Sec82|8.2 DOS Products]]
* [[#Sec90|'''9.0 NDIS Network Driver Enablement Process''']]
* [[#Sec91|9.1 IBM Testing Overview]]
* [[#Sec92|9.2 NDIS MAC Driver Enablement Overview]]
* [[#Sec93|9.3 NDIS Driver Enablement Offering]]
** [[#Sec931|9.3.1 DWB Functional Verification Test]]
** [[#Sec932|9.3.2 National Software Testing Laboratories Compatibility Test]]
** [[#Sec933|9.3.3 IBM Complementary Delivery of OEM NDIS MAC Drivers]]
*** [[#Sec9331|9.3.3.1 Prerequisites for Distribution]]
*** [[#Sec9332|9.3.3.2 NDIS Driver Availability For Customers]]
** [[#Sec934|9.3.4 National Language Support]]
* [[#Notices|Notices]]
** [[#Copyright|Copyrights]]
** [[#Disclaimers|Disclaimers]]
** [[#Trademarks|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.
 
[[Image: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.
 
[[Image: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.
 
[[Image: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.
 
[[Image: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.
 
[[Image:images/overvi51.gif]] [[Image: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.
 
[[Image:images%5Covervie6.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:
 
<pre class="western">  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</pre>
 
 
 
 
== '''Notices''' ==
 
May, 1993
 
Issued by:
 
'''IBM Corporation''' <br />'''Personal Software Products''' <br />'''11400 Burnet Road''' <br />'''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 &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
 
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or program(s) described in this publication at any time.
 
It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.
 
 
-----
 
 
 
=== Copyright Notices ===
 
© '''Copyright International Business Machines Corporation 1992, 1993. All rights reserved.'''
 
Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
 
 
-----
 
 
 
=== Disclaimers ===
 
References in this 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:
 
{|
|width="33%"|OS/2
|width="33%"|IBM
|width="33%"|Extended Services
|}
 
The following terms, denoted by a double asterisk (**) in this publication, are trademarks of other companies as follows:
 
{|
|width="50%"|Microsoft
|width="50%"|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:
 
* [[lanmang.htm|''3Com*/Microsoft LAN Manager** Network Driver Interface Specification Version 2.0.1 Final'']]
* [[overview.htm|''LAN Adapter and Protocol Support IBM Product Overview'']]
* [[serverov.htm|''IBM OS/2 LAN Server 3.0 Product Overview'']]
* [[transpor.htm|''IBM Network Transport Services/2 Version 1.0 Product Overview'']]
* [[requirem.htm|''NDIS Implementation Information for IBM LAN Systems, NDIS Device Driver Requirements'']]
* [[inifform.htm|''NDIS Implementation Information for IBM LAN Systems, Extended NIF Format'']]
* [[extent.htm|''NDIS Implementation Information for IBM LAN Systems, NDIS Extensions'']]
* [[techref.htm|''NDIS Implementation Information for IBM LAN Systems, OS/2 Messaging and National Language Support'']]
* [[mesnls.htm|''NDIS Implementation Information for IBM LAN Systems, IBM OS/2 LAN Technical Reference Extensions'']]
* [[interop.htm|''White Paper on NetBIOS Applications Interoperability'']]
 
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 DOS''is 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. <br />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]]
*[[IBM OS/2 LAN Server 3.0 Product Overview]]
*[[NDIS Implementation Information for IBM LAN Systems - IBM OS/2 LAN Technical Reference Extensions]]
*[[NDIS Driver Developer's Tool Kit for OS/2 and DOS TestTool User's Manual]]
*[[NDIS Driver Developer's Tool Kit for OS/2 and DOS TestTool User's Manual]]


= Documents =
[[Category:LAN Device Driver Documentation]]
 
* [[IBM Network Transport Services/2 Version 1.0 Product Overview]]
 
[[Category:Driver Articles]]

Latest revision as of 18:06, 28 August 2017

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

Retrieved from "https://www.edm2.com/index.php?title=LAN_Device_Driver_Documentation&oldid=49364"