Fonction ZwAllocateVirtualMemory (ntifs.h)

Article
08/07/2023

La routine ZwAllocateVirtualMemory réserve, valide ou les deux, une région de pages dans l’espace d’adressage virtuel en mode utilisateur d’un processus spécifié.

Syntaxe

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
);

Paramètres

[in] ProcessHandle

Handle pour le processus pour lequel le mappage doit être effectué. Utilisez la macro NtCurrentProcess , définie dans Ntddk.h, pour spécifier le processus actuel.

[in, out] BaseAddress

Pointeur vers une variable qui recevra l’adresse de base de la région de pages allouée. Si la valeur initiale de ce paramètre n’est pas NULL, la région est allouée à partir de l’adresse virtuelle spécifiée arrondie à la limite d’adresse de taille de page hôte suivante. Si la valeur initiale de ce paramètre est NULL, le système d’exploitation détermine où allouer la région.

[in] ZeroBits

Nombre de bits d’adresse d’ordre élevé qui doivent être zéro dans l’adresse de base de la vue de section. Cette valeur doit être inférieure à 21 et n’est utilisée que lorsque le système d’exploitation détermine où allouer la région, comme lorsque BaseAddress a la valeur NULL.

[in, out] RegionSize

Pointeur vers une variable qui recevra la taille réelle, en octets, de la région allouée des pages. La valeur initiale de ce paramètre spécifie la taille, en octets, de la région et est arrondie à la limite de taille de page hôte suivante. *RegionSize ne peut pas être égal à zéro en entrée.

[in] AllocationType

Masque de bits contenant des indicateurs qui spécifient le type d’allocation à effectuer. Le tableau suivant décrit ces indicateurs.

Indicateur	Signification
MEM_COMMIT	La région de pages spécifiée doit être validée. L’un des MEM_COMMIT, MEM_RESET ou MEM_RESERVE doit être défini.
MEM_PHYSICAL	Allouez de la mémoire physique. Cet indicateur est uniquement destiné à être utilisé avec la mémoire AWE (Address Windowing Extensions). Si MEM_PHYSICAL est défini, MEM_RESERVE doit également être défini, aucun autre indicateur ne peut être défini et La protection doit être définie sur PAGE_READWRITE.
MEM_RESERVE	La région de pages spécifiée doit être réservée. L’un des MEM_COMMIT, MEM_RESET ou MEM_RESERVE doit être défini.
MEM_RESET	Réinitialisez l’état de la région spécifiée afin que si les pages se trouvent dans un fichier de pagination, elles soient ignorées et que les pages de zéros soient apportées. Si les pages sont en mémoire et modifiées, elles sont marquées comme non modifiées afin qu’elles ne soient pas écrites dans le fichier de pagination. Le contenu n’est pas mis à zéro. Le paramètre Protect n’est pas utilisé, mais il doit être défini sur une valeur valide. L’un des MEM_COMMIT, MEM_RESET ou MEM_RESERVE doit être défini ; si MEM_RESET est défini, aucun autre indicateur ne peut être défini.
MEM_TOP_DOWN	La région spécifiée doit être créée à l’adresse virtuelle la plus élevée possible en fonction de ZeroBits.

[in] Protect

Masque de bits contenant des indicateurs de protection de page qui spécifient la protection souhaitée pour la région validée des pages. Le tableau suivant décrit ces indicateurs.

