PALLOCATE_COMMON_BUFFER_EX Rückruffunktion (wdm.h)

Artikel
02/27/2024

Die AllocateCommonBufferEx-Routine weist Arbeitsspeicher für einen gemeinsamen Puffer zu und ordnet diesen Speicher zu, sodass sowohl der Prozessor als auch ein Gerät, das DMA-Vorgänge ausführt, auf ihn zugreifen kann.

Syntax

PALLOCATE_COMMON_BUFFER_EX PallocateCommonBufferEx;

PVOID PallocateCommonBufferEx(
  [in]           PDMA_ADAPTER DmaAdapter,
  [in, optional] PPHYSICAL_ADDRESS MaximumAddress,
  [in]           ULONG Length,
  [out]          PPHYSICAL_ADDRESS LogicalAddress,
  [in]           BOOLEAN CacheEnabled,
  [in]           NODE_REQUIREMENT PreferredNode
)
{...}

Parameter

[in] DmaAdapter

Ein Zeiger auf eine DMA_ADAPTER Struktur. Diese Struktur ist das Adapterobjekt, das den Bus-master DMA-Gerät oder System-DMA-Kanal des Treibers darstellt. Der Aufrufer hat diesen Zeiger aus einem vorherigen Aufruf der IoGetDmaAdapter-Routine abgerufen.

[in, optional] MaximumAddress

Ein Zeiger auf eine Variable, die die maximale logische Adresse für den allgemeinen Puffer enthält. Dieser Parameter gibt an, dass der Puffer aus dem Speicher unterhalb dieser Adresse zugeordnet werden soll. Dieser Parameter ist optional und kann als NULL angegeben werden, um anzugeben, dass keine maximale Adresse vorhanden ist.

[in] Length

Die Größe des allgemeinen Puffers in Bytes, der für den DMA-Vorgang zugewiesen werden soll.

[out] LogicalAddress

Ein Zeiger auf eine Variable, in die diese Routine die logische Adresse schreibt, die das Gerät für den Zugriff auf den allgemeinen Puffer verwenden kann. Das DMA-Gerät sollte diese logische Adresse anstelle der physischen Adresse verwenden, die von einer Routine wie MmGetPhysicalAddress zurückgegeben wird.

[in] CacheEnabled

Gibt an, ob die Routine den zwischengespeicherten Speicher im zuzuordnenden allgemeinen Puffer aktivieren oder deaktivieren muss. Bei TRUE ist die Zwischenspeicherung aktiviert. Wenn FALSE, ist es deaktiviert. Wenn die Hardwareplattform keine Cachekohärenz für DMA-Vorgänge erzwingt, übergeben Sie FALSE. Informationen zu diesem Parameter auf ARM- oder ARM 64-basierten Prozessoren-Zielcomputern finden Sie unter Hinweise.

[in] PreferredNode

Der bevorzugte NUMA-Knoten, von dem aus der Arbeitsspeicher zugeordnet werden soll. Wenn N die Anzahl von NUMA-Knoten in einem Multiprozessorsystem ist, ist PreferredNode eine Zahl im Bereich 0 bis N–1. Legen Sie PreferredNode für ein System mit einem Prozessor oder ein Nicht-NUMA-Multiprozessorsystem auf Null fest.

Rückgabewert

AllocateCommonBufferEx gibt die virtuelle Adresse des Arbeitsspeichers zurück, der dem gemeinsamen Puffer zugeordnet ist. Wenn der Puffer nicht zugeordnet werden kann, wird NULL zurückgegeben.

Hinweise

AllocateCommonBufferEx ist keine Systemroutine, die direkt nach Name aufgerufen werden kann. Diese Routine kann nur durch zeiger von der Adresse aufgerufen werden, die in einer DMA_OPERATIONS-Struktur zurückgegeben wird. Treiber erhalten die Adresse dieser Routine, indem Sie IoGetDmaAdapter aufrufen, wobei das Versionselement des DeviceDescription-Parameters auf DEVICE_DESCRIPTION_VERSION3 festgelegt ist. Wenn IoGetDmaAdapterNULL zurückgibt, ist die Routine auf Ihrer Plattform nicht verfügbar.

AllocateCommonBufferEx ist eine erweiterte Version der AllocateCommonBuffer-Routine . In der folgenden Liste sind die Features zusammengefasst, die nur in der erweiterten Version verfügbar sind:

Der Aufrufer kann eine maximale logische Adresse für den allgemeinen Puffer angeben, der zugeordnet werden soll.
Der Aufrufer kann einen bevorzugten NUMA-Knoten angeben, in dem der allgemeine Puffer zugeordnet werden soll.

Auf Computern mit ARM- oder ARM 64-basierten Prozessoren haben Cacheeinstellungen im System ACPI eine höhere Priorität als der CacheEnabled-Parameterwert , der vom Treiber übergeben wird. Wenn die ACPI-_CCA-Methode angibt, dass das Gerät nicht im Cache kohärent ist, deaktiviert das Betriebssystem die Zwischenspeicherung, auch wenn der Treiber zwischengespeicherten Arbeitsspeicher mit cacheEnabled auf TRUE zuweist.

Auf Computern mit ARM- oder ARM 64-basierten Prozessoren weist das Betriebssystem einen nicht zwischengespeicherten gemeinsamen Puffer als Gerätespeicher zu. Weitere Informationen zum Puffer finden Sie in den Abschnitten A3.5.1 und A3.5.6 im Referenzhandbuch zur ARMv7-Architektur.

Der Prozessor lässt keinen falsch ausgerichteten Zugriff auf den Gerätespeicher zu. Ihr Treiber muss immer mithilfe von natürlich ausgerichteten Vorgängen auf Daten aus dem allgemeinen Puffer zugreifen. Die meisten Kernelroutinen akzeptieren den Gerätespeicher nicht als Eingabeparameter. Beispielsweise kann ein Netzwerktreiber den Gerätespeicher nicht an NdisMIndicateReceiveNetBufferLists übergeben. Wenn Ihr Treiber Daten aus einem allgemeinen DMA-Puffer an eine Kernelroutine übergeben muss, weisen Sie entweder den Puffer zu, wobei CacheEnabled auf TRUE festgelegt ist, oder kopieren Sie die Daten aus dem nicht zwischengespeicherten allgemeinen Puffer in eine temporäre Poolzuordnung.

Weitere Informationen zu DMA-Vorgängen, die einen allgemeinen Puffer verwenden, finden Sie in den folgenden Themen:

Verwenden allgemeiner Puffer

Verwenden Common-Buffer Bus-Master DMA

Verwenden Common-Buffer System-DMA

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 8.
Zielplattform	Desktop
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
IRQL	PASSIVE_LEVEL

Weitere Informationen