WdfDmaTransactionAllocateResources-Funktion (wdfdmatransaction.h)

Artikel
08/08/2023

[Gilt nur für KMDF]

Die WdfDmaTransactionAllocateResources-Methode reserviert einen DMA-Enabler im Einzelpaket oder Systemmodus für die exklusive (und wiederholte) Verwendung mit dem angegebenen Transaktionsobjekt. Der Treiber kann die Transaktion mehrmals initialisieren und initiieren, während er reservierte Ressourcen hält.

Syntax

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

Parameter

[in] DmaTransaction

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

[in] DmaDirection

Ein WDF_DMA_DIRECTION typisierter 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. Bei null leitet das Framework die erforderliche Anzahl von Kartenregistern aus 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 DmaDirection-Parameter enthält einen ungültigen Wert.
STATUS_INSUFFICIENT_RESOURCES	Die Anzahl der Kartenregisteranforderungen überschreitet die anzahl, die dem Enabler zugewiesen wurde, oder der Treiber, der zuvor WdfDmaTransactionSetImmediateExecution genannt wurde, und die für die Anforderung benötigten Ressourcen sind nicht verfügbar.
STATUS_INVALID_DEVICE_REQUEST	DMA Version 3 oder höher ist nicht aktiviert, oder der Treiber, der diese Methode für eine Scatter-Gather-DMA-Aktivierung bezeichnet.

Hinweise

WdfDmaTransactionAllocateResources sendet eine Anforderung für Kartenregister an die System-DMA-Engine. 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-Ressourcen.

Frameworkbasierte Treiber rufen in der Regel WdfDmaTransactionAllocateResources aus einem E/A-Anforderungshandler auf. Ein Treiber kann WdfDmaTransactionAllocateResources auch über seine Rückruffunktion EvtDriverDeviceAdd aufrufen, nachdem er ein DMA-Enabler-Objekt erstellt hat.

Wenn WdfDmaTransactionAllocateResources mit einem DMA-Enabler "scatter/gather" aufgerufen wird, verursacht WdfDmaTransactionAllocateResources eine Überprüfung des Prüfers.

Der Treiber muss die von DmaTransaction angegebene Transaktion erstellen, bevor WdfDmaTransactionAllocateResources aufgerufen wird. Nach dem Aufruf von WdfDmaTransactionAllocateResources initialisiert und initiiert der Treiber die Transaktion. Der Treiber kann dasselbe Transaktionsobjekt mehrmals neu initialisieren und neu initialisieren, um die Verzögerung zu vermeiden, die andernfalls zwischen Transaktionen auftreten würde, wenn Kartenregister wieder zur HAL freigegeben und dann neu zugeordnet wurden.

Ein Treiber kann WdfDmaTransactionAllocateResources in den folgenden Situationen aufrufen:

Der Treiber empfängt eine Reihe von DMA-Kanälen in seiner Rückruffunktion EvtDevicePrepareHardware . In EvtDevicePrepareHardware initialisiert der Treiber eine DMA-Transaktion und ruft WdfDmaTransactionAllocateResources auf, um den Enabler für die exklusive Verwendung mit dieser Transaktion zu reservieren. Alternativ kann der Treiber WdfDmaTransactionAllocateResources über einen 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 von WdfDmaTransactionAllocateResources muss der Treiber die Anzahl der Kartenregister bestimmen, die für jede Transaktion erforderlich sind, die er mithilfe dieser Reservierung initiiert. Hierzu 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 von WdfDmaTransactionAllocateResources sollte der Treiber nicht mehr Kartenregister anfordern, als er beim Erstellen des Enablers angefordert hat.

Um WdfDmaTransactionAllocateResources nicht blockierend aufzurufen, sollte der Treiber zuerst WdfDmaTransactionSetImmediateExecution aufrufen.

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

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.11
Kopfzeile	wdfdmatransaction.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (siehe Versionierung der Frameworkbibliothek.)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf)