E100BEX

[This is preliminary documentation and subject to change.]

SUMMARY

This sample is an NDIS 5 deserialized miniport driver for the Intel EtherExpressTM PRO/100+ Ethernet PCI adapter and the Intel EtherExpressTM PRO/100B PCI adapter. It illustrates NDIS 4 and NDIS 5 features such as multiple packet sends/receives, scatter gather DMA, LBFO, media sense, WMI, and Power Management. It also has NDIS 5.1 miniport features such as cancellation of send packets and PNP event handler. This driver comes with a KD extension DLL.

If NDIS51_MINIPORT is defined, the driver only does scatter gather DMA method and it will fail the initialization if its call to NdisMInitializeScatterGatherDma fails.

This driver supports Plug and Play. The code is 64-bit compliant, and builds properly with Microsoft® Visual C® 6.0.

BUILDING THE SAMPLE

Run the build command from this directory to build the sample. That creates the binary E100bex.sys.

TOOLS

The NDISTEST tool can be used to test some of the features of this driver. Note that this is not a production driver, and is not intended to replace the driver in the Windows® 2000 build.

CODE TOUR

File Manifest

Files          Description
E100BEX.htm    The documentation for this sample (this file)
Net557ex.inf   The .inf file for installing the code sample
e100.rc        The resource file for the code sample
e100.mof       The WMI mof file for the code sample
precomp.h      Precompile header
 
mp.h           Miniport generic portion header file
mp_cmn.h       Common definitions for the miniport and kd extension dll
mp_dbg.h       Debug code definitions and structures
mp_def.h       NIC specific definitions       
mp_nic.h       Function prototypes for mp_nic.c, mp_init.c and mp_req.c
mp_dbg.c       Debug-related code
mp_init.c      Miniport initialization related routines
mp_main.c      DriverEntry and NDIS miniport handlers
mp_nic.c       Miniport send/receive routines
mp_req.c       Miniport OID related handlers
offload.h      Task offloading related data structures and function prototypes
offload.c      Task offloading related functions
 
e100_557.h     Hardware definitions and structures for Intel 82557 controllers
e100_def.h     Other hardware specific definitions, e100_wmi.h included in this file
e100_equ.h     Hardware specific constant definitions
e100_sup.h     Hardware specific function prototypes and inline functions
eeprom.c       Routines to access EEPROM information
physet.c       Routines to detect and set up the physical layer
routines.c     Miscellaneous utility functions
 
sources.inc    The sources include file
makefile.inc   Used to generate e100_wmi.h from e100.bmf which is compiled from e100.mof
sys\sources    Sources file to build NDIS 5.1 and NDIS 5.0 compliant driver
 
kd\e100kd.c    The C file for the KD extension DLL (e100kd.dll)
kd\e100kd.def  The definition file for the KD extension DLL
kd\e100kd.h    The header file for the KD extension DLL
kd\e100kd.rc   The resource file for the KD extension DLL
 

Programming Tour

Some of the features illustrated in this driver are listed below, along with the files that contain the feature.

  1. NDIS 4: SendPacketsHandler; multiple packets per send request are handled (MpSendPackets() in mp_main.c).
  2. NDIS 4: NdisMIndicateReceivePacket(); multiple packets per receive indication (MpHandleRecvInterrupt() in mp_nic.c).
  3. NDIS 4: Receive buffer grow and shrink; When the adapter driver begins to run out of receive memory, NdisMAllocateSharedMemoryAsyn() is called to allocate more shared memory for receive buffers (MpHandleRecvInterrupt() in mp_nic.c). When the traffic slows down, the driver frees the memory (MPReturnPacket() in mp_main.c)
  4. NDIS 4: NdisMRegisterAdapterShutdownHandler() is called at initialization time to make sure the adapter has a function that stops generating interrupts and receiving packets into main memory (MpInitiliaze() and MpShutdown() in mp_main.c).
  5. NDIS 4: Media disconnect/connect indications are supported. This allows the driver to tell NDIS when the adapter has lost or regained link (MpCheckForHang() in mp_main.c).
  6. NDIS 5: This driver is a de-serialized miniport, therefore it protects its resources using its own spin locks rather than relying on Ndis to serialize the calls to the driver. This driver only implements a simple method of using spin lock: it has a NdisAcquireSpinlock() at every entry point and a NdisReleaseSpinlock() at the return from those entry points. The locks could be done more efficiently in a production driver by moving the locking closer to the resources in the driver that need to be accessed with atomic operations.
  7. NDIS 5: WMI: There are several examples of using GUIDs to advertise custom driver SETs and QUERIES. The E100.mof and mp_req.c files implement the functionality, the Makefile.inc is used to generate e100_wmi.h file and the e100.rc file includes the .bmf data into the driver resource area. By default the private WMI GUIDs provided by the driver are only accessible to users with administrator privilege. If the driver wants to give SETs(WRITE) or QUERIES(READ) access to users without administrator privilege, it must set the corresponding flags to the GUIDs which it wants to give access to.
  8. NDIS 5: Power Management: This driver demonstrates how to respond to Power Management OIDs. It shows how the miniport driver should suspend and resume the netcard. The driver also sets WakeUp Patterns on the netcard and enables the netcard to wake up the machine on PatternMatch (this is only implemented on the 82559 version of the Intel NetCard).
  9. NDIS 5: LBFO: This driver shows how to use LBFO APIs to implement LBFO functionality. This driver implements a simple LBFO scenario. This driver uses the primary adapter to receive packets. On the send side, the driver sends packets on the first available secondary adapter. If no secondary adapter is available, the driver sends packets on the primary adapter (see mp_main.c).
  10. NDIS 5: NdisMInitializeScatterGatherDma; this driver always attempts to use scatter gather which is available in NDIS 5 and later. If this call fails (on Win98 and later), it falls back to use map registers.
  11. OFFLOAD: This driver shows how to handle OID_TCP_TASK_OFFLOAD to enable/disable task offload capabilities of a NIC, and how to handle per-packet information related to these capabilities. In particular, the driver implements algorithms for TCP/IP checksum offloading and segmentation of large TCP packets on the send side. Note that these algorithms are implemented in software purely for illustrative purposes. It is expected that these algorithms would be implemented in hardware. Shipping drivers should not perform task offload in software.
  12. NDIS 5.1: Send packet cancellation. The CancelSendPacketsHandler allows protocols to cancel pending send packets which are queued in the miniport send queue (MPCancelSendPackets() in mp_main.c).
  13. NDIS 5.1: PNP event notification handler. The miniport drivers can have a PnPEventNotifyHandler to process anything necessary when a PNP event happens (MPPnPEventNotify() in mp_main.c).
  14. NDIS 5.1: AdapterShutdownHandler is now a standard miniport handler starting NDIS 5.1. It eliminates the need to call NdisMRegisterAdapterShutdownhandler.
  15. The Kernel Debugger DLL in this package works on Windows XP and later Operating Systems.

 

 

Top of page

 

© 1999 Microsoft Corporation