(wdm.h) DEVICE_DESCRIPTION 结构

项目
02/27/2024

DEVICE_DESCRIPTION结构描述了驱动程序为其请求 DMA 适配器的物理设备的属性。

语法

typedef struct _DEVICE_DESCRIPTION {
  ULONG            Version;
  BOOLEAN          Master;
  BOOLEAN          ScatterGather;
  BOOLEAN          DemandMode;
  BOOLEAN          AutoInitialize;
  BOOLEAN          Dma32BitAddresses;
  BOOLEAN          IgnoreCount;
  BOOLEAN          Reserved1;
  BOOLEAN          Dma64BitAddresses;
  ULONG            BusNumber;
  ULONG            DmaChannel;
  INTERFACE_TYPE   InterfaceType;
  DMA_WIDTH        DmaWidth;
  DMA_SPEED        DmaSpeed;
  ULONG            MaximumLength;
  ULONG            DmaPort;
  ULONG            DmaAddressWidth;
  ULONG            DmaControllerInstance;
  ULONG            DmaRequestLine;
  PHYSICAL_ADDRESS DeviceAddress;
} DEVICE_DESCRIPTION, *PDEVICE_DESCRIPTION;

成员

Version

此结构的版本。传递给 IoGetDmaAdapter 例程的 DEVICE_DESCRIPTION 结构的 Version 成员确定此例程返回DMA_ADAPTER结构的哪个版本。下面是 Version 成员和相应 DMA_ADAPTER 版本的可能值的列表：

DEVICE_DESCRIPTION_VERSION

如果版本 = DEVICE_DESCRIPTION_VERSION，IoGetDmaAdapter 将忽略 IgnoreCount 成员，并返回DMA_ADAPTER结构的版本 1。

DEVICE_DESCRIPTION_VERSION1

如果版本 = DEVICE_DESCRIPTION_VERSION1，IoGetDmaAdapter 将使用 IgnoreCount 成员，并返回DMA_ADAPTER结构的版本 1。

DEVICE_DESCRIPTION_VERSION2

如果版本 = DEVICE_DESCRIPTION_VERSION2，IoGetDmaAdapter 使用 IgnoreCount 成员，并返回版本 2 的DMA_ADAPTER结构。版本 2 从 Windows XP 开始可用。

DEVICE_DESCRIPTION_VERSION3

如果版本 = DEVICE_DESCRIPTION_VERSION3，IoGetDmaAdapter 使用 IgnoreCount 成员，并返回DMA_ADAPTER结构的版本 3。版本 3 从Windows 8开始可用。

Master

设备是否为总线主 DMA 设备。如果设备是总线主 DMA 设备，则设置为 TRUE 。如果它是从属 DMA 设备，则将其设置为 FALSE 。

ScatterGather

对于总线主 DMA 设备，此成员指示设备是否支持散点/收集 DMA。如果设备可以执行散点/收集 DMA，则设置为 TRUE 。否则，将此成员设置为 FALSE。

对于从属 DMA 设备，不使用 ScatterGather 值。相反， IoGetDmaAdapter 假定从属 DMA 设备的散点/收集功能与设备连接到的基础系统 DMA 控制器的功能相同。

DemandMode

仅当版本 DEVICE_DESCRIPTION_VERSION2时才使用此成员。

对于从属 DMA 设备，此成员指示是否使用系统 DMA 控制器的需求模式。设置为 TRUE 以使用需求模式。否则，将此成员设置为 FALSE。

对于总线主 DMA 设备，不使用 DemandMode 值。

如果版本 DEVICE_DESCRIPTION_VERSION、DEVICE_DESCRIPTION_VERSION1或DEVICE_DESCRIPTION_VERSION3，则不使用 DemandMode 值。

AutoInitialize

对于从属 DMA 设备，此成员指示是否使用系统 DMA 控制器的自动初始化模式。设置为 TRUE 以使用自动初始化模式。否则，将此成员设置为 FALSE。

