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

[アーティクル]
2025/02/07

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

構文

C++

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

ドライバーによって決定されたアダプター制御コンテキスト。このコンテキストは、コンテキスト パラメーターとして、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 以降で使用できます。
ターゲットプラットフォームの	デスクトップ
ヘッダー	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
IRQL	DISPATCH_LEVEL

次の方法で共有

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

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース