1. NDIS-WDM Miniport Drivers Larry Cleeton Program Manager Windows Networking And Communications Microsoft Corporation

3. Agenda Overview of NDIS-WDM miniports Writing an NDIS-WDM miniport
Installing NDIS-WDM miniports
Remote NDIS

4. Background New expansion bus types have been introduced to the PC
USB in virtually every new PC
IEEE 1394 is becoming more common
Network devices are being designed to use these bus types
User does not have to crack the case
Device can be transferred to another machine easily

5. Driver Model Changes
The driver and hardware architecture for these new bus types is different from a traditional bus like PCI
NDIS miniport model has evolved
NDIS Miniports can now interface with a WDM driver instead of directly to hardware
WDM I/O Request Packets (IRPs) can be passed between the NDIS miniport and WDM driver (IoCallDriver)

6. USB Host Controller Driver
NDIS-WDM Miniport
Other
Protocols
TCP/IP
NDIS
NDIS.SYS
NDIS Calls and Data Structures
Miniport driver
WDM Calls and Data Structures
USB Bus Driver
USBD.SYS
USB Host Controller Driver

7. Writing And NDIS-WDM Miniport
Learn NDIS miniport interfaces (DDK)
Learn general WDM IRP handling (DDK, books)
Refer to DDK for WDM bus specific driver interfaces for USB, etc.
Use Windows® 2000 DDK

8. General Driver Tips Preprocessor #define(s)
NDIS_WDM=1
To cause ndis.h to include wdm.h
USE_KLOCKS=1
To ensure you get spinlocks on Windows 9x
Don’t mix NDIS and WDM resources
Match up alloc/free symmetrically

9. Required Functions (1 of 2)
MiniportShutdown
MiniportInitialize
MiniportHalt
MiniportReset
MiniportReturnPacket

10. Required Functions (2 of 2)
Connectionless media
MiniportSend or SendPackets
MiniportQueryInformation
MiniportSetInformation
Connection-oriented media
MiniportCoSendPackets
MiniportCoRequest

11. Unnecessary Functions
Interrupt functions
MiniportISR
MiniportHandleInterrupt
MiniportEnableInterrupt
MiniportDisableInterrupt
MiniportTransferData
MiniportAllocateComplete
MiniportCheckForHang*

12. Initialization MiniportInitialize
Alloc device specific data structures
NdisMGetDeviceProperty() gets pointer to device object to which to send IRPs using IoCallDriver()
NdisMSetAttributes (NDIS_ATTRIBUTE_DESERIALIZE)
NdisMRegisterAdapterShutdownHandler()

13. Halting MiniportHalt Tell device you are going away
Cancel and wait for any outstanding IRPs to finish
Can block until IRPs complete
Complete pending upper-edge NDIS operations
Free device specific data structures

14. Sending Data MiniportSend or MiniportSendPackets
Prepare one or more IRPs for each NDIS_PACKET
Complete by calling NdisMSendComplete() when all IRPs for a packet are complete

15. Preparing Send Buffers
Build an MDL chain
Alloc buffer for message header
Alloc MDL for message header buffer
For each NDIS_BUFFER
Get NDIS_BUFFER vaddr, len
Alloc MDL for this buffer
Chain MDL to previous MDL

16. Receiving Data Submit “read” IRPs to bus driver When IRP completes…
Encapsulate received data packet in NDIS_PACKET and NDIS_BUFFER
NdisMIndicateReceivePacket()

17. Special Notes – Windows 9x (1 of 3)
All send completions, receive indications and status indications should be called from within the context of an NDIS-called routine
Transmit completions and receives will come into your driver in the context of the lower WDM driver
It is necessary to queue those events, start another thread with an NDIS timer and complete operations there

18. Special Notes – Windows 9x (2 of 3)
Psuedo-code for receive indications
Acquire spinlock to Adapter structure;
Queue NDIS_PACKET to tail of list of pending receives;
if (Adapter->IndicatingReceives == FALSE) {
Adapter->IndicatingReceives = TRUE;
NdisSetTimer(&Adapter->IndicateTimer, 0); }
Release spinlock;

19. Special Notes – Windows 9x (3 of 3)
Psuedo-code for IndicateTimer handler
Acquire spinlock to Adapter structure;
while (pending receive queue is not empty) {
Dequeue NDIS_PACKET from pending receive queue;
Release spinlock;
Status = NDIS_GET_PACKET_STATUS(pNdisPacket);
NdisMIndicateReceivePacket();
if (Status == NDIS_STATUS_RESOURCES) {
Call own returnpacket handler with this packet; }
Acquire spinlock;
Adapter->IndicatingReceives = FALSE;

20. Power Management
NDIS handles all Plug and Play and PM IRPs on behalf of the NDIS WDM miniport
Driver should respond to PM OIDs, based on device capabilities, in the same way it would for an NDIS miniport for a PCI device

21. Installing NDIS-WDM Miniport
Create standard NDIS net class INF
Include Plug and Play IDs of device as usual but specific to new bus type

22. Remote NDIS (RNDIS)
Generalized NDIS message set implemented in a Microsoft® provided NDIS WDM miniport
IHV implements NDIS message set in their device’s firmware
Specification and overview:
Beta drivers available upon request:

23. RNDIS Message Exchange
Remote NDIS
RNDIS Message Exchange
Windows PC
Protocols
USB Ethernet Device
RNDIS
Firmware
RNDIS
USB HC
USB Bus
USB
IEEE 1394 HC
IEEE 1394 Bus
1394
IEEE 1394
Eth MAC
Ethernet

24. Call To Action Use Remote NDIS if possible
Create NDIS-WDM drivers where necessary
Test using NDIS tester and WHQL HCT tools

25. More Information Windows Driver and Hardware Development
Remote NDIS beta drivers
Windows Hardware Quality Labs
Programming the Microsoft Windows Driver Model
Walter Oney, Microsoft Press

26. Discussion