DEVICE_DESCRIPTION-Struktur (wdm.h)

Artikel
02/27/2024

Die DEVICE_DESCRIPTION-Struktur beschreibt die Attribute des physischen Geräts, für das ein Treiber einen DMA-Adapter anfordert.

Syntax

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;

Member

Version

Die Version dieser Struktur. Das Versionselement der DEVICE_DESCRIPTION-Struktur , das an die IoGetDmaAdapter-Routine übergeben wird, bestimmt, welche Version der DMA_ADAPTER-Struktur von dieser Routine zurückgegeben wird. Im Folgenden ist eine Liste der möglichen Werte des Versionselements und der entsprechenden DMA_ADAPTER Versionen aufgeführt:

DEVICE_DESCRIPTION_VERSION

Wenn Version = DEVICE_DESCRIPTION_VERSION, ignoriert IoGetDmaAdapter das IgnoreCount-Element und gibt Version 1 der DMA_ADAPTER-Struktur zurück.

DEVICE_DESCRIPTION_VERSION1

Wenn Version = DEVICE_DESCRIPTION_VERSION1, verwendet IoGetDmaAdapter das IgnoreCount-Element und gibt Version 1 der DMA_ADAPTER-Struktur zurück.

DEVICE_DESCRIPTION_VERSION2

Wenn Version = DEVICE_DESCRIPTION_VERSION2, verwendet IoGetDmaAdapter das IgnoreCount-Element und gibt Version 2 der DMA_ADAPTER-Struktur zurück. Version 2 ist ab Windows XP verfügbar.

DEVICE_DESCRIPTION_VERSION3

Wenn Version = DEVICE_DESCRIPTION_VERSION3, verwendet IoGetDmaAdapter den IgnoreCount-Member und gibt Version 3 der DMA_ADAPTER-Struktur zurück. Version 3 ist ab Windows 8 verfügbar.

Master

Gibt an, ob es sich bei dem Gerät um ein Bus-master DMA-Gerät handelt. Legen Sie auf TRUE fest, wenn es sich bei dem Gerät um ein Bus-master DMA-Gerät handelt. Legen Sie auf FALSE fest, wenn es sich um ein untergeordnetes DMA-Gerät handelt.

ScatterGather

Für ein Bus-master DMA-Gerät gibt dieses Element an, ob das Gerät scatter/gather DMA unterstützt. Legen Sie auf TRUE fest, wenn das Gerät DMA zum Scatter-/Sammeln ausführen kann. Legen Sie andernfalls diesen Member auf FALSE fest.

Für ein untergeordnetes DMA-Gerät wird der ScatterGather-Wert nicht verwendet. Stattdessen geht IoGetDmaAdapter davon aus, dass die Scatter/Gather-Funktion eines untergeordneten DMA-Geräts mit der des zugrunde liegenden System-DMA-Controllers identisch ist, mit dem das Gerät verbunden ist.

DemandMode

Dieses Element wird nur verwendet, wenn Version DEVICE_DESCRIPTION_VERSION2 ist.

Für ein untergeordnetes DMA-Gerät gibt dieser Member an, ob der Bedarfsmodus des System-DMA-Controllers verwendet werden soll. Legen Sie auf TRUE fest, um den Bedarfsmodus zu verwenden. Legen Sie andernfalls diesen Member auf FALSE fest.

Für ein Bus-master DMA-Gerät wird der DemandMode-Wert nicht verwendet.

Wenn Version DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 oder DEVICE_DESCRIPTION_VERSION3 ist, wird der DemandMode-Wert nicht verwendet.

AutoInitialize

Für ein untergeordnetes DMA-Gerät gibt dieses Element an, ob der Autoinitialisierungsmodus des System-DMA-Controllers verwendet werden soll. Legen Sie auf TRUE fest, um den Autoinitialisierungsmodus zu verwenden. Legen Sie andernfalls diesen Member auf FALSE fest.

Für ein Bus-master DMA-Gerät wird der AutoInitialize-Wert nicht verwendet.

Dma32BitAddresses

Dieses Element wird nur verwendet, wenn Version DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 oder DEVICE_DESCRIPTION_VERSION2 ist.

Dma32BitAddresses gibt an, ob das Gerät vollständige 32-Bit-Adressen für DMA-Vorgänge verwenden kann. Legen Sie auf TRUE fest, wenn das Gerät 32-Bit-Adressen unterstützt. Legen Sie andernfalls diesen Member auf FALSE fest.

Wenn Version = DEVICE_DESCRIPTION_VERSION3, wird der Dma32BitAddresses-Wert nicht verwendet.

IgnoreCount

Gibt an, ob der Übertragungsindikator des DMA-Controllers ignoriert werden soll. Legen Sie auf TRUE fest, wenn der DMA-Controller auf dieser Plattform keinen genauen Übertragungsindikator beisteuert und daher eine Problemumgehung erfordert. Legen Sie andernfalls diesen Member auf FALSE fest.