Indicateur	Signification
PAGE_NOACCESS	Aucun accès à la région validée des pages n’est autorisé. Une tentative de lecture, d’écriture ou d’exécution de la région validée entraîne une exception de violation d’accès, appelée erreur de protection générale (GP).
PAGE_READONLY	L’accès en lecture seule et l’exécution à la région validée des pages sont autorisés. Une tentative d’écriture de la région validée entraîne une violation d’accès.
PAGE_READWRITE	L’accès en lecture, écriture et exécution à la région validée des pages est autorisé. Si l’accès en écriture à la section sous-jacente est autorisé, une seule copie des pages est partagée. Sinon, les pages sont partagées en lecture seule/copie en écriture.
PAGE_EXECUTE	L’exécution de l’accès à la région validée des pages est autorisé. Une tentative de lecture ou d’écriture dans la région validée entraîne une violation d’accès.
PAGE_EXECUTE_READ	L’exécution et l’accès en lecture à la région validée des pages sont autorisés. Une tentative d’écriture dans la région validée entraîne une violation d’accès.
PAGE_EXECUTE_READWRITE	L’accès d’exécution, de lecture et d’écriture à la région validée des pages est autorisé.
PAGE_GUARD	Les pages de la région deviennent des pages de protection. Toute tentative de lecture ou d’écriture dans une page de protection entraîne le déclenchement d’une exception STATUS_GUARD_PAGE. Les pages de protection agissent donc comme une alarme d’accès one-shot. Cet indicateur est un modificateur de protection de page, valide uniquement lorsqu’il est utilisé avec l’un des indicateurs de protection de page autres que PAGE_NOACCESS. Lorsqu’une tentative d’accès conduit le système à désactiver la page de protection status, la protection de la page sous-jacente prend le relais. Si une exception de page de protection se produit pendant un service système, le service retourne généralement une défaillance status indicateur.
PAGE_NOCACHE	La région des pages doit être allouée en tant que non-mise en cache. PAGE_NOCACHE n’est pas autorisé pour les sections.
PAGE_WRITECOMBINE	Permet la combinaison d’écritures, c’est-à-dire la fusion des écritures du cache vers main mémoire, où le matériel les prend en charge. Cet indicateur est principalement utilisé pour la mémoire tampon d’image afin que les écritures sur la même ligne de cache soient combinées dans la mesure du possible avant d’être écrites sur l’appareil. Cela peut considérablement réduire les écritures dans le bus à la mémoire vidéo (par exemple). Si le matériel ne prend pas en charge la combinaison d’écritures, l’indicateur est ignoré. Cet indicateur est un modificateur de protection de page, valide uniquement lorsqu’il est utilisé avec l’un des indicateurs de protection de page autres que PAGE_NOACCESS.

Valeur retournée

ZwAllocateVirtualMemory retourne STATUS_SUCCESS ou une erreur status code. Les codes de status d’erreur possibles incluent les éléments suivants :

Remarques

ZwAllocateVirtualMemory peut effectuer les opérations suivantes :

Commitez une région de pages réservées par un appel précédent à ZwAllocateVirtualMemory.
Réservez une région de pages gratuites.
Réserver et valider une région de pages libres.

Les pilotes en mode noyau peuvent utiliser ZwAllocateVirtualMemory pour réserver une plage d’adresses virtuelles accessibles aux applications dans le processus spécifié, puis effectuer des appels supplémentaires à ZwAllocateVirtualMemory pour valider des pages individuelles à partir de la plage réservée. Cela permet à un processus de réserver une plage de son espace d’adressage virtuel sans consommer de stockage physique jusqu’à ce qu’il soit nécessaire.

Chaque page de l’espace d’adressage virtuel du processus se trouve dans l’un des trois états décrits dans le tableau suivant.

State	Signification
FREE	La page n’est pas validée ou réservée et n’est pas accessible au processus. ZwAllocateVirtualMemory peut réserver, ou simultanément réserver et valider, une page gratuite.
RÉSERVÉ	La plage d’adresses ne peut pas être utilisée par d’autres fonctions d’allocation, mais la page n’est pas accessible au processus et n’a aucun stockage physique associé. ZwAllocateVirtualMemory peut valider une page réservée, mais il ne peut pas la réserver une deuxième fois. ZwFreeVirtualMemory peut libérer une page réservée, ce qui en fait une page gratuite.
ENGAGÉS	Le stockage physique est alloué à la page et l’accès est contrôlé par un code de protection. Le système initialise et charge chaque page validée dans la mémoire physique uniquement à la première tentative de lecture ou d’écriture dans cette page. À l’arrêt du processus, le système libère le stockage pour les pages validées. ZwAllocateVirtualMemory peut valider une page déjà validée. Cela signifie que vous pouvez valider une plage de pages, qu’elles aient déjà été validées ou non, et que la fonction n’échoue pas. ZwFreeVirtualMemory peut désengager une page validée, libérer le stockage de la page, ou il peut simultanément désengager et libérer une page validée.

La mémoire allouée en appelant ZwAllocateVirtualMemory doit être libérée en appelant ZwFreeVirtualMemory.

Pour plus d’informations sur la gestion de la mémoire, consultez Gestion de la mémoire pour les pilotes Windows.

Notes

Si l’appel à la fonction ZwAllocateVirtualMemory se produit en mode utilisateur, vous devez utiliser le nom « NtAllocateVirtualMemory » au lieu de « ZwAllocateVirtualMemory ».

Pour les appels à partir de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment dans la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Utilisation des versions Nt et Zw des routines des services système natifs.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000
Plateforme cible	Universal
En-tête	ntifs.h (inclure Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport),PowerIrpDDis(wdm),SpNoWait(storport), StorPortStartIo(storport)

Voir aussi

Utilisation des versions Nt et Zw des routines natives des services système natifs

ZwFreeVirtualMemory