NDIS Implementation Information for IBM LAN Systems - NDIS Device Driver Requirements

From EDM2
Revision as of 17:10, 9 April 2017 by Ak120 (Talk | contribs)

Jump to: navigation, search

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

Contents

About This Publication

This publication provides a description of requirements for device drivers written to the Network Driver Interface Specification (NDIS). The requirements identified are primarily product-related such as: installation, configuration and packaging. It is intended as a supplement to the functional requirements identified in the NDIS specification. The relationship of key NDIS functions to IBM* LAN software products using both DOS* and OS/2* are explained.

Related Publications

  • 3Com**/Microsoft** LAN Manager Network Driver Interface Specification
  • IBM NTS/2* LAN Adapter and Protocol Support* Configuration Guide (96F8489)
  • IBM LAN Support Program Users' Guide (20G0988)
  • IBM LAN Technical Reference (SC30-3383)
  • IBM LAN Technical Reference Supplement (SD21-0049)
  • NDIS Implementation Information for IBM LAN Systems, OS/2 Messaging and National Language Support
  • NDIS Implementation Information for IBM LAN Systems, NDIS Extensions
  • NDIS Implementation Information for IBM LAN Systems, Extended NIF Format
  • PS/2 Hardware Interface Tech Ref - Architectures (S84F-9808)

1.0 NDIS Device Driver Requirements

1.1 Deliverables

The following items are required deliverables for an NDIS device driver:

  • Documentation file
    The purpose of the documentation file(s) is to provide all the information necessary to use the NDIS device driver(s). For a detailed description of the documentation file refer to section 2.3, "Documentation file requirements".
  • DOS
    • DOS device driver executable file
    • Network Information File (NIF)
    • Message file
    The DOS message file is identical to the OS/2 message file. For a detailed description of message files refer to section 1.4, "Device driver message support".
  • OS/2
    • OS/2 device driver executable file
    • Network Information File (NIF)
    • Message file
    • Message help file

1.2 File Naming Conventions

1.2.1 Device driver executable file

The filenames of the DOS and OS/2 NDIS device drivers should indicate the type of LAN adapter supported. For example, IBMTOK, IBMFDDI and MACETH indicate Token-Ring, FDDI and Ethernet respectively. The extension should be "DOS" or "OS2" as in: IBMTOK.DOS, IBMFDDI.OS2 and MACETH.OS2. For a list of IBM NDIS device drivers see Appendix B. "IBM MAC device drivers".

1.2.2 Message tile

The DOS and OS/2 message files must have a 3 character filename and an extension of "MSG". For example, LT2.MSG, LT5.MSG and MAC.MSG are the message files for the IBMTOK, IBMFDDI and MACETH device drivers.

Note, the message filenames of "LTn" are a convention used by IBM generated device drivers. This naming convention came about because early versions of NDIS support in OS/2 were referred to as "LAN Transport". Even though LAN Transport existed only in the OS/2 environment, the naming convention has been carried over to DOS NDIS device drivers for consistency.

Note, the messages in the message file use the filename as a message prefix. For example, LT20033E, would be the 33rd message in the LT2.MSG file. Message numbers are considered essential in problem resolution. This topic will be discussed in section 1.4, "Device driver message support".

1.2.3 Message help file

Message help files have an "H" appended to the filename of the associated message file. For example, LT2H.MSG is the message help file for LT2.MSG. The message help files contain a detailed explanation of the message and a suggested user action. They are used in conjunction with the OS/2 Help Facility. This topic will be discussed in more detail in section 1.4, "Device driver message support".

1.2.4 NIF and other miscellaneous files

The network information file (NIF) should have the same filename as the executable device driver. This leads to the OS/2 and DOS NIF file (files with different contents) having the same filename and extension, for example IBMFDDI.NIF. However, this has never surfaced as a problem since they are isolated in separate directories and never used in the same installation process.

Miscellaneous files should also use the filename of the executable device driver when possible. For example, the file containing the downloadable microcode for the IBM FDDI Workstation adapters is named IBMFDDI.BIN.

1.3 Installation and Configuration issues

1.3.1 Network information files

NDIS device driver installation entails copying the necessary device driver files from the adapter's option diskette and modifying the configuration files so that the device driver can be started successfully. Device driver configuration allows users to alter attributes of the device driver such as: number of buffers, buffer sizes, timer values or other adapter specific options. Device driver installation and configuration are closely related since they are often done in the same procedure.

In DOS, the device driver installation and configuration can be done by the DXMAID program of LAN Support Program. In OS/2, the same results can be accomplished using the LAN Adapter and Protocol Support (LAPS) installation and configuration program. Both of these programs rely on the device driver's network information file (NIF) to define the installation and configuration framework for the driver.

A NIF file which is written according to the Extended NIF Format chapter must be supplied with every NDIS device driver. For installation, the NIF describes which files must be copied from the adapter's option diskette and how to modify the CONFIG.SYS and PROTOCOL.INI files. For configuration, the NIF provides parameter ranges, defaults and help information.

The SNIFFLE.EXE utility will verify the syntax of the NIF file. Some details about NIF file contents are in the next

1.3.2 Support of NETADDRESS keyword

If the NDIS device driver supports "software gettable station addresses" according to the service flags of the MAC Service-Specific Characteristics table, it should provide a NETADDRESS option in the NIF. This allows multiple protocol stacks to share the same adapter without requiring the protocols to be started in a certain order.

Note, inform the user that the MAC address should be specified in canonical form for any of the Ethernet MAC types and non-canonical form (or MSB, most significant bit first) for the 802.5 MAC type. This information can be provided in the NETADDRESS parameter help text.

The NDIS device driver must guarantee that the "group address" bit is not set via the NETADDRESS parameter. The "group address" bit is the most significant bit of the 48 bit destination address (in non-canonical form). This rule may actually be enforced by the adapter. If not, the NDIS device driver must prevent a group address from being assigned as a locally administered address.

It is also possible to set the locally administered address of an adapter from some protocol drivers. This support exists for those NDIS MAC drivers which do not support NETADDRESS. Unfortunately it is a source of confusion for NDIS MAC drivers which support NETADDRESS. If the locally administered address is set by both the NDIS MAC driver and the protocol driver, the protocol driver's address is set last and therefore overwrites the address set by the NDIS MAC driver.

1.3.3 DRIVERNAME string in OS/2 NIFs

The drivername string must not end with a decimal number(s) in order to circumvent a problem in an early version of the LAPS installation and configuration program. In this version of the program, a drivername string which ends with a decimal number will not have its DEVICE= statement automatically inserted into the CONFIG.SYS file. This problem was resolved in LAPS version 2.10. The level of LAPS can be queried with the OS/2 command, SYSLEVEL.

1.3.4 NIF Title

The DOS and OS/2 NIF titles should contain the name of the adapter followed by the filename of the device driver executable in parenthesis. An example of a DOS NIF title would be: 

IBM Token-Ring Network 16/4 Adapter II (IBM16TR.DOS)

This is the format that the LAN Support Program uses and it seems to make sense to couple the adapter to a device driver filename.

1.3.5 OS-specific features

The NIF file is the appropriate place to introduce OS-specific installation and configuration alternatives. Since system memory is a more valuable resource in DOS than OS/2, the default configuration for the DOS NIF file may allocate less system memory than the OS/2 NIF file. For example, buffer-size defaults may be minimal on DOS, enough to accommodate the maximum frame size. But on OS/2 the buffer-size defaults may be larger.

1.3.6 Manual installation and configuration

When a user does not have the DXMAID or LAPS installation and configuration programs available, they will have to manually install and configure the device driver. Manual installation and configuration should be avoided whenever possible. The purpose of the installation and configuration programs is to protect the user from the unique installation and configuration features of each device driver.

When necessary, the user can manually install the device driver by copying the appropriate files off of the adapter's option diskette and updating the CONFIG.SYS and PROTOCOL.INI files. The device drivers can be manually configured by altering the device driver's section of the PROTOCOL.INI file. Manual installation and configuration must be addressed in the documentation file of the adapter's option diskette. Refer to section 2.3, "Documentation file requirements"for a detailed description of the documentation file guidelines.

1.4 Device driver message support

The NDIS device driver message support is described in detail in the OS/2 Messaging and National Language Support chapters. A brief summary of message support and the DOS and OS/2 differences is described in the following sections.

1.4.1 Message file utility

