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

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

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 値を返すことができます。

リターンコード	説明
STATUS_SUCCESS	操作が成功しました。
STATUS_INSUFFICIENT_RESOURCES	ルーチンで十分なメモリを割り当てられなかったか、転送に必要なマップレジスタの数が IoGetDmaAdapter によって返される値より大きい。
STATUS_BUFFER_TOO_SMALL	バッファーが、要求された転送に対して小さすぎます。

注釈

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)