Application-defined memory allocation callback function that replaces the default memory allocator.
PVOID VirtualAlloc(
LPVOID lpAddress,
SIZE_T dwSize,
DWORD flAllocationType,
DWORD flProtect
)
lpAddress
Type: LPVOID
[in] The starting address of the region to allocate. If the memory is being reserved, the specified address is rounded down to the nearest multiple of the allocation granularity. If the memory is already reserved and is being committed, the address is rounded down to the next page boundary. To determine the size of a page and the allocation granularity on the host computer, use the GetSystemInfo function. If this parameter is NULL, the system determines where to allocate the region.
dwSize
Type: SIZE_T
[in] The size of the region, in bytes. If the lpAddress parameter is NULL, this value is rounded up to the next page boundary. Otherwise, the allocated pages include all pages containing one or more bytes in the range from lpAddress to lpAddress+dwSize. This means that a 2-byte range straddling a page boundary causes both pages to be included in the allocated region.
flAllocationType
Type: DWORD
[in] The type of memory allocation. This parameter must contain one of the following values.
| Value | Meaning |
|---|---|
| MEM_COMMIT | Allocates memory charges (from the overall size of memory and the paging files on disk) for the specified reserved memory pages. The function also guarantees that when the caller later initially accesses the memory, the contents will be zero. Actual physical pages are not allocated unless/until the virtual addresses are actually accessed. To reserve and commit pages in one step, call VirtualAlloc with MEM_COMMIT | MEM_RESERVE. The function fails if you attempt to commit a page that has not been reserved. The resulting error code is ERROR_INVALID_ADDRESS. An attempt to commit a page that is already committed does not cause the function to fail. This means that you can commit pages without first determining the current commitment state of each page. |
| MEM_RESERVE | Reserves a range of the process’s virtual address space without allocating any actual physical storage in memory or in the paging file on disk. You can commit reserved pages in subsequent calls to the VirtualAlloc function. To reserve and commit pages in one step, call VirtualAlloc with MEM_COMMIT | MEM_RESERVE. Other memory allocation functions, such as malloc and LocalAlloc, cannot use a reserved range of memory until it is released. |
| MEM_RESET | Indicates that data in the memory range specified by lpAddress and dwSize is no longer of interest. The pages should not be read from or written to the paging file. However, the memory block will be used again later, so it should not be decommitted. This value cannot be used with any other value. Using this value does not guarantee that the range operated on with MEM_RESET will contain zeros. If you want the range to contain zeros, decommit the memory and then recommit it. When you specify MEM_RESET, the VirtualAlloc function ignores the value of flProtect. However, you must still set flProtect to a valid protection value, such as PAGE_NOACCESS. VirtualAlloc returns an error if you use MEM_RESET and the range of memory is mapped to a file. A shared view is only acceptable if it is mapped to a paging file. |
| MEM_RESET_UNDO | MEM_RESET_UNDO should only be called on an address range to which MEM_RESET was successfully applied earlier. It indicates that the data in the specified memory range specified by lpAddress and dwSize is of interest to the caller and attempts to reverse the effects of MEM_RESET. If the function succeeds, that means all data in the specified address range is intact. If the function fails, at least some of the data in the address range has been replaced with zeroes. This value cannot be used with any other value. If MEM_RESET_UNDO is called on an address range which was not MEM_RESET earlier, the behavior is undefined. When you specify MEM_RESET, the VirtualAlloc function ignores the value of flProtect. However, you must still set flProtect to a valid protection value, such as PAGE_NOACCESS. |
This parameter can also specify the following values as indicated.
| Value | Meaning |
|---|---|
| MEM_LARGE_PAGES | Allocates memory in physically contiguous 64 KB chunks. |
| MEM_4MB_PAGES | Allocates memory in physically contiguous 4 MB chunks, and also uses 2 MB page table entries on the CPU. |
| MEM_GRAPHICS | Allocates memory in the virtual address range shared with the GPU for graphics allocations. Any memory committed with MEM_GRAPHICS will also be mapped into the GPU’s page tables. |
| MEM_PHYSICAL | Reserves an address range that can be used to map Address Windowing Extensions (AWE) pages. This value must be used with MEM_RESERVE and no other values. |
| MEM_TOP_DOWN | Allocates memory at the highest possible address. This can be slower than regular allocations, especially when there are many allocations. |
| MEM_WRITE_WATCH | Causes the system to track pages that are written to in the allocated region. If you specify this value, you must also specify MEM_RESERVE. To retrieve the addresses of the pages that have been written to since the region was allocated or the write-tracking state was reset, call the GetWriteWatch function. To reset the write-tracking state, call GetWriteWatch or ResetWriteWatch. The write-tracking feature remains enabled for the memory region until the region is freed. |
| MEM_TITLE | Causes the allocation to be in the 4TB to 8TB range. If MEM_TITLE is not specified, allocations will be in the 2TB to 4TB range. Cannot be used with MEM_GRAPHICS. |
flProtect
Type: DWORD
[in] The memory protection for the region of pages to be allocated. If the pages are being committed, you can specify any one of the memory protection constants.
| Value | Description |
|---|---|
| PAGE_GPU_COHERENT | Specifies that memory shared with the GPU will be kept coherent between CPU and GPU caches. |
| PAGE_GPU_EXECUTE | Specifies that memory will be executable on the GPU. This is required for command buffers. |
| PAGE_GPU_READONLY | Specifies that memory will be read-only on the GPU. |
| PAGE_EXECUTE | Not supported on Xbox One. |
| PAGE_EXECUTE_READ | Not supported on Xbox One. |
| PAGE_EXECUTE_READWRITE | Not supported on Xbox One. |
| PAGE_EXECUTE_WRITECOPY | Not Supported on Xbox One. |
| PAGE_NOACCESS | Disables all access to the committed region of pages. An attempt to read from, write to, or execute the committed region results in an access violation. |
| PAGE_READONLY | Enables read-only access to the committed region of pages. An attempt to write to the committed region results in an access violation. If Data Execution Prevention is enabled, an attempt to execute code in the committed region results in an access violation. |
| PAGE_READWRITE | Enables read-only or read/write access to the committed region of pages. If Data Execution Prevention is enabled, attempting to execute code in the committed region results in an access violation. |
| PAGE_WRITECOPY | This flag is not supported by the VirtualAlloc or VirtualAllocEx functions. |
The following are modifiers that can be used in addition to the options provided in the previous table, except as noted.
| Value | Description |
|---|---|
| PAGE_GUARD | Pages in the region become guard pages. Any attempt to access a guard page causes the system to raise a STATUS_GUARD_PAGE_VIOLATION exception and turn off the guard page status. Guard pages thus act as a one-time access alarm. When an access attempt leads the system to turn off guard page status, the underlying page protection takes over. If a guard page exception occurs during a system service, the service typically returns a failure status indicator. This value cannot be used with PAGE_NOACCESS, MEM_GRAPHICS, and MEM_4MB_PAGES. |
| PAGE_NOCACHE | Sets all pages to be non-cachable. Applications should not use this attribute except when explicitly required for a device. Using the interlocked functions with memory that is mapped with SEC_NOCACHE can result in an EXCEPTION_ILLEGAL_INSTRUCTION exception. The PAGE_NOCACHE flag cannot be used with the PAGE_GUARD, PAGE_NOACCESS, or PAGE_WRITECOMBINE flags. PAGE_NOCACHE is only supported on MEM_LARGE_PAGES or MEM_4MB_PAGES allocations. |
| PAGE_WRITECOMBINE | Sets all pages to be write-combined. Applications should not use this attribute except when explicitly required for a device. Using the interlocked functions with memory that is mapped as write-combined can result in an EXCEPTION_ILLEGAL_INSTRUCTION exception. The PAGE_WRITECOMBINE flag cannot be specified with the PAGE_NOACCESS, PAGE_GUARD, and PAGE_NOCACHE flags. PAGE_WRITECOMBINE is only supported on MEM_LARGE_PAGES or MEM_4MB_PAGES allocations. |
Type: PVOID
Returns a pointer to the allocated memory.
Header: Declared in memoryapi.h.