WdfCommonBufferCreateWithConfig-Funktion (wdfcommonbuffer.h)

Artikel
08/08/2023

[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-Enabler-Objekt, das der Treiber durch einen vorherigen Aufruf von WdfDmaEnablerCreate abgerufen hat.

[in] Length

Die gewünschte Größe des neuen Puffers in Byte.

[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 Variable vom Typ WDFCOMMONBUFFER, die ein Handle auf ein allgemeines 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 keinen Puffer zuordnen.

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

Hinweise

Die WdfCommonBufferCreateWithConfig-Methode weist Arbeitsspeicher zu und ordnet ihn 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, eine Pufferausrichtungsanforderung für den Puffer anzugeben. Die Pufferausrichtungsanforderung überschreibt die Pufferausrichtungsanforderung, die der Treiber beim Aufrufen von WdfDeviceSetAlignmentRequirement angegeben hat. Ihr Treiber kann WdfCommonBufferCreateWithConfig anstelle von WdfCommonBufferCreate verwenden, wenn der Treiber einen Puffer erstellen soll, der eine andere Ausrichtungsanforderung hat als der, den WdfDeviceSetAlignmentRequirement angegeben hat.

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 aus seiner Rückruffunktion EvtDriverDeviceAdd auf.

Das Betriebssystem bestimmt, ob der zwischengespeicherte Arbeitsspeicher im allgemeinen Puffer aktiviert werden soll, der zugeordnet werden soll. Diese Entscheidung basiert auf der Prozessorarchitektur und dem Gerätebus.

Auf Computern mit x86-basierten, x64-basierten und Itanium-basierten Prozessoren ist zwischengespeicherter Arbeitsspeicher aktiviert. Auf Computern mit ARM- oder ARM 64-basierten Prozessoren aktiviert das Betriebssystem nicht automatisch zwischengespeicherten Arbeitsspeicher 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 im Cache kohärent ist.

Weitere Informationen zu allgemeinen Puffern finden Sie unter Verwenden von allgemeinen Puffern.

Beispiele

Im folgenden Codebeispiel wird eine WDF_COMMON_BUFFER_CONFIG-Struktur initialisiert und dann ein 10-Byte-Puffer erstellt, der an einer 32-Byte-Grenze 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	Universell
KMDF-Mindestversion	1.1
Kopfzeile	wdfcommonbuffer.h (einschließen von WdfCommonBuffer.h)
Bibliothek	Wdf01000.sys (siehe Versionsverwaltung der Frameworkbibliothek).)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)