> ## 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 L'adresse de départ de la région à allouer. Si la mémoire est réservée, 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 qu'elle est en cours de validation, l'adresse est arrondie à la limite de page inférieure. Si ce paramètre est NULL, le système détermine où allouer la région.
*Size* \_In\_
Type : SIZE\_T La taille de la région, en octets. Si le paramètre *BaseAddress* est 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 dans 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 Le 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\`.
Une tentative de validation d'une plage d'adresses spécifique en spécifiant **MEM\_COMMIT** sans **MEM\_RESERVE** et avec une *BaseAddress* non NULL échoue, à moins que toute la plage n'ait déjà été réservée. Le code d'erreur résultant est **ERROR\_INVALID\_ADDRESS**.
Une tentative de validation d'une page déjà validée ne provoque pas l'échec de la fonction. Cela signifie que vous pouvez valider des pages sans d'abord déterminer 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 subséquents à la fonction **XMemVirtualAlloc**, ou mapper directement des pages physiques à l'aide de **XMemMapPhysicalPages**.
Les autres fonctions d'allocation de mémoire, comme **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 les paramètres de protection de page et de cohérence de cache au moment de la réservation, ce qui constitue 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 à 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 à **PAGE\_NOACCESS**. L'utilisation de **MEM\_RESERVE\_PLACEHOLDER** retourne toujours une adresse alignée sur 2 Mo afin de garantir qu'elle pourra être utilisée avec **MEM\_2MB\_PAGES** par la suite. 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 la ramener à 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é retiré du *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 par le processeur (CPU). | | **XMEM\_GRAPHICS**
0x00000003 | Alloue de la mémoire accessible à la fois par le CPU et le GPU. Toute mémoire validée avec **XMEM\_GRAPHICS** sera 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 restreint 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 que le D3D12Device ait été créé ou que D3DConfigureVirtualMemory ait été appelé. 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 CPU. 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 plutôt qu'à 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 au moyen de [XMemMapPhysicalPages](/fr-CA/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 avancé, 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 utiliseront par défaut XMEM\_GPU\_OPTIMAL\_BANDWIDTH\_PREFERRED et toutes les autres allocations utiliseront 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 n'importe lesquels parmi a-z, A-Z, 0-9 et \$. La fonction [XMemMakeTag](/fr-CA/reference/system/xmem/functions/xmemmaketag) peut être utilisée pour construire l'encodage correct de la valeur de la 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 sera représentée par les 24 bits supérieurs du paramètre. La balise peut être récupérée au moyen de [XMemVirtualQuery](/fr-CA/reference/system/xmem/functions/xmemvirtualquery) et sera également affichée dans l'analyse de la mémoire de 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 La protection de la mémoire pour la région de pages à allouer. Si les pages sont en cours de validation, vous pouvez spécifier n'importe laquelle 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 requise lorsque **XMEM\_GRAPHICS** ou **XMEM\_GRAPHICS\_32BIT\_ADDRESS** est spécifié. Cette exigence constitue 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 (p. ex. 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. Ceci est requis 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 CPU 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 de retour Type : PVOID Si la fonction réussit, la valeur de retour est l'adresse de base de la région de pages allouée. Si la fonction échoue, la valeur de retour est **NULL**. Pour obtenir des informations d'erreur détaillées, appelez GetLastError. ## Remarques Chaque page a 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 jusqu'à ce qu'il soit nécessaire. Si le paramètre *BaseAddress* n'est pas **NULL**, la fonction utilise les paramètres *BaseAddress* et *Size* pour calculer la région de pages à allouer. L'état actuel de toute la plage de pages doit être compatible avec le type d'allocation spécifié par le paramètre *AllocationType*. Sinon, la fonction échoue et aucune des pages 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-CA/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, pour en faire 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 retourné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'utilisation 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 de l'initialisation à zéro. De plus, il est simple pour un appelant d'implémenter l'initialisation à zéro de la mémoire retournée au moment de son choix. En n'imposant pas cette garantie de VirtualAlloc, l'implémentation de **XMemVirtualAlloc** dispose d'une plus grande souplesse pour offrir de meilleures performances. **XMemVirtualAlloc** diffère également de VirtualAlloc en ce que la mémoire obtenue au moyen de cet appel d'API est immédiatement disponible. En revanche, les adresses mémoire retournées par VirtualAlloc ne seront remplies de pages physiques qu'au premier accès, au moyen 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 modifier l'état de l'un de ces indicateurs lors de la validation de la mémoire sera ignorée silencieusement. La validation de la mémoire réussira, mais la mémoire conservera 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-CA/reference/system/xmem/xmem_members)
[XMemMapPhysicalPages](/fr-CA/reference/system/xmem/functions/xmemmapphysicalpages)
VirtualFree ## Related topics - [Working with the Microsoft GDK Game OS memory manager](/build/console-features/memory/system-memory-working.md) - [Trabajo con el administrador de memoria del sistema operativo de juego del Microsoft GDK](/es/build/console-features/memory/system-memory-working.md) - [使用 Microsoft GDK 游戏 OS 内存管理器](/zh-CN/build/console-features/memory/system-memory-working.md) - [Microsoft GDK Game OS 메모리 관리자 사용](/ko/build/console-features/memory/system-memory-working.md) - [Microsoft GDK ゲーム OS メモリ マネージャーの使用](/ja-jp/build/console-features/memory/system-memory-working.md)