ZwAllocateVirtualMemory-Funktion (ntifs.h)

Artikel
02/26/2024

Die ZwAllocateVirtualMemory-Routine reserviert, commitsiert oder beides einen Bereich von Seiten innerhalb des virtuellen Adressraums für den Benutzermodus eines angegebenen Prozesses.

Syntax

NTSYSAPI NTSTATUS ZwAllocateVirtualMemory(
  [in]      HANDLE    ProcessHandle,
  [in, out] PVOID     *BaseAddress,
  [in]      ULONG_PTR ZeroBits,
  [in, out] PSIZE_T   RegionSize,
  [in]      ULONG     AllocationType,
  [in]      ULONG     Protect
);

Parameter

[in] ProcessHandle

Ein Handle für den Prozess, für den die Zuordnung durchgeführt werden soll. Verwenden Sie das in Ntddk.h definierte NtCurrentProcess-Makro , um den aktuellen Prozess anzugeben.

[in, out] BaseAddress

Ein Zeiger auf eine Variable, die die Basisadresse des zugeordneten Seitenbereichs empfängt. Wenn der Anfangswert dieses Parameters ungleich NULL ist, wird der Bereich ab der angegebenen virtuellen Adresse zugeordnet, die auf die nächste Adressgrenze der Hostseite gerundet wird. Wenn der Anfangswert dieses Parameters NULL ist, bestimmt das Betriebssystem, wo die Region zugeordnet werden soll.

[in] ZeroBits

Die Anzahl der Adressbits hoher Reihenfolge, die in der Basisadresse der Abschnittsansicht null sein müssen. Dieser Wert muss kleiner als 21 sein und wird nur verwendet, wenn das Betriebssystem bestimmt, wo die Region zugeordnet werden soll, z. B. wenn BaseAddressNULL ist.

[in, out] RegionSize

Ein Zeiger auf eine Variable, die die tatsächliche Größe des zugeordneten Bereichs von Seiten in Byte empfängt. Der Anfangswert dieses Parameters gibt die Größe des Bereichs in Bytes an und wird auf die nächste Größengrenze der Hostseite aufgerundet. *RegionSize darf bei Eingaben nicht null sein.

[in] AllocationType

Eine Bitmaske, die Flags enthält, die den Typ der auszuführenden Zuordnung angeben. In der folgenden Tabelle werden diese Flags beschrieben.

Flag	Bedeutung
MEM_COMMIT	Der angegebene Bereich von Seiten muss committet werden. Eine der MEM_COMMIT, MEM_RESET oder MEM_RESERVE muss festgelegt werden.
MEM_PHYSICAL	Ordnen Sie physischen Arbeitsspeicher zu. Dieses Flag ist ausschließlich für die Verwendung mit AWE-Speicher (Address Windowing Extensions) vorgesehen. Wenn MEM_PHYSICAL festgelegt ist, muss auch MEM_RESERVE festgelegt werden, andere Flags dürfen nicht festgelegt werden, und Schützen muss auf PAGE_READWRITE festgelegt werden.
MEM_RESERVE	Der angegebene Bereich von Seiten muss reserviert werden. Eine der MEM_COMMIT, MEM_RESET oder MEM_RESERVE muss festgelegt werden.
MEM_RESET	Setzen Sie den Zustand des angegebenen Bereichs zurück, sodass seiten, wenn sie sich in der Auslagerungsdatei befinden, verworfen und Seiten mit Nullen angezeigt werden. Wenn sich die Seiten im Arbeitsspeicher befinden und geändert werden, werden sie als nicht geändert markiert, sodass sie nicht in die Auslagerungsdatei geschrieben werden. Der Inhalt wird nicht auf null gesetzt. Der Protect-Parameter wird nicht verwendet, muss aber auf einen gültigen Wert festgelegt werden. Eine der MEM_COMMIT, MEM_RESET oder MEM_RESERVE muss festgelegt werden. wenn MEM_RESET festgelegt ist, kann kein anderes Flag festgelegt werden.
MEM_TOP_DOWN	Die angegebene Region sollte mit der höchsten möglichen virtuellen Adresse basierend auf ZeroBits erstellt werden.

