DEVICE_DESCRIPTION-Struktur (wdm.h)
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.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Wird ab Windows 2000 unterstützt. |
| Header | wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h) |