IoGetDmaAdapter 関数 (wdm.h)
IoGetDmaAdapter ルーチンは、物理デバイス オブジェクトの DMA アダプター構造体へのポインターを返します。
構文
_DMA_ADAPTER * IoGetDmaAdapter(
[in, optional] PDEVICE_OBJECT PhysicalDeviceObject,
[in] _DEVICE_DESCRIPTION *DeviceDescription,
[out] PULONG NumberOfMapRegisters
);
パラメーター
[in, optional] PhysicalDeviceObject
DMA アダプター構造を要求するデバイスの物理デバイス オブジェクトへのポインター。
[in] DeviceDescription
物理デバイスの属性を記述する DEVICE_DESCRIPTION 構造体へのポインター。 DEVICE_DESCRIPTION構造体のバージョン セットに関係なく、この関数は常に を返します DMA_ADAPTER->Version == 1。
[out] NumberOfMapRegisters
ドライバーが DMA 転送操作に割り当てることができるマップ レジスタの最大数を出力時に指すポインター。
戻り値
IoGetDmaAdapter は、システム定義 DMA 操作をサポートする関数へのポインターを含む DMA_ADAPTER 構造体へのポインターを返します。 構造体を割り当てることができない場合、ルーチンは NULL を返します。 DeviceDescription パラメーターの説明については、上記のバージョン コメントを参照してください。
注釈
このルーチンを呼び出す前に、ドライバーは DeviceDescription が指すDEVICE_DESCRIPTION構造体をゼロ初期化し、そのデバイスの関連情報をこの構造体に追加する必要があります。
成功した場合、ルーチンの戻り値は DMA_ADAPTER 構造体を指します。 この構造体には、 DMA_OPERATIONS 構造体へのポインターが含まれています。これは、ドライバーが DMA 操作を実行するために後で使用できる関数へのポインターのテーブルです。 ルーチンが返すこの構造体のバージョンは、次のように決定されます。
ドライバーがDEVICE_DESCRIPTION構造体の Version メンバーを DEVICE_DESCRIPTION_VERSION またはDEVICE_DESCRIPTION_VERSION1に設定した場合、返される DMA_ADAPTER 構造体は 、DMA_OPERATIONS 構造体のバージョン 1 を指します。
ドライバーが Version = DEVICE_DESCRIPTION_VERSION2を設定した場合、 返されるDMA_ADAPTER 構造体は、バージョン 2 がサポートされている場合 、DMA_OPERATIONS 構造体のバージョン 2 を指します。それ以外の場合、ルーチンは NULL を返します。 ドライバーは、バージョン 2 関数を使用する前に、バージョン 2 がサポートされているかどうかを確認するためにチェックする必要があります。
ドライバーが Version = DEVICE_DESCRIPTION_VERSION3を設定した場合、 返されるDMA_ADAPTER 構造体は、バージョン 3 がサポートされている場合 、DMA_OPERATIONS 構造体のバージョン 3 を指します。それ以外の場合、ルーチンは NULL を返します。 ドライバーは、バージョン 3 関数を使用する前に、バージョン 3 がサポートされているかどうかを確認するためにチェックする必要があります。 バージョン 3 は、Windows 8 以降でサポートされています。
PnP ドライバーは、AddDevice ルーチンが呼び出されたとき、またはデバイスの PnP IRP_MN_START_DEVICE要求を処理するときに IoGetDmaAdapter を呼び出します。 この IRP には、ドライバーが DeviceDescription 構造体で指定する必要があるデバイスのハードウェア リソースに関する情報が含まれています。
呼び出し元は、DeviceDescription 構造体の MaximumLength メンバーを使用して、使用できるマップ レジスタの最適な数を示します。 I/O マネージャーは、この最大サイズの DMA 転送操作に対応するために十分なマップ レジスタの割り当てを試みます。 出力時に、I/O マネージャーは NumberOfMapRegisters パラメーターで、割り当てるマップ レジスタの数を返します。 ドライバーは、戻り値をチェックする必要があります。ドライバーが要求したマップ レジスタの数と同じ数を受け取る保証はありません。
アダプター オブジェクトを解放するには、ドライバーは、DMA_ADAPTER構造体で返されたポインターを介して PutDmaAdapter を呼び出す必要があります。
前述のように、IoGetDmaAdapter は、DeviceDescription-Version> で指定されたDMA_ADAPTER構造のバージョンをサポートしていない場合、NULL を返します。 呼び出し元は、ルーチンが要求されたバージョンの DMA_ADAPTER 構造体へのポインターを返すかどうかを判断するために、この動作に依存する必要があります。 IoGetDmaAdapter がDMA_ADAPTER構造体のバージョン 1 またはバージョン 2 またはバージョン 3 へのポインターを返す場合、この構造体の Version メンバーは常に 1 に設定されます。 したがって、呼び出し元は、返されたDMA_ADAPTER構造体の Version メンバーを使用して、この構造体のバージョン 1、2、および 3 を区別できません。
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| Header | wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI コンプライアンス規則 | HwStorPortProhibitedDDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm) |