PBUILD_SCATTER_GATHER_LIST コールバック関数 (wdm.h)
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 | 指定した 長 が大きすぎてバッファー内に収まりません。 |
備考
BuildScatterGatherList は、名前で直接呼び出すことができるシステム ルーチンではありません。 このルーチンは、DMA_OPERATIONS 構造体で返されるアドレスからのポインターによってのみ呼び出すことができます。 ドライバーは、DeviceDescription パラメーター DEVICE_DESCRIPTION_VERSION2 に設定された Version メンバーを使用して IoGetDmaAdapter を呼び出すことによって、このルーチンのアドレスを取得します。 IoGetDmaAdapter が NULL 返す場合、このルーチンはプラットフォームでは使用できません。
BuildScatterGatherList は、GetScatterGatherList と同じ操作を実行します。ただし、ScatterGatherBuffer パラメーターで指定されたバッファーを使用して、作成する散布図/収集リストを保持します。 これに対し、GetScatterGatherList は、散布図/収集リストを保持するバッファーを動的に割り当てます。 バッファーの割り当てに使用できるメモリが不足している場合、GetScatterGatherList はSTATUS_INSUFFICIENT_RESOURCES エラーで失敗する可能性があります。 このシナリオを回避する必要があるドライバーは、散布図/収集リストを保持するバッファーを事前に割り当て、代わりに BuildScatterGatherList 使用できます。
ドライバーは、CalculateScatterGatherList ルーチンを使用して、散布図/収集リストを保持するために割り当てるバッファーのサイズを決定できます。
ドライバーは、PutScatterGatherList を呼び出すときに使用するために、ScatterGatherBuffer の散布図/収集リストへのポインター保持する必要があります。 ドライバーは、呼び出す必要があります PutScatterGatherList (一覧をフラッシュ) 一覧内のデータにアクセスする前にします。
必要条件
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows XP 以降のバージョンの Windows で使用できます。 |
| ターゲット プラットフォーム の | デスクトップ |
| ヘッダー | wdm.h (Wdm.h を含む) |
| IRQL | DISPATCH_LEVEL |
| DDI コンプライアンス規則 を する | IrqlDispatch(wdm) |
関連項目
CalculateScatterGatherList の
GetScatterGatherList を する
IoGetDmaAdapter の
PutScatterGatherList を する