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

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

AllocateAdapterChannelEx ルーチンは、DMA 転送を実行するために必要なリソースを割り当て、ドライバー提供の AdapterControl ルーチンを呼び出して DMA 転送を開始します。

構文

PALLOCATE_ADAPTER_CHANNEL_EX PallocateAdapterChannelEx;

NTSTATUS PallocateAdapterChannelEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            ULONG NumberOfMapRegisters,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_CONTROL ExecutionRoutine,
  [in, optional]  PVOID ExecutionContext,
  [out, optional] PVOID *MapRegisterBase
)
{...}

パラメーター

[in] DmaAdapter

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

[in] DeviceObject

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

[in] DmaTransferContext

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

[in] NumberOfMapRegisters

DMA 転送で使用するマップレジスタの数。呼び出し元のドライバーは、現在の転送要求を満たすために必要なマップレジスタの数と使用可能なマップレジスタの数の小さい方にこの値を設定する必要があります。ドライバーは、転送に必要なマップレジスタの数を取得するために GetDmaTransferInfo ルーチンを呼び出し、使用可能なマップレジスタの数を取得するために IoGetDmaAdapter ルーチンを呼び出しました。

[in] Flags

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

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

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

[in, optional] ExecutionRoutine

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

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

[in, optional] ExecutionContext

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

[out, optional] MapRegisterBase

ルーチンが割り当てられたマップレジスタにハンドルを書き込む変数へのポインター。呼び出し元は、 FlushAdapterBuffersEx、 FlushAdapterBuffers、 FreeMapRegisters、または MapTransferEx ルーチンにパラメーターとしてこのハンドルを指定できます。

DMA_SYNCHRONOUS_CALLBACK フラグが設定されている場合、MapRegisterBase は有効な NULL 以外のポインターである必要があります。 ExecutionRoutine パラメーターが NULL 以外の場合、MapRegisterBase は NULL である必要があります。 MapRegisterBase が NULL 以外で、DMA_SYNCHRONOUS_CALLBACK フラグが設定されていない場合、または MapRegisterBase と ExecutionRoutine の両方が NULL の場合、呼び出しは失敗します。

戻り値

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

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

注釈

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

AllocateAdapterChannelEx は、DMA 操作を実行するために必要なリソースを割り当てます。これらのリソースには、DMA チャネルとマップレジスタが含まれます。 DMA アダプターで使用するために必要なすべてのリソースが割り当てられた後、 AllocateAdapterChannelEx は 呼び出し元から提供された AdapterControl ルーチンを呼び出して DMA 操作を開始します。

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

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

要求された DMA リソースがすぐに使用できない場合、 AllocateAdapterChannelEx はリソースを待機せず、 AdapterControl ルーチンを呼び出しません。代わりに、 AllocateAdapterChannelEx は失敗し、STATUS_INSUFFICIENT_RESOURCESを返します。
DMA_SYNCHRONOUS_CALLBACK フラグが設定されている場合、ドライバーは AdapterControl ルーチンを指定する必要はありません。
ドライバーが AdapterControl ルーチンを提供する場合、 DMA_SYNCHRONOUS_CALLBACK フラグは、 AllocateAdapterChannelEx が返される前に、呼び出し元のスレッドのコンテキストでこのルーチンが呼び出されることを示します。
ドライバーが AdapterControl ルーチンを提供しない場合、 ドライバーは AllocateAdapterChannelEx が返された後に割り当てられたリソースを使用できます。この場合、ドライバーは、割り当てられたリソースの使用が完了した後に FreeAdapterObject を呼び出す必要があります。

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

要件

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