[in] Protect

Eine Bitmaske, die Seitenschutzflags enthält, die den gewünschten Schutz für den committeten Bereich von Seiten angeben. In der folgenden Tabelle werden diese Flags beschrieben.

Flag	Bedeutung
PAGE_NOACCESS	Es ist kein Zugriff auf den committeten Bereich der Seiten zulässig. Ein Versuch, die committete Region zu lesen, zu schreiben oder auszuführen, führt zu einer Zugriffsverletzungs-Ausnahme, die als Allgemeiner Schutzfehler (GP) bezeichnet wird.
PAGE_READONLY	Schreibgeschützt und der Ausführungszugriff auf den committeten Bereich von Seiten ist zulässig. Ein Versuch, die committete Region zu schreiben, führt zu einer Zugriffsverletzung.
PAGE_READWRITE	Lese-, Schreib- und Ausführungszugriff auf den committeten Bereich von Seiten ist zulässig. Wenn Schreibzugriff auf den zugrunde liegenden Abschnitt zulässig ist, wird eine einzelne Kopie der Seiten freigegeben. Andernfalls werden die Seiten beim Schreiben schreibgeschützter/kopiert freigegeben.
PAGE_EXECUTE	Ausführen des Zugriffs auf den committeten Bereich von Seiten ist zulässig. Ein Versuch, den committeten Bereich zu lesen oder zu schreiben, führt zu einer Zugriffsverletzung.
PAGE_EXECUTE_READ	Der Ausführungs- und Lesezugriff auf den committeten Bereich von Seiten ist zulässig. Ein Versuch, in die region zu schreiben, führt zu einer Zugriffsverletzung.
PAGE_EXECUTE_READWRITE	Ausführungs-, Lese- und Schreibzugriff auf den committeten Bereich von Seiten ist zulässig.
PAGE_GUARD	Seiten in der Region werden zu Schutzseiten. Jeder Versuch, aus einer Schutzseite zu lesen oder darauf zu schreiben, führt dazu, dass das System eine STATUS_GUARD_PAGE Ausnahme auslöst. Schutzseiten fungieren somit als One-Shot-Zugriffsalarm. Dieses Flag ist ein Seitenschutzmodifizierer, der nur gültig ist, wenn es mit einem der anderen Seitenschutzflags als PAGE_NOACCESS verwendet wird. Wenn ein Zugriffsversuch dazu führt, dass das System die Schutzseite status deaktiviert, übernimmt der zugrunde liegende Seitenschutz. Wenn während eines Systemdiensts eine Ausnahme für eine Schutzseite auftritt, gibt der Dienst in der Regel einen Fehler status Indikator zurück.
PAGE_NOCACHE	Der Bereich der Seiten sollte als nicht zwischenspeicherbar zugeordnet werden. PAGE_NOCACHE ist für Abschnitte nicht zulässig.
PAGE_WRITECOMBINE	Ermöglicht das Kombinieren von Schreibvorgängen, d. h. das Zusammenführen von Schreibvorgängen aus dem Cache in Standard Arbeitsspeicher, wo dies von der Hardware unterstützt wird. Dieses Flag wird hauptsächlich für den Framepufferspeicher verwendet, sodass Schreibvorgänge in die gleiche Cachezeile nach Möglichkeit kombiniert werden, bevor sie auf das Gerät geschrieben werden. Dadurch können Schreibvorgänge über den Bus in den Videospeicher (z. B.) erheblich reduziert werden. Wenn die Hardware das Kombinieren von Schreibvorgängen nicht unterstützt, wird das Flag ignoriert. Dieses Flag ist ein Seitenschutzmodifizierer, der nur gültig ist, wenn es mit einem der anderen Seitenschutzflags als PAGE_NOACCESS verwendet wird.

Rückgabewert

