PALLOCATE_COMMON_BUFFER Rückruffunktion (wdm.h)

Artikel
08/08/2023

Die AllocateCommonBuffer-Routine weist Arbeitsspeicher zu und ordnet ihn zu, sodass sowohl vom Prozessor als auch von einem Gerät für DMA-Vorgänge gleichzeitig darauf zugegriffen werden kann.

Syntax

PALLOCATE_COMMON_BUFFER PallocateCommonBuffer;

PVOID PallocateCommonBuffer(
  [in]  PDMA_ADAPTER DmaAdapter,
  [in]  ULONG Length,
  [out] PPHYSICAL_ADDRESS LogicalAddress,
  [in]  BOOLEAN CacheEnabled
)
{...}

Parameter

[in] DmaAdapter

Zeiger auf die DMA_ADAPTER-Struktur, die von IoGetDmaAdapter zurückgegeben wird und den Bus-master-Adapter oder DMA-Controller darstellt.

[in] Length

Gibt die Anzahl der zuzuordnenden Bytes an.

[out] LogicalAddress

Zeiger auf eine Variable, die die logische Adresse empfängt, die das Gerät für den Zugriff auf den zugeordneten Puffer verwenden kann. Verwenden Sie diese Adresse, anstatt MmGetPhysicalAddress aufzurufen, da das System plattformspezifische Speichereinschränkungen berücksichtigen kann.

[in] CacheEnabled

Gibt an, ob der zugeordnete Arbeitsspeicher zwischengespeichert werden kann.

Konvertiert die Zeichenfolgendarstellung einer Zahl in einem angegebenen Stil und einem kulturspezifischen Format in die entsprechende 32-Bit-Ganzzahl mit Vorzeichen. 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. Es wird davon ausgegangen, dass alle DMA-Vorgänge, die von einem Gerät ausgeführt werden, mit den relevanten CPU-Caches kohärent sind, was möglicherweise das Zwischenspeichern dieses Arbeitsspeichers ist. Wenn Ihr Treiber die Zwischenspeicherung deaktivieren muss, rufen Sie stattdessen AllocateCommonBufferEx auf.

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.

Rückgabewert

AllocateCommonBuffer gibt die virtuelle Basisadresse des zugeordneten Bereichs zurück. Wenn der Puffer nicht zugeordnet werden kann, wird NULL zurückgegeben.

Hinweise

AllocateCommonBuffer ist keine Systemroutine, die direkt nach Namen aufgerufen werden kann. Diese Routine kann nur durch den 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.

AllocateCommonBuffer unterstützt DMA, bei dem das Gerät und der Prozessor kontinuierlich über den Systemspeicher kommunizieren, wie in einer Steuerungsstruktur für ein Bus-master DMA-Gerät.

AllocateCommonBuffer unterstützt auch untergeordnete Geräte, deren Treiber den Autoinitialisierungsmodus eines System-DMA-Controllers verwenden.

AllocateCommonBuffer führt folgendes aus:

Ordnet Arbeitsspeicher zu, der sowohl vom Prozessor als auch vom Gerät aus erreicht werden kann. Dieser Arbeitsspeicher wird mit dem Gerät zusammenhängend angezeigt.
Ordnet Kartenregister zu, um den Puffer zuzuordnen, falls dies vom System erforderlich ist.
Richtet eine Übersetzung für das Gerät ein, einschließlich des Ladens von Kartenregistern bei Bedarf.

Um den Speicher des residenten Systems wirtschaftlich zu nutzen, sollten Treiber so wenige dieser Puffer pro Gerät wie möglich zuordnen. AllocateCommonBuffer weist mindestens eine Seite Arbeitsspeicher zu, unabhängig von der angeforderten Länge. Nach einer erfolgreichen Zuordnung, die weniger als PAGE_SIZE Bytes anfordert, kann der Aufrufer nur auf die angeforderte Länge zugreifen. Nach einer erfolgreichen Zuordnung, die mehr als ein integrales Vielfaches von PAGE_SIZE Bytes anfordert, kann der Aufrufer nicht auf alle verbleibenden Bytes auf der letzten zugeordneten Seite zugreifen.

Wenn ein Treiber mehrere Seiten gemeinsamen Pufferraums benötigt, die Seiten jedoch nicht zusammenhängend sein müssen, sollte der Treiber anstelle einer großen Anforderung mehrere One-Page-Anforderungen an AllocateCommonBuffer senden. Dieser Ansatz spart zusammenhängenden Speicher.

Treiber rufen in der Regel AllocateCommonBuffer als Teil des Gerätestarts auf, während sie auf eine PnP-IRP_MN_START_DEVICE-Anforderung reagieren. Nach dem Start ist es möglich, dass nur 1-Seiten-Anforderungen erfolgreich sind, falls vorhanden.

Anforderungen

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

Weitere Informationen