PALLOCATE_COMMON_BUFFER_EX Rückruffunktion (wdm.h)
Die AllocateCommonBufferEx Routine weist Speicher für einen gemeinsamen Puffer zu und ordnet diesen Speicher zu, sodass sowohl vom Prozessor als auch von einem Gerät, das DMA-Vorgänge ausführt, darauf zugegriffen werden 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 das Busmaster-DMA-Gerät oder den DMA-Kanal des Treibers darstellt. Der Aufrufer hat diesen Zeiger aus einem vorherigen Aufruf an die 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 unter dieser Adresse aus dem Speicher zugewiesen 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 zugeordnet 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 MmGetPhysicalAddresszurückgegeben wird.
[in] CacheEnabled
Gibt an, ob die Routine zwischengespeicherten Speicher im allgemeinen Puffer aktivieren oder deaktivieren muss, der zugewiesen werden soll. Wenn WAHR, ist die Zwischenspeicherung aktiviert. Wenn FALSE, ist sie deaktiviert. Wenn die Hardwareplattform die Cachekoherenz für DMA-Vorgänge nicht erzwingt, übergeben Sie FALSE. Informationen zu diesem Parameter auf ARM- oder ARM 64-basierten Prozessoren auf Zielcomputern finden Sie in den Hinweisen.
[in] PreferredNode
Der bevorzugte NUMA-Knoten, von dem der Speicher zugewiesen 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 für ein 1-Prozessorsystem oder ein Nicht-NUMA-Multiprozessorsystem PreferredNode- auf Null fest.
Rückgabewert
AllocateCommonBufferEx gibt die virtuelle Adresse des für den allgemeinen Puffer zugewiesenen Speichers zurück. Wenn der Puffer nicht zugeordnet werden kann, wird NULL zurückgegeben.
Bemerkungen
AllocateCommonBufferEx ist keine Systemroutine, die direkt nach Namen aufgerufen werden kann. Diese Routine kann nur durch Zeiger von der in einer DMA_OPERATIONS Struktur zurückgegebenen Adresse aufgerufen werden. Treiber rufen die Adresse dieser Routine ab, indem sie IoGetDmaAdapter- mit dem Versionselement des DeviceDescription--Parameters aufrufen, der 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 zugewiesen werden soll.
Der Aufrufer kann einen bevorzugten NUMA-Knoten angeben, in dem der allgemeine Puffer zugewiesen werden soll.
Auf Computern mit ARM- oder ARM 64-basierten Prozessoren haben Cacheeinstellungen im System ACPI eine höhere Priorität als der vom Treiber übergebene CacheEnabled Parameterwert. Wenn die ACPI-_CCA-Methode angibt, dass das Gerät nicht kohärent ist, deaktiviert das Betriebssystem die Zwischenspeicherung, auch wenn der Treiber zwischengespeicherten Speicher zuweist, wobei CacheEnabled auf TRUE festgelegt ist.
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 aus dem ARMv7 Architecture Reference Manual.
Der Prozessor lässt keinen falsch ausgerichteten Zugriff auf den Gerätespeicher zu. Ihr Treiber muss immer auf Daten aus dem allgemeinen Puffer zugreifen, indem natürlich ausgerichtete Vorgänge verwendet werden. 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 den Puffer entweder mit CacheEnabled zu, auf TRUE festgelegt ist, oder kopieren Sie die Daten aus dem nicht zwischengespeicherten gemeinsamen Puffer in eine temporäre Poolzuordnung.
Weitere Informationen zu DMA-Vorgängen, die einen allgemeinen Puffer verwenden, finden Sie in den folgenden Themen:
Verwenden von allgemeinen Puffern
Verwenden Common-Buffer Bus-Master DMA-
Verwenden Common-Buffer System-DMA-
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Verfügbar ab Windows 8. |
| Zielplattform- | Desktop |
| Header- | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL- | PASSIVE_LEVEL |