WdfDmaTransactionAllocateResources-Funktion (wdfdmatransaction.h)

Artikel
03/22/2025

[Gilt nur für KMDF]

Die WdfDmaTransactionAllocateResources Methode behält sich einen DMA-Aktivierungsmodus für exklusive (und wiederholte) Verwendung mit dem angegebenen Transaktionsobjekt vor. Der Treiber kann die Transaktion mehrmals initialisieren und initiieren, während reservierte Ressourcen aufbewahrt werden.

Syntax

NTSTATUS WdfDmaTransactionAllocateResources(
  [in] WDFDMATRANSACTION   DmaTransaction,
  [in] WDF_DMA_DIRECTION   DmaDirection,
  [in] ULONG               RequiredMapRegisters,
  [in] PFN_WDF_RESERVE_DMA EvtReserveDmaFunction,
  [in] PVOID               EvtReserveDmaContext
);

Die Parameter

[in] DmaTransaction

Ein Handle für das DMA-Transaktionsobjekt, für das DMA-Ressourcen reserviert werden sollen.

[in] DmaDirection

Ein WDF_DMA_DIRECTION-typed-Wert, der die DMA-Übertragungsrichtung angibt, für die die Ressourcen reserviert werden. Wenn der Treiber kein Duplexprofil angegeben hat, ignoriert das Framework diesen Wert.

[in] RequiredMapRegisters

Die Anzahl der Kartenregister, die der Fahrer reservieren möchte. Wenn null, leitet das Framework die erforderliche Anzahl von Kartenregistern von der initialisierten Transaktion ab.

[in] EvtReserveDmaFunction

Ein Zeiger auf die EvtReserveDma Ereignisrückruffunktion des Treibers.

[in] EvtReserveDmaContext

Ein Zeiger auf einen Puffer, der den Kontext enthält, der für die EvtReserveDma Ereignisrückruffunktion des Treibers bereitgestellt werden soll.

Rückgabewert

WdfDmaTransactionAllocateResources gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode einen der folgenden Werte zurück.

Rückgabecode	BESCHREIBUNG
STATUS_INVALID_PARAMETER	Der parameter DmaDirection enthält einen ungültigen Wert.
STATUS_INSUFFICIENT_RESOURCES	Die Anzahl der Zuordnungsregisteranforderungen überschreitet die Anzahl, die dem Enabler zugewiesen wurde, oder der treiber, der zuvor WdfDmaTransactionSetImmediateExecution aufgerufen wurde und die für die Anforderung erforderlichen Ressourcen nicht verfügbar sind.
STATUS_INVALID_DEVICE_REQUEST	DMA, Version 3 oder höher, ist nicht aktiviert, oder der Treiber, der diese Methode für eine XY-Gather-DMA-Aktivierung aufgerufen hat.

Bemerkungen

WdfDmaTransactionAllocateResources sendet eine Anforderung für Kartenregister an das System-DMA-Modul. Wenn die Anforderung erfüllt wurde, ruft das Framework die EvtReserveDma Ereignisrückruffunktion des Treibers auf. Weitere Informationen zum Reservieren von Ressourcen finden Sie unter Reservieren von DMA Resources.

Frameworkbasierte Treiber rufen in der Regel WdfDmaTransactionAllocateResources innerhalb eines E/A-Anforderungshandlersauf. Ein Treiber kann auch WdfDmaTransactionAllocateResources- aus seiner EvtDriverDeviceAdd Rückruffunktion aufrufen, nachdem ein DMA-Aktivierungsobjekt erstellt wurde.

Wenn WdfDmaTransactionAllocateResources mit einem Punkt/Gather-DMA-Enabler aufgerufen wird, führt zu einer Prüffehlerüberprüfung.

Der Treiber muss die durch DmaTransaction- angegebene Transaktion erstellen, bevor WdfDmaTransactionAllocateResourcesaufgerufen wird. Nach dem Aufrufen WdfDmaTransactionAllocateResourcesinitialisiert und initiiert der Treiber die Transaktion. Der Treiber kann dasselbe Transaktionsobjekt mehrmals neu initialisieren und erneut initialisieren, sodass die Verzögerung vermieden wird, die sonst zwischen Transaktionen auftreten würde, da Kartenregister wieder an die HAL zurückgeführt und dann neu zugewiesen wurden.

Ein Treiber kann WdfDmaTransactionAllocateResources- in den folgenden Situationen aufrufen:

Der Treiber empfängt eine Reihe von DMA-Kanälen in seiner EvtDevicePrepareHardware Rückruffunktion. In EvtDevicePrepareHardwareinitialisiert der Treiber eine DMA-Transaktion und ruft WdfDmaTransactionAllocateResources auf, um den Enabler zur exklusiven Verwendung mit dieser Transaktion zu reservieren. Alternativ kann der Treiber WdfDmaTransactionAllocateResources- von einem Anforderungshandler aufrufen und dann die Transaktion mehrmals initiieren.
Der Treiber muss eine Reihe von Transaktionen auf dem Enabler ausführen. Der Treiber reserviert den Enabler, initialisiert und initiiert mehrere Transaktionen mit demselben Transaktionsobjekt und gibt dann den Enabler frei.

Vor dem Aufrufen WdfDmaTransactionAllocateResourcesmuss der Treiber die Anzahl der Kartenregister bestimmen, die für jede Transaktion erforderlich sind, die mit dieser Reservierung initiiert wird. Dazu kann der Treiber entweder die [ADDRESS_AND_SIZE_TO_SPAN_PAGES](.) aufrufen. /wdm/nf-wdm-address_and_size_to_span_pages.md) Makro oder WdfDmaTransactionGetTransferInfo.

Beim Aufrufen WdfDmaTransactionAllocateResourcessollte der Treiber nicht mehr Kartenregister anfordern, als es beim Erstellen des Enablers angefordert wurde.

Um WdfDmaTransactionAllocateResources auf nicht blockierende Weise aufzurufen, sollte der Treiber zuerst WdfDmaTransactionSetImmediateExecutionaufrufen.

WdfDmaTransactionAllocateResources erfordert DMA Version 3. Um DMA Version 3 auszuwählen, legen Sie den WdmDmaVersionOverride Mitglied von WDF_DMA_ENABLER_CONFIG auf 3 fest.

Anforderungen

Anforderung	Wert
Zielplattform	universell
Minimale KMDF-Version	1.11
Kopfzeile	wdfdmatransaction.h (include Wdf.h)
Bibliothek	Wdf01000.sys (siehe Framework-Bibliotheksversionsverwaltung.)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf)