IoGetDmaAdapter-Funktion (wdm.h)

Artikel
02/27/2024

Die IoGetDmaAdapter-Routine gibt einen Zeiger auf die DMA-Adapterstruktur für ein physisches Geräteobjekt zurück.

Syntax

_DMA_ADAPTER * IoGetDmaAdapter(
  [in, optional] PDEVICE_OBJECT      PhysicalDeviceObject,
  [in]           _DEVICE_DESCRIPTION *DeviceDescription,
  [out]          PULONG              NumberOfMapRegisters
);

Parameter

[in, optional] PhysicalDeviceObject

Zeiger auf das physische Geräteobjekt für das Gerät, das die DMA-Adapterstruktur anfordert.

[in] DeviceDescription

Zeiger auf eine DEVICE_DESCRIPTION-Struktur , die die Attribute des physischen Geräts beschreibt. Unabhängig von der in der DEVICE_DESCRIPTION-Struktur festgelegten Version gibt diese Funktion immer zurück DMA_ADAPTER->Version == 1.

[out] NumberOfMapRegisters

Ein Zeiger auf die maximale Anzahl von Kartenregistern, die der Treiber für jeden DMA-Übertragungsvorgang zuordnen kann.

Rückgabewert

IoGetDmaAdapter gibt einen Zeiger auf eine DMA_ADAPTER-Struktur zurück, die Zeiger auf Funktionen enthält, die systemdefinierte DMA-Vorgänge unterstützen. Wenn die Struktur nicht zugeordnet werden kann, gibt die Routine NULL zurück. Siehe Versionskommentar oben in der Beschreibung des DeviceDescription-Parameters .

Hinweise

Vor dem Aufrufen dieser Routine muss ein Treiber die DEVICE_DESCRIPTION Struktur null initialisieren, auf die von DeviceDescription verwiesen wird, und dann die relevanten Informationen für sein Gerät dieser Struktur hinzufügen.

Bei Erfolg verweist der Rückgabewert der Routine auf eine DMA_ADAPTER-Struktur . Diese Struktur enthält einen Zeiger auf eine DMA_OPERATIONS-Struktur , bei der es sich um eine Tabelle mit Zeigern auf Funktionen handelt, die der Treiber anschließend zum Ausführen von DMA-Vorgängen verwenden kann. Die Version dieser Struktur, die die Routine zurückgibt, wird wie folgt bestimmt:

Wenn der Treiber das Versionselement der DEVICE_DESCRIPTION-Struktur auf DEVICE_DESCRIPTION_VERSION oder DEVICE_DESCRIPTION_VERSION1 festlegt, verweist die zurückgegebene DMA_ADAPTER-Struktur auf Version 1 der DMA_OPERATIONS-Struktur .

Wenn der Treiber Version = DEVICE_DESCRIPTION_VERSION2 festlegt, verweist die zurückgegebene DMA_ADAPTER-Struktur auf Version 2 der DMA_OPERATIONS-Struktur , wenn Version 2 unterstützt wird; andernfalls gibt die Routine NULL zurück. Treiber müssen überprüfen, ob Version 2 unterstützt wird, bevor sie versuchen, eine Funktion der Version 2 zu verwenden.

Wenn der Treiber Version = DEVICE_DESCRIPTION_VERSION3 festlegt, verweist die zurückgegebene DMA_ADAPTER-Struktur auf Version 3 der DMA_OPERATIONS-Struktur , wenn Version 3 unterstützt wird; andernfalls gibt die Routine NULL zurück. Treiber müssen überprüfen, ob Version 3 unterstützt wird, bevor sie versuchen, eine Funktion der Version 3 zu verwenden. Version 3 wird ab Windows 8 unterstützt.

Ein PnP-Treiber ruft IoGetDmaAdapter auf, wenn seine AddDevice-Routine aufgerufen wird oder wenn er eine PnP-IRP_MN_START_DEVICE-Anforderung für ein Gerät verarbeitet. Diese IRP enthält Informationen zu den Hardwareressourcen des Geräts, die der Treiber in der DeviceDescription-Struktur bereitstellen muss.

Der Aufrufer verwendet das MaximumLength-Element in der DeviceDescription-Struktur , um die optimale Anzahl von Kartenregistern anzugeben, die er verwenden kann. Der E/A-Manager versucht, genügend Kartenregister zuzuweisen, um einen DMA-Übertragungsvorgang dieser maximalen Größe zu ermöglichen. Bei der Ausgabe gibt der E/A-Manager im Parameter NumberOfMapRegisters die Anzahl der Kartenregister zurück, die er ordnet. Treiber sollten den zurückgegebenen Wert überprüfen. es gibt keine Garantie, dass ein Treiber die gleiche Anzahl von Kartenregistern erhält, die er angefordert hat.

Um das Adapterobjekt freizugeben, sollte der Treiber PutDmaAdapter über den zeiger aufrufen, der in der DMA_ADAPTER-Struktur zurückgegeben wird.

Wie bereits beschrieben, gibt IoGetDmaAdapterNULL zurück, wenn die Version der DMA_ADAPTER Struktur nicht unterstützt wird, die von DeviceDescription-Version> angegeben wird. Aufrufer sollten sich auf dieses Verhalten verlassen, um zu bestimmen, ob die Routine einen Zeiger auf die angeforderte Version der DMA_ADAPTER-Struktur zurückgibt. Wenn IoGetDmaAdapter einen Zeiger auf Version 1 oder Version 2 oder Version 3 der DMA_ADAPTER-Struktur zurückgibt, wird das Versionselement dieser Struktur immer auf 1 festgelegt. Daher kann der Aufrufer das Versionselement der zurückgegebenen DMA_ADAPTER-Struktur nicht verwenden, um zwischen den Versionen 1, 2 und 3 dieser Struktur zu unterscheiden.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm)