WdfCommonBufferCreateWithConfig-Funktion (wdfcommonbuffer.h)
[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 |
|---|---|
|
Der Treiber hat einen ungültigen Parameter angegeben. |
|
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.
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) |
Weitere Informationen
WdfCommonBufferGetAlignedLogicalAddress
WdfCommonBufferGetAlignedVirtualAddress