ZwAllocateVirtualMemory gibt entweder STATUS_SUCCESS oder einen Fehler status Code zurück. Mögliche Fehler status Codes:

Hinweise

ZwAllocateVirtualMemory kann die folgenden Vorgänge ausführen:

Committen Sie einen Bereich von Seiten, die durch einen vorherigen Aufruf von ZwAllocateVirtualMemory reserviert wurden.
Reservieren Sie eine Region mit kostenlosen Seiten.
Reservieren und Committen einer Region mit kostenlosen Seiten.

Kernelmodustreiber können ZwAllocateVirtualMemory verwenden, um einen Bereich von virtuellen Adressen zu reservieren, auf die im angegebenen Prozess zugegriffen werden kann, und dann zusätzliche Aufrufe an ZwAllocateVirtualMemory durchführen, um einzelne Seiten aus dem reservierten Bereich zu committen. Dadurch kann ein Prozess einen Bereich des virtuellen Adressraums reservieren, ohne physischen Speicher zu verwenden, bis er benötigt wird.

Jede Seite im virtuellen Adressraum des Prozesses befindet sich in einem der drei in der folgenden Tabelle beschriebenen Zustände.

State	Bedeutung
FREE	Die Seite ist nicht committet oder reserviert und für den Prozess nicht zugänglich. ZwAllocateVirtualMemory kann eine kostenlose Seite reservieren oder gleichzeitig reservieren und commiten.
RESERVIERT	Der Adressbereich kann nicht von anderen Zuordnungsfunktionen verwendet werden, aber der Prozess kann nicht auf die Seite zugreifen und verfügt über keinen physischen Speicher. ZwAllocateVirtualMemory kann eine reservierte Seite committen, aber nicht ein zweites Mal reservieren. ZwFreeVirtualMemory kann eine reservierte Seite freigeben, was sie zu einer kostenlosen Seite macht.
COMMITTET	Physischer Speicher wird für die Seite zugewiesen, und der Zugriff wird durch einen Schutzcode gesteuert. Das System initialisiert und lädt jede zugesagte Seite erst beim ersten Versuch, diese Seite zu lesen oder zu schreiben, in den physischen Arbeitsspeicher. Wenn der Prozess beendet wird, gibt das System den Speicher für verpflichtete Seiten frei. ZwAllocateVirtualMemory kann eine bereits zugesagte Seite committen. Dies bedeutet, dass Sie einen Bereich von Seiten committen können, unabhängig davon, ob sie bereits committet wurden, und die Funktion nicht fehlschlägt. ZwFreeVirtualMemory kann eine committete Seite aufheben, den Speicher der Seite freigeben oder gleichzeitig die Aussetzung und Freigabe einer gebundenen Seite aufheben.

Durch aufrufen von ZwAllocateVirtualMemory zugewiesener Arbeitsspeicher muss durch Aufrufen von ZwFreeVirtualMemory freigegeben werden.

Weitere Informationen zur Speicherverwaltung finden Sie unter Arbeitsspeicherverwaltung für Windows-Treiber.

Hinweis

Wenn der Aufruf der ZwAllocateVirtualMemory-Funktion im Benutzermodus erfolgt, sollten Sie den Namen "NtAllocateVirtualMemory" anstelle von "ZwAllocateVirtualMemory" verwenden.

Bei Aufrufen von Kernelmodustreibern können sich die NtXxx - und ZwXxx-Versionen einer Windows Native System Services-Routine anders verhalten, da sie Eingabeparameter verarbeiten und interpretieren. Weitere Informationen zur Beziehung zwischen den Nt Xxx- und ZwXxx-Versionen einer Routine finden Sie unter Verwenden von Nt- und Zw-Versionen der Systemdienstroutinen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000
Zielplattform	Universell
Header	ntifs.h (include Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm), SpNoWait(storport), StorPortStartIo(storport)

Weitere Informationen

Verwenden von Nt- und Zw-Versionen der Systemdienstroutinen

ZwFreeVirtualMemory