NDIS Implementation Information for IBM LAN Systems - Extended NIF Format

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

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

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


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

This document refers to the following publications for additional information:
 * Microsoft/3Com LAN Manager Network Driver Interface Specification (NDIS), Version 2.0.1, October 8, 1990
 * NDIS implementation Information for IBM LAN Systems, OS/2 Messaging and National Language Support, May 1993
 * NDIS Implementation Information for IBM LAN Systems, NDIS Extensions, May 1993

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

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

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

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

2.1 Common Sections
[component name] Type =  Title =  Version= Component version number> Drivername=  {Xports=  {, ,...,}} {Exec = } {Copyfile = <8.3 File name> {,<8.3 File name>,...,<8.3 File name>}}
 * Note:Entries enclosed in braces {} are optional. Text surrounded by less than and greater than symbols < > is not significant and is used for information purposes only.

[File] Name = Filename> {,,...,} {Path = } Definitions:


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


 * Type:Defines the driver type as follows:
 * NDIS:This is used for MAC drivers only. A MAC driver of this type would expect a DEVICE= statement in CONFIG.SYS for every instance of the driver to be loaded. It would also expect a numeric digit appended to the driver name in the PROTOCOL.INI file for every nth instance of the driver, where n is greater than 1.
 * NDIS_SNGL:This is used for MAC drivers only. A MAC driver of this type would expect only one DEVICE= statement in CONFIG.SYS regardless of how many instances of the driver were configured. It would also expect every instance of the driver name to be identical (no numeric digit appended) in the PROTOCOL.INI file.
 * NDIS_MULT:This is used for MAC drivers only. A MAC driver of this type would expect a DEVICE= statement in CONFIG.SYS for every instance of the driver to be loaded in much the same way as a driver of type NDIS. However, it would also expect that subsequent instances of the DEVICE= statements in the CONFIG.SYS file be built using the names on the NAME = statement in the NIF file. The first DEVICE= would be given the first name on the NAME= statement, the second DEVICE= would be given the second name on the NAME= statement, and so on. The number of adapters supported for drivers of this type is limited to the number of files listed on the NAME= statement in the NIF file. As with a driver of type NDIS, it would also expect a numeric digit appended to the drivername in the PROTOCOL.INI file for every nth instance of the driver where n is greater than 1.
 * PROTOCOL:NDIS protocol driver
 * SERVICE:There are no services defined at this time.


 * Title:Defines the component name that would be displayed to the user during configuration. For a MAC driver, this is the adapters supported by this driver. For a protocol driver, this is the type of protocol that was provided by this driver.


 * Version:Defines the version of the component. The recommended format for this field is xxx where x can be any numeric digit. Although this field is not used by LAPS at this time, it may be used in the future to implement some form of driver versioning. In that case, xxx would be treated as a DecNum as defined later in this section.
 * DriverName''':Defines the name that is placed in PROTOCOL.INI.
 * Xports:Defines for an NDIS driver the list of transports with which the driver has been tested and certified. This is done by comparing this value with the drivername field of all protocol drivers.
 * Exec:Defines an executable file that would be called after the driver is installed and configured. It is ignored by LAPS at this time.
 * CopyFile:Allows for specification of files to be copied if this configuration is to be used on another system. The IBMCOM subdirectory is assumed by LAPS and should be omitted.
 * File.Name:|Defines the name of the device driver that will be added to CONFIG.SYS using a DEVICE= statement. No path should be included with this keyboard.
 * File.Path:Defines the location of all previously listed device drivers. This keyword would be ignored by LAPS since all drivers are placed in \IBMCOM\MACS or in \IBM\PROTOCOL. This keyword is optional.

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

2.2 Parameter Section
Although parameter definitions are not required, most NIF files have them following the common information. Each parameter and its attributes are grouped in sections with the parameter name as the section name. The parameter name, enclosed in brackets, precedes each section, with attributes on separate lines. Keywords are pre-defined (there are no "roll your own" keywords). Configuration code ignores unrecognized keywords. The format of the parameter section is as follows: [parameter_name] Tag =  < Interrupt | IOAddress | DMA Channel | RamAddress | RamAddrSize | RomAddress | RomAddrSize > Display =      < "display text" > Type = < DecNum | Hexadecimal | HexNum | String | HexString | None | Decimal> StrLength = < X > (where X is a Decimal value) Default =      < Default Value > Range = < 1 - X | X > Step =  Set =  < Value1, Value2,...,ValueX > NlsSet =       < Value1, Value2,...,ValueX > Scope = < Global | Local > Optional =     < Yes | No > Editable =     < Yes | No > Virtual =      < Yes | No > Help = < "help text" > Definitions:

[parameter_]

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

Tag

A tag used to help identify and manage parameter cross-checking and conflict identification. The tag is not placed in PROTOCOL.INI. Tag can have the following values:
 * Interrupt:Identifies an interrupt level
 * IOAddress:Identifies an I/O address
 * DMAChannel:Identifies a DMA channel
 * RamAddress:Identifies a RAM address
 * RamAddrSize:Identifies the RAM size
 * RomAddress:Identifies a ROM address
 * RomAddrSize:Identifies the ROM size


 * Note:LAPS does not currently use the tag keyword.


 * Display:Identifies the text that is displayed to the user when prompted for input for this parameter. This a required field.
 * Type:Identifies the data type of the parameter. It may have the following values:
 * Decimal:UnSigned numeric value, for example, the number 256. It is converted to a 31-bit signed numeric value, so it cannot exceed that value.
 * DecNum:UnSigned numeric value. It is converted to a 32-bit unsigned numeric value, so it cannot exceed that value.
 * Hexadecimal:Signed numeric value. The hexadecimal equivalent of a signed decimal value. This is placed in PROTOCOL.INI. with 0x preceding the hexadecimal value (the 0x should be omitted in the NIF file).
 * HexNum:Unsigned numeric value. The hexadecimal equivalent of an unsigned decimal value. This is place in PROTOCOL.INI with 0x preceding the hexadecimal value (the 0x should be omitted in the NIF file).
 * String:String consists of ASCII characters. Strings containing commas or blank space must be enclosed in quotes. It is placed in PROTOCOL.INI by LAPS as a quoted string.
 * HexString:String consisting of valid hexadecimal characters. It is validated by the configuration utility and placed in PROTOCOL.INI as a quoted string.
 * None:The parameter itself is the value. This is also assumed if the keyboard is absent.
 * StrLength:Identifies the maximum length of the string or HexString parameter type and is required for these types.
 * Default:The optional default value for the current parameter.
 * Range:An optional range in the form:
 * DecNum - DecNum for decimal types
 * HexNum-HexNum for hexidecimal or hexstring types.
 * Note: If no upper bound is specified, it implies that there is no maximum value (Nomax).
 * Step Optional step value used in conjunction with the range to provide for modulo or rounding. It can be a numeric or the special value K, for Kilobytes. Step defaults to 1. This keyword is optional.


 * Set:An optional set of valid values for the parameter in the form:
 * DecNum1,...,DecNumN for decimal types
 * HexNum1,...HexNumN for hexadecimal and/or hexString types
 * String1,...,StringN for String types
 * Note: Set and range are mutually exclusive.

NlsSet

An optional set of valid values for the parameter in the form:
 * DecNum1,...,DecNumN for decimal types
 * HexNum1,...,HexNumN for hexadecimal and/or hexString types
 * String1,...,StringN for String types
 * Note: NlsSet and range are mutually exclusive.


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

Scope

This keyword defines how the parameter should be treated if the driver supports multiple instances. This applies to transport drivers only. Values for scope are:
 * Global:Only one instance of the parameter can be entered. It apples to all adapters bound by the protocol. This is the default.
 * Local:Optional values are allowed on a per adapter basis. In PROTOCOL.INI, the parameter values, separated by commas, follow the equal sign (=).
 * Optional:Optionally specifies whether the parameter is required at all times or not:
 * NO Required for Basic (and Advanced) configuration.
 * YES Optional. If not changed by the user, and there is no default, the parameter is omitted from PROTOCOL.INI. In this case, it is assumed that the device driver has hard-coded the default. YES is the default.

Editable

Optionally specifies whether the user can edit parameter values.

NO

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

YES

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

Virtual

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

NO

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

YES

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

Help

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

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

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

3.0 NIF File Example
This example is the original NDIS MAC driver that was shipped with LAPS in Extended Services for OS/2 and OS/2 LAN Server 2.0 for support of the IBM Token-Ring Network 16/4 Bus Master Server Adapter/A. [IBMTRBM] Type = NDIS_SNGL Title = "IBM Token-Ring Network Busmaster Server Adapter" Version= 1.0 DriverName = IBMTRBM$ XPORTS = NETBEUI LANDD COPYFILE = MACS\MONT400.BIN, MACS\WRTRAM.BIN, LT4.MSG, LT4H.MSG

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

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

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

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

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

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

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

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

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

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

Notices
May, 1993

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

First Edition (May 1992)

Second Edition (May 1993)

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

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

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

Copyright Notices
© '''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: