WdfCommonBufferCreateWithConfig-Funktion (wdfcommonbuffer.h)

Artikel
02/07/2025

[Gilt nur für KMDF]

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

Syntax

NTSTATUS WdfCommonBufferCreateWithConfig(
  [in]           WDFDMAENABLER             DmaEnabler,
  [in]           size_t                    Length,
  [in]           PWDF_COMMON_BUFFER_CONFIG Config,
  [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.

[in] Config

Ein Zeiger auf eine WDF_COMMON_BUFFER_CONFIG Struktur, die Konfigurationsinformationen zum Puffer enthält.

[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

WdfCommonBufferCreateWithConfig 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 WdfCommonBufferCreateWithConfig 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.

Darüber hinaus ermöglicht WdfCommonBufferCreateWithConfig- ihrem Treiber die Angabe einer Pufferausrichtungsanforderung für den Puffer. Die Pufferausrichtungsanforderung setzt die Pufferausrichtungsanforderung außer Kraft, die der Treiber beim Aufruf WdfDeviceSetAlignmentRequirementangegeben hat. Ihr Treiber kann WdfCommonBufferCreateWithConfiganstelle von WdfCommonBufferCreateverwenden, wenn der Treiber einen Puffer erstellen soll, der eine andere Ausrichtungsanforderung hat als die, die WdfDeviceSetAlignmentRequirement angegeben.

Nachdem Ihr Treiber WdfCommonBufferCreateWithConfig-aufgerufen 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 WdfCommonBufferCreateWithConfig innerhalb seiner EvtDriverDeviceAdd Rückruffunktion auf.

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.

Weitere Informationen zu allgemeinen Puffern finden Sie unter Using Common Buffers

Beispiele

Im folgenden Codebeispiel wird eine WDF_COMMON_BUFFER_CONFIG Struktur initialisiert und anschließend ein 10-Byte-Puffer erstellt, der an einer Grenze von 32 Byte ausgerichtet ist.

WDF_COMMON_BUFFER_CONFIG  commonBufConfig;
WDFCOMMONBUFFER  commonBuffer;

WDF_COMMON_BUFFER_CONFIG_INIT(
                              &commonBufConfig,
                              FILE_32_BYTE_ALIGNMENT
                              );

status = WdfCommonBufferCreateWithConfig(
                                         DmaEnabler,
                                         10,
                                         &commonBufConfig,
                                         WDF_NO_OBJECT_ATTRIBUTES,
                                         &commonBuffer
                                         );
if (!NT_SUCCESS (status)) {
    return status;
}

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.1
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)