ATA Miniport Nuts and Bolts Michael Xing SDE II Device and Storage Technologies xiaoxing@microsoft.com

Agenda Why ATA Miniport? ATA Port / Miniport Model ATA Port / Miniport Interfaces New Interfaces in Windows 7 Best Practices

Why ATA miniport? Do I need an miniport driver? Controllers supported by inbox drivers Microsoft inbox ATA miniport drivers: atapi.sys – developed for legacy PATA controllers msahci.sys – developed for SATA controllers Consider options other than a driver Special requirements that are not covered by inbox drivers: Your hardware uses ATA protocol but has a different transfer layer or exposes special feature(s) Contact us about feature support before developing your own miniport driver

Why ATA miniport? Which port driver model should I use? Windows versions support ATAport: Vista and later Storport: Server 2003 and later Command protocol selection ATAport / miniport command protocol: ATA Storport / miniport command protocol: SCSI Common ATA functionalities implemented in ATA port driver Such as set device attributes, set transfer mode, etc. Less code in miniport

ATA Port/Miniport Model – Driver Stack Class Driver ATA Port DLLs - ATAport.sys - PCIIDEx.sys ATA Miniport Driver PCI Driver

ATA Port/Miniport Model – Loading Sequence PCIIDEx.sys Create Channel FDO Create Device FDO Load ATA Miniport Load ATAport.sys Create Channel PDO Load Class Driver Create Controller PDO Enumerate Channels Create Device PDO PCI Driver Create Controller FDO Enumerate Devices ATA Controller

ATA Port/Miniport Model – Role of ATA Port Driver I/O translation into ATA protocol I/O queuing with prioritization considered Sense Data generation for ATA devices PnP and power request handling Request to miniport driver in push mode

ATA Port/Miniport Model – Role of ATA Miniport Driver Convert ATA command into final transfer layer package if necessary Send final command to device Monitor interrupt for command completion Negotiate for channel and device parameters Select queue depth Freeze/unfreeze queue according to device status

Port / Miniport Interfaces – General ATAport Default Miniport ATA Port DLLs - ATAport.sys - PCIidex.sys Channel Interface ATA Controller I/O Controller Interface Vendor Miniport ATA Miniport Driver PCIidex

Port / Miniport Interfaces – Miniport Major Routines Controller Interface Routines DriverEntry() AtaAdapterControl() – PnP, power operations AtaControllerChannelEnabled() – Channel is usable or not Channel Interface Routines AtaChannelInitRoutine() – Set routine pointers for channel IdeHwControl() – PnP, power operations IdeHwInitialize() – Device initialization IdeHwBuildIo() – I/O preparation IdeHwStartIo() – Execute the I/O IdeHwInterrupt() – Monitor hardware activities; process I/O completion

Port / Miniport Interfaces - Controller Interfaces ATA Port Processes AtaControllerChannelEnabled() Create Channel PDO AtaAdapterControl() with IdeStart Enumerate Channels DriverEntry() (Set callback function pointers) Start Device (Controller) Add Device - Create Controller FDO Load PCIIDEx.sys Load ATA Miniport Load ATAport.sys AtaPortInitializeEx()

Port / Miniport Interfaces - Channel Interfaces ATA Port Processes IdeHwInterrupt() I/O IdeHwStartIo() Create Device PDO IdeHwBuildIo() Configure Devices IdeHwInitialize() Enumerate Devices IdeHwControl() with IdeStart Start Channel AtaChannelInitRoutine() Add Device – Create Channel FDO

Port / Miniport Interfaces – I/O Interface IDE_REQUEST_BLOCK Contains Structure for ATA TaskFile I/O execute mode – PIO or DMA Data buffer for the I/O Other information needed by Miniport driver to execute the command Status and Error field Usage I/O request Miniport action, such as power down the device // 0x100 - 0x1FF indicate ATA commands #define IRB_FUNCTION_ATA_COMMAND 0x100 #define IRB_FUNCTION_ATA_IDENTIFY 0x101 #define IRB_FUNCTION_ATA_READ 0x102 #define IRB_FUNCTION_ATA_WRITE 0x103 #define IRB_FUNCTION_ATA_FLUSH 0x104 #define IRB_FUNCTION_ATA_SMART 0x105 // 0x200 - 0x2FF indicate ATAPI commands #define IRB_FUNCTION_ATAPI_COMMAND 0x200 #define IRB_FUNCTION_REQUEST_SENSE 0x201 // 0x400-0x4FF indicate miniport commands #define IRB_FUNCTION_MINIPORT_COMMAND 0x400 #define IRB_FUNCTION_ADAPTER_FLUSH 0x401 #define IRB_FUNCTION_SHUTDOWN 0x402 #define IRB_FUNCTION_POWER_CHANGE 0x403 #define IRB_FUNCTION_LUN_RESET 0x404 #define IRB_FUNCTION_MINIPORT_IOCTL 0x405 #define IRB_FUNCTION_POWER_REBOOT 0x406

New Interfaces in Windows 7 System Reboot Notification IRB_FUNCTION_POWER_REBOOT Vendor-Defined Power Management IDE_CONTROL_ACTION – IdeVendorDefined Device Parameter Flags Removable Device Flag – DFLAGS_REMOVABLE_DEVICE FUA Support Flag – DFLAGS_FUA_SUPPORT

Best Practices - Device Parameter Changes Changing removable device flag in Microsoft Miniport driver for SATA controller BOOLEAN AhciHwInitialize ( IN PVOID ChannelExtension, IN OUT PIDE_DEVICE_PARAMETERS DeviceParameters, IN PIDENTIFY_DEVICE_DATA IdentifyData ) { … // 3.1 Removable Device Detect if ((channelExtension->Px->CMD.HPCP) || ((channelExtension->CAP.SXS) && (channelExtension->Px->CMD.ESP))) { // Px->CMD.HPCP indicates that the port is hot-pluggable. (both signal and power cable) // CAP.SXS && Px->CMD.ESP indicates that it's an ESATA port. (only signal cable) DeviceParameters->DeviceCharacteristics |= DFLAGS_REMOVABLE_DEVICE; } return TRUE;

Best Practices – Pause Process AtaPortStallExecution() Spin locks the CPU for x microseconds Less than one millisecond delays Should be used during hibernate or crash dump AtaPortRequestTimer() Causes the port driver to trigger a callback routine after x microseconds Greater than one millisecond delays Best when used with multiphase functions

Best Practices – I/O Error Reporting IRB_STATUS_DEVICE_ERROR Most common I/O error code IRB_STATUS_BUSY Host is busy Make sure to pause the queues with AtaPortDeviceBusy() IRB_STATUS_SELECTION_TIMEOUT Not necessarily retried Port driver may reset the device IRB AtaStatus and Error fields Only valid on IRB_STATUS_DEVICE_ERROR or IRB_STATUS_SELECTION_TIMEOUT

Calls to Action Read “ATA Miniport Drivers” in MSDN http://msdn.microsoft.com/en-us/library/aa508877.aspx Refer to sample code Microsoft Miniport driver for AHCI controller in WDK at src\storage\msahci Ask questions at ATA Miniport Driver Development Forum http://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=1837&SiteID=1 Contact us about feature support: ataportq@microsoft.com

Resources Related Specifications Related Sessions ATA - http://www.t13.org SATA - http://www.serialata.org AHCI - http://developer.intel.com/technology/serialata/ahci.htm Related Sessions Session Day / Time Storport Drivers from the Ground Up Tues. 8:30-9:30 and Wed. 9:45-10:45 Storport Smorgasboard Tues. 4-5 and Wed. 11-12

Questions ?