The OS/2 Programmer's Toolkit contains a Message file utility called MKMSGF.EXE. This utility must be used to create the message file and the message help file. The MKMSGF.EXE utility translates a flat ASCII file into a packed file with a header which describes the offset and length of each message. The DosGetMessage function call requires that the message file is prepared by the MKMSGF.EXE utility.

Messages can no longer be built internal to the device driver. The external message file is a feature common to both DOS and OS/2 device drivers.

1.4.2 Message numbers

Message numbers are considered essential in problem resolution. Message numbers are of the format: PPPnnnns. Where PPP is a message prefix, for example LT2 and nnnn is a decimal number. The last character is either an: "E" (error), "I" (informational) or "W" (warning) indicating the severity of the message.

Message numbering is a feature common to both DOS and OS/2 device drivers. For a list of the reserved message prefixes see Appendix C, "Reserved message prefixes".

1.4.3 OS/2 message device driver logging

The OS/2 message device driver provides a feature which will receive messages from other device drivers. These messages will be written to a log file (\...\LANTRAN.LOG). The log file can be checked for error or warning messages after the system has completed initialization. The log file is very useful for verifying the successful initialization and Binding of the device drivers in the system. The message device driver logging is available only on OS/2 systems.

1.4.4 OS/2 help facility

The OS/2 help facility allows a user to get a detailed explanation and suggested action for an error message. The help facility obtains the explanation and suggested action information from the device driver's message help file. The help facility is invoked by entering "help" followed by the message number at the OS/2 command prompt, for example, "HELP LT20033E". This feature is available only on OS/2 systems.

Note, the OS/2 help facility expects the message prefix to be only 3 characters in length.

1.5 Copyright

All device drivers must have the appropriate copyright information. This usually consists of displaying a copyright statement to the screen during system initialization as well as expanding the copyright statement in ASCII form in the beginning of the executable code. Make sure you consult your company's legal department for your specific product's requirements.

1.6 National Language Support (NLS)

1.6.1 Message and message help translation

The message file and message help file must be translated for every language supported. The translators must be instructed to NOT translate: filenames (eg. PROTOCOL.INI), keywords (eg. DRIVERNAME), or directories etc.

1.6.2 NIF translation

Everything within double quotes can be translated in the NIF file. The single exception is that default values are specified in double qoutes and these can't be translated. The items of the NIF which usually have to be translated are: the title of the common section, the display text and help text of each parameter section. This is very similar to the translation necessary for the adapter definition file (ADF).

Note, the name of each parameter in the parameter section of the NIF file is NOT translated. The device driver does not need to search for translated keywords in the PROTOCOL.INI file.

1.6.3 Documentation file translation

Each documentation file will have unique translation instructions. The translators must be instructed to NOT translate: filenames (eg. PROTOCOL.INI), keywords (eg. DRIVERNAME), or directories etc.

1.6.4 Verification and testing

It's very important that the implementation of the translated files be verified, especially double byte character sets (DBCS).

1.7 NDIS support

802.5 MAC types must support the IBM Extensions described in the NDIS Extensions chapter. These extensions are necessary for the NDIS implementation of the 802.2 protocol stack to be consistent with the native (before NDIS) 802.2 implementation.

Also, as stated in the NDIS specification, the NDIS device driver must provide a general MAC type of 802.5, 802.3, DIX or DIX + 802.3 to be a "generally available" MAC. If the adapter is not one of the general medias, an internal mapping between the actual media and a general MAC type must be made by the NDIS device driver.

1.8 Functional requirements

1.8.1 Addressing limitations

A 16-bit adapter has 24 address connections which allow it to use addresses less than 16 MB. When an address greater than or equal to 16 MB is given to the NDIS device driver, it should return INVALID_PARAMETER as the TransmitChain return code.

This limitation can also arise when a 32-bit adapter, which has 32 address connections, has the flexibility to reside in a 16-bit slot. In this case, the adapter must inform the NDIS device driver (or the "system" in general) of the slot's addressing characteristics. Again, when a 32-bit adapter is in a 16-bit slot and an address greater than or equal to 16 MB is given to the NDIS device driver, it should return INVALID_PARAMETER as the TransmitChain return code.

1.8.2 Device Driver clean up for unsolicited disconnects

