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_ADAPTER 结构的指针，该结构包含指向支持系统定义 DMA 操作的函数的指针。 如果无法分配结构，则例程返回 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 是否受支持。
如果驱动程序设置 版本 = DEVICE_DESCRIPTION_VERSION3，则返回 DMA_ADAPTER 结构指向版本 3 的 DMA_OPERATIONS 结构（如果支持版本 3）;否则，例程返回 NULL。 在尝试使用任何版本 3 函数之前，驱动程序必须检查以查看版本 3 是否受支持。 从 Windows 8 开始支持版本 3。
当调用其 AddDevice 例程或处理设备的 PnP IRP_MN_START_DEVICE请求时，PnP 驱动程序会调用 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） |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI 符合性规则 | HwStorPortProhibitedDDI (storport) 、 IrqlIoPassive5 (wdm) 、 PowerIrpDDis (wdm) |