WdfDmaEnablerCreate-Funktion (wdfdmaenabler.h)

  • Artikel

[Gilt nur für KMDF]

Die WdfDmaEnablerCreate-Methode erstellt ein DMA-Enabler-Objekt.

Syntax

NTSTATUS WdfDmaEnablerCreate(
  [in]           WDFDEVICE               Device,
  [in]           PWDF_DMA_ENABLER_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES  Attributes,
  [out]          WDFDMAENABLER           *DmaEnablerHandle
);

Parameter

[in] Device

Ein Handle für ein Framework-Geräteobjekt.

[in] Config

Ein Zeiger auf eine WDF_DMA_ENABLER_CONFIG-Struktur . Treiber müssen diese Struktur initialisieren, indem sie WDF_DMA_ENABLER_CONFIG_INIT aufrufen.

[in, optional] Attributes

Ein Zeiger auf eine WDF_OBJECT_ATTRIBUTES-Struktur , die Objektattribute für das neue DMA-Enabler-Objekt angibt. Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[out] DmaEnablerHandle

Ein Handle für ein neues DMA-Enabler-Objekt.

Rückgabewert

WdfDmaEnablerCreate gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt die -Methode möglicherweise einen der folgenden Werte zurück.

Rückgabecode Beschreibung
STATUS_INVALID_PARAMETER
 Ein ungültiger Parameter wurde erkannt.
STATUS_INSUFFICIENT_RESOURCES

Es war nicht genügend Arbeitsspeicher vorhanden, um ein neues DMA-Enabler-Objekt zu erstellen.
STATUS_INFO_LENGTH_MISMATCH
 Die Größe der WDF_DMA_ENABLER_CONFIG-Struktur ist falsch.
STATUS_NOT_SUPPORTED
 Der Treiber hat DMA-Version 3 für ein früheres Betriebssystem als Windows 8 angefordert.
 

Eine Liste mit anderen Rückgabewerten, die von der WdfDmaEnablerCreate-Methode möglicherweise zurückgegeben werden, finden Sie unter Fehler bei der Erstellung von Frameworkobjekten.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

Frameworkbasierte Treiber müssen WdfDmaEnablerCreate aufrufen, bevor DMA-Transaktionen für ein Gerät erstellt werden.

Bevor ein Treiber WdfDmaEnablerCreate aufruft, muss er WdfDeviceSetAlignmentRequirement aufrufen.

Das Framework-Geräteobjekt, das der Device-Parameter von WdfDmaEnablerCreate angibt, wird immer zum übergeordneten Objekt für das neue DMA-Enabler-Objekt. Wenn der Treiber ein anderes übergeordnetes Element im ParentObject-Element der WDF_OBJECT_ATTRIBUTES-Struktur angibt, ignoriert das Framework diesen Wert. Das Framework löscht das DMA-Enabler-Objekt, wenn es das übergeordnete Objekt löscht.

Wenn WdfDmaEnablerCreate mit einem Config-Parameter aufgerufen wird, der ein DMA-Profil im Systemmodus anfordert, erstellt WdfDmaEnablerCreate eine teilweise initialisierte DMA-Aktivierung. Der Treiber muss anschließend WdfDmaEnablerConfigureSystemProfile aufrufen, um die DMA-Einstellungen für die zugrunde liegenden Kanäle einzurichten.

Weitere Informationen zu DMA-Enabler-Objekten und WdfDmaEnablerCreate finden Sie unter Aktivieren von DMA-Transaktionen.

Beispiele

Das folgende Codebeispiel stammt aus dem PLX9x5x-Beispieltreiber . In diesem Beispiel wird die Anforderung eines Geräts für die Pufferausrichtung festgelegt, eine WDF_DMA_ENABLER_CONFIG-Struktur initialisiert und WdfDmaEnablerCreate aufgerufen.

//
// PLx PCI9656 DMA_TRANSFER_ELEMENTS must be 16-byte aligned.
//
WdfDeviceSetAlignmentRequirement(
                                 DevExt->WdfDevice,
                                 PCI9656_DTE_ALIGNMENT_16
                                 );

//
// Create a new DMA enabler object instance. 
// Use scatter/gather, 64-bit addresses, and duplex-type profile.
//
{
    WDF_DMA_ENABLER_CONFIG   dmaConfig;
    WDF_DMA_ENABLER_CONFIG_INIT(
                                &dmaConfig,
                                WdfDmaProfileScatterGather64Duplex,
                                DevExt->MaximumTransferLength
                                );
    status = WdfDmaEnablerCreate(
                                 DevExt->WdfDevice,
                                 &dmaConfig,
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 &DevExt->DmaEnabler
                                 );
    if (!NT_SUCCESS (status)) {
        // Cannot continue, so release device resources.
        return status;
    }
}

Anforderungen

Anforderung Wert
Zielplattform Universell
KMDF-Mindestversion 1.0
Kopfzeile wdfdmaenabler.h (einschließen von Wdf.h)
Bibliothek Wdf01000.sys (siehe Versionsverwaltung der Frameworkbibliothek).)
IRQL PASSIVE_LEVEL
DDI-Complianceregeln DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Weitere Informationen

WDF_DMA_ENABLER_CONFIG

WDF_DMA_ENABLER_CONFIG_INIT

WDF_OBJECT_ATTRIBUTES

WdfDeviceSetAlignmentRequirement