PBUILD_SCATTER_GATHER_LIST コールバック関数 (wdm.h)

[アーティクル]
02/27/2024

BuildScatterGatherList ルーチンは、ドライバーが提供するバッファーを使用して分散/収集リストを構築して、DMA 操作用にシステムを準備します。

構文

PBUILD_SCATTER_GATHER_LIST PbuildScatterGatherList;

NTSTATUS PbuildScatterGatherList(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PMDL Mdl,
  [in] PVOID CurrentVa,
  [in] ULONG Length,
  [in] PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in] PVOID Context,
  [in] BOOLEAN WriteToDevice,
  [in] PVOID ScatterGatherBuffer,
  [in] ULONG ScatterGatherLength
)
{...}

パラメーター

[in] DmaAdapter

バスマスターアダプターまたは DMA コントローラーを表す IoGetDmaAdapter によって返されるDMA_ADAPTER構造体へのポインター。

[in] DeviceObject

DMA 操作のターゲットデバイスを表すデバイスオブジェクトへのポインター。

[in] Mdl

現在の IRP の MdlAddress メンバーによって指定されたバッファーを記述する MDL へのポインター。

[in] CurrentVa

DMA 転送操作にマップされるバッファーの MDL 内の現在の仮想アドレスへのポインター。

[in] Length

マップするバッファーの長さをバイト単位で指定します。

[in] ExecutionRoutine

システム DMA コントローラーまたはバスマスターアダプターが使用可能な場合に IRQL = DISPATCH_LEVELで呼び出される、ドライバー提供の AdapterListControl ルーチンへのポインター。

[in] Context

呼び出されたときに ExecutionRoutine に渡されるドライバーによって決定されたコンテキストへのポインター。

[in] WriteToDevice

DMA 転送の方向を示します。バッファーからデバイスへの転送の 場合は TRUE 、それ以外の場合は FALSE 。

[in] ScatterGatherBuffer

ルーチンが SCATTER_GATHER_LIST 構造体で埋める呼び出し元が指定したバッファーへのポインター。

[in] ScatterGatherLength

ScatterGatherBuffer パラメーターで渡されるバッファーのサイズをバイト単位で指定します。

戻り値

BuildScatterGatherList は 、次のいずれかの値を返します。

リターンコード	説明
STATUS_SUCCESS	操作は正常に完了しました。
STATUS_INSUFFICIENT_RESOURCES	転送に使用できるマップレジスタが不足しています。
STATUS_BUFFER_TOO_SMALL	指定した Length が大きすぎてバッファー内に収まりません。

注釈

BuildScatterGatherList は、名前で直接呼び出すことができるシステムルーチンではありません。このルーチンは、 DMA_OPERATIONS 構造体で返されるアドレスからのポインターによってのみ呼び出すことができます。ドライバーは、DeviceDescription パラメーターの Version メンバーをDEVICE_DESCRIPTION_VERSION2に設定して IoGetDmaAdapter を呼び出すことによって、このルーチンのアドレスを取得します。 IoGetDmaAdapter が NULL を返す場合、このルーチンはプラットフォームでは使用できません。

BuildScatterGatherList は GetScatterGatherList と同じ操作を実行しますが、 ScatterGatherBuffer パラメーターで指定されたバッファーを使用して、作成する散布/収集リストを保持します。これに対し、 GetScatterGatherList は、散布/収集リストを保持するバッファーを動的に割り当てます。バッファーの割り当てに十分なメモリが不足している場合、 GetScatterGatherList はSTATUS_INSUFFICIENT_RESOURCES エラーで失敗する可能性があります。このシナリオを回避する必要があるドライバーは、分散/収集リストを保持するバッファーを事前に割り当て、代わりに BuildScatterGatherList を 使用できます。

ドライバーは CalculateScatterGatherList ルーチンを使用して、分散/収集リストを保持するために割り当てるバッファーのサイズを決定できます。

ドライバーは、ドライバーが PutScatterGatherList を呼び出すときに使用するために、ScatterGatherBuffer の散布/収集リストへのポインターを保持する必要があります。ドライバーは、リスト内のデータにアクセスする前に 、PutScatterGatherList (リストをフラッシュする) を呼び出す必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows XP 以降のバージョンの Windows で使用できます。
対象プラットフォーム	デスクトップ
Header	wdm.h (Wdm.h を含む)
IRQL	DISPATCH_LEVEL
DDI コンプライアンス規則	IrqlDispatch(wdm)