对于总线主 DMA 设备，不使用 AutoInitialize 值。

Dma32BitAddresses

仅当版本 DEVICE_DESCRIPTION_VERSION、DEVICE_DESCRIPTION_VERSION1或DEVICE_DESCRIPTION_VERSION2时才使用此成员。

Dma32BitAddresses 指定设备是否可以对 DMA 操作使用完整的 32 位地址。如果设备支持 32 位地址，则设置为 TRUE 。否则，将此成员设置为 FALSE。

如果 Version = DEVICE_DESCRIPTION_VERSION3，则不使用 Dma32BitAddresses 值。

IgnoreCount

是否忽略 DMA 控制器的传输计数器。如果此平台中的 DMA 控制器不维护准确的传输计数器，因此需要解决方法，则设置为 TRUE 。否则，将此成员设置为 FALSE。

如果 Version = DEVICE_DESCRIPTION_VERSION，则不使用 IgnoreCount 值。

有关详细信息，请参见“备注”部分。

Reserved1

预留给系统使用。必须为 FALSE。

Dma64BitAddresses

仅当版本 DEVICE_DESCRIPTION_VERSION、DEVICE_DESCRIPTION_VERSION1或DEVICE_DESCRIPTION_VERSION2时才使用此成员。

Dma64BitAddresses 指定设备是否可以对 DMA 操作使用完整的 64 位地址。如果设备支持 64 位地址，则设置为 TRUE 。否则，将此成员设置为 FALSE。

如果 Version = DEVICE_DESCRIPTION_VERSION3，则不使用 Dma64BitAddresses 值。

BusNumber

系统为 I/O 总线分配的总线编号。 WDM 驱动程序不使用此成员。

DmaChannel

从属设备分配到的 DMA 通道的编号。设备驱动程序从启动设备的 IRP_MN_START_DEVICE 请求中收到的资源列表中获取此通道号。有关此数字的详细信息，请参阅 CM_PARTIAL_RESOURCE_DESCRIPTOR 中 Dma.Channel 成员的说明。

InterfaceType

用于 DMA 的 I/O 总线的接口类型。将此成员设置为指示接口类型的 INTERFACE_TYPE 枚举值。有关详细信息，请参见“备注”部分。

DmaWidth

对于从属 DMA 设备，此成员指定系统 DMA 控制器传输的 DMA 数据宽度。可能的值为 Width8Bits、 Width16Bits、 Width32Bits 和 Width64Bits。

对于总线主 DMA 设备，不使用 DmaWidth 值。

DmaSpeed

仅当版本 DEVICE_DESCRIPTION_VERSION、DEVICE_DESCRIPTION_VERSION1或DEVICE_DESCRIPTION_VERSION2时才使用此成员。

对于从属 DMA 设备，此成员为系统 DMA 指定以下速度之一： Compatible、 TypeA、 TypeB、 TypeC 或 TypeF。

对于总线主 DMA 设备，不使用 DmaSpeed 值。

如果 Version = DEVICE_DESCRIPTION_VERSION3，则不使用 DmaSpeed 值。

MaximumLength

设备在使用分配的适配器对象的 DMA 操作中可以传输的最大字节数。

DmaPort

微通道类型的总线端口号。此参数已过时，但会保留在结构中，以便与旧驱动程序兼容。

DmaAddressWidth

仅当版本 = DEVICE_DESCRIPTION_VERSION3时才使用此成员。

对于总线主 DMA 设备， DmaAddressWidth 指定 DMA 地址的宽度（以位为单位）。 DmaAddressWidth 值必须是非零值，并且不能超过 64。如果内存地址宽度大于 DMA 地址宽度，则需要映射寄存器来访问超出 DMA 控制器地址范围的内存区域。

对于从属 DMA 设备，不使用 DmaAddressWidth 值。相反， IoGetDmaAdapter 假定从属 DMA 设备的地址宽度与设备连接到的基础系统 DMA 控制器的地址宽度相同。