When the device driver is notified that the adapter has abruptly disconnected from the segment, the device driver passes a RingStatus indication to the protocol driver. This most commonly occurs when the cable is disconnected and the device driver presents a RingStatus indication, signalling that a lobe wire fault has occurred. At this time the device driver also indicates that the "MAC is not open" in the MAC status flag of the MAC Service-Specific Status table.

Once this has occurred, it is the responsibility of the application or protocol driver to retry re-connecting to the segment for a period of time, in case the event which caused the abrupt disconnect no longer exists. Or at the very least, the protocol driver must be able to resume operations when another application is started (or restarted).

However, for the protocol driver to be able to resume operations, it must have all of it's resources available. For example, when the adapter abruptly disconnects from the segment, the device driver may have transmits outstanding. If the adapter does not "post" these transmits as complete (causing the device driver to return them to the protocol driver - as it normally would), the device driver must complete these transmits. This returns all the outstanding transmit resources to the protocol driver so that it can resume operations when necessary.

1.8.3 IndicationComplete reentrancy

DOS NDIS device drivers have historically (ie IBMFDDI.DOS, IBMENI.DOS) been initially implemented as non-reentrant in the IndicationComplete call to the protocol. This deviates from the NDIS specification for IndicationComplete which states, "This routine is always entered with interrupts enabled and with the network adapter interrupt dismissed from the interrupt controller. Therefore, it may be reentered at the completion of another indication".

This problem is most commonly manifested by issuing "NET SEND" commands with the PC LAN Program (PCLP) product. When a "NET SEND" is issued, the destination station has a pop-up window displayed. This is displayed during the NetBIOS appendage call, which is also the protocol driver's IndicationComplete routine. The pop-up window will remain displayed for 1 minute. If the device driver is not capable of performing the IndicationComplete in a reentrant fashion, the protocol will not be able to receive any frames while the pop-up is displayed because the IndicationComplete call is also used to complete frame reception.

To verify this feature, issue a "NET SEND" command to a PCLP station and copy files from the same PCLP station. If the other station which is copying files loses its session while the pop-up is displayed, the DOS NDIS driver is probably not reentrant in IndicationComplete.

1.8.4 Interrupt Sharing

Interrupt sharing must be implemented on DOS drivers. Interrupt sharing considerations and implementation information are described in the PS/2 BIOS Interface Technical Reference.

1.8.5 InterruptRequest implementation

The InterruptRequest NDIS general request must be implemented by all DOS NDIS device drivers in order for the LAN Support Program 802.2 protocol driver to perform optimally. The necessity for this command is brought out when running the PERFORM3 benchmark performance test.

The InterruptRequest command allows the protocol to request that it be called at the IndicationComplete entry point. This is necessary because transmits given to the LSP protocol driver are not immediately issued, they are queued to the protocol driver's dispatcher component. The dispatcher component can only be entered on timer interrupts, TransmitConfirm's and IndicationComplete's. Therefore, invoking the InterruptRequest command will invoke the dispatcher, where queued transmits can be issued to the device driver.

When InterruptRequest is not implemented there is a tell-tale 55 ms. delay between transmits while running PERFORM3. This uniform delay is a result of the DOS timer acting as the mechanism to invoke the protocol driver's dispatcher component. This is enough of a delay to adversely affect the operation of the network (eg. NetBIOS sessions get lost).

When InterruptRequest is implemented correctly; throughput improvements of approximately 1000% are visible for 64 byte messages (700% for 512 byte messages and 400% for 4K byte messages).

1.8.6 LAN Network Manager support

The IBM LAN Network Manager (LNM) product relies on access to the Adapter Status Parameter (ASP) table and the MAC Buffer to report the condition of the local Token-Ring segment. The ASP table is described in Appendix B of the LAN Technical Reference. LNM acquires (via the 802.2 protocol driver) the address of the ASP table and the MAC Buffer through the extended MAC Service-Specific Characteristics (SSC) table defined in the NDIS Extensions chapter.

The Token-Ring "shared RAM" adapters maintain the ASP table and MAC Buffer in the read-only area of shared RAM. The addresses of the ASP table and the MAC Buffer can be stored in the MAC SSC extension, giving all protocol drivers (and their associated applications) access to them.

