VirtualAlloc2, fonction (memoryapi.h)

Réserve, valide ou modifie l’état d’une région de mémoire dans l’espace d’adressage virtuel d’un processus spécifié (la mémoire allouée est initialisée à zéro).

Syntaxe

PVOID VirtualAlloc2(
  [in, optional]      HANDLE                 Process,
  [in, optional]      PVOID                  BaseAddress,
  [in]                SIZE_T                 Size,
  [in]                ULONG                  AllocationType,
  [in]                ULONG                  PageProtection,
  [in, out, optional] MEM_EXTENDED_PARAMETER *ExtendedParameters,
  [in]                ULONG                  ParameterCount
);

Paramètres

[in, optional] Process

Handle vers un processus. La fonction alloue de la mémoire dans l’espace d’adressage virtuel de ce processus.

Le handle doit disposer du droit d’accès PROCESS_VM_OPERATION. Pour plus d’informations, consultez Processus de sécurité et de droits d’accès.

Si processus est NULL, la fonction alloue de la mémoire pour le processus appelant.

[in, optional] BaseAddress

Pointeur qui spécifie une adresse de départ souhaitée pour la région des pages que vous souhaitez allouer.

Si baseAddress est NULL, la fonction détermine où allouer la région.

Si baseAddress n’est pas NULL, toute structure MEM_ADDRESS_REQUIREMENTS fournie doit être constituée de tous les zéros, et l’adresse de base doit être un multiple de la granularité d’allocation du système. Pour déterminer la granularité d’allocation, utilisez la fonction GetSystemInfo.

Si cette adresse se trouve dans une enclave que vous n’avez pas initialisée en appelant InitializeEnclave, VirtualAlloc2 alloue une page de zéros pour l’enclave à cette adresse. La page doit être précédemment non validée et ne sera pas mesurée avec l’instruction EEXTEND du modèle de programmation Extensions Intel Software Guard.

Si l’adresse dans une enclave que vous avez initialisée, l’opération d’allocation échoue avec l’erreur ERROR_INVALID_ADDRESS. Cela est vrai pour les enclaves qui ne prennent pas en charge la gestion de la mémoire dynamique (par exemple SGX1). Les enclaves SGX2 autorisent l’allocation et la page doit être acceptée par l’enclave une fois qu’elle a été allouée.

[in] Size

Taille de la région de mémoire à allouer, en octets.

La taille doit toujours être un multiple de la taille de page.

Si baseAddress n’est pas NULL, la fonction alloue toutes les pages qui contiennent un ou plusieurs octets de la plage de BaseAddress à +Size. Cela signifie, par exemple, qu’une plage de 2 octets qui chevauche une limite de page entraîne l’allocation des deux pages par fonction.

[in] AllocationType

Type d’allocation de mémoire. Ce paramètre doit contenir l’une des valeurs suivantes.

Ce paramètre peut également spécifier les valeurs suivantes, comme indiqué.

[in] PageProtection

Protection de la mémoire pour la région des pages à allouer. Si les pages sont validées, vous pouvez spécifier l’une des constantes de protection de la mémoire .

Si BaseAddress spécifie une adresse dans une enclave, pageProtection ne peut pas être l’une des valeurs suivantes :

• PAGE_NOACCESS
• PAGE_GUARD
• PAGE_NOCACHE
• PAGE_WRITECOMBINE

Lors de l’allocation de mémoire dynamique pour une enclave, le paramètre pageProtection doit être PAGE_READWRITE ou PAGE_EXECUTE_READWRITE.

[in, out, optional] ExtendedParameters

Pointeur facultatif vers un ou plusieurs paramètres étendus de type MEM_EXTENDED_PARAMETER. Chacune de ces valeurs de paramètre étendues peut elle-même avoir un champ Type de MemExtendedParameterAddressRequirements ou MemExtendedParameterNumaNode. Si aucun paramètre étendu MemExtendedParameterNumaNode est fourni, le comportement est le même que pour les fonctions VirtualAlloc/MapViewOfFile (autrement dit, le nœud NUMA préféré pour les pages physiques est déterminé en fonction du processeur idéal du thread qui accède d’abord à la mémoire).

[in] ParameterCount

Nombre de paramètres étendus pointés par ExtendedParameters.

Valeur de retour

Si la fonction réussit, la valeur de retour est l’adresse de base de la région allouée de pages.

Si la fonction échoue, la valeur de retour est NULL . Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Remarques

Cette fonction vous permet de spécifier :

• une plage d’espace d’adressage virtuel et une restriction d’alignement power-of-2 pour les nouvelles allocations
• nombre arbitraire de paramètres étendus
• un nœud NUMA préféré pour la mémoire physique en tant que paramètre étendu (consultez le paramètre ExtendedParameters)
• une opération d’espace réservé (en particulier, remplacement).

