IoGetDmaAdapter-Funktion (wdm.h)

2025-02-07

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 DMA_ADAPTER->Version == 1zurück.

[out] NumberOfMapRegisters

Ein Zeiger auf die Ausgabe, 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 den Versionskommentar oben in der Beschreibung des DeviceDescription- Parameters.

Bemerkungen

Vor dem Aufrufen dieser Routine muss ein Treiber die DEVICE_DESCRIPTION Struktur initialisieren, auf die durch DeviceDescription verwiesen wird, und dann die relevanten Informationen für das 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 von der Routine zurückgegeben wird, wird wie folgt bestimmt:

Wenn der Treiber das Version Member 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 Beliebige Version 2-Funktion 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 Beliebige Version 3-Funktion zu verwenden. Version 3 wird ab Windows 8 unterstützt.

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

Der Aufrufer verwendet das MaximumLength Member in der DeviceDescription- Struktur, um die optimale Anzahl von Kartenregistern anzugeben, die es 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 NumberOfMapRegisters Parameter die Anzahl der zugeordneten Kartenregister zurück. Treiber sollten den zurückgegebenen Wert überprüfen; es gibt keine Garantie, dass ein Fahrer dieselbe Anzahl von Kartenregistern erhält, die er angefordert hat.

Um das Adapterobjekt freizugeben, sollte der Treiber PutDmaAdapter- über den in der DMA_ADAPTER Struktur zurückgegebenen Zeiger aufrufen.

Wie zuvor beschrieben, gibt IoGetDmaAdapter-NULL- zurück, wenn die Version der DMA_ADAPTER Struktur, die durch DeviceDescription->Versionangegeben wird, nicht unterstützt 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 Version Element dieser Struktur immer auf 1 festgelegt. Daher kann der Aufrufer das Version Member der zurückgegebenen DMA_ADAPTER Struktur nicht verwenden, um zwischen den Versionen 1, 2 und 3 dieser Struktur zu unterscheiden.

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Header-	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm)