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

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

AllocateAdapterChannel ルーチンは、ターゲットデバイスオブジェクトに代わって DMA 操作用にシステムを準備し、ドライバー提供の AdapterControl ルーチンを呼び出して DMA 操作を実行します。

構文

PALLOCATE_ADAPTER_CHANNEL PallocateAdapterChannel;

NTSTATUS PallocateAdapterChannel(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] ULONG NumberOfMapRegisters,
  [in] PDRIVER_CONTROL ExecutionRoutine,
  [in] PVOID Context
)
{...}

パラメーター

[in] DmaAdapter

バスマスターアダプターまたは DMA コントローラーを表す IoGetDmaAdapter によって返されるDMA_ADAPTER構造体へのポインター。

[in] DeviceObject

要求された DMA 操作のターゲットデバイスを表すデバイスオブジェクトへのポインター。

[in] NumberOfMapRegisters

転送で使用するマップレジスタの数を指定します。この値は、現在の転送要求を満たすために必要なマップレジスタの数と、 IoGetDmaAdapter によって返される使用可能なマップレジスタの数の少ない値です。

[in] ExecutionRoutine

ドライバー提供の AdapterControl ルーチンへのポインター。このルーチンは、システム DMA コントローラーまたはバスマスターアダプターが使用可能になったときに呼び出されます。

[in] Context

AdapterControl ルーチンに渡されるドライバーによって決定されたコンテキストへのポインター。

戻り値

このルーチンは、次の NTSTATUS 値のいずれかを返すことができます。

リターンコード	説明
STATUS_SUCCESS	アダプターチャネルが割り当てられています。 DMA 操作を開始すると、システムは AdapterControl ルーチンを呼び出します。
STATUS_INSUFFICIENT_RESOURCES	NumberOfMapRegisters は、IoGetDmaAdapter によって返される値よりも大きくなります。 AdapterControl ルーチンは呼び出されません。

注釈

AllocateAdapterChannel は、名前で直接呼び出すことができるシステムルーチンではありません。このルーチンは、 DMA_OPERATIONS 構造体で返されたアドレスからのポインターによってのみ呼び出されます。ドライバーは、 IoGetDmaAdapter を呼び出して、このルーチンのアドレスを取得します。

ドライバーは、ドライバーの DMA 操作を実行する AdapterControl ルーチンを登録する AllocateAdapterControl ルーチンを呼び出します。 AdapterControl ルーチンは、システム DMA コントローラーまたはバスマスターアダプターを使用して DMA 操作を実行します。

DMA 操作をすぐに実行できる場合、システムは直ちに AdapterControl を呼び出します。システム DMA コントローラーまたはバスマスターアダプターが現在使用されている場合、 AllocateAdapterChannel はアダプターが使用可能になるまで AdapterControl をキューに入れます。どちらの場合も、 AllocateAdapterChannel は STATUS_SUCCESSを返します。

システムに DMA 操作を実行するためのリソースがない場合、 AllocateAdapterChannel はSTATUS_INSUFFICIENT_RESOURCESを返します。その場合、 AdapterControl はキューに登録されていないため、ドライバーは適切なエラーコード (STATUS_INSUFFICIENT_RESOURCES など) を使用して現在の IRP を完了する必要があります。

このルーチンは、DMA コントローラーチャネルへの排他アクセスを予約し、指定したデバイスの現在の IRP の転送要求を満たすために必要な 1 つ以上の DMA 操作のレジスタをマップします。

デバイスオブジェクトに対して一度にキューに登録できる DMA 要求は 1 つだけです。したがって、ドライバーは、AdapterControl ルーチンの実行が完了するまで、同じデバイスオブジェクトに対する別の DMA 操作に対して AllocateAdapterChannel をもう一度呼び出さないでください。さらに、ドライバーは、その AdapterControl ルーチン内から AllocateAdapterChannel を呼び出す必要があります。

システムは、DeviceObject の CurrentIrp メンバーの値を AdapterControl の Irp パラメーターとして渡します。ドライバーの StartIo ルーチンから AllocateAdapterChannel が呼び出された場合、これは StartIo が処理するために呼び出された IRP を指すと保証されます。それ以外の場合、AdapterControl の Irp パラメーターを使用するには、ドライバーは、AllocateAdapterChannel を呼び出す前に、現在の IRP を指す CurrentIrp を設定する必要があります。

要件

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