PALLOCATE_ADAPTER_CHANNEL コールバック関数 (wdm.h)
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 値のいずれかを返すことができます。
| リターン コード | 説明 |
|---|---|
|
アダプター チャネルが割り当てられています。 DMA 操作を開始すると、システムは AdapterControl ルーチンを呼び出します。 |
|
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) |