WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 Writing SCSIPORT Miniport Drivers Sid Sidhartha Software Design Engineer Windows Driver Experience sidharth@microsoft.com

WHDC PowerPoint Template Notes & Handouts Contents WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 SCSIPORT Architecture overview SCSI Miniport model PNP/Power handling for miniport I/O handling for miniport Common Miniport Errors Debugging SCSI Miniports Resources

Need For SCSI Miniports WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 Windows Device Driver Model is complex PNP/POWER handling for bus drivers is involved Storage vendors need to focus on writing hardware specific code, not on Windows intricacies A WDM storage driver needs to handle performance, queuing, forward progress under low memory conditions and complex synchronization problems

Advantages Of A Miniport model WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 No synchronization issues No PNP/Power complexity Simple interface to help concentrate on actually programming the hardware Miniport shielded from OS changes

Miniport Synchronization WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 SCSIPORTStartIO Interrupt Levels Level 14 USB Miniport Level 13 Level 12 Level 11 HwStartIO Level 10

Miniport Synchronization Issues WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 Advantages Miniport becomes simple to write No synchronization primitives needed Disadvantages Every time any Miniport routine is called, all interrupts at that level are blocked Polling by calling “StallExecution” is not desirable

WHDC PowerPoint Template Notes & Handouts PNP Support WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 Interrupts, ports, memory for the adapter are provided to the miniport during startup and restart During a Disable/Stop, port ensures disconnecting the interrupt, freeing the resources, etc. Port supports hot plug by providing SCSIPORTNotification (BusChangeDetected) call SCSI inquiry command is used to discover LUNs Port generates unique PNP-ID-based on inquiry string

WHDC PowerPoint Template Notes & Handouts PNP Gotchas WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 SCSIPORTNotification (BusChangeDetected) is not a synchronous call The dead LUN could get lot of IO before finally being removed from the OS The whole bus is scanned again and all the devices inquired Device enumeration is an expensive operation

WHDC PowerPoint Template Notes & Handouts POWER Support WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 Port provides idle detection support for disk LUNS are powered on/off by START_STOP_UNIT Command Power to the adapter is controlled by HwScsiAdapterControl call Port driver manages all S-D IRP translations and calls miniport only during adapter start and shutdown

WHDC PowerPoint Template Notes & Handouts IO: DMA Support WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 Miniport is shielded from OS DMA routines Miniport is provided with a physically contiguous common buffer that may be shared between CPU and bus-master HBA Simple interface to obtain physical address of the common buffer A per request storage area is also allocated for the Miniport

IO: Tags And Queue Management WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 Tags generated for I/O are on a per Adapter basis Untagged requests cause port to wait for all active I/O on the LUN to complete NextRequest / NextLuRequest, are the mechanisms for Miniport to request more I/O For LUNS that support tagged queuing, use NextLuRequest to maximize throughput

WHDC PowerPoint Template Notes & Handouts I/O: Busy Processing WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 SCSIPORT supports busy processing on a LUN as opposed to adapter Level LUN transitions to a busy state when a SRB is completed with status BUSY All requests to the LUN are stopped, and the busy request is retried after 1s Miniport must call NextRequest in response to every request being returned as Busy

WHDC PowerPoint Template Notes & Handouts I/O: Bus Resets WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 Large I/O delays lead to miniport’s HwResetBus routine being called Miniport should ensure completion of all outstanding requests in this routine No more requests are issued to the miniport for a Reset Hold Period (currently 4s) The SCSI bus may also be reset to restart a hung adapter

WHDC PowerPoint Template Notes & Handouts Callbacks WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 MiniPort may request timer callbacks MiniPort may request a callback at DPC level from it’s ISR CallDisableInterrupts / CallEnableInterrupts should be used with care

WHDC PowerPoint Template Notes & Handouts Error Processing WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 Set the SrbStatus field wisely Use SCSIPORTLogError to log real adapter/link errors, not LUN failures Update the DataTransferLength field of the SRB appropriately Fill in the SenseData carefully

Important Registry Keys WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 NumberOfRequests TotalSenseDataBytes TimeoutValue DriverParameter(s) ResetHoldTime MaximumSGList

WHDC PowerPoint Template Notes & Handouts Debugging: Tools WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 Debugger Extensions scsikd.dll Windows 2000, Windows XP, Windows Server 2003. minipkd.dll Windows Server 2003 only. SCSI Verifier Windows XP and Windows Server 2003 only.

Debugging: SCSI Verifier WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 SCSI verifier is a great debugging and testing aid for miniport developers Verifier thunks calls to miniport for maintaining state Verifier bug-checks with a unique error code in case of rule violations Verifier does advanced error detection like remapping SRB extensions to physically non-contiguous pages

Debugging: Locating Adapters/LUNS WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 0: kd> !object \device\scsi Object: e12a2520 Type: (863d12c8) Directory ObjectHeader: e12a2508 HandleCount: 0 PointerCount: 9 Directory Object: e1001100 Name: Scsi Hash Address Type Name ---- ------- ---- ---- 04 86352040 Device adpu160m1Port3Path0Target6Lun0 11 86353040 Device adpu160m1Port3Path0Target1Lun0 13 86334a70 Device lp6nds351 22 862e6040 Device adpu160m1Port3Path0Target0Lun0

Debugging: Locating Adapters/LUNS WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 0: kd> !minipkd.adapters Adapter \Driver\lp6nds35 DO 86334a70 DevExt 86334b28 Adapter \Driver\adpu160m DO 8633da70 DevExt 8633db28 LUN 862e60f8 @(0,0,0) c ev pnp(00/ff) pow(0,0) DevObj 862e6040 LUN 863530f8 @(0,1,0) c ev p d pnp(00/ff) pow(0,0) DevObj 86353040 LUN 862e50f8 @(0,2,0) c ev pnp(00/ff) pow(0,0) DevObj 862e5040 LUN 863520f8 @(0,6,0) ev pnp(00/ff) pow(0,0) DevObj 86352040 Adapter \Driver\adpu160m DO 86376040 DevExt 863760f8 Flags c - claimed m - missing e - enumerated v - visible p – paging d – dump h - hibernate

WHDC PowerPoint Template Notes & Handouts Common Problems WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 Bugcheck 0x7A and 0x77 Hangs and timeouts Reproducible problems Interrupt storms and no interrupts Scatter gather lists

Common Problems: Bug-Check 7A/77 WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 Reset due to device/port timeout Selection timeout Controller errors !scsikd.classext displays LUN error log !errlog often identifies useful info

Common Problems: Hangs And Timeouts WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 SCSIPORT DPC not running !pcr, !stacks, !process 0 7 Miniport fails to ask for next request !devobj <FDO>, !scsikd.scsiext Request is stuck in SCSIPORT Waiting for map registers

Common Problems: Interrupts WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 Problems No interrupts Interrupt storms What to do… Check if your interrupt is shared Step over ISR to see if hardware is generating interrupt storm

WHDC PowerPoint Template Notes & Handouts Resources WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 Microsoft Windows DDK http://www.microsoft.com/ddk Debugging tools http://www.microsoft.com/ddk/debugging OSR’S NTDEV mailing list http://www.ntdev.org Links http://www.microsoft.com/whdc/hwdev/tech/storage/entstor/default.mspx

WHDC PowerPoint Template Notes & Handouts Saturday, June 16, 2018 © 2003 Microsoft Corporation. All rights reserved. This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.