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 を指します。
ドライバーがバージョン = DEVICE_DESCRIPTION_VERSION2 設定した場合、返される DMA_ADAPTER 構造体は、バージョン 2 がサポートされている場合、DMA_OPERATIONS 構造体のバージョン 2 を指します。それ以外の場合、ルーチンは NULL 返します。 ドライバーは、バージョン 2 の関数を使用する前に、バージョン 2 がサポートされているかどうかを確認する必要があります。
ドライバーが Version = DEVICE_DESCRIPTION_VERSION3 に設定した場合、バージョン 3 がサポートされている場合、返される DMA_ADAPTER 構造体は 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 を区別することはできません。
必要条件
| 要件 | 価値 |
|---|---|
| ターゲット プラットフォーム の | 万国 |
| ヘッダー | wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む) |
| ライブラリ | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI コンプライアンス規則 を する | HwStorPortProhibitedDDDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm) |
関連項目
AddDevice の
PutDmaAdapter を する