NDIS Implementation Information for IBM LAN Systems - Extended NIF Format

From EDM2
Jump to: navigation, search

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

About This Document

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

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

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

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

This document refers to the following publications for additional information:

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

1.0 NDIS NIF File Definition

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

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

2.0 NIF Format Definition and Description

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

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

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

2.1 Common Sections

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

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

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

Definitions:

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

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

2.2 Parameter Section

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

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

Definitions:

[parameter_]

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

Tag

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

Interrupt
Identifies an interrupt level
IOAddress
Identifies an I/O address
DMAChannel
Identifies a DMA channel
RamAddress
Identifies a RAM address
RamAddrSize
Identifies the RAM size
RomAddress
Identifies a ROM address
RomAddrSize
Identifies the ROM size

Note: LAPS does not currently use the tag keyword.

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

NlsSet

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

DecNum1,...,DecNumN for decimal types

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

String1,...,StringN for String types

Note: NlsSet and range are mutually exclusive.

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

Scope

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

Global

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

Local

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

Optional

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

NO

Required for Basic (and Advanced) configuration.

YES

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

Editable

Optionally specifies whether the user can edit parameter values.

NO

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

YES

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

Virtual

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

NO

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

YES

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

Help

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

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

2.3 Multiple NIF Files per Driver

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

3.0 NIF File Example

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

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

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

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

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

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

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

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

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

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

4.0 SNIFFLE - A NIF validator

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

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

SNIFFLE IBMTOK.NIF

Notices

May, 1993

Issued by:

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

First Edition (May 1992)

Second Edition (May 1993)

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

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

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

Copyright Notices

© 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:

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