StorPortBuildScatterGatherList 函式 (storport.h)

發行項
02/29/2024

StorPortBuildScatterGatherList 例程會為指定的數據緩衝區建立散佈/收集清單。

語法

ULONG StorPortBuildScatterGatherList(
  [in]      PVOID                        HwDeviceExtension,
  [in]      PVOID                        Mdl,
  [in]      PVOID                        CurrentVa,
  [in]      ULONG                        Length,
  [in]      PPOST_SCATTER_GATHER_EXECUTE ExecutionRoutine,
  [in]      PVOID                        Context,
  [in]      BOOLEAN                      WriteToDevice,
  [in, out] PVOID                        ScatterGatherBuffer,
  [in]      ULONG                        ScatterGatherBufferLength
);

參數

[in] HwDeviceExtension

主機總線適配卡的硬體裝置擴充功能指標， (HBA) 。

[in] Mdl

記憶體描述項清單的指標， (MDL) ，描述與數據緩衝區相關聯的記憶體頁面。

[in] CurrentVa

數據緩衝區的虛擬位址。

[in] Length

數據緩衝區的長度，以位元組為單位。

[in] ExecutionRoutine

迷你埠驅動程式提供的 ExecutionRoutine指標。 Storport 驅動程式會在建立散佈/收集清單之後呼叫此例程。迷你埠驅動程式應該執行在執行例程內使用散佈/收集清單的所有作業，而不是在呼叫 StorPortBuildScatterGatherList 例程的程式代碼中執行。

ExecutionRoutine 宣告如下：

VOID
ExecutionRoutine (
    IN PVOID  *DeviceObject,
    IN PVOID  *Irp,
    IN PSTOR_SCATTER_GATHER_LIST  ScatterGather,
    IN PVOID  Context
    );

DeviceObject

迷你埠驅動程序應該忽略此參數。

Irp

迷你埠驅動程序應該忽略此參數。

ScatterGather

包含指定數據緩衝區散佈/收集清單之STOR_SCATTER_GATHER_LIST 結構的指標。

Context

StorPortBuildScatterGatherList 函式的 Context 參數中指定的內容值。

Storport 驅動程式會在 IRQL = DISPATCH_LEVEL呼叫迷你埠驅動程序的執行 Routine 。

[in] Context

埠驅動程序傳遞至 ExecutionRoutine 參數中指定的執行例程的內容值。執行例程會使用此值來唯一識別要求。

[in] WriteToDevice

值，表示 DMA 傳輸的方向。 TRUE 值表示從數據緩衝區到裝置的傳輸，而 FALSE 值表示從裝置到數據緩衝區的傳輸。

[in, out] ScatterGatherBuffer

接收散佈/收集清單之迷你埠所提供緩衝區的指標。迷你埠驅動程式可以呼叫 StorPortAllocatePool 例程來配置此緩衝區的記憶體。

[in] ScatterGatherBufferLength

ScatterGatherBuffer 參數所指向之緩衝區的大小，以位元組為單位。

傳回值

StorPortBuildScatterGatherList 會傳回下列其中一個值：

傳回碼	Description
STOR_STATUS_NOT_IMPLEMENTED	此函式不會在作用中的操作系統上實作。
STOR_STATUS_SUCCESS	表示例程已成功建立散佈/收集清單。重要請參閱。
STOR_STATUS_INVALID_PARAMETER	傳遞的 HwDeviceExtension 為 NULL。
STOR_STATUS_INVALID_IRQL	呼叫是在無效的 IRQL 進行。
STOR_STATUS_INSUFFICIENT_RESOURCES	系統沒有足夠的地圖緩存器可供傳輸使用。
STOR_STATUS_BUFFER_TOO_SMALL	Length 參數太大而無法放入緩衝區內。

備註

迷你埠驅動程式會呼叫 StorPortPutScatterGatherList ，以釋放 StorPortBuildScatterGatherList 在建構散佈/收集清單時配置的資源。

迷你埠驅動程序必須先呼叫 StorPortPutScatterGatherList ，再釋放或重複使用配置給散佈/收集清單的記憶體。

注意如果 StorPortBuildScatterGatherList 傳回STOR_STATUS_SUCCESS， 則 ExecutionRoutine 中的回呼已成功排入佇列，以在建立散佈/收集清單之後執行。迷你埠不得假設已呼叫 ExecutionRoutine ，或當 StorPortBuildScatterGatherList 傳回時，散佈/收集清單已就緒。如有必要，迷你埠可以同步處理 StorPortBuildScatterGatherList 之後的程式代碼執行，以及 ExecutionRoutine 中的回呼，以確保散佈/收集清單可供使用。

規格需求

需求	值
目標平台	Universal
標頭	storport.h (包含 Storport.h)
IRQL	DISPATCH_LEVEL

另請參閱

STOR_SCATTER_GATHER_LIST

StorPortAllocatePool

StorPortPutScatterGatherList

共用方式為