> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # XMemVirtualAlloc > XMemVirtualAlloc # XMemVirtualAlloc Réserve, valide ou modifie l'état d'une région de pages dans l'espace d'adressage virtuel du processus appelant. Contrairement à la fonction Win32 standard VirtualAlloc, il n'est *pas* garanti que la mémoire allouée par cette fonction soit automatiquement initialisée à zéro. ## Syntaxe ```cpp theme={null} PVOID XMemVirtualAlloc( PVOID BaseAddress, SIZE_T Size, DWORD AllocationType, ULONGLONG XMemFlags, DWORD PageProtection ) ``` ### Paramètres *BaseAddress* \_In\_opt\_
Type : PVOID Adresse de départ de la région à allouer. Si la mémoire est en cours de réservation, l'adresse spécifiée est arrondie au multiple inférieur le plus proche de la granularité d'allocation (4K, 64K ou 2 Mo sur XBOX). Si la mémoire est déjà réservée et en cours de validation, l'adresse est arrondie à la limite de page inférieure. Si ce paramètre a la valeur NULL, le système détermine où allouer la région.
*Size* \_In\_
Type : SIZE\_T Taille de la région, en octets. Si le paramètre *BaseAddress* a la valeur NULL, cette valeur est arrondie à la limite de page supérieure. Sinon, les pages allouées incluent toutes les pages contenant un ou plusieurs octets de la plage allant de *BaseAddress* à *BaseAddress*+*Size*. Cela signifie qu'une plage de 2 octets chevauchant une limite de page entraîne l'inclusion des deux pages dans la région allouée.
*AllocationType* \_In\_
Type : DWORD Type d'allocation de mémoire. Ce paramètre doit contenir l'une des valeurs suivantes. | Valeur | Signification | | | - | - | - | | **MEM\_COMMIT**
0x00001000 | Alloue des charges de mémoire (à partir de la taille globale de la mémoire) pour les pages de mémoire réservées spécifiées. Pour réserver et valider des pages en une seule étape, appelez **XMemVirtualAlloc** avec \`MEM\_COMMIT | MEM\_RESERVE\`.
Toute tentative de validation d'une plage d'adresses spécifique en spécifiant **MEM\_COMMIT** sans **MEM\_RESERVE** et avec une valeur *BaseAddress* non NULL échoue, sauf si la plage entière a déjà été réservée. Le code d'erreur obtenu est **ERROR\_INVALID\_ADDRESS**.
Une tentative de validation d'une page déjà validée n'entraîne pas l'échec de la fonction. Cela signifie que vous pouvez valider des pages sans déterminer au préalable l'état de validation actuel de chaque page. | | **MEM\_RESERVE**
0x00002000 | Réserve une plage de l'espace d'adressage virtuel du processus sans allouer de stockage physique réel en mémoire. Vous pouvez valider les pages réservées lors d'appels ultérieurs à la fonction **XMemVirtualAlloc**, ou mapper directement des pages physiques à l'aide de **XMemMapPhysicalPages**.
Les autres fonctions d'allocation de mémoire, telles que **malloc** et **new**, ne peuvent pas utiliser une plage de mémoire réservée tant qu'elle n'est pas libérée.

Notez que le nouveau gestionnaire de mémoire du *Microsoft Game Development Kit (GDK)* sur XBOX exige des paramètres de protection de page et de cohérence de cache au moment de la réservation ; il s'agit d'un changement par rapport à la version précédente du système d'exploitation XBOX. | | | **MEM\_RESERVE\_PLACEHOLDER**
0x00040000 | Un espace réservé réserve des adresses virtuelles, mais ne verrouille pas l'adresse virtuelle sur une taille de page ou une protection de page. La taille de page et la protection de page sont choisies lors du remplacement de l'espace réservé par une réservation ou une validation réelle à l'aide de **MEM\_REPLACE\_PLACEHOLDER**. Pour créer un espace réservé, appelez **XMemVirtualAlloc** avec **MEM\_RESERVE \| MEM\_RESERVE\_PLACEHOLDER** et PageProtection défini sur **PAGE\_NOACCESS**. L'utilisation de **MEM\_RESERVE\_PLACEHOLDER** renvoie toujours une adresse alignée sur 2 Mo afin de garantir qu'elle puisse être utilisée ultérieurement avec **MEM\_2MB\_PAGES**. Toutefois, une fois réservé, l'espace réservé peut être fractionné à n'importe quelle granularité (4K, 64K ou 2 Mo) à l'aide de VirtualFree avec **MEM\_RELEASE \| MEM\_PRESERVE\_PLACEHOLDER**. | | | **MEM\_REPLACE\_PLACEHOLDER**
0x00004000 | Remplace un espace réservé par une allocation privée normale. Lorsque vous remplacez un espace réservé, BaseAddress et Size doivent correspondre exactement à ceux de l'espace réservé. Après avoir remplacé un espace réservé par une allocation privée, pour libérer cette allocation et revenir à un espace réservé, consultez le paramètre **dwFreeType** de **VirtualFree** et **VirtualFreeEx**. | | Ce paramètre peut également spécifier les valeurs suivantes, comme indiqué. | Valeur | Signification | | - | - | | **MEM\_2MB\_PAGES**
0x20000000 | Spécifie une taille de page de 2 Mo. | | **MEM\_64K\_PAGES**
0x20400000 | Spécifie une taille de page de 64K. | Pour les titres ERA, **MEM\_LARGE\_PAGES** représentait des pages de 64K, et sur le bureau Windows, il représente des pages de 2 Mo. En raison de cette ambiguïté, il a été supprimé pour le *Microsoft Game Development Kit (GDK)*.
*XMemFlags* \_In\_
Type : ULONGLONG Utilisé sur XBOX pour obtenir certains types de mémoire spécialisés. Ce paramètre doit contenir l'une des valeurs suivantes. | Valeur | Signification | | - | - | | **XMEM\_CPU**
0x00000001 | Alloue de la mémoire accessible uniquement au processeur. | | **XMEM\_GRAPHICS**
0x00000003 | Alloue de la mémoire accessible à la fois par le processeur et par le GPU. Toute mémoire validée avec **XMEM\_GRAPHICS** est mappée dans les tables de pages du GPU. | | **XMEM\_GRAPHICS\_32BIT\_ADDRESS**
0x00000007 | Spécifie que l'adresse attribuée automatiquement se trouve dans les 4 Go inférieurs de l'espace d'adressage. La mémoire validée à l'aide de cet indicateur est également accessible par le GPU. | Sur XBOX, il est possible d'allouer de la mémoire avec une adresse de mémoire virtuelle restreinte qui garantit que les bits de poids fort ne sont pas utilisés. L'utilisation de l'une des valeurs suivantes limite l'adresse au nombre de bits indiqué. **XMEM\_40BIT\_ADDRESS** (0x00007000ULL), **XMEM\_41BIT\_ADDRESS** (0x00006000ULL), **XMEM\_42BIT\_ADDRESS** (0x00005000ULL), **XMEM\_43BIT\_ADDRESS** (0x00004000ULL), **XMEM\_44BIT\_ADDRESS** (0x00003000ULL), **XMEM\_45BIT\_ADDRESS** (0x00002000ULL), **XMEM\_46BIT\_ADDRESS** (0x00001000ULL). La mémoire graphique ne peut pas être allouée avant la création du D3D12Device ou l'appel de D3DConfigureVirtualMemory. Si de la mémoire visible par le GPU est demandée, les titres sont *tenus* de spécifier également des indicateurs explicites de protection de page graphique ; il n'existe plus de valeur par défaut basée sur les paramètres de protection de page du processeur. Il s'agit d'un changement par rapport aux versions antérieures du système d'exploitation XBOX. Ce paramètre peut également spécifier les valeurs suivantes, comme indiqué. | Valeur | Signification | | - | - | | **XMEM\_TOOL**
0x00000010 | Spécifie que les allocations sont imputées à la partition des outils au lieu de la partition du titre. Cet indicateur exige que **MEM\_2MB\_PAGES** ou **MEM\_64K\_PAGES** soit spécifié dans le paramètre *AllocationType*. | | **XMEM\_MAPPABLE**
0x00000020 | Spécifie que l'allocation est une réservation d'adresses destinée aux mappages de pages physiques via [XMemMapPhysicalPages](/fr/reference/system/xmem/functions/xmemmapphysicalpages). Cet indicateur exige que **MEM\_RESERVE** et **MEM\_2MB\_PAGES** ou **MEM\_64K\_PAGES** soient spécifiés dans le paramètre *AllocationType*. | Sur les appareils Anaconda et les appareils Dante émulant Anaconda, lors de l'utilisation du mode de mémoire de titre Advanced, les paramètres suivants peuvent également être appliqués. Ces paramètres sont ignorés dans tous les autres cas. Ces indicateurs sont facultatifs. S'ils ne sont pas spécifiés, toutes les allocations graphiques utilisent par défaut XMEM\_GPU\_OPTIMAL\_BANDWIDTH\_PREFERRED et toutes les autres allocations utilisent par défaut XMEM\_STANDARD\_BANDWIDTH\_PREFERRED. | Valeur | Signification | | - | - | | **XMEM\_STD\_BW\_REQ** ou
**XMEM\_STANDARD\_BANDWIDTH\_REQUIRED**
0x00000080 | Spécifie que les allocations doivent être satisfaites à l'aide de mémoire à bande passante standard. | | **XMEM\_STD\_BW\_PREF** ou
**XMEM\_STANDARD\_BANDWIDTH\_PREFERRED**
0x00000180 | Spécifie que les allocations doivent privilégier la mémoire à bande passante standard et n'utiliser la mémoire à bande passante optimale pour le GPU que si la mémoire à bande passante standard est épuisée. | | **XMEM\_GPU\_OPTBW\_REQ** ou
**XMEM\_GPU\_OPTIMAL\_BANDWIDTH\_REQUIRED**
0x00000280 | Spécifie que les allocations doivent être satisfaites à l'aide de mémoire à bande passante optimale pour le GPU. | | **XMEM\_GPU\_OPTBW\_PREF** ou
**XMEM\_GPU\_OPTIMAL\_BANDWIDTH\_PREFERRED**
0x00000380 | Spécifie que les allocations doivent privilégier la mémoire à bande passante optimale pour le GPU et n'utiliser la mémoire à bande passante standard que si la mémoire à bande passante optimale pour le GPU est épuisée. | Le paramètre *XMemFlags* comprend une balise facultative de code à quatre caractères. Les caractères peuvent être a-z, A-Z, 0-9 et \$. La fonction [XMemMakeTag](/fr/reference/system/xmem/functions/xmemmaketag) peut être utilisée pour construire l'encodage correct de la valeur de balise à la bonne position de bits. La balise ne peut être associée qu'à des régions de mémoire validées, et non à des réservations. Cette balise de code à quatre caractères est représentée par les 24 bits de poids fort du paramètre. La balise peut être récupérée via [XMemVirtualQuery](/fr/reference/system/xmem/functions/xmemvirtualquery) et s'affiche également dans l'analyse de mémoire PIX. Exemple : ```cpp theme={null} PVOID mem = XMemVirtualAlloc(NULL, size, MEM_64K_PAGES | MEM_COMMIT, XMemMakeTag('Fred') | XMEM_CPU, PAGE_READWRITE); ```
*PageProtection* \_In\_
Type : DWORD Protection de la mémoire pour la région de pages à allouer. Si les pages sont en cours de validation, vous pouvez spécifier l'une des constantes de protection de la mémoire. Les valeurs propres à XBOX suivantes sont autorisées pour le paramètre *PageProtection*, et l'une d'elles est obligatoire lorsque **XMEM\_GRAPHICS** ou **XMEM\_GRAPHICS\_32BIT\_ADDRESS** est spécifié. Cette exigence est un changement par rapport à la version précédente du système d'exploitation XBOX. Ces valeurs peuvent également être spécifiées à d'autres fonctions de gestion de la mémoire (par exemple, VirtualProtect) pour des adresses mémoire situées dans des plages allouées avec **XMEM\_GRAPHICS**. | Valeur | Signification | | - | - | | **PAGE\_GRAPHICS\_NOACCESS**
0x0800 | Spécifie que la mémoire ne sera pas accessible sur le GPU. | | **PAGE\_GRAPHICS\_READONLY**
0x1000 | Spécifie que la mémoire sera en lecture seule sur le GPU. | | **PAGE\_GRAPHICS\_READWRITE**
0x2000 | Spécifie que la mémoire sera en lecture-écriture sur le GPU. | | **PAGE\_GRAPHICS\_EXECUTE**
0x4000

**GRAPHICS\_EXECUTE\_READ**
0x8000

**PAGE\_GRAPHICS\_EXECUTE\_READWRITE**
0x10000 | Spécifie que la mémoire sera exécutable sur le GPU. Cela est obligatoire pour les mémoires tampons de commandes. | Ce paramètre peut également spécifier la valeur suivante, comme indiqué. | Valeur | Signification | | - | - | | **PAGE\_GRAPHICS\_COHERENT**
0x20000 | Spécifie que la mémoire partagée avec le GPU sera maintenue cohérente entre les caches du processeur et du GPU. | | **PAGE\_GRAPHICS\_NOCACHE**
0x40000 | Spécifie que la mémoire n'est pas mise en cache lors de l'accès par le GPU. Cet indicateur s'applique uniquement aux consoles XBOX Series X\|S. | ### Valeur renvoyée Type : PVOID Si la fonction réussit, la valeur renvoyée est l'adresse de base de la région de pages allouée. Si la fonction échoue, la valeur renvoyée est **NULL**. Pour obtenir des informations d'erreur étendues, appelez GetLastError. ## Remarques Chaque page possède un état de page associé. La fonction **XMemVirtualAlloc** peut effectuer les opérations suivantes : * Valider une région de pages réservées * Réserver une région de pages libres * Réserver et valider simultanément une région de pages libres **XMemVirtualAlloc** ne peut pas réserver une page déjà réservée. Elle 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, sans que la fonction échoue. Vous pouvez utiliser **XMemVirtualAlloc** pour réserver un bloc de pages, puis effectuer des appels supplémentaires à **XMemVirtualAlloc** pour valider des pages individuelles du bloc réservé. Cela permet à un processus de réserver une plage de son espace d'adressage virtuel sans consommer de stockage physique tant que celui-ci n'est pas nécessaire. Si le paramètre *BaseAddress* n'a pas la valeur **NULL**, la fonction utilise les paramètres *BaseAddress* et *Size* pour calculer la région de pages à allouer. L'état actuel de la plage entière de pages doit être compatible avec le type d'allocation spécifié par le paramètre *AllocationType*. Sinon, la fonction échoue et aucune page n'est allouée. Cette exigence de compatibilité n'empêche pas la validation d'une page déjà validée, comme mentionné précédemment. La fonction **XMemVirtualAlloc** peut être utilisée pour réserver, dans l'espace d'adressage virtuel du processus appelant, une région de mémoire désignée pour le mappage de pages physiques. Cette région de mémoire peut ensuite être utilisée pour mapper des pages physiques dans la mémoire virtuelle et les en retirer, selon les besoins de l'application. Les valeurs **MEM\_RESERVE** et **MEM\_64K\_PAGES** doivent être définies dans le paramètre *AllocationType* ; la valeur **MEM\_COMMIT** ne doit pas être définie. **XMEM\_MAPPABLE** doit être défini dans le paramètre *XMemFlags*. L'espace d'adressage réservé de cette façon est validé à l'aide de l'API [XMemMapPhysicalPages](/fr/reference/system/xmem/functions/xmemmapphysicalpages). La fonction VirtualFree peut annuler la validation d'une page validée, libérant ainsi le stockage de la page, ou elle peut simultanément annuler la validation d'une page validée et la libérer. Elle peut également libérer une page réservée, ce qui en fait une page libre. En plus de fournir une extension pour les caractéristiques de mémoire propres à XBOX, cette API diffère de VirtualAlloc en n'imposant pas de contrat garantissant que la mémoire renvoyée est initialisée à zéro. **XMemVirtualAlloc** ne garantit pas non plus la conservation du contenu antérieur de la mémoire. La plupart des cas d'usage de **XMemVirtualAlloc** dans les jeux consistent à obtenir de la mémoire graphique (qui ne bénéficie généralement pas d'une initialisation à zéro) ou à ajouter de la mémoire à des implémentations de tas qui tirent peu d'avantages d'une initialisation à zéro. En outre, il est trivial pour un appelant d'implémenter l'initialisation à zéro de la mémoire renvoyée au moment de son choix. En n'imposant pas cette garantie de VirtualAlloc, l'implémentation de **XMemVirtualAlloc** dispose de plus de flexibilité pour offrir de meilleures performances. **XMemVirtualAlloc** diffère également de VirtualAlloc en ce que la mémoire obtenue via cet appel d'API est immédiatement disponible. En revanche, les adresses mémoire renvoyées par VirtualAlloc ne sont renseignées avec des pages physiques qu'au premier accès, par le biais d'une opération coûteuse de défaut de page. La mémoire allouée avec **XMemVirtualAlloc** doit être libérée avec VirtualFree. Les indicateurs de protection de page **PAGE\_NOCACHE** et **PAGE\_WRITECOMBINE** sont fixés au moment de la réservation de la mémoire et ne peuvent pas être modifiés lors d'une demande de validation ultérieure. Toute tentative de modification de l'état de l'un de ces indicateurs lors de la validation de la mémoire est ignorée silencieusement. La validation de la mémoire réussit, mais la mémoire conserve l'état d'origine de ces indicateurs. Exemples : ```cpp theme={null} // Allocate standard CPU only memory, using default (4K) pages PVOID cpuMemory = XMemVirtualAlloc (NULL, 1024 * 1024, MEM_RESERVE | MEM_COMMIT, XMEM_CPU, PAGE_READWRITE); ``` ```cpp theme={null} // Allocate 1MB of tooling memory using 64K pages PVOID cpu64kmemory = XMemVirtualAlloc (NULL, 1024 * 1024, MEM_64K_PAGES | MEM_RESERVE | MEM_COMMIT, XMEM_TOOL | XMEM_CPU, PAGE_READWRITE); ``` ```cpp theme={null} // Allocate 2MB graphics memory PVOID gfx64kmemory = XMemVirtualAlloc (NULL, 2 * 1024 * 1024, MEM_2MB_PAGES | MEM_RESERVE | MEM_COMMIT, XMEM_GRAPHICS, PAGE_READWRITE | PAGE_GRAPHICS_READONLY); ``` ```cpp theme={null} // Allocate 1MB of graphics memory using 64K pages in 32b address space PVOID gfxmemory32b = XMemVirtualAlloc (NULL, 1024 * 1024, MEM_64K_PAGES | MEM_RESERVE | MEM_COMMIT, XMEM_GRAPHICS_32BIT_ADDRESS, PAGE_READONLY | PAGE_GRAPHICS_READWRITE); ``` ```cpp theme={null} // Reserve 1GB of CPU visible VA space using 64K pages PVOID cpuReserve = XMemVirtualAlloc (NULL, 1024 * 1024 * 1024, MEM_64K_PAGES | MEM_RESERVE, XMEM_CPU, PAGE_READWRITE); // Now commit the first 2MB of the reservation PVOID cpuCommit = XMemVirtualAlloc (cpuReserve, 2 * 1024 * 1024, MEM_COMMIT, XMEM_CPU, PAGE_READWRITE); ``` ```cpp theme={null} // Reserve 4MB of visible VA space intended for direct physical page mapping // Note that physical pages are always 64KB and this reservation assumes // any allocations will be in 32 or 64 page (2MB\4MB) blocks PVOID physicalReserve = XMemVirtualAlloc (NULL, 4 * 1024 * 1024, MEM_2MB_PAGES | MEM_RESERVE, XMEM_GRAPHICS | XMEM_MAPPABLE, PAGE_READONLY | PAGE_GRAPHICS_COHERENT | PAGE_GRAPHICS_READWRITE); ``` ## Configuration requise **En-tête :** xmem.h **Bibliothèque :** xmem.lib **Plateformes prises en charge :** consoles de la famille XBOX One et consoles XBOX Series ## Voir aussi [Référence XMem](/fr/reference/system/xmem/xmem_members)
[XMemMapPhysicalPages](/fr/reference/system/xmem/functions/xmemmapphysicalpages)
VirtualFree ## Related topics - [Utilisation du gestionnaire de mémoire du système d'exploitation de jeu Microsoft GDK](/fr/build/console-features/memory/system-memory-working.md) - [XMemVirtualQuery](/fr/reference/system/xmem/functions/xmemvirtualquery.md) - [XMemMapPhysicalPages](/fr/reference/system/xmem/functions/xmemmapphysicalpages.md) - [XMemMapPhysicalPagesScatter](/fr/reference/system/xmem/functions/xmemmapphysicalpagesscatter.md) - [XMEM_OPTIONS](/fr/reference/system/xmem/enums/xmem_options.md)