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

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. 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 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 et sera également affichée dans l’analyse de la mémoire de PIX. Exemple :

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. 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 :

// Allocate standard CPU only memory, using default (4K) pages
PVOID cpuMemory = XMemVirtualAlloc (NULL,
                                    1024 * 1024,
                                    MEM_RESERVE | MEM_COMMIT,
                                    XMEM_CPU,
                                    PAGE_READWRITE);

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

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

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

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

// 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
XMemMapPhysicalPages
VirtualFree

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

XMemVirtualAlloc

XMemVirtualAlloc

Syntaxe

Paramètres

Valeur de retour

Remarques

Configuration requise

Voir aussi

​XMemVirtualAlloc

​Syntaxe

​Paramètres

​Valeur de retour

​Remarques

​Configuration requise

​Voir aussi

XMemVirtualAlloc

Syntaxe

Paramètres

Valeur de retour

Remarques

Configuration requise

Voir aussi