A miniport driver includes driver objects, driver code, and the NDIS library code. The Windows NT DDK provides ndis.h as the main header file for miniports. This file defines the entry points for the miniport, the NDIS library functions, and common data structures. The Network Reference contains the definitions of the miniport, protocol, and NdisXxx functions, the common data structures, and OIDs.
Miniport Adapter Object
NDIS uses a software object called a logical adapter to represent each NIC in the system. The logical adapter corresponds to a Windows NT device object managed by the I/O subsystem. The device object that represents the adapter contains information about an associated NIC, such as name, network address, and the base address of the NIC. It also contains data about the current state of the driver in relation to the hardware, such as number of bindings, binding handles, filter database, and logical adapter references. NDIS passes a handle to this structure to MiniportInitialize; the miniport NIC driver will supply this handle in subsequent calls to NDIS. This structure is maintained by NDIS and is opaque to the miniport.
When a miniport NIC driver is called to initialize an adapter it manages, it creates its own internal data structure to represent the adapter. The driver uses this structure to keep device-specific state information it needs to manage the NIC. The miniport NIC driver will pass a handle to this structure to NDIS when it calls NdisMSetAttributes or NdisMSetAttributesEx and, when NDIS calls the miniport’s entry points, it will pass this handle, identifying the correct adapter to the driver. This structure is owned and maintained by the miniport NIC driver.
Network Object Identifiers
The miniport NIC driver also maintains a set of objects identified by a system-defined object identifier (OID) that represents information about the driver’s capabilities and current status. To query this information, a higher level driver calls NdisRequest and passes the OID to the NDIS library with a buffer large enough to hold the returned data. The OID specifies the type of information requested by the caller, such as the size of lookahead buffer the miniport supports. The request is passed to the miniport’s MiniportQueryInformation entry point. If the caller does not provide a large enough buffer for the information, the miniport writes the number of bytes needed for the data, along with a relevant failure status code.
For more information about OIDs, see the Network Driver Reference.
Miniport NIC Driver Code
The typical miniport NIC driver must have a small number of functions to communicate through NDIS with upper layers and the hardware. The complete list is described in Section 2.3; not all functions are required. Chapter 3 describes which functions are optional, which are required, and why.
Many of a miniport’s functions can operate either synchronously or asynchronously. The asynchronous functions have corresponding completion functions in the NDIS library that must be called when an operation is finished. See the Network Driver Reference for more information about these functions.
The DDK includes sample code for miniports that manage several types of network cards. These sample drivers can be tailored to a driver developer’s needs. The sample drivers contain functions that can be adapted to a new but similar driver. There are always hardware-dependent functions that must be written by the driver developer. However, many functions (primarily those that communicate with the NDIS library instead of a network interface card) are fairly standard. For these driver functions, the code in a sample driver might be usable with little or no modification.
These samples include the following:
·NE2000, a 16-bit ISA card that uses programmed I/O.
·NE3200, a 32-bit EISA bus-mastering card that uses 16-bit DMA transfers.
·Lance (AMD 7990) Ethernet chip.
·IBM Token Ring 16/4 Adapter.
·IBM Token Ring 16/4 Adapter II.
·DC21X4 busmaster DMA Adapter
NDIS Library
The NDIS library is packaged in ndis.sys, a kernel-mode export library (an export library is a .sys file that functions similarly to a dynamic-link library), as a set of abstract functions, with emphasis on macros for maximum performance. Both protocol and NIC drivers, including WAN NIC drivers, link against this library. The NDIS library functions are defined in the Network Driver Reference.