The Token-Ring busmaster adapters maintain the ASP table and MAC Buffer in adapter memory, the device driver must "shadow" them into workstation memory. The workstation addresses of the shadowed ASP table and MAC Buffer are then stored in the MAC SSC extension. The device driver must periodically refresh the shadowed ASP table and MAC Buffer, the recommended refresh interval is once every second.

Maintaining the ASP table and MAC Buffer in this manner provides protocol drivers and applications with a consistent level of information across all types of Token-Ring adapters.

1.8.7 ModifyOpenParms implementation

The ModifyOpenParms is a new NTDIS general request described in the NDIS Extensions chapter. The purpose of this command is to allow applications to dynamically control low-level functions on the adapter. For example, after a Token-Ring adapter has been initialized and in use for a period of time, a user may choose to have the adapter "pass Beacon MAC frames" to the system. This would most likely be required by an application being started which performs LAN management type functions. A very similar situation could occur for FDDI adapters and the processing of SMT frames.

The ModifyOpenParms request is most commonly passed to the NDIS device driver by the 802.2 protocol drivers when a DIR.OPEN.DIRECT or DIR.MODIFY.OPEN.PARMS CCB is issued in OS/2 or DOS, respectively. The OPEN_OPTIONS parameter contains the low-level adapter functions to be modified.

1.8.8 ResetMAC implementation

The purpose of the ResetMAC NDIS general request is to dynamically "issue a hardware reset to the network adapter" in order to recover from a fatal adapter error. If it isn't supported (support is optional), re-booting the system is the common procedure for invoking the device driver initialization code and therefore resetting the adapter.

As serious as it sounds, the ResetMAC general request has not been implemented because the adapters seldom have spurious fatal errors and the initialization code which would have to remain resident, is a burden in the DOS environment.

The most common error which the NDIS device driver/adapter have to recover from involves lobe wire faults. Recovery from lobe wire fault errors can be accomplished by re-opening the adapter when the fault has been corrected. It's not necessary to "issue a hardware reset to the network adapter" via ResetMAC to recover from a lobe wire fault error.

Even though ResetMAC is optional, it's analogous command in Novell's Open Data-Link Interface (ODI) specification is not. According to the ODI Developer's s Guide for DOS Workstation HSMs and ODI Developer's Guide for OS/2 Workstation Driversthe HSM or Driver I/O control routine of DriverReset "issues a hardware reset to the physical board". This is a factor when using the ODI-to-NDIS mappers because the DriverReset routine relies on the ResetMAC NDIS general request in order to reset the "physical board".

1.8.9 Remote Program Load (RPL) support

The description of the NDIS Bind system request states, "For compatibility with remote initial program load, MAC drivers must not manipulate the adapter at Init-time. The MAC driver is free to determine if the network adapter is present, but must leave any hardware manipulation to Bind-time processing."

Some initial IBM device drivers violate the NDIS specification in this area. The IBM FDDI Workstation Adapter drivers and the IBM Token-Ring Busmaster Server Adapter/A driver initialize the adapter at Init-time. These drivers function successfully with their respective adapters because the adapters do not support RPL. However, since these were some of the early drivers to be completed they have been used as code examples. The IBM Token-Ring 16/4 Adapter II drivers and the IBM LANStreamer* Adapter drivers initialize the adapter at Bind-time.

If a device driver initializes the adapter at Init-time, the RPL procedure will not succeed. The RPL procedure relies on a NetBIOS link being active between the RPL client and the RPL server. This link is maintained by the (DOS) device driver contained in the RPL boot block. Moreover, one of the files "downloaded" over this link is another copy of the device driver (or the OS/2 copy). This copy is "downloaded" by the processing of a CONFIG.SYS file from a redirected disk drive. If the "downloaded" instance of the device driver initializes the adapter at Init-time, the NetBIOS link will be lost between the RPL client and RPL server.

2.0 LAN Adapter option diskette issues

2.1 Directory structure

The device driver related directories of a LAN Adapter option diskette are listed in the following table.

Table 1. Device driver directories on Adapter option diskette