DmaControllerInstance

未使用。

DmaRequestLine

仅当版本 = DEVICE_DESCRIPTION_VERSION3时才使用此成员。

对于从属 DMA 设备， DmaRequestLine 指定设备连接到的 DMA 控制器上的请求行。设备驱动程序从启动设备的 IRP_MN_START_DEVICE 请求中接收的资源列表中获取此请求行的编号。有关请求行号的详细信息，请参阅 CM_PARTIAL_RESOURCE_DESCRIPTOR 中的 u.DmaV3.RequestLine 成员的说明。

对于总线主 DMA 设备，不使用 DmaRequestLine 值。

DeviceAddress

仅当版本 = DEVICE_DESCRIPTION_VERSION3时才使用此成员。

对于从属 DMA 设备， DeviceAddress 是设备上的数据寄存器的内存映射地址，用作 DMA 传输的源或目标。此数据寄存器位于与设备启动地址已知的特定于设备的偏移量处。此寄存器的宽度由 DmaWidth 成员指定。设备驱动程序从启动设备的 IRP_MN_START_DEVICE 请求中接收的资源列表获取设备启动地址。有关此地址的详细信息，请参阅 CM_PARTIAL_RESOURCE_DESCRIPTOR 中 u.Memory.Start 成员的说明。

对于总线主 DMA 设备，不使用 DeviceAddress 成员。

注解

使用 DMA 传输数据的设备的驱动程序使用 DEVICE_DESCRIPTION 结构将有关设备的信息传递到 IoGetDmaAdapter 例程。驱动程序调用此例程以请求物理设备对象的适配器对象 (PDO) 。此 PDO 表示设备与用于 DMA 的 I/O 总线的物理连接。有关详细信息，请参阅获取适配器对象。

若要为 DMA 控制器分配资源，I/O 管理器需要有关控制器的信息，但只能从驱动程序获取其中一些信息。例如，总线主设备的驱动程序知道设备是支持散点/收集 DMA 还是使用完整的 32 位地址。或者，从属设备的驱动程序可以从驱动程序在启动设备的 IRP_MN_START_DEVICE 请求中接收的资源列表中确定 DMA 通道号。驱动程序使用 DEVICE_DESCRIPTION 结构将此信息传递给 I/O 管理器。

在调用 IoGetDmaAdapter 之前，驱动程序应首先对整个 DEVICE_DESCRIPTION 结构进行零初始化，然后填写所选成员来描述设备。

InterfaceType 成员指定将用于 DMA 的总线接口的类型。如果将 InterfaceType 设置为 InterfaceTypeUndefined，IoGetDmaAdapter 将查询 PDO 以确定设备的正确接口类型。或者，可以指定显式接口类型，例如 Internal、 Isa、 Eisa 或 PCIBus。有关详细信息，请参阅 INTERFACE_TYPE 中支持的接口类型列表。

如果 ScatterGather 成员设置为 TRUE ， 而 InterfaceType 成员设置为 PCIBus，则 忽略 Dma32BitAddresses 成员， IoGetDmaAdapter 假定设备支持 32 位 DMA 地址。

如果 Dma64BitAddresses 成员设置为 TRUE，则 忽略 Dma32BitAddresses 成员， IoGetDmaAdapter 假定设备支持 64 位 DMA 地址。

若要指示 DMA 控制器硬件无法可靠地维护准确的传输计数，请将 IgnoreCount 设置为 TRUE，并将 Version 设置为 DEVICE_DESCRIPTION_VERSION 以外的值。在具有此类 DMA 控制器的平台中，操作系统会忽略 DMA 传输计数器，但必须在 DMA 操作期间采取特殊预防措施来保持数据完整性。通常，使用解决方法来补偿缺陷的 DMA 控制器会降低 DMA 传输的速度。

仅当计算机的 ACPI 固件支持 TypeF 时，驱动程序才应指定 TypeF 作为 DmaSpeed 值。