PGET_SCATTER_GATHER_LIST コールバック関数 (wdm.h)
GetScatterGatherList ルーチンは、システム DMA コントローラーまたはバス マスター アダプターを介して、ターゲット デバイス オブジェクトに代わって DMA 散布/収集操作のためにシステムを準備します。
構文
PGET_SCATTER_GATHER_LIST PgetScatterGatherList;
NTSTATUS PgetScatterGatherList(
[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] DmaAdapter
バス マスター アダプターまたは DMA コントローラーを表す IoGetDmaAdapter によって返されるDMA_ADAPTER構造体へのポインター。
[in] DeviceObject
DMA 操作のターゲット デバイスを表すデバイス オブジェクトへのポインター。
[in] Mdl
現在の IRP の MdlAddress にあるバッファーを記述する MDL へのポインター。
[in] CurrentVa
DMA 転送操作にマップされるバッファーの MDL 内の現在の仮想アドレスへのポインター。
[in] Length
マップする長さをバイト単位で指定します。
[in] ExecutionRoutine
システム DMA コントローラーまたはバス マスター アダプターが使用可能な場合にDISPATCH_LEVELで呼び出される、ドライバー提供の AdapterListControl ルーチンへのポインター。
[in] Context
ドライバーが呼び出されたときにドライバーの AdapterListControl ルーチンに渡されるドライバーによって決定されたコンテキストへのポインター。
[in] WriteToDevice
DMA 転送の方向を示します。バッファーからデバイスへの転送の 場合は TRUE 、それ以外の場合は FALSE 。
戻り値
このルーチンは、次のいずれかの NTSTATUS 値を返すことができます。
| リターン コード | 説明 |
|---|---|
|
操作が成功しました。 |
|
ルーチンで十分なメモリを割り当てられなかったか、転送に必要なマップ レジスタの数が IoGetDmaAdapter によって返される値より大きい。 |
|
バッファーが、要求された転送に対して小さすぎます。 |
注釈
GetScatterGatherList ルーチンは、散布/収集リストを保持するバッファーを動的に割り当てます。 バッファーの割り当てが失敗した場合に考えられる NTSTATUS 値については、戻り値を参照してください。
GetScatterGatherList は、名前で直接呼び出すことができるシステム ルーチンではありません。 このルーチンは、 DMA_OPERATIONS 構造体で返されるアドレスからのポインターによってのみ呼び出されます。 ドライバーは、 IoGetDmaAdapter を呼び出して、このルーチンのアドレスを取得します。
適切な DMA チャネルと必要なマップ レジスタが使用可能になるとすぐに、 GetScatterGatherList は散布図/収集リストを作成し、マップ レジスタを初期化してから、ドライバーが提供する AdapterListControl ルーチンを呼び出して I/O 操作を実行します。
GetScatterGatherList は 、分散/収集 DMA を実行するドライバーの AllocateAdapterChannel ルーチンと MapTransfer ルーチンのアクションを組み合わせます。 GetScatterGatherList は、転送に必要なマップ レジスタの数を決定し、マップ レジスタを割り当て、DMA のバッファーをマップして、散布図/収集リストに入力します。 その後、指定された AdapterListControl ルーチンを呼び出し、 ScatterGather の散布/収集リストへのポインターを渡します。 ドライバーは 、PutScatterGatherList を呼び出すときに使用するために、このポインターを保持する必要があります。 GetScatterGatherList には、AllocateAdapterChannel に適用されるキュー制限はありません。
AdapterListControl ルーチンでは、ドライバーは I/O を実行する必要があります。 ドライバーが指定したルーチンから返されると、 GetScatterGatherList はマップ レジスタを保持しますが、DMA アダプター構造を解放します。 ドライバーは、バッファー内のデータにアクセスする前に 、PutScatterGatherList (バッファーをフラッシュする) を呼び出す必要があります。
このルーチンは、すべてのチェーンされた MDL で必要なマップ レジスタの合計数が、使用可能なマップ レジスタの数を超えていない場合に、チェーンされた MCL を処理できます。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 以降のバージョンの Windows で使用できます。 Windows 98 または Windows Me ではサポートされていません。 |
| 対象プラットフォーム | デスクトップ |
| Header | wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む) |
| IRQL | DISPATCH_LEVEL |
| DDI コンプライアンス規則 | IrqlDispatch(storport)、IrqlDispatch(storport)、 IrqlDispatch(wdm) |