IoGetDmaAdapter 関数 (wdm.h)

[アーティクル]
03/08/2024

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)