HW_BUILDIO回呼函式（storport.h）

發行項
02/07/2025

HwStorBuildIo 例程會先以未同步方式存取共用系統數據結構的 SRB，再將它傳遞至 HwStorStartIo 。

語法

HW_BUILDIO HwBuildio;

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

參數

DeviceExtension

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

Srb

要處理的 SCSI 要求區塊（SRB）指標。

傳回值

HwStorBuildIo 會傳回 true，告知呼叫者，如果 StorPort 認為 LUN 已準備好接收 I/O，則 StorPort 應該呼叫 HwStorStartIo 例程。 HwStorBuildIo 會傳回 FALSE，通知呼叫者不應將 SRB 傳遞給 HwStorStartIo。在這種情況下，迷你埠驅動程序必須呼叫 StorPortNotification，且通知類型為 RequestComplete來完成 SRB。這可以在 HwStorBuildIo 或迷你埠驅動程式的其他地方完成，只要 SRB 在 SRB 結構 TimeOutValue 欄位中指定的逾時之前完成。

言論

HwStorBuildIo 的名稱只是 HW_INITIALIZATION_DATA 結構中 HwBuildIo 成員所指向的迷你埠函式佔位符。此例程的實際原型定義於 storport.h ，如下所示：

typedef
BOOLEAN
HW_BUILDIO (
  _In_ PVOID DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

埠驅動程式會在 DISPATCH IRQL 呼叫 HwStorBuildIo 例程，而不需要保留任何微調鎖定。因此，HwStorBuildIo允許 透過 storPortAcquireSpinLock使用 storPortAllocatePool 和相互排除的記憶體配置。在多處理器環境中，一次可以使用多個 HwStorBuildIo，因此小型埠驅動程式必須同步處理系統資源的存取權，如果一個以上的 HwStorBuildIo 實例在任何指定時間都處於作用中狀態，則可能處於爭用狀態。

透過完成 HwStorBuildIo 中耗時的 I/O 設定活動，而不是在 HwStorStartIo中，迷你埠驅動程式可啟用更高的 I/O 並行，因而改善 I/O 輸送量。為了達到最高效能，迷你埠驅動程序應該在 HwStorBuildIo 盡可能進行前置處理，以便盡可能短的時間透過 HwStorStartIo 將要求傳送至 HBA。預先處理的數據和狀態可以儲存在 DeviceExtension 或 SrbExtension 結構中。只有修改 DeviceExtension 的唯一部分，因為不會保留鎖定。 HwStorBuildIo 和 HwStorStartIo 會收到下列 Srb 函式類型：

SRB_FUNCTION_EXECUTE_SCSI：將CDB傳送至指定的總線/目標/lun。
- Srb->DataTransferLength 適用於所有 Cdbs。
- Srb->DataBuffer 會針對讀取和寫入要求 NULL。若要存取相關聯的數據，請使用 StorPortGetScatterGatherList 或 StorPortGetSystemAddress （適用於程式控制 I/O）來取得散佈收集清單或緩衝區的虛擬位址。對於其他要求，Srb->Databuffer 會指向與 Srb 相關聯的數據。
- Srb->PathId 有效，代表指定給 Storport StorPortNotification （BusChange）中的 pathid。迷你埠驅動程式的寫入器需要使用 pathid 作為迷你埠內總線數據表的索引。
- Srb->TargetId 和 Srb->Lun 有效。
SRB_FUNCTION_IO_CONTROL：已定義迷你埠。
- Srb->DataTransferLength 和 Srb->DataBuffer 在要求者設定時有效。
- Srb->PathId、Srb->TargetId 和 Srb->Lun 都是有效的。
SRB_FUNCTION_RESET_LOGICAL_UNIT：重設指定的邏輯單元（如果裝置已啟用）。
- Srb->DataTransferLength 和 Srb->DataBuffer 無效。
- Srb->PathId、Srb->TargetId 和 Srb->Lun 都是有效的。
SRB_FUNCTION_RESET_DEVICE：重設指定的 Scsi 目標。
- Srb->DataTransferLength 和 Srb->DataBuffer、Srb->Lun 無效。
- Srb->PathId 和 Srb->TargetId 有效。
SRB_FUNCTION_RESET_BUS：重設指定 SCSI 總線上的所有目標。
- 只有 Srb->PathId 有效。
SRB_FUNCTION_FLUSH：指示迷你埠驅動程式排清所有快取的數據。
- 只有在迷你埠驅動程式在 PORT_CONFIGURATION_INFORMATION 結構中設定 CachesData == TRUE 時才執行。
- Srb->PathId、Srb->TargetId 和 Srb->Lun 都是有效的。
SRB_FUNCTION_SHUTDOWN：指示迷你埠驅動程式排清所有準備關閉的快取數據。
- 只有在迷你埠驅動程式在 PORT_CONFIGURATION_INFORMATION 結構中設定 CachesData == TRUE 時才執行。
- Srb->PathId、Srb->TargetId 和 Srb->Lun 都是有效的。
SRB_FUNCTION_DUMP_POINTERS：提供迷你埠驅動程序支援損毀傾印和休眠所需的資訊。
- 此要求會傳送至 Storport 虛擬迷你埠驅動程式，用來控制保存損毀傾印數據的磁碟。從 Windows 8 開始，非虛擬迷你埠驅動程式可以選擇性地接收此要求。
- Srb->PathId、Srb->TargetId 和 Srb->Lun 都是有效的。
SRB_FUNCTION_FREE_DUMP_POINTERS：從 Windows 8 開始，此要求會傳送至迷你埠，以釋放在SRB_FUNCTION_DUMP_POINTERS要求期間配置的資源。
- Srb->PathId、Srb->TargetId 和 Srb->Lun 都是有效的。

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

如需此迷你埠驅動程式例程中可以和無法安全地執行之動作的詳細資訊，請參閱 Unsynchronized HwStorBuildIo 例程。

例子

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

例如，若要定義名為 MyHwBuildIo的 HwStorBuildIo 回呼例程，請使用 HW_BUILDIO 類型，如下列程式代碼範例所示：

HW_BUILDIO MyHwBuildIo;

然後，實作回呼例程，如下所示：

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

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