IoGetDmaAdapter-Funktion (wdm.h)
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) |