Wenn Version = DEVICE_DESCRIPTION_VERSION, wird der IgnoreCount-Wert nicht verwendet.

Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

Reserved1

Ist für das System reserviert. Muss FALSE sein.

Dma64BitAddresses

Dieses Element wird nur verwendet, wenn Version DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 oder DEVICE_DESCRIPTION_VERSION2 ist.

Dma64BitAddresses gibt an, ob das Gerät vollständige 64-Bit-Adressen für DMA-Vorgänge verwenden kann. Legen Sie auf TRUE fest, wenn das Gerät 64-Bit-Adressen unterstützt. Legen Sie andernfalls diesen Member auf FALSE fest.

Wenn Version = DEVICE_DESCRIPTION_VERSION3, wird der Dma64BitAddresses-Wert nicht verwendet.

BusNumber

Die systemseitig zugewiesene Busnummer für den E/A-Bus. Dieses Element wird nicht von WDM-Treibern verwendet.

DmaChannel

Die Nummer des DMA-Kanals, dem ein untergeordnetes Gerät zugewiesen ist. Der Gerätetreiber ruft diese Kanalnummer aus der Ressourcenliste ab, die er in der IRP_MN_START_DEVICE Anforderung empfängt, die das Gerät startet. Weitere Informationen zu dieser Nummer finden Sie in der Beschreibung des Dma.Channel-Members in CM_PARTIAL_RESOURCE_DESCRIPTOR.

InterfaceType

Der Schnittstellentyp des E/A-Busses, der für DMA verwendet werden soll. Legen Sie dieses Element auf den INTERFACE_TYPE-Enumerationswert fest, der den Schnittstellentyp angibt. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

DmaWidth

Für ein untergeordnetes DMA-Gerät gibt dieses Member die DMA-Datenbreite für Übertragungen durch den System-DMA-Controller an. Mögliche Werte sind Width8Bits, Width16Bits, Width32Bits und Width64Bits.

Für ein Bus-master DMA-Gerät wird der DmaWidth-Wert nicht verwendet.

DmaSpeed

Dieses Element wird nur verwendet, wenn Version DEVICE_DESCRIPTION_VERSION, DEVICE_DESCRIPTION_VERSION1 oder DEVICE_DESCRIPTION_VERSION2 ist.

Für ein untergeordnetes DMA-Gerät gibt dieses Element eine der folgenden Geschwindigkeiten für System-DMA an: Compatible, TypeA, TypeB, TypeC oder TypeF.

Für ein Bus-master DMA-Gerät wird der DmaSpeed-Wert nicht verwendet.

Wenn Version = DEVICE_DESCRIPTION_VERSION3, wird der DmaSpeed-Wert nicht verwendet.

MaximumLength

Die maximale Anzahl von Bytes, die das Gerät in einem DMA-Vorgang übertragen kann, der das zugeordnete Adapterobjekt verwendet.

DmaPort

Die Busportnummer vom Typ Microchannel. Dieser Parameter ist veraltet, wird aber aus Gründen der Kompatibilität mit Legacytreibern in der Struktur beibehalten.

DmaAddressWidth

Dieses Element wird nur verwendet, wenn Version = DEVICE_DESCRIPTION_VERSION3.

Für ein Bus-master DMA-Gerät gibt DmaAddressWidth die Breite einer DMA-Adresse in Bits an. Der DmaAddressWidth-Wert muss nonzero sein und darf 64 nicht überschreiten. Wenn die Breite der Speicheradresse größer als die Breite der DMA-Adresse ist, sind Kartenregister erforderlich, um auf einen Speicherbereich zuzugreifen, der außerhalb der Adressreichweite des DMA-Controllers liegt.

Für ein untergeordnetes DMA-Gerät wird der DmaAddressWidth-Wert nicht verwendet. Stattdessen geht IoGetDmaAdapter davon aus, dass die Adressbreite eines untergeordneten DMA-Geräts mit der des zugrunde liegenden System-DMA-Controllers übereinstimmt, mit dem das Gerät verbunden ist.

DmaControllerInstance

Wird nicht verwendet.

DmaRequestLine

Dieses Element wird nur verwendet, wenn Version = DEVICE_DESCRIPTION_VERSION3.

Für ein untergeordnetes DMA-Gerät gibt DmaRequestLine die Anforderungszeile auf dem DMA-Controller an, mit dem das Gerät verbunden ist. Der Gerätetreiber ruft die Nummer dieser Anforderungszeile aus der Ressourcenliste ab, die er in der IRP_MN_START_DEVICE Anforderung empfängt, die das Gerät startet. Weitere Informationen zur Anforderungszeilennummer finden Sie in der Beschreibung des u.DmaV3.RequestLine-Members in CM_PARTIAL_RESOURCE_DESCRIPTOR.

Für ein Bus-master DMA-Gerät wird der DmaRequestLine-Wert nicht verwendet.

DeviceAddress

Dieses Element wird nur verwendet, wenn Version = DEVICE_DESCRIPTION_VERSION3.

Bei einem untergeordneten DMA-Gerät ist DeviceAddress die Speicherzuordnungsadresse des Datenregisters auf dem Gerät, das als Quelle oder Ziel für eine DMA-Übertragung verwendet wird. Dieses Datenregister befindet sich an einem bekannten, gerätespezifischen Offset der Gerätestartadresse. Die Breite dieses Registers wird durch das DmaWidth-Element angegeben. Der Gerätetreiber ruft die Startadresse des Geräts aus der Ressourcenliste ab, die er in der IRP_MN_START_DEVICE Anforderung empfängt, die das Gerät startet. Weitere Informationen zu dieser Adresse finden Sie in der Beschreibung des u.Memory.Start-Members in CM_PARTIAL_RESOURCE_DESCRIPTOR.

Für ein Bus-master DMA-Gerät wird das DeviceAddress-Element nicht verwendet.

Hinweise

Der Treiber eines Geräts, das DMA zum Übertragen von Daten verwendet, verwendet die DEVICE_DESCRIPTION-Struktur , um Informationen über das Gerät an die IoGetDmaAdapter-Routine zu übergeben. Der Treiber ruft diese Routine auf, um ein Adapterobjekt für ein physisches Geräteobjekt (PDO) anzufordern. Dieses PDO stellt die physische Verbindung des Geräts mit dem E/A-Bus dar, der für DMA verwendet werden soll. Weitere Informationen finden Sie unter Abrufen eines Adapterobjekts.

Zum Zuweisen von Ressourcen für einen DMA-Controller benötigt der E/A-Manager Informationen zum Controller, kann jedoch einige dieser Informationen nur von einem Treiber abrufen. Beispielsweise weiß der Treiber für ein Bus-master-Gerät, ob das Gerät scatter/gather DMA unterstützt oder vollständige 32-Bit-Adressen verwendet. Alternativ kann der Treiber für ein untergeordnetes Gerät die DMA-Kanalnummer aus der Ressourcenliste ermitteln, die der Treiber in der IRP_MN_START_DEVICE Anforderung empfängt, die das Gerät startet. Der Treiber verwendet die DEVICE_DESCRIPTION-Struktur , um diese Informationen an den E/A-Manager zu übergeben.

Vor dem Aufrufen von IoGetDmaAdapter sollte der Treiber zunächst die gesamte DEVICE_DESCRIPTION-Struktur null initialisieren und dann ausgewählte Elemente eingeben, um das Gerät zu beschreiben.

Das InterfaceType-Element gibt den Typ der Busschnittstelle an, der für DMA verwendet wird. Wenn Sie InterfaceType auf InterfaceTypeUndefined festlegen, fragt IoGetDmaAdapter den PDO ab, um den richtigen Schnittstellentyp für Ihr Gerät zu ermitteln. Oder Sie können einen expliziten Schnittstellentyp angeben, z. B . Internal, Isa, Eisa oder PCIBus. Weitere Informationen finden Sie in der Liste der unterstützten Schnittstellentypen in INTERFACE_TYPE.

Wenn das ScatterGather-Element auf TRUE und der InterfaceType-Member auf PCIBus festgelegt ist, wird das Dma32BitAddresses-Element ignoriert, und IoGetDmaAdapter geht davon aus, dass das Gerät 32-Bit-DMA-Adressen unterstützt.

Wenn der Dma64BitAddresses-Member auf TRUE festgelegt ist, wird der Dma32BitAddresses-Member ignoriert, und IoGetDmaAdapter geht davon aus, dass das Gerät 64-Bit-DMA-Adressen unterstützt.

Um anzugeben, dass die DMA-Controllerhardware keine genaue Übertragungsanzahl zuverlässig aufrechterhalten kann, legen Sie IgnoreCount auf TRUE fest, und legen Sie Version auf einen anderen Wert als DEVICE_DESCRIPTION_VERSION fest. Auf einer Plattform mit einem solchen DMA-Controller ignoriert das Betriebssystem den DMA-Übertragungszähler, muss jedoch besondere Vorsichtsmaßnahmen treffen, um die Datenintegrität während DMA-Vorgängen aufrechtzuerhalten. In der Regel beeinträchtigt die Verwendung einer Problemumgehung zum Kompensieren eines fehlerhaften DMA-Controllers die Geschwindigkeit von DMA-Übertragungen.

Ein Treiber sollte TypeF als DmaSpeed-Wert nur angeben, wenn die ACPI-Firmware des Computers dies unterstützt.