Directory Contents
\ Adapter-specific files: *.ADF, *.DGS, main documentation file, etc.
\ All files for OS/2 NDIS device driver in IBM environments
\ Misc device driver install files (eg. OEMSETUP.INF for WFW)
\DOS All files for DOS NDIS device driver in IBM environments
\NOVELL\OS2 All files for ODI OS/2 workstation driver
\NOVELL\DOS All files for ODI DOS workstation driver
\NOVELL\NETWARE\286SERV All files for IPX Netware LAN driver
\NOVELL\NETWARE\386SERV All files for ODI Netware LAN driver

The OS/2 NDIS files are stored in the root directory because "A:\" is the default source drive and directory for the LAPS installation and configuration program. The DOS NDIS files are stored in the \DOS directory because "A:\DOS" is the default source drive and directory for the LAN Support Program's installation aid DXMAID.

2.2 Adapter-related files

The adapter-related files are usually provided by adapter development. This information is contained here to explain as much of the basic adapter option diskette as possible.

2.2.1 MCA - Adapter definition files and diagnostics

Adapter definition files (ADF) are required for Micro Channel* systems. The ADF file is used as configuration input to the Setup program on the reference diskette. The naming convention of the ADF files requires the filename of the ADF to begin with an "@", followed by the adapter ID. The extension is "ADF". For example, @8FC8.ADF is the ADF file for the IBM Token-Ring 16/4 Busmaster Adapter/A. The adapter's diagnostics program uses the same filename as the ADF, the extension is "DGS". For example, @8FC8.DGS.

2.2.1.1 Arbitration level 4

Micro Channel arbitration level 4 should not be used as a choice for the arbitration level. There was an old version of the Setup program which did not flag arbitration level 4 as "in use". This would allow undetected conflicts to occur. There are plenty of available arbitration levels without using level 4.

2.2.1.2 Busmaster adapters

Busmaster adapters should code the NODMA keyword in the ADF file to indicate that a DMA channel is not used by the adapter.

2.2.2 ISA

An ISA adapter may be shipped with a configuration program in place of an ADF file, since ADF files do not exist in an ISA system. Some ISA adapter's still have switches and are not software configurable.

2.2.3 EISA - Configuration files

EISA adapters are shipped with a configuration file, similar in function to an ADF file. The EISA configuration files begin with an "!" and have an extension of "CFG".

2.3 Documentation file requirements

The purpose of the documentation file is to provide all the information necessary to use the NDIS device driver. Therefore, the NDIS device driver doesn't have to be documented in the adapter's Installation and Testing manual. The Installation and Testing manual should direct the user to a documentation file on the option diskette, for device driver information. This file is usually a README-type file and it should reside in the root directory of the option diskette.

The documentation file can also be used to accommodate any adapter related information which wasn't available when hen the Installation and Testing manual was created. The softcopy form of the documentation file is meant to replace the distribution of a device driver hardcopy document.

2.3.1 Documentation file alternatives

Documentation files which address specific topics can be located in the appropriate directories. For example, a README file about LAN Support Program (eg. README.LSP) could be in the \NDIS\DOS directory. The main README file in the root directory should indicate where all the other documentation files are located.

The documentation scheme above does not guarantee that the documentation files will be copied off the adapter option diskette. If they are, they may be overwritten with another adapter's README files later. In order to provide documentation files that are installed along with device driver executables and not overwritten unintentionally, a documentation file should have the same filename as the executable and a "DOC" extension. For example, IBMFDDI.DOC This file could be added to the COPYFILE statement of the NIF to guarantee that it gets installed from the option diskette. Since it has a specific filename, it won't get overwritten as easily as a README-type file. Again, the main README file in the root directory should itemize all the documentation files on the adapter option diskette.

2.4 National Language Support (NLS) on option diskette

The adapter definition files and diagnostic program messages must be translated. The ADF translation guidelines are described in the Setup section of the PS/2 Hardware Interface Tech Ref - Architectures. For example, a prompt string can not exceed 38 characters. Usually the translators are aware of these guidelines. The translation rules for the diagnostic program are unique for each diagnostic program.

2.4.1 NLS alternatives

An option diskette is usually created to support either one language or all languages for a product. If the option diskette supports only one language, multiple language-specific option diskettes must be made. Otherwise, one option diskette contains all versions of the translated files.

