MapUserPhysicalPages-Funktion (memoryapi.h)

Artikel
03/01/2024

Ordnet zuvor physische Speicherseiten an einer angegebenen Adresse in einer AWE-Region ( Address Windowing Extensions ) zu.

Verwenden Sie die MapUserPhysicalPagesScatter-Funktion , um die Batchzuordnung und das Aufheben der Belegung mehrerer Regionen durchzuführen.

64-Bit-Windows auf Itanium-basierten Systemen: Aufgrund der unterschiedlichen Seitengrößen wird MapUserPhysicalPages für 32-Bit-Anwendungen nicht unterstützt.

Syntax

BOOL MapUserPhysicalPages(
  [in] PVOID      VirtualAddress,
  [in] ULONG_PTR  NumberOfPages,
  [in] PULONG_PTR PageArray
);

Parameter

[in] VirtualAddress

Ein Zeiger auf die Startadresse des Speicherbereichs, der neu zugeordnet werden soll.

Der Wert von lpAddress muss sich innerhalb des Adressbereichs befinden, den die VirtualAlloc-Funktion zurückgibt, wenn die Region Adressfenstererweiterungen (Address Windowing Extensions , AWE) zugeordnet wird.

[in] NumberOfPages

Die Größe des physischen Arbeitsspeichers und des virtuellen Adressraums, für den Übersetzungen in Seiten erstellt werden sollen.

Der virtuelle Adressbereich ist ab lpAddress zusammenhängend. Die physischen Frames werden vom UserPfnArray angegeben.

Die Gesamtanzahl der Seiten darf von der Startadresse nicht über das Ende des bereichs hinausgehen, der in AllocateUserPhysicalPages angegeben ist.

[in] PageArray

Ein Zeiger auf ein Array von physischen Seitenrahmennummern.

Diese Frames werden durch das Argument lpAddress zugeordnet, wenn sie von dieser Funktion zurückgegeben werden. Die Größe des zugeordneten Arbeitsspeichers sollte mindestens die NumberOfPages-Malgröße des Datentyps ULONG_PTR sein.

Versuchen Sie nicht, diesen Puffer zu ändern. Es enthält Betriebssystemdaten, und eine Beschädigung kann katastrophal sein. Die Informationen im Puffer sind für eine Anwendung nicht nützlich.

Wenn dieser Parameter NULL ist, wird der angegebene Adressbereich nicht zugeordnet. Außerdem werden die angegebenen physischen Seiten nicht freigegeben, und Sie müssen FreeUserPhysicalPages aufrufen, um sie freizugeben.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert TRUE.

Wenn die Funktion fehlschlägt, ist der Rückgabewert FALSE , und es wird keine Zuordnung durchgeführt – teilweise oder anderweitig. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die physischen Seiten sind nicht zugeordnet, aber nicht freigegeben. Sie müssen FreeUserPhysicalPages aufrufen, um die physischen Seiten freizugeben.

Es kann eine beliebige Anzahl von Seiten des physischen Arbeitsspeichers angegeben werden, aber der Arbeitsspeicher darf sich nicht außerhalb des virtuellen Adressraums erstrecken, den VirtualAlloc zuweist. Vorhandene Adresszuordnungen werden automatisch mit den neuen Übersetzungen überschrieben, und die alten Übersetzungen werden nicht zugeordnet.

Sie können keine physischen Speicherseiten außerhalb des bereichs zuordnen, der in AllocateUserPhysicalPages angegeben ist. Sie können mehrere Regionen gleichzeitig zuordnen, aber sie können sich nicht überlappen.

Physische Seiten können sich an jeder physischen Adresse befinden, aber machen Sie keine Annahmen über die Kontinuität der physischen Seiten.

Um die Zuordnung des aktuellen Adressbereichs aufzuheben, geben Sie NULL als Arrayparameter für den physischen Speicher an. Alle aktuell zugeordneten Seiten sind nicht zugeordnet, werden aber nicht freigegeben. Sie müssen FreeUserPhysicalPages aufrufen, um die physischen Seiten freizugeben.

In einer Multiprozessorumgebung behält diese Funktion die Kohärenz des Hardwareübersetzungspuffers bei. Wenn sie von dieser Funktion zurückgegeben werden, wird garantiert, dass alle Threads auf allen Prozessoren die richtige Zuordnung sehen.

Um eine Anwendung zu kompilieren, die diese Funktion verwendet, definieren Sie das _WIN32_WINNT Makro als 0x0500 oder höher. Weitere Informationen finden Sie unter Verwenden der Windows-Header.

Beispiele

Ein Beispiel finden Sie unter AWE-Beispiel.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	memoryapi.h (einschließlich Windows.h, Memoryapi.h)
Bibliothek	onecore.lib
DLL	Kernel32.dll