WdfCommonBufferCreate-Funktion (wdfcommonbuffer.h)

Artikel
08/08/2023

[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-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. Die maximal zulässige Puffergröße beträgt (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 Variable vom Typ WDFCOMMONBUFFER, die ein Handle auf ein allgemeines 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 keinen Puffer zuordnen.

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

Hinweise

Die WdfCommonBufferCreate-Methode ordnet 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. Nachdem Ihr Treiber WdfCommonBufferCreate 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 WdfCommonBufferCreate aus seiner Rückruffunktion EvtDriverDeviceAdd auf.

Bevor der Treiber WdfDmaEnablerCreate aufruft, kann er WdfDeviceSetAlignmentRequirement aufrufen, um eine Pufferausrichtungsanforderung festzulegen. Wenn der Treiber WdfDeviceSetAlignmentRequirement nicht aufruft, werden Puffer an Wortgrenzen ausgerichtet. Wenn Ihr Treiber mehrere DMA-Aktivierungsmodule erstellt, die jeweils eine andere Pufferausrichtung erfordern, kann der Treiber WdfDeviceSetAlignmentRequirement vor jedem Aufruf von WdfDmaEnablerCreate aufrufen.

Um einen allgemeinen Puffer mit einer Ausrichtungsanforderung zu erstellen, die sich von der Ausrichtungsanforderung unterscheidet, die der Treiber mit WdfDeviceSetAlignmentRequirement angegeben hat, kann der Treiber WdfCommonBufferCreateWithConfig anstelle von WdfCommonBufferCreateCreate aufrufen.

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.

Das DMA-Enabler-Objekt, das der DmaEnabler-Parameter von WdfCommonBufferCreate angibt, wird zum übergeordneten Objekt für das neue allgemeine Pufferobjekt. Der Treiber kann dieses übergeordnete Element nicht ändern, und das ParentObject-Element 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 WdfObjectDelete aufrufen.

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

Beispiele

Im folgenden Codebeispiel wird gezeigt, wie Sie einen gemeinsamen Puffer abrufen. Im Beispiel werden Informationen zum allgemeinen Puffer im vom Treiber definierten Kontextbereich gespeichert, der durch den 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	Universell
KMDF-Mindestversion	1.0
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)