HW_BUILDIO回呼函式 (storport.h)

發行項
02/26/2024

HwStorBuildIo 例程會在將共用系統數據結構傳遞至 HwStorStartIo 之前，先使用未同步存取的 SRB 來處理 SRB。

語法

HW_BUILDIO HwBuildio;

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

參數

DeviceExtension

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

Srb

要處理的 SCSI 要求區塊指標 (SRB) 。

傳回值

如果 StorPort 認為 LUN 已準備好接收 I/O，HwStorBuildIo 會傳回 TRUE，通知呼叫者 StorPort 應該呼叫 HwStorStartIo 例程。 HwStorBuildIo 會傳回 FALSE ，通知呼叫端不應將 SRB 傳遞至 HwStorStartIo。在這種情況下，迷你埠驅動程序必須使用 RequestComplete 的通知類型呼叫 StorPortNotification 來完成 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 中允許使用 StorPortAllocatePool 和透過 StorPortAcquireSpinLock 進行相互排除的記憶體配置。在多處理器環境中，一次可以有一個以上的 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 (進行 Dma 傳輸) 或 StorPortGetSystemAddress (，讓程式控制的 I/O ) 取得散佈檔收集清單或緩衝區的虛擬位址。對於其他要求，Srb-Databuffer> 會指向與 Srb 相關聯的數據。
- Srb-PathId> 有效，代表 在 StorPortNotification 中提供給 Storport (BusChange) 的路徑標識符。迷你埠驅動程式的寫入器必須使用 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的詳細資訊，請參閱標註函式行為。