次の方法で共有


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

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

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

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

戻り値

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

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

注釈

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

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

こちらもご覧ください

AdapterControl

AllocateAdapterChannel

CancelAdapterChannel

DEVICE_OBJECT

DMA_ADAPTER

DMA_OPERATIONS

FlushAdapterBuffers

FlushAdapterBuffersEx

FreeAdapterObject

FreeMapRegisters

GetDmaTransferInfo

InitializeDmaTransferContext

IoGetDmaAdapter

MapTransferEx