HW_STARTIO回呼函式 (storport.h)

發行項
02/26/2024

Storport 驅動程式會針對每個傳入 I/O 要求呼叫 HwStorStartIo 例程一次。

語法

HW_STARTIO HwStartio;

BOOLEAN HwStartio(
  PVOID DeviceExtension,
  PSCSI_REQUEST_BLOCK Srb
)
{...}

參數

DeviceExtension

迷你埠驅動程式每個 HBA 儲存區域的指標。

Srb

要啟動之 SCSI 要求區塊的指標。

傳回值

如果成功起始要求，HwStorStartIo 會傳回 TRUE。否則會傳回 FALSE。

備註

HwStorStartIo 會起始 I/O 作業。 StorPort 的設計目的是使用 HwStorBuildIo 中備妥的迷你埠私人數據，並儲存在 DeviceExtension 或 Srb-SrbExtension> 中。因為 HwStorBuildIo 是在沒有微調鎖定的情況下呼叫，所以在 HwStorBuildIo 中盡可能準備數據，即可達到最佳的驅動程式效能。

Storport 會以下列方式呼叫 HwStorStartIo ：

針對記憶體非虛擬迷你埠驅動程式，根據PORT_CONFIGURATION_INFORMATION中設定的 SynchronizationModel 值，Storport 一律會使用相同的 IRQL 呼叫 HwStorStartIo，並使用內部微調鎖定來確保 I/O 要求會循序起始。 IRQL DISPATCH_LEVEL (全双工模式) 或 DIRQL (半雙工模式) 。

在半雙工模式中處理 I/O 時， HwStorStartIo 例程不需要取得自己的微調鎖定。此外，HwStorStartIo 例程中不允許使用 StorPortAllocatePool 和透過 StorPortAcquireSpinLock 進行相互排除的記憶體配置。在全雙工模式中， StorPortAllocatePool 和 StorPortAcquireSpinLock 可用於 HwStorStartIo 例程。

如果非虛擬迷你埠支援 StorPortInitializePerfOpts (STOR_PERF_CONCURRENT_CHANNELS) 所設定的並行通道優化，則可能會同時呼叫 HwStorStartIo 。在此情況下，迷你埠必須確保任何共用資源都受到鎖定保護。透過此效能優化，Storport 不會在呼叫 HwStorStartIo 之前取得 StartIo 鎖定，而且迷你埠必須視需要提供自己的鎖定。
針對記憶體虛擬迷你埠驅動程式，Storport 會在任何 IRQL <= DISPATCH_LEVEL 呼叫 HwStorStartIo，而且不會使用內部微調鎖定。 HwStorStartIo 例程可以藉由呼叫 StorPortAcquireSpinLock 來取得自己的微調鎖定。此外，記憶體虛擬迷你埠驅動程式的 HwStorStartIo 例程中允許呼叫 StorPortAllocatePool。

收到 SCSI 狀態時，預期會完成 SRB。當 Storport 驅動程式使用 RequestComplete 的 NotificationType 呼叫 StorPortNotification 來完成 SRB 時，SRB 預期會在 Srb 的 SrbStatus 字段中傳回下列其中一個值：

SRB_STATUS_SUCCESS
- 指出已傳送 Srb，且可能傳回數據) 的 SCSI 狀態 (。
- Storport 會將數據和狀態傳回給呼叫端。
- 迷你埠動作是無的，除非使用 StorPortNotification for RequestComplete 來完成要求，可能是來自 HwStorDpcRoutine。
SRB_STATUS_BUSY
- 表示傳送 Srb (時發生暫時性問題，例如適配卡緩存器或緩衝區忙碌) 。
- Storport 會捨棄 Srb-SrbExtension> 指向的原始 Srb 延伸模組，並發出新的延伸模組。 Storport 會在後續對 HwStorBuildIo 和 HwStorStartIo 的呼叫中傳送具有新發行 Srb 延伸模組的原始 Srb。原始 Srb 延伸模組中的所有數據都會遺失。
- 迷你埠不應該更新 Srb 的 DataTransferLength。
- 因為發出新的 Srb 擴充功能，所以迷你埠必須確定它永遠不會在 SCSI 交易中間發出SRB_STATUS_BUSY。交易啟動之後，必須完成或取消交易。交易期間的硬體忙碌狀態必須由迷你埠驅動程序處理。

HwStorStartIo 名稱是一個佔位符，用來描述HW_INITIALIZATION_DATA結構的 HwStartIo 成員中設定的迷你埠例程。此結構會傳入 StorPortInitialize 的 HwInitializationData 參數。此例程的實際原型定義於 Storport.h 中，如下所示：

typedef
BOOLEAN
(*PHW_STARTIO) (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

從 Windows 8 開始，Srb 參數可以指向 SCSI_REQUEST_BLOCK 或 STORAGE_REQUEST_BLOCK。如果 Srb函式欄位中的函式識別碼SRB_FUNCTION_STORAGE_REQUEST_BLOCK，則 SRB 是STORAGE_REQUEST_BLOCK要求結構。

範例

若要定義 HwStorStartIo 回呼例程，您必須先提供靜態驅動程式驗證程式 (SDV) 和其他驗證工具所需的函式宣告，如下列程式代碼範例所示：

若要定義 HwStorStartIo 回呼函式，您必須先提供函式宣告來識別您要定義的回呼函式類型。 Windows 提供一組驅動程式的回呼函式類型。使用回呼函式類型宣告函式有助於驅動程式的程式代碼分析、靜態驅動程式驗證器 (SDV) ，以及其他驗證工具尋找錯誤，而且這是撰寫 Windows 操作系統驅動程式的需求。

例如，若要定義名為 MyHwStartIo 的 HwStorStartIo 回呼例程，請使用 HW_STARTIO 類型並實作回呼例程，如下所示：

HW_STARTIO MyHwStartIo

BOOLEAN
MyHwStartIo (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );
  {
      ...
  }

HW_STARTIO函式類型定義於 Storport.h 頭檔中。若要在執行程式代碼分析工具時更精確地識別錯誤，請務必將新增至函式 _Use_decl_annotations_ annotation 定義。可確保 _Use_decl_annotations_ annotation 會使用頭檔中套用至 HW_STARTIO 函式類型的註釋。如需函數宣告需求的詳細資訊，請參閱使用 Storport 驅動程式的函式角色類型宣告函式。如需的相關信息 _Use_decl_annotations_，請參閱標註函式行為。