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

[アーティクル]
03/08/2023

GetScatterGatherListEx ルーチンは、DMA 転送に必要なリソースを割り当て、散布図/収集リストを作成し、ドライバー提供の AdapterListControl ルーチンを呼び出して DMA 転送を開始します。

注意事項

システム DMA デバイスに対してこのルーチンを呼び出さないでください。

構文

PGET_SCATTER_GATHER_LIST_EX PgetScatterGatherListEx;

NTSTATUS PgetScatterGatherListEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            PMDL Mdl,
  [in]            ULONGLONG Offset,
  [in]            ULONG Length,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in, optional]  PVOID Context,
  [in]            BOOLEAN WriteToDevice,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PSCATTER_GATHER_LIST *ScatterGatherList
)
{...}

パラメーター

[in] DmaAdapter

DMA_ADAPTER構造体へのポインター。この構造体は、ドライバーのバスマスター DMA デバイスを表すアダプターオブジェクトです。呼び出し元は、 IoGetDmaAdapter ルーチンの以前の呼び出しからこのポインターを取得しました。

[in] DeviceObject

DEVICE_OBJECT構造体へのポインター。この構造体は、要求された DMA 操作のターゲットデバイスを表す物理デバイスオブジェクト (PDO) です。

[in] DmaTransferContext

初期化された DMA 転送コンテキストへのポインター。このコンテキストは、 InitializeDmaTransferContext ルーチンの以前の呼び出しによって初期化されました。このコンテキストは、すべてのアダプター割り当て要求で一意である必要があります。保留中の割り当て要求を取り消すには、呼び出し元が要求の DMA 転送コンテキストを CancelAdapterChannel ルーチンに提供する必要があります。

[in] Mdl

仮想メモリ内のロックダウンバッファーのコレクションの物理ページレイアウトを記述する MDL チェーンへのポインター。 DMA 転送の散布/収集リストでは、 Offset パラメーターと Length パラメーターで指定されたこのメモリの領域が使用されます。 MDL チェーンの詳細については、「 MDL の使用」を参照してください。

[in] Offset

スキャッター/ギャザー DMA 転送の開始オフセット。このパラメーターは、MDL チェーン内の最初の MDL 内のバッファーの先頭からのバイトオフセットです。 MDL チェーン内の MDL でバッファー領域の合計 N バイトを指定した場合、 Offset の有効な値は 0 から N から 1 の範囲になります。

[in] Length

DMA 転送の長さ (バイト単位)。 MDL チェーンがバッファー領域の N バイトの合計を指定する場合、有効な値 の長さは 1 ~ N オフセットの範囲です。

[in] Flags

アダプターチャネル割り当てフラグ。次のフラグがサポートされています。

フラグ	説明
DMA_SYNCHRONOUS_CALLBACK	GetScatterGatherListEx ルーチンは同期的に呼び出されます。このフラグが設定され、必要な DMA リソースがすぐに使用できない場合、呼び出しは失敗し、STATUS_INSUFFICIENT_RESOURCESを返します。

DMA_SYNCHRONOUS_CALLBACK フラグが設定されている場合、ExecutionRoutine パラメーターは省略可能であり、NULL にすることができます。このフラグが設定されていない場合、 ExecutionRoutine は有効な NULL 以外のポインターである必要があります。このフラグの詳細については、「解説」セクションを参照してください。

[in, optional] ExecutionRoutine

ドライバーの DMA 転送を開始するドライバー指定の AdapterListControl ルーチンへのポインター。 I/O マネージャーは、アダプターオブジェクトに必要なリソースが割り当てられた後、 AdapterListControl ルーチンを呼び出します。 AdapterListControl ルーチンが戻った後、I/O マネージャーはアダプターオブジェクトと、このオブジェクトに割り当てられたリソースを自動的に解放します。

DMA_SYNCHRONOUS_CALLBACK フラグが設定されている場合、ExecutionRoutine パラメーターは省略可能であり、NULL にすることができます。このパラメーターが NULL の場合、呼び出し元は GetScatterGatherListEx によって割り当てられたリソースを使用して 、GetScatterGatherListEx が返された後に DMA 転送を実行できます。詳細については、「解説」を参照してください。

[in, optional] Context

ドライバーによって決定されたアダプター制御コンテキスト。このコンテキストは、Context パラメーターとして AdapterListControl ルーチンに渡されます。

[in] WriteToDevice

DMA 転送の方向。メモリからデバイスにデータを転送する書き込み操作では、このパラメーターを TRUE に設定します。デバイスからメモリにデータを転送する読み取り操作の場合は、このパラメーターを FALSE に設定します。

[in, optional] DmaCompletionRoutine

使用されていません。 NULL に設定します。

[in, optional] CompletionContext

使用されていません。 NULL に設定します。

[out, optional] ScatterGatherList

ルーチンが割り当てられた散布図/収集リストへのポインターを書き込む変数へのポインター。このパラメーターは 、SCATTER_GATHER_LIST 構造体を指します。ルーチンは、この構造体と、それが指す SCATTER_GATHER_ELEMENT 配列を割り当てます。