Cette API fournit des techniques spécialisées de gestion de la mémoire virtuelle pour prendre en charge les jeux hautes performances et les applications serveur. Par exemple, les espaces réservés permettent à une plage de mémoire réservée d’être partitionnée explicitement, superposée et mappée à nouveau ; cela peut être utilisé pour implémenter des régions arbitrairement extensibles ou des mémoires tampons d’anneau de mémoire virtuelle. VirtualAlloc2 permet également d’allouer de la mémoire avec un alignement spécifique de la mémoire.

Chaque page a un état de page associé. La fonction VirtualAlloc2 peut effectuer les opérations suivantes :

• Valider une région de pages réservées
• Réserver une région de pages gratuites
• Réserver et valider simultanément une région de pages libres

VirtualAlloc2 peut valider des pages déjà validées, mais ne peut pas réserver des pages déjà réservées. Cela signifie que vous pouvez valider une plage de pages, qu’elles aient déjà été validées et que la fonction ne échoue pas. En règle générale, seule une plage minimale de pages principalement non validées doit être spécifiée, car la validation d’un grand nombre de pages déjà validées peut entraîner la VirtualAlloc2 appel de prendre beaucoup plus de temps.

Vous pouvez utiliser VirtualAlloc2 pour réserver un bloc de pages, puis effectuer des appels supplémentaires à VirtualAlloc2 pour valider des pages individuelles à partir 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 lpAddress n’est pas NULL, la fonction utilise les paramètres lpAddress et dwSize pour calculer la région des 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 flAllocationType. 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 ; consultez la liste précédente.

Pour exécuter du code généré dynamiquement, utilisez VirtualAlloc2 pour allouer de la mémoire, et la fonction VirtualProtectEx pour accorder l’accès PAGE_EXECUTE.

La fonction VirtualAlloc2 peut être utilisée pour réserver une zone de mémoire AWE (Address Windowing Extensions) dans l’espace d’adressage virtuel d’un processus spécifié. Cette région de mémoire peut ensuite être utilisée pour mapper des pages physiques dans et hors mémoire virtuelle, selon les besoins de l’application. Les valeurs MEM_PHYSICAL et MEM_RESERVE doivent être définies dans le paramètre AllocationType . La valeur MEM_COMMIT ne doit pas être définie. La protection de page doit être définie sur PAGE_READWRITE.

La fonction VirtualFreeEx peut décommit une page validée, libérer le stockage de la page ou libérer simultanément une page validée. Il peut également libérer une page réservée, ce qui en fait une page gratuite.

Lors de la création d’une région qui sera exécutable, le programme appelant a la responsabilité de garantir la cohérence du cache via un appel approprié à FlushInstructionCache une fois le code en place. Sinon, les tentatives d’exécution de code hors de la région nouvellement exécutable peuvent produire des résultats imprévisibles.

Exemples

Scénario 1. Créez une mémoire tampon circulaire en mappant deux vues adjacentes de la même section de mémoire partagée.

#include <windows.h>
#include <stdio.h>
#include <stdlib.h>

//
// This function creates a ring buffer by allocating a pagefile-backed section
// and mapping two views of that section next to each other. This way if the
// last record in the buffer wraps it can still be accessed in a linear fashion
// using its base VA.
//

