WdfCommonBufferCreate-Funktion (wdfcommonbuffer.h)

Artikel
02/07/2025

[Gilt nur für KMDF]

Die WdfCommonBufferCreate Methode erstellt einen Speicherpuffer, auf den sowohl der Treiber als auch ein DMA-Gerät (Direct Memory Access) gleichzeitig zugreifen können.

Syntax

NTSTATUS WdfCommonBufferCreate(
  [in]           WDFDMAENABLER          DmaEnabler,
  [in]           size_t                 Length,
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]          WDFCOMMONBUFFER        *CommonBuffer
);

Parameter

[in] DmaEnabler

Ein Handle für ein DMA-Aktivierungsobjekt, das der Treiber durch einen vorherigen Aufruf von WdfDmaEnablerCreateabgerufen hat.

[in] Length

Die gewünschte Größe des neuen Puffers in Bytes. Die maximal zulässige Puffergröße ist (MAXULONG - PAGE_SIZE) Bytes.

[in, optional] Attributes

Ein Zeiger auf eine WDF_OBJECT_ATTRIBUTES Struktur, die Objektattribute für das allgemeine Pufferobjekt angibt. (Das ParentObject-Element der Struktur muss NULL-sein.) Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[out] CommonBuffer

Ein Zeiger auf eine WDFCOMMONBUFFER-typierte Variable, die ein Handle für ein gängiges Pufferobjekt empfängt.

Rückgabewert

WdfCommonBufferCreate gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Der Treiber hat einen ungültigen Parameter angegeben.
STATUS_INSUFFICIENT_RESOURCES	Das Framework konnte kein allgemeines Pufferobjekt zuordnen, oder das System konnte einen Puffer nicht zuordnen.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Die WdfCommonBufferCreate Methode weist Arbeitsspeicher zu und ordnet sie zu, sodass sowohl der Treiber als auch ein Gerät gleichzeitig für DMA-Vorgänge darauf zugreifen können. Nachdem Ihr Treiber WdfCommonBufferCreateaufgerufen hat, muss der Treiber:

Rufen Sie WdfCommonBufferGetAlignedVirtualAddress auf, um die virtuelle Adresse des Puffers abzurufen, die der Treiber verwenden kann.
Rufen Sie WdfCommonBufferGetAlignedLogicalAddress auf, um die logische Adresse des Puffers abzurufen, die das Gerät verwenden kann.

Ein Treiber ruft in der Regel WdfCommonBufferCreate innerhalb seiner EvtDriverDeviceAdd Rückruffunktion auf.

Bevor der Treiber WdfDmaEnablerCreateaufruft, kann er WdfDeviceSetAlignmentRequirement- aufrufen, um eine Pufferausrichtungsanforderung festzulegen. Wenn der Treiber WdfDeviceSetAlignmentRequirementnicht aufruft, werden Puffer an Wortgrenzen ausgerichtet. Wenn Ihr Treiber mehrere DMA-Aktivierungen erstellt, kann der Treiber WdfDeviceSetAlignmentRequirement- aufrufen, bevor jeder Aufruf von WdfDmaEnablerCreate.

Um einen allgemeinen Puffer mit einer Ausrichtungsanforderung zu erstellen, die sich von der Ausrichtungsanforderung unterscheidet, die der mit WdfDeviceSetAlignmentRequirementangegebene Treiber hat, kann der Treiber WdfCommonBufferCreateWithConfig anstelle von WdfCommonBufferCreateaufrufen.

Das Betriebssystem bestimmt, ob zwischengespeicherter Speicher im allgemeinen Puffer aktiviert werden soll, der zugewiesen werden soll. Diese Entscheidung basiert auf der Prozessorarchitektur und dem Gerätebus.

Auf Computern mit x86-basierten, x64-basierten und Itanium-basierten Prozessoren ist der zwischengespeicherte Speicher aktiviert. Auf Computern mit ARM- oder ARM 64-basierten Prozessoren aktiviert das Betriebssystem nicht automatisch zwischengespeicherten Speicher für alle Geräte. Das System basiert auf der ACPI_CCA-Methode für jedes Gerät, um zu bestimmen, ob das Gerät zwischengespeichert ist.

Das DMA-Enabler-Objekt, das vom DmaEnabler Parameter von WdfCommonBufferCreate angegeben wird, wird zum übergeordneten Objekt für das neue allgemeine Pufferobjekt. Der Treiber kann dieses übergeordnete Element nicht ändern, und das ParentObject Member der WDF_OBJECT_ATTRIBUTES Struktur muss NULL-sein. Das Framework löscht jedes allgemeine Pufferobjekt, wenn es das übergeordnete DMA-Enabler-Objekt löscht. Alternativ können Sie das allgemeine Pufferobjekt explizit löschen, indem Sie WdfObjectDeleteaufrufen.

Weitere Informationen zu allgemeinen Puffern finden Sie unter Using Common Buffers.

Beispiele

Das folgende Codebeispiel zeigt, wie Sie einen allgemeinen Puffer abrufen. Im Beispiel werden Informationen zum allgemeinen Puffer im vom Treiber definierten Kontextbereich gespeichert, der vom DevExt Zeiger identifiziert wird.

DevExt->CommonBufferSize = sizeof(COMMON_BUFFER_STRUCT);  // Your structure size
status = WdfCommonBufferCreate(
                               DevExt->DmaEnabler,
                               DevExt->CommonBufferSize,
                               WDF_NO_OBJECT_ATTRIBUTES,
                               &DevExt->CommonBuffer
                               );
if (status == STATUS_SUCCESS) {
    DevExt->CommonBufferBaseVA = 
        WdfCommonBufferGetAlignedVirtualAddress(DevExt->CommonBuffer);
    DevExt->CommonBufferBaseLA =
        WdfCommonBufferGetAlignedLogicalAddress(DevExt->CommonBuffer); 
}

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Header-	wdfcommonbuffer.h (include WdfCommonBuffer.h)
Library	Wdf01000.sys (siehe Framework-Bibliotheksversionsverwaltung.)
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)