IoGetDmaAdapter 函数 (wdm.h)

项目
02/27/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_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)