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

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

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

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)

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

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

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

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

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

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

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()

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

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

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

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

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

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;

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;

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

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

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: http://www.microsoft.com/hwdev/network Beta drivers available upon request: rndisfb@microsoft.com

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

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

More Information Windows Driver and Hardware Development http://www.microsoft.com/hwdev Remote NDIS beta drivers rndisfb@microsoft.com Windows Hardware Quality Labs http://www.microsoft.com/hwtest Programming the Microsoft Windows Driver Model Walter Oney, Microsoft Press

Discussion