NDIS Concepts The following article originally appeared in the Winter 1991 Issue of 3TECH, The 3Com Technical Journal. 3TECH is published quarterly by 3Com Corporation, Santa Clara, CA 95052. Subscriptions to 3TECH are available at a rate of $35 per calendar year. To order subscriptions to 3TECH write to 3TECH Journal, 3Com, P.O. Box 58145, Santa Clara, CA 95052-9953. All orders must be prepaid and reference 3C2869. Note: This file has been modified from the original article to be printable with ascii characters. It uses PC extended ascii graphics characters to make boxes for figures, so the printer should support the PC character set to print these correctly. NDIS Concepts The Network Driver Interface Specification (NDIS) is a standardized interface for OS/2 or DOS network platforms. NDIS provides access to the network services at the Data Link layer and is especially useful if the access must be shared. Software developers who need to employ their own network protocol implementations can program to the NDIS interface and utilize NDIS-compliant drivers provided by network hardware vendors. This frees the protocol developer from programming directly to various network interface cards and solves compatibility problems on machines with multiple protocols. This article explains why the Network Driver Interface Specification was developed, and describes its organization and operation. Some of the information is general, and will be of interest to a broad group of people involved with networks. A good deal of the information is quite detailed and technical. It is intended primarily to give network programmers an overview of NDIS and what is involved in binding a protocol to an vendor- supplied MAC driver for a network adapter board. The Old Way Traditionally, network software vendors for the MS-DOS environment have used ad hoc methods to implement the protocols and drivers that link applications to their resident network hardware. The entity that performs these network functions and provides communication between applications is usually referred to as a protocol stack. In the OSI Reference Model, the stack would correspond to the Data Link, Network, Transport, and Session layers, with some stacks possibly including higher layers. At the stack's top end is a user interface or some type of applications programming interface (API) and, at the bottom end, are the interfacing routines that control the network adapter hardware. In implementation, a stack might consist of one system driver, multiple drivers, a program, or a combination of drivers and programs. Figure 1 shows three alternative stacks that could be used to perform equivalent network functions. In a typical implementation (for example, NetBIOS over XNS, in figure 1) the Data Link, Network, and Transport layers might be implemented as three separate system drivers, and the Session layer as a TSR program. Usually, the interfacing between the layers would be accomplished through a proprietary interface developed by the vendor and the application would communicate to NetBIOS via software interrupts. This works fine in a homogeneous network environment, but as networks grow more complex, it is becoming 1 desirable to have the flexibility to utilize mixtures of different protocols, application interfaces, and network media. Figure 1. Typical Protocol Implementations Without NDIS OSI NetBios Sockets Model over over XNS TCP/IP 旼컴컴컴컴컴컴커 旼컴컴컴컴컴컴� 旼컴컴컴컴컴컴� � Application � � � � � 쳐컴컴컴컴컴컴캑 � Application � � Application � -� Application � Presentation � � � � � Software 쳐컴컴컴컴컴컴캑 쳐컴컴컴컴컴컴� 쳐컴컴컴컴컴컴� � Session � � NetBIOS � � BSD � -- API � � � � � Socket � 쳐컴컴컴컴컴컴캑 쳐컴컴컴컴컴컴� 쳐컴컴컴컴컴컴� � Transport � � SPP � � TCP � \ 쳐컴컴컴컴컴컴캑 쳐컴컴컴컴컴컴� 쳐컴컴컴컴컴컴� � Protocol � Network � � IDP � � IP � / 쳐컴컴컴컴컴컴캑 쳐컴컴컴컴컴컴� 쳐컴컴컴컴컴컴� � Data Link � � Driver � � Driver � -- Adapter � � 쳐컴컴컴컴컴컴� 쳐컴컴컴컴컴컴� Driver 쳐컴컴컴컴컴컴캑 쳐컴 H/W 컴캑 쳐컴 H/W 컴캑 � Physical � � Media � � Media � 읕컴컴컴컴컴컴켸 읕컴컴컴컴컴컴� 읕컴컴컴컴컴컴� The Problem to be Solved Compatibility issues between various networking implementations can make it difficult or impossible to accomplish some seemingly simple tasks. For example, assume that we have an Ethernet network that has two types of file servers attached. One server runs an XNS protocol with NetBIOS at the Session layer. The other server runs a TCP/IP protocol with a Berkeley Socket Session interface. We would like to write a program to run on a workstation that can copy a file from the first server to the second. In this example, let's say we have two sets of software from two vendors that are designed to communicate with each of the servers, and that the vendors have defined a programmer's interface that should allow us to write a program which talks to the two stacks. Assuming that we have enough memory to load both stacks at one time, we will probably find that our biggest configuration problem occurs at the bottom of the stacks. At the Data Link layer, each of the vendors has supplied us with a driver for use with their protocol stack that can control the EtherLink II adapter board that we have in our station. Most 2 likely, we will find that each of these drivers expects to have exclusive ownership and control of the EtherLink II. As one of the drivers tries to control the board, it interrupts or corrupts the functions being attempted by the other driver. What is needed is one driver that can control the adapter and be shared by the two protocols. In May of 1988, 3Com and Microsoft released NDIS, which was jointly developed in conjunction with LAN Manager. The NDIS specification is a standard designed to alleviate compatibility issues for both OS/2 and DOS network platforms. The NDIS specification should be beneficial to both the protocol-level network software developer, who now has a standard interface available, and the user, who gains from the flexibility and interoperability advantages of protocols using NDIS. NDIS Organization All network software components compliant with NDIS definitions are drivers. These drivers can be classified into two types: protocol drivers, and Media Access Control (MAC) drivers. NDIS allows protocol drivers to be device drivers, TSR's, or DOS applications, however, for this discussion, we are going to assume that all NDIS drivers are device drivers--the simplest and most common implementation. The MAC driver forms the bottom layer of the stack and is the driver that directly controls the network hardware. The remaining higher layers of the protocol stack are implemented in one or more protocol drivers. The MAC layer is a sublayer within the OSI Data Link layer that is defined by IEEE 802 specifications. This layer is the appropriate point for a driver that manages the network hardware and implements the transmission and reception of network data packets. NDIS MAC drivers are provided by 3Com and many other network hardware vendors (see Table 1 for a partial list) and can be used with any vendor's NDIS compliant protocol drivers. 3 Table 1. Companies Supporting NDIS 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � Companies with NDIS MAC Drivers � � � � Note: The entire list of companies shipping NDIS MAC drivers � � is too long for this article, but includes: � � � � 3Com Interlan � � AST Research Proteon � � AT&T Tiara � � Compaq Ungermann-Bass � � Exelan Western Digital � � IBM � � � � Companies with OS or Application Supporting NDIS � � � � 3Com - LAN Manager � � AT&T - LAN Manager � � Banyan - Vines (workstation) � � DEC - LAN Works � � FTP - PC/TCP � � IBM - LanServer, OS/2 Extended � � Microsoft - LAN Manager � � Pacer - Pacerlink � � Sun - PC-NFS � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� NDIS Stacks All NDIS drivers, both MAC and protocol, share a basic common modular structure. Each driver has an upper and lower boundary. The drivers are linked to form a stack by connecting, or binding, the upper boundary of one driver to the lower boundary of another driver during the binding portion of driver initialization. This binding process can be repeated multiple times, linking several drivers, daisychain fashion, to form the stack. The MAC driver, at the bottom of the stack, always has its lower boundary connected to the physical layer--the network hardware. The simplest configuration of drivers is one MAC driver supporting one network adapter card, bound to a single protocol driver that spans from the MAC layer to the Session layer (see Figure 2). This forms a single protocol stack of two drivers. Optionally, the protocol part of this stack might be made using two or more protocol drivers to form a single stack of three or more drivers. NDIS also allows us to have two completely parallel stacks in one machine, each with its own adapter card and MAC driver, to implement two different protocols. 4 Figure 2. NDIS - Single Protocol, Single MAC OSI IEEE Using Reference Model NDIS Model 旼컴컴컴컴컴컴� � ABC Protocol� � � � LLC � � Driver � � � 쳐컴컴컴컴컴컴� NDIS -팠袴袴袴袴袴袴� � � � � Intfc � NDIS � � Data Link � � MAC � � MAC Driver � � � � 802.3/802.5 � 쳐컴컴컴컴컴컴� � � � � � 3Com LAN � � � � � � Adapter � 쳐컴컴컴컴컴컴캑 쳐컴컴컴컴컴컴� 쳐컴컴컴컴컴컴� � Physical � � Network � � Network � � � � Cabling � � Cabling � 읕컴컴컴컴컴컴켸 읕컴컴컴컴컴컴� 읕컴컴컴컴컴컴� Figure 3. NDIS - Multiple Protocols, Single MAC OSI IEEE Using Reference Model NDIS Model 旼컴컴컴컴컫컴컴컴컴컴� 쿌BC Protoc쿦YZ Protoc� � Drvr 旼컴좔컴� Drvr � � � � LLC � � � Vector� � � � 쳐컴컴컴컴컴컴� 突袴佶賈袴袴袴賈袴佶袴� � � � � / � NDIS � � Data Link � � MAC � NDIS � MAC Driver � � � � 802.3/802.5 � Intfc 쳐컴컴컴컴컴컴� � � � � � 3Com LAN � � � � � � Adapter � 쳐컴컴컴컴컴컴캑 쳐컴컴컴컴컴컴� 쳐컴컴컴컴컴컴� � Physical � � Network � � Network � � � � Cabling � � Cabling � 읕컴컴컴컴컴컴켸 읕컴컴컴컴컴컴� 읕컴컴컴컴컴컴� More importantly, NDIS lets us have just one adapter card and a single MAC driver with the MAC driver bound to two separate protocol drivers (see Figure 3). Therefore, two protocols (XNS and TCP/IP, for instance) can share the same MAC driver and adapter card. This configuration solves the problem discussed earlier in which files needed to be copied from two servers running different protocols. To complete the picture, we can also have two adapter cards and MAC drivers, with both the MAC drivers bound to one protocol 5 driver (Figure 4). This configuration could be used to create a network bridge with one protocol connected to two networks. Figure 4. NDIS - Single Protocol, Multiple MACs OSI IEEE Using Reference Model NDIS Model NDIS 旼컴컴컴컴컴컴� Intfc � JKL Protocol� � � � LLC � \ � Driver � � � 쳐컴컴컴컴컴컴� 郞袴袴賈袴袴袴佶袴袴賈袴袴袴� � � � � � NDIS � NDIS � � Data Link � � MAC � � MAC Driver � MAC Driver � � � � 802.3/802.5 � 쳐컴컴컴컴컴컴탠컴컴컴컴컴컴� � � � � � 3Com LAN � 3Com LAN � � � � � � Adapter � Adapter � 쳐컴컴컴컴컴컴캑 쳐컴컴컴컴컴컴� 쳐컴컴컴컴컴컴탠컴컴컴컴컴컴� � Physical � � Network � � Network � Network � � � � Cabling � � Cabling � Cabling � 읕컴컴컴컴컴컴켸 읕컴컴컴컴컴컴� 읕컴컴컴컴컴컴좔컴컴컴컴컴컴� Driver Structures The drivers communicate with each other by a defined set of primitives. The NDIS document has clearly specified a set of primitives for the interface between the MAC driver and protocol driver and for managing the NDIS driver binding process. Although it is possible to implement a protocol stack with multiple protocol drivers, currently no primitives are defined by NDIS for these upper layers. This is not a serious limitation, since a stack with multiple protocol drivers would generally have all of the protocol drivers common to one vendor. There is less need for a standardized interface between protocol drivers than at the MAC layer where sharing resources, and multiple vendors, is more likely. Each driver contains a series of module characteristic data structures that provide information describing the purpose and capabilities of the driver, and that manage the linkage and operation of the driver during and after initialization. The main structure is called the Common Characteristics Table and contains the name of the driver and version information. This is the highest level table for a driver; other types of characteristics tables are located from pointers in this table. The Common Characteristics table also contains basic information about what type of binding is supported at the upper and lower boundaries of the driver. The binding information is in the form of a byte identifying the OSI layer that is supported for the 6 boundary. This byte can be examined by other drivers to determine if it is appropriate to bind to the driver. The common characteristics table contains pointers to the other module characteristics tables -- the service specific characteristics table, service specific status table, and upper and lower dispatch tables. These tables give specific information related to the service that the driver performs, manage its operation, and record linkage points to other drivers after the driver is bound. Managing Binding and Initialization To form the protocol stacks from the individual drivers we need to get the right drivers hooked together in the desired sequence. This is accomplished in the initialization and binding process. Three components are used to manage and control the process -- PROTOCOL.INI (an ASCII configuration parameter file), PROTMAN.DOS or PROTMAN.OS2 (the protocol manager -- a special driver), and NETBIND.EXE (a program that initiates the final driver binding process). The initialization and binding process is essentially the same whether the operating system is DOS or OS/2. Some minor adjustments need to be made (for instance, selecting either PROTMAN.DOS or PROTMAN.OS2) and some different parameters may be required, but the discussion that follows applies to either environment. The ASCII file PROTOCOL.INI contains the instructions for assembling the protocol stack or stacks from the NDIS network drivers. It also contains parameters that are needed to configure the individual drivers. At CONFIG.SYS initialization time, the Protocol Manager Driver reads this file. The file is created -- much as CONFIG.SYS is created -- either directly, by the administrator typing the information with an editor, or by some type of installation program. The PROTOCOL.INI information is grouped into a number of logical sections of the form: [module name] parameter=value The module name is the name of the NDIS driver, as contained in the common characteristics table for the driver. There will be one module section for each of the NDIS drivers that describes the driver's configuration. Each section can have multiple parameters, but must have at least one, the DRIVERNAME. Figure 5 shows the contents of a simple PROTOCOL.INI file that has entries for three drivers. The first is Protocol Manager, 7 the special driver that controls the binding process -- more about its purpose later. In PROTOCOL.INI the Protocol Manager entry is currently optional, but it may be required in the future, so it's a good idea to include it. The second module section is for the EtherLink II adapter's MAC driver, and the last section is for an arbitrary protocol driver. Figure 5. PROTOCOL.INI File Contents ;*************************** ; Example PROTOCOL.INI file ;*************************** [PROTMGR] DRIVERNAME=PROTMAN$ [ETHERLINKII] DRIVERNAME=ELNKII$ INTERRUPT=3 TRANSCEIVER=EXTERNAL [PROTOTST] DRIVERNAME=PROTO$ BUFFSIZE=2048 BINDINGS=ETHERLINKII Notice that, in each section, the first parameter is DRIVERNAME=. This parameter must be included and must specify a name that uniquely defines the NDIS module. In most cases it will be the driver name that the driver registers to the operating system during initialization. The driver determines the name that must be used, because the driver uses the DRIVERNAME entries as a key when searching PROTOCOL.INI data for its relevant module section. Any number of additional, optional parameter entries can be included in a module section. One purpose of these parameters is to allow control of the driver configuration. A set of valid configuration options will be defined for any particular driver. In the case of the ETHERLINKII section in Figure 5, we have selected two of the possible options for this driver. INTERRUPT=3 tells the driver to use hardware interrupt channel 3 and TRANSCEIVER=EXTERNAL tells the driver to configure the adapter for its external transceiver. In the PROTOTST protocol driver, the BUFFSIZE parameter might direct a protocol to use a particular size for its internal buffers. The BINDINGS= parameter is a special parameter that is valid only for protocol drivers and specifies the module name of the driver with which the protocol should attempt to bind on its lower 8 boundary. This parameter determines which drivers will be bound together to form the stack or stacks. In the PROTOCOL.INI of Figure 5, PROTOTST is bound to the ETHERLINKII driver. As mentioned earlier, the component of the NDIS environment that manages the binding process is the Protocol Manager, which has the file name PROTMAN.DOS for DOS or PROTMAN.OS2 for OS/2. Protocol Manager has two main functions: it keeps and manages common data for the NDIS drivers, and it controls the binding sequence. Functions of the Protocol Manager are needed by the NDIS drivers during their system level initialization, so the Protocol Manager driver must be loaded in CONFIG.SYS before any of the other NDIS drivers. The Protocol Manager driver was written by 3Com and is available from both 3Com and Microsoft. Any vendor needing Protocol Manager or NETBIND.EXE for use in the initialization of their network software products can obtain them and include them with their products. Protocol Manager and NETBIND.EXE are also a standard part of LAN Manager as shipped by 3Com and Microsoft. Driver Initialization The Protocol Manager gathers NDIS related information during the system CONFIG.SYS initialization of the drivers. During its initialization, the Protocol Manager driver reads the PROTOCOL.INI file and parses the information into a set of structures, called the Configuration Memory Image, that are accessible by the other NDIS drivers. Because the other NDIS drivers use this information, the Protocol Manager must be the first NDIS driver to initialize. As CONFIG.SYS processing continues, the other drivers are directed to initialize by the operating system. During initialization they must open the Protocol Manager device (PROTMAN$) and then issue a GetProtocolManagerInfo primitive to obtain, from the Protocol Manager, a pointer to the Configuration Memory Image (the PROTOCOL.INI data). The drivers find the section of this data that pertains to them and use any parameters found there to adjust their initialization process. One result of this is that drivers may modify their loaded size, based on parameter requirements, to optimize host memory consumption. If the driver is a protocol and it finds a BINDINGS= parameter, it will assess whether or not this binding is valid. Finally, the driver must issue a RegisterModule primitive to the protocol manager to register itself. During this register, the driver passes a pointer to its common characteristics table, and for a protocol driver, a list of modules to which it wants to bind, based on the BINDINGS= parameter. 9 After CONFIG.SYS processing completes, the Protocol Manager has a list of the active NDIS drivers, their characteristics, including entry points, and the desired bindings. Driver Binding The actual binding of NDIS drivers starts when some program issues the BindAndStart primitive call to the PROTMAN$ device. For all current Microsoft OS implementations this call will come from the execution of NETBIND.EXE within a BAT or CMD file. After receiving the BindAndStart directive, Protocol Manager will take the binding information from the module registrations and build a binding hierarchy tree. Starting at the bottom of this tree (the MAC end) the Protocol Manager works up the tree and issues an InitiateBind primitive to each protocol module that needs a driver bound on its lower boundary. As part of the InitiateBind call, the driver is passed a pointer to the common characteristics table of the module to be bound. The protocol driver that was instructed to initiate the bind will then issue a Bind primitive directly to the driver that it wishes to bind. When the bind completes, each driver will have a pointer to the common characteristics of the other, and therefore its entry points. After the Protocol Manager has processed all of the binding tree, all the appropriate network drivers will be bound to each other. The protocol stack is then fully operational and the drivers can access each other by calling the dispatch entry points for communication. Figure 6, Driver Initialization and Binding, summarizes the binding process. 10 Figure 6. Initialization and Binding Process A. CONFIG.SYS initialization begins. 1. Protocol Manager driver does its initialization. a. Protocol Manager reads the PROTOCOL.INI file and builds the Configuration Memory Image. 2. Other NDIS drivers do their initialization. a. Open the PROTMAN$ device. b. Issue GetProtocolManagerInfo to gain access to ProtMan configuration image. c. Read config parameters from the image and use them to complete initialization. d. Issue RegisterModule to register Characteristics info with Protocol Manager. B. CONFIG.SYS processing ends. C. Binding process starts when the NETBIND.EXE program opens the PROTMAN$ device and issues a BindAndStart to Protocol Manager. 1. Protocol Manager builds a binding tree from RegisterModule info. 2. Protocol Manager starts at the bottom and calls drivers with InitiateBind. a. Each called driver issues Bind to the specified module to complete binding. D. When all modules are bound, Protocol Manager returns from BindAndStart. One more factor is involved in the binding process if more than one protocol is to be bound to a MAC driver. MAC drivers can only have one binding at their upper boundary. To link one MAC to multiple protocols, the Protocol Manager inserts a component, called Vector, between the MAC and the protocols (see Figure 3). Vector is part of the Protocol Manager and will be bound between the MAC and each of the protocols. To do this, the Protocol Manager first binds the MAC driver to Vector by issuing a Bind 11 call to the MAC driver, then it issues an InitiateBind call to each of the protocols directing them to bind to a Vector entry rather than the MAC entry. The basic function of Vector is to route incoming packets between the protocols. When a packet is received by a MAC driver, it will issue a notification of the event to its upper boundary. When vector is involved, it will pass this notification, first to one, then to the other protocol, until one protocol accepts the packet or all have rejected it. Other functions can be passed, essentially directly, between protocols and the MAC, but this vectoring of incoming packets is key to implementing multiple protocols on one MAC. MAC to Protocol Interface and Operation The main purpose of the NDIS interface is to let the bound drivers communicate with each other. To that end, the NDIS is largely concerned with defining a set of functions that dictate how the MAC driver will communicate with the protocol bound on its upper layer. Table 2, NDIS Primitives, lists the primitives that are defined for this MAC-to-Protocol communication. All communication between the MAC and its bound protocol will be accomplished using these primitives. In Table 2, the individual primitives are grouped into the main functional categories that they perform. In the first group there are functions for the transmission of network packets from the protocol through the MAC and onto the network, and for the reception of packets in the reverse direction. In the control group are all the functions that the protocol uses to control or modify the operation of the adapter and MAC driver. The asynchronous status group contains functions that the MAC uses to report events to the protocol. Finally, the Binding group has the functions used to accomplish the driver binding process. The most important of these have already been described. The remainder are extensions to allow binding and unbinding of dynamically loadable protocols. More on this subject later. 12 Table 2. NDIS PRIMITIVES 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � TRANSMIT AND RECEIVE � � � 쿟ransmitChain v Initiate transmission of a frame� 쿟ransmitConfirm ^ Imply completion of frame � � transmit � 쿝eceiveLookahead ^ Indicate arrival of received � � frame and offer lookahead data � 쿟ransferData v Request transfer of received � � frame from MAC to protocol � 쿔ndicationComplete ^ Allow protocol to do post- � � processing on indication � 쿝eceiveChain ^ Indicate reception of a frame in� � MAC managed buffers � 쿝eceiveRelease v Return frame buffer to the MAC � � that owns it � � � � CONTROL � � � 쿔ndicationOff v Disable indications from the MAC� 쿔ndicationOn v Enable indications from the MAC � 쿔nitiateDiagnostics v Start MAC runtime diagnostics � 쿝eadErrorLog v Get error log info from MAC � 쿞etStationAddress v Set network address of the � � station � 쿚penAdapter v Issue open request to network � � adapter � 쿎loseAdapter v Issue close request to network � � adapter � 쿝esetMAC v Reset MAC software and adapter � � hardware � 쿞etPacketFilter v Specify filtering params for � � received packets � 쿌ddMulticastAddress v Specify multicast address for � � adapter � 쿏eleteMulticastAddress v Remove previously added � � multicast address � 쿢pdateStatistics v Cause MAC to update statistics � � counters � 쿎learStatistics v Cause MAC to clear statistics � � counters � 쿔nterruptRequest v Protocol requests later async � � indication from MAC � 쿞etFunctionalAddress v Cause adapter to change its � � functional address � 쿞etLookahead v Set length of visible data for � � ReceiveLookahead � 쿒eneralRequestConfirmation ^ Confirm completion of previous � � General Request (see text for � � more explanation) � � � � ASYNCHRONOUS STATUS � � � 쿝ingStatus ^ Indicate a change in ring status� 쿌dapterCheck ^ Indicate error from adapter � 쿞tartReset ^ Indicate adapter has started a � � reset � 쿐ndReset ^ Indicate adapter has completed � � reset � 쿔nterruptIndication ^ MAC response due to � � InterruptRequest � � � � � � BINDING � � � 쿔nitiateBind p>m Instruct a module to bind to � � another module � 쿍ind m>m Exchange Characteristic Table � � info with another module � 쿔nitiatePrebind p>m In OS/2 dynamic bind mode, � � instruct a module to restart � � its prebind initialization � 쿔nitiateUnbind p>m Instruct a module to unbind � � from another module � 쿢nbind m>m Delete linkage info with � � another module � 쿒etProtocolManagerInfo m>p Retrieve pointer to � � Configuration Image � 쿝egisterModule m>p Register Characteristics and � � Bindlist with Protocol Manager � 쿍indAndStart e>p Initiate the binding process � 쿒etProtocolManagerLinkage m>p Get entry point for Protocol � � Manager � 쿒etProtocolIniPath d>p Get file path for the � � PROTOCOL.INI file � 쿝egisterProtocolManagerInfo d>p Dynamic mode, register new � � Configuration Image � 쿔nitAndRegister d>p Dynamic mode OS/2, restart � � prebind initialization � 쿢nbindAndStop d>p Dynamic mode, Unbind and � � terminate a module � 쿍indStatus e>p Retrieve info on current � � bindings � 쿝egisterStatus e>p Query if a specific module is � � registered � � � � KEY: � � ^ - MAC to protocol � � v - protocol to MAC � � p>m - Protocol Manager to driver module � � m>p - driver module to Protocol Manager � � e>p - ? to Protocol Manager; ? is normally an � � executable program � � d>p - dynamic protocol or control program to � � Protocol Manager � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� The center column of the primitive table has a symbol that indicates the direction in which the primitive calls are passed. To submit a primitive, the caller driver pushes a series of parameters on the system stack and calls an entry point in the called driver. The entry points are known to the calling driver as a result of the binding process. The common characteristics table, whose address was passed during binding, has dispatch tables chained off of it. The defined entry points for the driver are in a dispatch table. 14 The MAC driver's upper dispatch table and the addresses it contains are shown below: MAC Upper Dispatch Table GeneralRequest TransmitChain TransferData ReceiveRelease IndicationOn IndicationOff These are the entry points that the protocol driver will call to request primitive execution by the MAC. All of these, except GeneralRequest, are called direct primitives because they serve just the one primitive function implied by the entry name. The GeneralRequest entry serves the remainder of the primitive calls, other than binding, that are passed to the MAC. In Table 2, the GeneralRequest primitives are all the primitives in the group labeled CONTROL, except IndicationOn and IndicationOff, which have their own direct entries. The Direct Primitives have their own entry points because these are performance-critical functions. The primitives employing the GeneralRequest entry, being less critical, can share a common entry. The GeneralRequests identify themselves by passing an opcode as one of their parameters. On the protocol driver side, the protocol lower dispatch table defines the entry points from the MAC to the protocol. The table and its contents are as follows: Protocol Lower Dispatch Table GeneralRequestConfirm TransmitConfirm ReceiveLookahead* IndicationComplete ReceiveChain* Status* * denotes Indications All of these entries except Status are direct. Status is the entry for the asynchronous status group in the primitive table, and these primitive calls also have an opcode that identifies the type so they can share one entry. In a sense, GeneralRequestConfirm can also be viewed as a shared entry. 15 There is only one primitive for this entry, but it is generated by the MAC at the end of any of the GeneralRequests to the MAC and contains the request handle of the original primitive request to the MAC. Therefore, it is shared functionally in response to all of the GeneralRequest primitives. Some of the entries in this list are marked with an asterisk to show that they are Indications. Indications are a special class of requests that imply some special handling. In implementation, they are usually associated with notifications to the protocol that are made from the MAC while it is in interrupt context. Because of this, the protocol is required to handle Indications as efficiently as possible. (For example, it might put the received frame on a queue.) After the protocol processes the indication, it returns control to the caller, the MAC. The MAC will enable as much interrupt processing as possible and then call IndicationComplete to give the protocol an opportunity to perform more processing on the Indication in a less critical mode (e.g., to decode the previously queued receive frame). Transmit and Receive Information in Table 2 identifies the basic purpose of each NDIS Primitive. Of these, transmit and receive are the key functions at the MAC-protocol interface level, so let's examine the primitives serving these functions in a little more detail. Network packets, or frames, are the data units that are transferred between the MAC and the protocol by the transmit and receive primitives. These packets include all the information, other than hardware related functions such as preamble and checksum, that will be sent out on the network medium. As a result, the protocol, on transmit, must build the entire packet, including data link fields such as source and destination addresses. Likewise, on receive, the protocol must process the packet down to these levels. The passing of packet data across the interface between the protocol and MAC is accomplished, whenever possible, by exchanging pointers to buffers or to a descriptor that, in turn, points to several data buffers. The objective is to avoid unnecessary, time-consuming copying of data between buffers. In transmit, the packet data buffers are owned by the host system and managed by the protocol driver. NDIS defines a structure, the transmit data buffer descriptor, that allows the packet data to be contained either in one buffer, or in a series of chained buffers. To initiate a transmit, the protocol assembles the packet data into buffers, puts the buffer addresses in the buffer descriptor structure, and calls the MAC with the TransmitChain primitive. The primitive contains a pointer to the buffer descriptor. 16 The MAC has two options for processing the transmit. The MAC will choose one or the other at its own discretion; the protocol must be capable of handling either. In the first, called synchronous transmission, the MAC copies all the packet data and returns to the protocol with a code signifying that the data buffers are free and the transmit is complete. Optionally, the MAC can return with a code signifying that the transmit is queued (this is called asynchronous transmission). It implies that the buffers are not free and the transmit has not yet completed. Later, after the MAC has copied all the transmit data, it will call the protocol with a TransmitConfirm primitive (the asynchronous response) to inform the protocol that the buffers are now free and the transmit is complete. An additional feature available in transmit is immediate data. The protocol has the option of beginning the transmit buffers with up to 64 bytes of immediate data. This immediate data, if present, is always the first data to be transmitted. The MAC must fully process or copy this data before returning from the TransmitChain call, even if it will asynchronously process any remaining data buffers for the call. This feature allows the protocol to have a small locally managed buffer that only needs to be valid during the TransmitChain primitive call. A protocol might use this for building packet header information, or for entire small protocol-generated packets, such as acknowledgements. For receiving packets, the process can work in one of two ways: using ReceiveLookahead and TransferData primitives, or using the ReceiveChain primitive. The method that is used is determined by the MAC, depending on how the MAC and adapter can handle data buffering. It is generally a function of whether the adapter has on-board receive buffers that use I/O or DMA to transfer the data, or whether the adapter buffers are memory-mapped and accessible directly by the host. For buffers on the adapter that use programmed I/O or DMA to transfer the data, the reception process will use a ReceiveLookahead and TransferData pair of primitives. When the MAC has received a packet that it wants to present to the protocol, it indicates this by calling the ReceiveLookahead primitive of the protocol. The ReceiveLookahead call contains a pointer to a short portion of the data at the beginning of the packet. This usually means that the MAC must have first DMA'ed this lookahead data to a buffer in the host. At this point, the protocol driver can examine the lookahead data to determine if it wants the packet. In some cases, the packet may not be of interest to the protocol. If the packet is not needed, the protocol can return to the MAC indicating a reject and that the receive is complete. If the packet is needed, the 17 protocol calls the TransferData primitive of the MAC which results in the MAC transferring the remainder of the data to a protocol buffer. The purpose of the ReceiveLookahead implementation is to avoid unnecessary data transfers between the MAC and the protocol. This technique improves the efficiency of the network stack. If the adapter has receive buffers that are accessible as host memory, receive will be implemented with the ReceiveChain primitive. For this type of buffering, the MAC will own and manage the receive buffers. For flexibility, this mode has a ReceiveChain buffer descriptor structure, similar to the transmit structure, that lets multiple separate buffers be joined for one packet transfer. When the MAC has a received packet to present to the protocol, it builds a buffer descriptor for the packet and calls the protocol with ReceiveChain. When the protocol gets the ReceiveChain Indication, it has two options. In the simplest case, the protocol can copy all of the packet data and return to the MAC specifying that the receive is complete and the buffers are free. In the other case, the protocol can defer copying the buffers and return to the MAC specifying that the buffers are still in use. The protocol will later complete the copying of the buffers and then call the MAC with a ReceiveRelease primitive to indicate that the buffers are now free and the receive is done. In all of these receive scenarios, the primitive calls issued to the protocol are indications. This means that the protocol drivers need to observe certain rules and that the MAC must issue an IndicationComplete call to the protocol as part of the process. See the NDIS document for more information about these indication issues. Dynamic Binding As mentioned earlier, some primitives for binding which haven't been discussed are provided to support dynamic binding. Dynamic binding is a new concept that has been added in Version 2.0.1 of the NDIS document. Dynamic binding allows a protocol to be added to, or removed from an existing network configuration after the initialization process has completed. The dynamic protocol driver must be written for this purpose and will normally be implemented as a TSR or transient program module. See the NDIS document for a full explanation of dynamic binding and unbinding. The main advantage of dynamic binding is freeing system memory until it is actually needed for a particular protocol. This is most useful in the DOS environment where there is a 640K memory limit and it is difficult to have multiple protocol stacks loaded simultaneously. 18 DOS Versus OS/2 NDIS has all the features needed to allow writing network drivers that will run in either the DOS or the OS/2 environment. A driver can only be used with one of these operating systems (the very same driver can't be used for both), but the structure of the driver can be identical for both environments. We have found that one set of source code can be used to make versions for both DOS and OS/2. Where different techniques are required, a small piece of code can be selected via conditional compile or assembly statements for the two versions. An example of such a difference, is that a certain call might need to use Interrupt 21h in a DOS-based driver, versus an IOCTL call for OS/2. A conditional selection of a few lines of code can implement one or the other. The make process for the driver will select the correct environment. Network device drivers are not very different in structure from other types of device drivers. The device driver must be written to conform to the architecture in which it will run - DOS or OS/2. All of the normal issues apply in writing NDIS drivers for both of these environments. Several books and articles are available that explain general driver development issues. See the list of references at the end of this article for some titles. Summary One of the main goals of the Network Driver Interface Specification is to save network software developers from reinventing the wheel for each new version of network adapter hardware. A protocol that is written with an NDIS interface at its base should be able to function, unchanged, with many different types of adapter hardware. In addition, the manufacturers of the network hardware should be in the best position to write efficient and bug-free MAC drivers for their own boards. 3Com and many other vendors (see Table 1) have NDIS MAC drivers available to support their network hardware. Using the standardized NDIS interface also allows a new level of sharing of network resources in a machine. Multiple protocols and multiple hardware adapters can coexist -- even those from different vendors. Input was sought from many leaders in the network industry to guarantee that the specification is flexible enough to meet most networking needs, however, 3Com carefully defined the functions so that performance would not be sacrificed for this flexibility. 19 If you are a network software developer, I hope this article has provided enough information for you to evaluate whether NDIS can help in your situation. For the complete description, the NDIS document can be obtained from 3Com at the following address: 3Com - Network Adapter Division Software Product Marketing 5400 Bayfront Plaza P.O. Box 58145 Santa Clara, Ca. 95052-8145 -- Author Bio: Rex Allers is a Systems Engineer in the Technical Services Operation at 3Com, specializing in support for developers. Rex has worked in engineering and support in the computer industry for longer than he cares to admit, and has been at 3Com since 1986. References: 1. "Microsoft/3Com LAN Manager Network Driver Interface Specification" 2. "The Open Book", Marshall Rose, Prentice Hall, 1990 3. "Advanced MS-DOS", Ray Duncan, Microsoft Press, 1986 4. "Writing MS-DOS Device Drivers", Robert S. Lai, Addison Wesley, 1987 5. "OS/2 Programmer's Guide", Ed Iacobucci, McGraw-Hill, 1988 6. "Writing OS/2 Device Drivers", Raymond Westwater, Addison Wesley, 1989 20