Writing Great Network Drivers for Windows ®

1. Writing Great Network Drivers for Windows® Tom Fout Program ManagerWindows® Operating Systems DivisionMicrosoft® Corporation

2. Topics • General Miniport guidelines • Common issues • Installation • Initialization/de-initialization • Operation • Testing • Performance guidelines

3. General Miniport Guidelines • OS specific functions reduce portability • Use only NDIS & WDM Interfaces • Note on Current Header Inconsistencies • Use BINARY_COMPATIBLE flag • Also For Portability • Full MAC Support Will be Gone Soon • Write Miniports for Longevity

4. Installation... • Common INF Issues • Never use Tabs • Don’t use Hybrid INFs (For Windows 2000 inclusion only) • Start Type Should be ‘3’ • Displayed UI Must be Localizable • ISAPNP/Legacy Mode Devices • Have Two NDI sections • Bustype=1; Bustype=14 • List ALL Plug and Play IDs

5. ...Installation • Have Keyword Defaults • Predefined in Driver • Don’t Bail if Key Cannot be Read • Don’t use Co or Class Installer • Unless Required – Can Be Complex • Multiport Serial, WAN, Layered Drivers • Check INF Quality with Tools • ChkINF Perl Script in DDK

6. Initialization... • Initialize Quickly – Effects System Boot • Perform Media Detection First – • Skip Speed Detection if Not Connected • If Connected – Defer Speed to Timer • Querying Hardware Resources • Use NdisMQueryAdapterResources • Use Standard Key names if Compatibility with Windows NT® 4.0 is Required • Do not access bus config space • Trust the Resources Returned by NDIS • Manage your resources • Free what you allocate • Reset what you Set • Release what you Acquire

7. …Initialization... • Use proper Initialization Order • Map IO/Memory First • Hook Interrupt Before Accessing Device • When you allocate interrupt, ISR may be called right away • Only indicate Media Connect after Sense • Not every step of n-way sense • Indicate It – Or we will Poll! • Reflect appropriate Media Speed • Especially after Media Change Indication • Don’t Indicate Status until Init Returns • NdisMAllocateMapRegisters • Dma32BitAddresses=TRUE • Unless Can’t Access Memory > 16MB

8. …Initialization • Event logging • For Out Of The Ordinary Events • Make it Descriptive • Only Log it Once • Use meaningful parameter defaults • Avoid UI • Auto Tune (I.e. Receive Buffers) • Don’t Scan the Bus during Initialization • If the HW is Plug and Play, it’s there when the driver is asked to initialize

9. Operation • Interrupt handling • Determine if Yours • Keep Interrupt State • Disable interrupts • Wait for DPC to Re-enable • MiniportCheckForHang handler • Determine if the HW is Functioning Properly • Request Reset if Not

10. Operation • Implement a Reset State Machine • Don’t stall, issuing Commands in a loop • Avoid Stalling • During Reset - it’s running a DPC • Media Sense/Negotiation • Longer than Microseconds • APIs can fail and so can HW • Be prepared to handle this

11. Operation • Support Power Management • Even if you don’t support Wake On LAN • Capabilities, QueryPower, SetPower OIDs • Improves Resume Time - Suspend/Hibernate • Note: NdisImmediateXxx APIs • Lookahead Size • Does not include MAC headers • Intermediate drivers • Must be Plug and Play and Power Managed • See DDK and Passthru Sample

12. Operation • Conserve CPU Cycles • E.g. Don’t Spin waiting for a bit to change • No Send Completions at DIRQL • Beware Performance Enhancements • That expect specific service timing • May work in some versions of Windows • May break in others

13. De-Initialization • Don’t Leave Hardware in Undefined State • Reset to Quiescent State • Support Dynamic Start and Stop • Don’t require a reboot • Differentiate Halt and Shutdown • Halt - device being stopped or removed • Free resources, reset HW • Cancel all timers • Shutdown - System shutting down • Reset HW to Quiet State • Don’t free resources or cleanup state