For example, each IBM FDDI Workstation adapter's option diskette supports one language. The LT5.MSG file is a common file among all of the diskettes, but its contents are language-specific. The IBM FDDI Workstation adapter was translated for German, Italian and Japanese.

If one option diskette were created to contain all translated fries, "instructions" need to be supplied in order to use the correct translation of each file. These "instructions" could be manual directions or part of an automated procedure. The language-specific files might reside in unique directories, or they might all be in one directory with unique extension names. A common extension used to bring attention to language-specific files is the country code (eg. .049 for German or .001 for U.S. English). The list of available country codes is commonly documented in the operating system's command reference. The country codes supported by OS/2 2.0 are listed in the IBM Product Overview chapter.

2.4.2 Verification and testing

It's very important that the implementation of the translated files be verified, especially double byte character sets (DBCS).

Appendix A. NDIS driver driver checklists

The NDIS device driver checklists below should be the first items verified upon entering Functional Verification Test (FVT) and System Verification Test (SVT). Some of the "feature to verify" descriptions are abbreviated. Refer to the description of the feature earlier in the document for further details.

A.1 FVT checklist

Table 2. NDIS device driver deliverables
Feature to verify DOS comments OS/2 comments
Does driver executable have correct name? NA, for now.
Does external message file exist?
Does external msg file have correct name? (eg LTx.MSG)
Does external message help file exist?
Does msg help file have correct name? (eg LTxH.MSG) NA, for now.
Does Network Information file (NIF) exist?
Does NIF have correct name?
Do miscellaneous file(s) have correct name(s)?
Table 3. NDIS device driver Installation and Configuration
Feature to verify DOS comments OS/2 comments
Does SNIFFLE parse the NIF successfully?
Does NIF have executable filename in title?
Does DRIVERNAME match filename of executable?
Does DRIVERNAME string NOT end with a number?
Is NETADDRESS a PROTOCOL.INI keyword?
Is Group bit prevented from being set by NETADDRESS?
If Ethernet, is NETADDRESS in canonical form?
Configurable parms match across: .ADF, .NIF, README, etc?

Table 4. NDIS device driver message support

Feature to verify

DOS comments

OS/2 comments

Is copyright statement accurate?

Is copyright statement expanded in code?

Is copyright in code accurate?

Do the message prefix identifiers exist?

Are the message prefix identifiers correct? (eg LTxnnnnS)

Are the messages displayed to the console?

Are the messages logged to LANTRAN.LOG?

NA, for now.

Does help facility work with the external msg help file?

NA, for now.

Table 5. NDIS device driver Initialization

Feature to verify

DOS comments

OS/2 comments

Does each PROTOCOL.INI parm have accurate error msg?

Does each parameter have a syntax error msg?

Is the default for each parameter successful?

Is the maximum for each parameter successful?

Is the (maximum+ 1) for each parameter successful?

Is the minimum for each parameter successful?

Is the (minimum-l) for each parameter successful?

Does each parm function at the default value?

If init errors, does NETBIND fail?

Do multiple adapters initialize successfully?

Table 6. ADF file (for Micro Channel adapters only)

Feature to verify

DOS comments

OS/2 comments

Is arbitration level 4 for Busmasters omitted?

Is the NODMA keyword coded for Busmasters?

Is the help text for each choice accurate?

Is the default for each parameter successful?

Is the maximum for each parameter successful?

Is the (maximum+ 1) for each parameter unsuccessful?

Is the minimum for each parameter successful?

Is the (minimum-l) for each parameter unsuccessful?

A.2 SVT checklist

Table 7. NDIS device driver run-time functions

Feature to verify

DOS comments

OS/2 comments

Is InterruptRequest supported for DOS?

NA.

Is interrupt sharing supported?


Is the 16MB boundary checked?

Is IndicationComplete re-entrant?

Do multiple adapters operate successfully?

Is IndicationComplete call re-entrant?

Does the device driver recover if cable pulled?

Can LNM access the Adapter Status Parms table (TR only)?  

Appendix B. IBM MAC device drivers

