1 / 26

Sid Sidhartha Software Design Engineer Windows Driver Experience sidharth@microsoft.com

Writing SCSIPORT Miniport Drivers. Sid Sidhartha Software Design Engineer Windows Driver Experience sidharth@microsoft.com. Contents. SCSIPORT Architecture overview SCSI Miniport model PNP/Power handling for miniport I/O handling for miniport Common Miniport Errors

calhoun
Download Presentation

Sid Sidhartha Software Design Engineer Windows Driver Experience sidharth@microsoft.com

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. Writing SCSIPORT Miniport Drivers Sid SidharthaSoftware Design EngineerWindows Driver Experience sidharth@microsoft.com

  2. Contents • SCSIPORT Architecture overview • SCSI Miniport model • PNP/Power handling for miniport • I/O handling for miniport • Common Miniport Errors • Debugging SCSI Miniports • Resources

  3. Need For SCSI Miniports • 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

  4. Advantages Of A Miniport model • No synchronization issues • No PNP/Power complexity • Simple interface to help concentrate on actually programming the hardware • Miniport shielded from OS changes

  5. Miniport Synchronization SCSIPORTStartIO Interrupt Levels Level 14 Miniport USB Level 13 Level 12 Level 11 HwStartIO Level 10

  6. Miniport Synchronization Issues • 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

  7. PNP Support • 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

  8. PNP Gotchas • 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

  9. POWER Support • 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

  10. IO: DMA Support • 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

  11. IO: Tags And Queue Management • 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

  12. I/O: Busy Processing • 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

  13. I/O: Bus Resets • 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

  14. Callbacks • MiniPort may request timer callbacks • MiniPort may request a callback at DPC level from it’s ISR • CallDisableInterrupts / CallEnableInterrupts should be used with care

  15. Error Processing • 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

  16. Important Registry Keys • NumberOfRequests • TotalSenseDataBytes • TimeoutValue • DriverParameter(s) • ResetHoldTime • MaximumSGList

  17. Debugging: Tools • 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.

  18. Debugging: SCSI Verifier • 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

  19. Debugging: Locating Adapters/LUNS 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

  20. Debugging: Locating Adapters/LUNS 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

  21. Common Problems • Bugcheck 0x7A and 0x77 • Hangs and timeouts • Reproducible problems • Interrupt storms and no interrupts • Scatter gather lists

  22. Common Problems: Bug-Check 7A/77 • Reset due to device/port timeout • Selection timeout • Controller errors • !scsikd.classext displays LUN error log • !errlog often identifies useful info

  23. Common Problems: Hangs And Timeouts • 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 • !devobj <FDO>, !scsikd.scsiext

  24. Common Problems: Interrupts • 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

  25. Resources • 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

  26. © 2003 Microsoft Corporation. All rights reserved. This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.

More Related