void*
CreateRingBuffer (
    unsigned int bufferSize,
    _Outptr_ void** secondaryView
    )
{
    BOOL result;
    HANDLE section = nullptr;
    SYSTEM_INFO sysInfo;
    void* ringBuffer = nullptr;
    void* placeholder1 = nullptr;
    void* placeholder2 = nullptr;
    void* view1 = nullptr;
    void* view2 = nullptr;

    GetSystemInfo (&sysInfo);

    if ((bufferSize % sysInfo.dwAllocationGranularity) != 0) {
        return nullptr;
    }

    //
    // Reserve a placeholder region where the buffer will be mapped.
    //

    placeholder1 = (PCHAR) VirtualAlloc2 (
        nullptr,
        nullptr,
        2 * bufferSize,
        MEM_RESERVE | MEM_RESERVE_PLACEHOLDER,
        PAGE_NOACCESS,
        nullptr, 0
    );

    if (placeholder1 == nullptr) {
        printf ("VirtualAlloc2 failed, error %#x\n", GetLastError());
        goto Exit;
    }

    //
    // Split the placeholder region into two regions of equal size.
    //

    result = VirtualFree (
        placeholder1,
        bufferSize,
        MEM_RELEASE | MEM_PRESERVE_PLACEHOLDER
    );

    if (result == FALSE) {
        printf ("VirtualFreeEx failed, error %#x\n", GetLastError());
        goto Exit;
    }

    placeholder2 = (void*) ((ULONG_PTR) placeholder1 + bufferSize);

    //
    // Create a pagefile-backed section for the buffer.
    //

    section = CreateFileMapping (
        INVALID_HANDLE_VALUE,
        nullptr,
        PAGE_READWRITE,
        0,
        bufferSize, nullptr
    );

    if (section == nullptr) {
        printf ("CreateFileMapping failed, error %#x\n", GetLastError());
        goto Exit;
    }

    //
    // Map the section into the first placeholder region.
    //

    view1 = MapViewOfFile3 (
        section,
        nullptr,
        placeholder1,
        0,
        bufferSize,
        MEM_REPLACE_PLACEHOLDER,
        PAGE_READWRITE,
        nullptr, 0
    );

    if (view1 == nullptr) {
        printf ("MapViewOfFile3 failed, error %#x\n", GetLastError());
        goto Exit;
    }

    //
    // Ownership transferred, don't free this now.
    //

    placeholder1 = nullptr;

    //
    // Map the section into the second placeholder region.
    //

    view2 = MapViewOfFile3 (
        section,
        nullptr,
        placeholder2,
        0,
        bufferSize,
        MEM_REPLACE_PLACEHOLDER,
        PAGE_READWRITE,
        nullptr, 0
    );

    if (view2 == nullptr) {
        printf ("MapViewOfFile3 failed, error %#x\n", GetLastError());
        goto Exit;
    }

    //
    // Success, return both mapped views to the caller.
    //

    ringBuffer = view1;
    *secondaryView = view2;

    placeholder2 = nullptr;
    view1 = nullptr;
    view2 = nullptr;

Exit:

    if (section != nullptr) {
        CloseHandle (section);
    }

    if (placeholder1 != nullptr) {
        VirtualFree (placeholder1, 0, MEM_RELEASE);
    }

    if (placeholder2 != nullptr) {
        VirtualFree (placeholder2, 0, MEM_RELEASE);
    }

    if (view1 != nullptr) {
        UnmapViewOfFileEx (view1, 0);
    }

    if (view2 != nullptr) {
        UnmapViewOfFileEx (view2, 0);
    }

    return ringBuffer;
}

int __cdecl wmain()
{
    char* ringBuffer;
    void* secondaryView;
    unsigned int bufferSize = 0x10000;

    ringBuffer = (char*) CreateRingBuffer (bufferSize, &secondaryView);

    if (ringBuffer == nullptr) {
        printf ("CreateRingBuffer failed\n");
        return 0;
    }

    //
    // Make sure the buffer wraps properly.
    //

    ringBuffer[0] = 'a';

    if (ringBuffer[bufferSize] == 'a') {
        printf ("The buffer wraps as expected\n");
    }

    UnmapViewOfFile (ringBuffer);
    UnmapViewOfFile (secondaryView);
}

Scénario 2. Spécifiez un nœud NUMA préféré lors de l’allocation de la mémoire.

void*
AllocateWithPreferredNode (size_t size, unsigned int numaNode)
{
    MEM_EXTENDED_PARAMETER param = {0};

    param.Type = MemExtendedParameterNumaNode;
    param.ULong = numaNode;

    return VirtualAlloc2 (
        nullptr, nullptr,
        size,
        MEM_RESERVE | MEM_COMMIT,
        PAGE_READWRITE,
        &param, 1);
}

Scénario 3. Allouez de la mémoire dans une plage d’adresses virtuelle spécifique (sous 4 Go, dans cet exemple) et avec un alignement spécifique.

void*
AllocateAlignedBelow2GB (size_t size, size_t alignment)
{
    MEM_ADDRESS_REQUIREMENTS addressReqs = {0};
    MEM_EXTENDED_PARAMETER param = {0};

    addressReqs.Alignment = alignment;
    addressReqs.HighestEndingAddress = (PVOID)(ULONG_PTR) 0x7fffffff;

    param.Type = MemExtendedParameterAddressRequirements;
    param.Pointer = &addressReqs;

    return VirtualAlloc2 (
        nullptr, nullptr,
        size,
        MEM_RESERVE | MEM_COMMIT,
        PAGE_READWRITE,
        &param, 1);
}

Exigences

Voir aussi

fonctions de gestion de la mémoire

ReadProcessMemory

fonctions de mémoire virtuelle

VirtualAllocExNuma

VirtualFreeEx

VirtualLock

VirtualProtect

virtualQuery

writeProcessMemory