Table 8. NDIS device drivers
DOS device driver OS/2 device driver Adapter product
IBMTRDB.DOS IBMTRDB.OS2 LANStreamer Adapter
IBM16TR.DOS IBM16TR.OS2 Token-Ring Network 16/4 Adapter II
IBMFDDI.DOX IBMFDDI.OS2 FDDI Workstation Adapters
IBMENI.DOS IBMENI.OS2 LAN Adapter for Ethernet
IBMENII.DOS IBMENII.OS2 LAN Adapter/A for Ethernet
IBMTOK.DOS IBMTOK.OS2 Token-Ring Network Adapter II, Token-Ring Network 16/4 Adapter, Token-Ring Adapter II/A, Token-Ring Network 16/4 Adapter/A, Token-Ring Network PS/2 Model P70 386 Adapter/A
IBMNET.OS2 PC Network Broadband Adapter II, PC Network Adapter II Frequency 2, PC Network Adapter II Frequency 3, PC Network Baseband Adapter II
IBMNETA.OS2 PC Network Broadband Adapter II/A, PC Network Adapter II/A Frequency 2, PC Network Adapter II/A Frequency 3, PC Network Baseband Adapter II/A
IBMTRBM.OS2 Token-Ring Network 16/4 Busmaster Server Adapter/A
IBMXLN.DOS IBMXLN.OS2 3174 Peer Communications
Table 9. Novell device drivers
DOS Workstn OS/2 Workstn 286 Server 386 Server Adapter product
IBMTRDBO.LAN LANStreamer Adapter
TOKENBM.COM TOKENBM.SYS TOKEN.LAN
TOKENBM.LAN 		TOKENBM.LAN Token-Ring Network 16/4 Adapter II
IBMFDDIO.COM IBMFDDIO.OS2 IBMFDDIO.LAN FDDI Workstation Adapters
IBMENIO.COM IBMENIOP.SYS
IBMENIOS.SYS 		NE2000A1.LAN
NE2000A2.LAN 		IBMENIO.LAN LAN Adapter for Ethernet
IBMENIIO.COM IBMENIIO.SYS IBMENIIO.LAN LAN Adapter/A for Ethernet
Table 10. Defined IBM message prefixes
Prefix Device Driver
LT0 802.2 and NetBIOS protocol drivers (LANDD.OS2 and NETBEUI.OS2)
LT1 IBM PC Network MAC drivers
LT2 IBM Token-Ring Network driver
LT3 IBM 3174 Peer Communication Network driver
LT4 IBM Token-Ring Network 16/4 Busmaster Server Adapter/A driver
LT5 IBM FDDI Workstation Adapter driver
LT6 IBM LANStreamer Adapter
LT7
LT8 IBM ODI2NDI Enablers
LT9
LTA IBM LAN Adapter for Ethernet driver
LTB IBM LAN Adapter/A for Ethernet driver
LTC In development
LTD In development
LTE In development
LTF In development
LTG In development
Table 11. Other message prefixes
Prefix Device Driver
PRO Protocol Manager
BRZ IBM Token-Ring Network 16/4 Adapter II
UBI Ungermann-Bass** NUIpc** and NUIps/2**
ETH IBM Adapter/A for Ethernet Networks driver
MAC SMC EtherCard PLUS** and PLUS/A**
MAC 3Com** Etherlink II** and EtherLink/MC** (Note, no external message file)

Notices

May, 1993

Issued by:

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

First Edition (May 1993)

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

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

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

Requests for copies of this publication and for technical information about IBM products should be made to your IBM Authorized Dealer or your IBM Marketing Representative.

Copyright Notices

© 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, IBM Corporation, Purchase, NY 10577.

Trademarks

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

IBM OS/2 LAN Adapter and Protocol Support
DOS NTS/2 Micro Channel
Extended Edition LANStreamer  

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

3Com 3Com Corporation
EtherLink II 3Com Corporation
EtherLink/MC 3Com Corporation
LAN Manager Microsoft Corporation
Microsoft Microsoft Corporation
EtherCard PLUS Standard Microsystems Corporation
EtherCard PLUS/A Standard Microsystems Corporation
NUIpc Ungermann-Bass Corporation
NUlps/2 Ungermann-Bass Corporation
Ungermann-Bass Ungermann-Bass Corporation
Retrieved from "http://www.edm2.com/index.php?title=NDIS_Implementation_Information_for_IBM_LAN_Systems_-_NDIS_Device_Driver_Requirements&oldid=46250"