14. De-Initialization • Additional Notes On Halt: • If CancelTimer Fails, Timer has Fired • Wait for Timer To Complete • Ensure Timer is not Re-Queued • Indicating with NdisMIndicateReceivePacket • Make sure outstanding Packets have Been Returned – Before Returning from Halt • Check PacketPoolUsage or Ref Count

15. De-Initialization • When Reset: • When Reset Completes, Nothing is Pending • Abort All Pending Requests/Packets • De-serialized drivers are responsible for completing the aborted requests/packets • NDIS Has No Record of Pending Req. • NDIS_STATUS_REQUEST_ABORTED • Standard miniports should simply Abort • NDIS Will Complete the Aborted requests/packets • AddressingReset to have NDIS Restore State

16. Testing • Test with all of the main x86 HALs • Legacy • MPS • ACPI • APIC • MPS ACPI • ! Because we will ! • Test Additional Features (Enable Them) • Task Offload, 802.1p, WOL…

17. Performance Guidelines • Scalability • Task offload • Path length reduction

18. Performance GuidelinesScalability • Don’t de-serialize by protecting the driver with a single spinlock • Minimize spinlock acquires, releases, and hold times (avoid spinlocks) • Use spinlocks to protect data - not code • When using locks, avoid IRQL changes • Use NdisDprAcquireSpinLock in DPR, Etc… • Cache-line align important data structures • NdisGetCacheFillSize • To avoid False Sharing

19. Performance GuidelinesScalability • Partition data structures • Use Per-Processor Data Structures • Use Interlocked Operations • Convert Queues to Ring Buffers • Move Pointers with InterlockedIncrement • Use Push/Pop/PopAll Slist operation • i.e. NdisInterlockedPushEntrySList • Consider Needs for Statistics Accuracy • Avoid Protecting Counters • Keep Per-Processor Statistics

20. Performance GuidelinesTask Offload • Implement task offload • Checksum Offload • Both Send and Receive • Up to 30% Performance Boost (CPU) • Large Send • No Hardware Support? - implement in Software • Fast Forward Path (FFP)

21. Performance GuidelinesPath Length Reduction • Use Interrupt Moderation • Interrupt per number of packets or bytes • Use Interrupt Avoidance • Only Interrupt if Necessary • E.g. if in DPC, don’t interrupt • Use Large Frame Sizes where Possible • Use Lookaside Lists for memory allocation • For fixed size allocations • Grab as many as needed for main code paths

22. Performance GuidelinesPath Length Reduction • Use new DMA function • NdisMInitializeScatterGatherDma • Replaces NdisMAllocateMapRegisters • NDIS_PER_PACKET_INFO_FROM_PACKET • Retrieves scatter-gather list from the packet • Streamline DMA transfers by aggregating target pages • Indicate batch mode packet indications • NdisMIndicateReceivePacket • Dynamically grow/shrink receive buffers • NdisMAllocateSharedMemoryAsync • NdisReturnPackets • De-serialized drivers should expect during indication

23. Performance GuidelinesPath Length Reduction • Profile your Code (kernprof) • Find out where most time is spent • Optimize There • Tuning parameters • Auto tune where possible • Registry based tuning parameters • Use sensible names and defaults

24. New NDIS APIs • NdisMInitializeScatterGatherDma • Load Balance/Failover (LBFO) • NdisMSetMiniportSecondary • NdisMPromoteMiniport • NdisMRemoveMiniport • NdisMRegisterDevice (Deregister) • Create Accessible Device Object • NdisMRegisterUnloadHandler • Read/Write Locks • NdisInitializeReadWriteLock, NdisAcquireReadWriteLock, NdisReleaseReadWriteLock

25. Other API Notes • NdisGetReceivedPacket • NdisQueryReceiveInformation • NdisSetTimer/NdisCancelTimer • Protocol & Compatible Versions • Not Obsolete • NdisMSetTimer/NdisMCancelTimer • NdisAllocatePacket/NdisFreePacket • Free Macro vs. Function • Recompile w/ Windows 2000 DDK