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

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

構文

PBUILD_SCATTER_GATHER_LIST_EX PbuildScatterGatherListEx;

NTSTATUS PbuildScatterGatherListEx(
  [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]            PVOID ScatterGatherBuffer,
  [in]            ULONG ScatterGatherLength,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PVOID ScatterGatherList
)
{...}

パラメーター

[in] DmaAdapter

DMA_ADAPTER 構造体へのポインター。 この構造体は、ドライバーのバス マスター DMA デバイスまたはシステム 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 フラグが設定されている場合、ExecutionRoutine パラメーターは省略可能であり、NULLできます。 このフラグが設定されていない場合、ExecutionRoutine は、有効な非NULL ポインターである必要があります。 このフラグの詳細については、「解説」セクションを参照してください。

[in, optional] ExecutionRoutine

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

DMA_SYNCHRONOUS_CALLBACK フラグが設定されている場合、ExecutionRoutine は省略可能であり、NULLできます。 ExecutionRoutine が NULL場合、呼び出し元は BuildScatterGatherListExによって割り当てられたリソース 使用できます。 詳細については、「解説」セクションを参照してください。

[in, optional] Context

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

[in] WriteToDevice

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

[in] ScatterGatherBuffer

DMA 転送の散布図/収集リストをルーチンが書き込む呼び出し元によって割り当てられたバッファーへのポインター。 このリストは、SCATTER_GATHER_LIST 構造体から始まり、その後に SCATTER_GATHER_ELEMENT 配列が続きます。

[in] ScatterGatherLength

ScatterGatherBuffer パラメーターで渡されるバッファーのサイズ (バイト単位)。 割り当てられたバッファー サイズは、散布図/収集リストと、オペレーティング システムがこのバッファーに格納する内部データを格納するのに十分な大きさである必要があります。 必要なバッファー サイズを計算するには、GetDmaTransferInfo を呼び出すか、CalculateScatterGatherList ルーチン します。

[in, optional] DmaCompletionRoutine

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

[in, optional] CompletionContext

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

[out, optional] ScatterGatherList

DMA 転送の散布図/収集リストへのポインターをルーチンが書き込む変数へのポインター。 このリストは、SCATTER_GATHER_ELEMENT 配列へのポインターを含む SCATTER_GATHER_LIST 構造体で始まります。 この出力ポインターは常に、ScatterGatherBuffer パラメーター値と一致します。

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

戻り値

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

備考

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

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

BuildScatterGatherListEx は、GetScatterGatherListEx ルーチンに似ていますが、呼び出し元が散布図/収集リストのバッファーを割り当てる必要がある点が異なります。

たとえば、ドライバーは、デバイスの初期化中に 1 つ以上の散布図/収集バッファーを事前に割り当て可能性があります。 その後、このようなバッファーを使用する BuildScatterGatherListEx 呼び出しは、GetScatterGatherListEx 呼び出しが失敗する可能性があるメモリの可用性が低い状況で成功する可能性があります。

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

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

• 要求されたリソースがすぐに使用できない場合、BuildScatterGatherListEx はリソースを待機せず、散布図/収集リストを作成せず、AdapterListControl ルーチンを呼び出しません。 代わりに、BuildScatterGatherListEx 失敗し、STATUS_INSUFFICIENT_RESOURCESを返します。

• DMA_SYNCHRONOUS_CALLBACK フラグが設定されている場合、ドライバーは AdapterListControl ルーチンを指定する必要はありません。

• ドライバーが AdapterListControl ルーチンを提供する場合、DMA_SYNCHRONOUS_CALLBACK フラグは、呼び出し元のスレッドのコンテキストでこのルーチンが呼び出されることを示 BuildScatterGatherListEx が返されます。

• ドライバーが AdapterListControl ルーチンを提供しない場合、ドライバーは、BuildScatterGatherListEx が返された後、割り当てられたリソースと散布図/収集リスト 使用できます。 この場合、ドライバーは、有効な非NULLScatterGatherList ポインターを指定する必要があります。 さらに、ドライバーによって開始された DMA 転送が完了した後、ドライバーは、FreeAdapterObject ルーチンを呼び出して、BuildScatterGatherListEx アダプター オブジェクトに割り当てられたリソース 解放する必要があります。

BuildScatterGatherListEx は、BuildScatterGatherList ルーチンの拡張バージョンです。 次の一覧は、拡張バージョンでのみ使用できる機能をまとめたものです。

必要条件

関連項目

AdapterListControl

AllocateAdapterChannelEx の

CalculateScatterGatherList の

DMA_OPERATIONS

DmaCompletionRoutine

FreeAdapterObject を する

GetScatterGatherList を する

GetScatterGatherListEx を する

MapTransferEx