Fonction NtAllocateVirtualMemory (ntifs.h)

Article
07/11/2023

La routine NtAllocateVirtualMemory 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

__kernel_entry NTSYSCALLAPI NTSTATUS NtAllocateVirtualMemory(
  [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 BaseAddress 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 BaseAddress 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. Utilisé uniquement lorsque le système d’exploitation détermine où allouer la région, comme lorsque BaseAddress* a la valeur NULL. Notez que lorsque ZeroBits est supérieur à 32, il devient un masque de bits.

[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 RegionSize 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 pour la région de pages spécifiée. Le tableau suivant décrit les indicateurs les plus courants. Pour obtenir la liste complète des indicateurs et descriptions possibles, consultez VirtualAlloc .

Notes

L’un des MEM_COMMIT, MEM_RESET ou MEM_RESERVE doit être défini.

Indicateur	Signification
MEM_COMMIT	La région de pages spécifiée doit être validée.
MEM_RESERVE	La région de pages spécifiée doit être réservée.
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. Si MEM_RESET est défini, aucun autre indicateur ne peut être défini.
Autres indicateurs MEM_XXX	Consultez VirtualAlloc.

[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_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

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

STATUS_ACCESS_DENIED
STATUS_ALREADY_COMMITTED
STATUS_COMMITMENT_LIMIT
STATUS_CONFLICTING_ADDRESSES
STATUS_INSUFFICIENT_RESOURCES
STATUS_INVALID_HANDLE
STATUS_INVALID_PAGE_PROTECTION
STATUS_NO_MEMORY
STATUS_OBJECT_TYPE_MISMATCH
STATUS_PROCESS_IS_TERMINATING

Remarques

NtAllocateVirtualMemory peut effectuer les opérations suivantes :

Commitez une région de pages réservées par un appel précédent à NtAllocateVirtualMemory.
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 NtAllocateVirtualMemory pour réserver une plage d’adresses virtuelles accessibles aux applications dans le processus spécifié, puis effectuer des appels supplémentaires à NtAllocateVirtualMemory 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. NtAllocateVirtualMemory 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é. NtAllocateVirtualMemory peut valider une page réservée, mais il ne peut pas la réserver une deuxième fois. NtFreeVirtualMemory 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. NtAllocateVirtualMemory 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. NtFreeVirtualMemory peut désengager une page validée, libérer le stockage de la page, ou il peut simultanément déscommitre et libérer une page validée.

La mémoire allouée en appelant NtAllocateVirtualMemory doit être libérée en appelant NtFreeVirtualMemory.

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

Note Si l’appel à la fonction NtAllocateVirtualMemory 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	HwStorPortProhibitedDIS, PowerIrpDDis, SpNoWait, StorPortStartIo

Voir aussi

NtFreeVirtualMemory