WdfDmaEnablerCreate-Funktion (wdfdmaenabler.h)
[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 |
|---|---|
|
Ein ungültiger Parameter wurde erkannt. |
|
Es war nicht genügend Arbeitsspeicher vorhanden, um ein neues DMA-Enabler-Objekt zu erstellen. |
|
Die Größe der WDF_DMA_ENABLER_CONFIG-Struktur ist falsch. |
|
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) |