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 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. 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 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 et s’affiche également dans l’analyse de mémoire PIX. Exemple :

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

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

(all) API references

Error codes

Audio API reference

Chat API reference

Developer kit only API reference

Graphics API reference

Input API reference

Lighting API reference

Networking API reference

XBOX PC remote iteration API reference

System API reference

Tools API reference

Windows device portal REST API reference

XBOX services API reference

MicrosoftGame.config reference

XMemVirtualAlloc

XMemVirtualAlloc

Syntaxe

Paramètres

Valeur renvoyée

Remarques

Configuration requise

Voir aussi

​XMemVirtualAlloc

​Syntaxe

​Paramètres

​Valeur renvoyée

​Remarques

​Configuration requise

​Voir aussi

XMemVirtualAlloc

Syntaxe

Paramètres

Valeur renvoyée

Remarques

Configuration requise

Voir aussi