ScatterGatherList パラメーターは省略可能であり、ExecutionRoutine パラメーターが NULL 以外の場合は NULL にすることができます。

DMA_SYNCHRONOUS_CALLBACK フラグが設定され、ExecutionRoutine パラメーターが NULL の場合、ScatterGatherList は有効な NULL 以外のポインターである必要があります。 ExecutionRoutine が NULL 以外の場合、ScatterGatherList は省略可能であり、呼び出し元のドライバーが散布/収集リストを必要としない場合は NULL にすることができます。 getScatterGatherListEx 呼び出しは、DMA_SYNCHRONOUS_CALLBACK フラグが設定されていて、ScatterGatherList と ExecutionRoutine の両方が NULL であるか、DMA_SYNCHRONOUS_CALLBACK フラグが設定されておらず、ExecutionRoutine が NULL の場合に失敗します。

戻り値

GetScatterGatherListEx は、呼び出しが成功した場合にSTATUS_SUCCESSを返します。考えられるエラーの戻り値には、次の状態コードが含まれます。

リターンコード	説明
STATUS_INVALID_PARAMETERS	呼び出し元によって渡されたパラメーター値が無効であるため、ルーチンは失敗しました。
STATUS_INSUFFICIENT_RESOURCES	ルーチンは、DMA 転送に必要なリソースを割り当てませんでした。

注釈

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

GetScatterGatherListEx は、バスマスターアダプターに対してのみ使用します。システム DMA アダプターには、このルーチンを使用しないでください。

バスマスターデバイスのドライバーは 、GetScatterGatherListEx を 使用して、AllocateAdapterChannelEx ルーチンと MapTransferEx ルーチンによって実行される操作を 1 回の呼び出しに結合できます。 GetScatterGatherListEx は 、次の操作を実行します。

DMA 転送に必要なリソースを割り当てます。
Mdl、Offset、Length の各パラメーターの値に基づいて、散布図/収集リストを作成します。
ドライバー提供の AdapterListControl ルーチンを呼び出し、パラメーターとしてこのルーチンに散布/収集リストを提供します。

割り当てられたリソースは、 AdapterListControl ルーチンから戻った後に自動的に解放されます。 GetScatterGatherListEx が同期的に呼び出される場合 (つまり、DMA_SYNCHRONOUS_CALLBACK フラグが設定されている場合)、AdapterListControl ルーチンを省略できます。この場合、呼び出し元は割り当てられたリソースを使用して 、GetScatterGatherListEx が返された後に DMA 転送を開始します。呼び出し元は、これらのリソースを明示的に解放する必要があります。

既定では、 GetScatterGatherListEx は 、要求されたリソース割り当てが完了するのを待たずに非同期的に返します。この戻り後、呼び出し元は必要に応じて CancelAdapterChannel ルーチンを呼び出して保留中の割り当て要求を取り消すことができます。

呼び出し元のドライバーが DMA_SYNCHRONOUS_CALLBACK フラグを設定すると、 GetScatterGatherListEx ルーチンは次のように動作します。

要求されたリソースがすぐに使用できない場合、 GetScatterGatherListEx はリソースを待機せず、散布/収集リストを作成せず、 AdapterListControl ルーチンを呼び出しません。代わりに、 GetScatterGatherListEx は 失敗し、STATUS_INSUFFICIENT_RESOURCESを返します。
DMA_SYNCHRONOUS_CALLBACK フラグが設定されている場合、ドライバーは AdapterListControl ルーチンを指定する必要はありません。
ドライバーが AdapterListControl ルーチンを提供する場合、 DMA_SYNCHRONOUS_CALLBACK フラグは、 GetScatterGatherListEx が返される前に、呼び出し元のスレッドのコンテキストでこのルーチンが呼び出されることを示します。
ドライバーが AdapterListControl ルーチンを提供しない場合、 ドライバーは、GetScatterGatherListEx が返された後、割り当てられたリソースと散布/収集リストを使用できます。この場合、ドライバーは有効な NULL 以外の ScatterGatherList ポインターを 指定する必要があります。さらに、ドライバーが DMA 転送を開始した後、ドライバーは FreeAdapterObject ルーチンを呼び出して、アダプターオブジェクトに割り当てられた GetScatterGatherListEx リソースを解放する必要があります。

GetScatterGatherListEx は、 GetScatterGatherList ルーチンの拡張バージョンです。次の機能は、拡張バージョンでのみ使用できます。

GetScatterGatherListEx は BuildScatterGatherListEx ルーチンに似ていますが、 GetScatterGatherListEx によって 散布/収集リストのバッファーが自動的に割り当てられる点が異なっています。

要件

要件	値
サポートされている最小のクライアント	Windows 8 以降で使用できます。
対象プラットフォーム	デスクトップ
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
IRQL	<= DISPATCH_LEVEL