DEVICE_DESCRIPTION 結構 (wdm.h)

發行項
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

如果 Version = DEVICE_DESCRIPTION_VERSION，IoGetDmaAdapter 會忽略 IgnoreCount 成員，並傳回 DMA_ADAPTER 結構的第 1 版。

DEVICE_DESCRIPTION_VERSION1

如果 Version = DEVICE_DESCRIPTION_VERSION1，IoGetDmaAdapter 會使用 IgnoreCount 成員，並傳回 DMA_ADAPTER 結構的第 1 版。

DEVICE_DESCRIPTION_VERSION2

如果 Version = DEVICE_DESCRIPTION_VERSION2，IoGetDmaAdapter 會使用 IgnoreCount 成員，並傳回 DMA_ADAPTER 結構的第 2 版。第 2 版是從 Windows XP 開始提供。

DEVICE_DESCRIPTION_VERSION3

如果 Version = 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 值。

如果 Version 是DEVICE_DESCRIPTION_VERSION、DEVICE_DESCRIPTION_VERSION1或DEVICE_DESCRIPTION_VERSION3，則不會使用 DemandMode 值。

AutoInitialize

對於次級 DMA 裝置，此成員會指出是否要使用系統 DMA 控制器的自動初始化模式。設定為 TRUE 以使用自動初始化模式。否則，請將這個成員設定為 FALSE。

對於總線主機 DMA 裝置，不會使用 AutoInitialize 值。

Dma32BitAddresses

只有當 Version 是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

只有當 Version 是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

只有當 Version 是DEVICE_DESCRIPTION_VERSION、DEVICE_DESCRIPTION_VERSION1或DEVICE_DESCRIPTION_VERSION2時，才會使用此成員。

對於次級 DMA 裝置，此成員會指定系統 DMA 的下列其中一個速度：相容、TypeA、TypeB、TypeC 或 TypeF。

對於總線主機 DMA 裝置，不會使用 DmaSpeed 值。

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

MaximumLength

裝置可以在使用配置配接器物件的 DMA 作業中傳輸的最大位元元組數目。

DmaPort

Microchannel-type 總線埠號碼。此參數已過時，但會保留在結構中，以便與舊版驅動程式相容。

DmaAddressWidth

只有當 Version = DEVICE_DESCRIPTION_VERSION3時，才會使用此成員。

針對總線主機 DMA 裝置，DmaAddressWidth 會指定 DMA 位址的寬度，以位為單位。 DmaAddressWidth 值必須是非零值，且不得超過 64。如果記憶體位址寬度大於 DMA 位址寬度，則需要對應緩存器才能存取超出 DMA 控制器位址觸達範圍的記憶體區域。

對於次級 DMA 裝置，不會使用 DmaAddressWidth 值。相反地， IoGetDmaAdapter 會假設從屬 DMA 裝置的位址寬度與裝置所連線的基礎系統 DMA 控制器相同。

DmaControllerInstance

未使用。

DmaRequestLine

只有當 Version = DEVICE_DESCRIPTION_VERSION3時，才會使用此成員。

針對次級 DMA 裝置，DmaRequestLine 會指定裝置所連線之 DMA 控制器上的要求行。設備驅動器會從啟動裝置之 IRP_MN_START_DEVICE 要求中收到的資源清單中取得此要求行的數目。如需要求行號的詳細資訊，請參閱 CM_PARTIAL_RESOURCE_DESCRIPTOR 中的 u.DmaV3.RequestLine 成員描述。

對於總線主機 DMA 裝置，不會使用 DmaRequestLine 值。

DeviceAddress

只有當 Version = 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 代表裝置對 I/O 總線的實體連線，以用於 DMA。如需詳細資訊，請參閱取得配接器物件。

若要配置 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 指定為 DmaSpeed 值。