XALLOC_ATTRIBUTES Structure

Contains values that describe the attributes of a memory allocation.

Syntax

typedef union _XALLOC_ATTRIBUTES {
    ULONGLONG dwAttributes;
    struct {
        ULONGLONG dwObjectType : 14;
        ULONGLONG dwPageSize : 2;
        ULONGLONG dwAllocatorId : 8;
        ULONGLONG dwAlignment : 5;
        ULONGLONG dwMemoryType : 4;
        ULONGLONG reserved : 31;
    }s;
} XALLOC_ATTRIBUTES, *PXALLOC_ATTRIBUTES;

Members

dwAttributes
Attributes of the allocation.

dwObjectType
Allocation type, as defined by the subsystem performing the allocation.

dwPageSize
The page size allocated. See the table in the remarks section for a list of allowed values.

dwAllocatorId
ID of the subsystem that performs the allocation. Each allocation is associated with an allocator ID, which identifies the subsystem that is requesting the allocation (or freeing) of memory. There are three potential sources of allocations: title, platform, and middleware components. For value ranges, see XALLOC_ALLOCATOR_IDS.

dwAlignment
The type of alignment required. See the table in the remarks section for a list of allowed values.

dwMemoryType
Specifies the type of memory that is desired for the allocation. You can choose one of several GPU-visible page types and caching behaviors, versus values that are useful for CPU-only memory allocations.

reserved
Reserved.

Remarks

dwObjectType

The values of dwObjectType are defined by the allocator that performs the allocation, and your title can use these values to either track different object types as they are allocated, or to vary the behavior of your allocator, depending on the type.

For example, if you defined an allocator for your particle system, you might define your own AllocatorId for your title as TitleAllocatorID_ParticleSystem and set it equal to 4, as well as a pool to contain particles that only collide with the ground-plane in your engine. This pool might have the ObjectType ID 2, because you already used 0 for emitters, and 1 for particles that do collide. It all depends on what precisely you want to track, and how your engine is structured.

Alternatively, you might not define IDs with such coarse granularity; you might instead pivot on the allocator ID for different allocation behaviors, and using the ObjectType ID purely for tracking purposes, with each object type in your game having its own value, regardless of subsystem.

Object type values must be within the range 0 to 16383.

dwMemoryType

XALLOC_MEMTYPE	Value	Description
XALLOC_MEMTYPE_HEAP_CACHEABLE	0x0	Indicates that the memory block does not need to be GPU visible, and should be cached.
XALLOC_MEMTYPE_GRAPHICS_WRITECOMBINE	0x1	Indicates that the memory block is mapped in the GPU page tables, and should act as write-combined memory.
XALLOC_MEMTYPE_GRAPHICS_WRITECOMBINE_GPU_READONLY	0x2	Indicates that the memory block is read only, is mapped in the GPU page tables, and should act as write-combined memory. This memory is not GPU cache coherent.
XALLOC_MEMTYPE_GRAPHICS_CACHEABLE	0x3	Indicates that the memory block is mapped in the GPU page tables, and should be cached and GPU cache coherent.
XALLOC_MEMTYPE_GRAPHICS_CACHEABLE_NONCOHERENT_GPU_READONLY	0x4	Indicates that the memory block is mapped in the GPU page tables, and while CPU cached, this memory is not GPU cache coherent. Extra caution must be used with this memory type to avoid seeing stale cache lines on either the CPU or GPU.
XALLOC_MEMTYPE_GRAPHICS_COMMAND_BUFFER_WRITECOMBINE	0x5	Indicates that the memory block is intended to be used as a GPU or DMA engine command-buffer, and should be write-combined. This memory is not GPU cache coherent.
XALLOC_MEMTYPE_GRAPHICS_COMMAND_BUFFER_CACHEABLE	0x6	Indicates that the memory block is intended to be used as a GPU or DMA engine command-buffer, and should be cached and GPU cache coherent.
XALLOC_MEMTYPE_PHYSICAL_CACHEABLE	0x7	Indicates that the memory block is physical and cacheable.
XALLOC_MEMTYPE_PHYSICAL_WRITECOMBINE	0x8	Indicates that the memory block is physical and should act as write-combined memory.
XALLOC_MEMTYPE_PHYSICAL_UNCACHED	0x9	Indicates that the memory block is physical and uncached.

dwPageSize Flags

You can specify the size of the pages used in the memory allocation by setting the value of dwPageSize. This parameter can have one of the values shown in the following table.

XALLOC_PAGESIZE	Value	Description
XALLOC_PAGESIZE_4KB	0	Allocate using 4 KB pages.
XALLOC_PAGESIZE_64KB	1	Allocate using 64 KB pages.
XALLOC_PAGESIZE_4MB	2	Allocate using 4 MB pages.

dwAlignment

By setting the value of dwAlignment, your code requests a specific alignment for the returned block of memory. You can also view this parameter as a value of 2n, where n is the desired alignment provided that you do not use values of n between 1 and 3, or greater than 16. It can have the values shown in the following table.

XALLOC_ALIGNMENT
XALLOC_ALIGNMENT_ANY
XALLOC_ALIGNMENT_16
XALLOC_ALIGNMENT_32
XALLOC_ALIGNMENT_64
XALLOC_ALIGNMENT_128
XALLOC_ALIGNMENT_256
XALLOC_ALIGNMENT_512
XALLOC_ALIGNMENT_1K
XALLOC_ALIGNMENT_2K
XALLOC_ALIGNMENT_4K
XALLOC_ALIGNMENT_8K
XALLOC_ALIGNMENT_16K
XALLOC_ALIGNMENT_32K
XALLOC_ALIGNMENT_64K

Non-Graphics Memory Suballocation

Non-graphics memory (memory allocated using XALLOC_MEMTYPE_HEAP_CACHEABLE) is suballocated based on the page size and alignment of the allocation.

4 KB page size and 16-byte alignment:
- Allocations less than 4 KB are tightly packed
- Allocations greater than or equal to 4 KB are aligned to a multiple of 4 KB
64 KB or 4 MB page size or an alignment other than 16-bytes:
- Allocations <= 4 KB are rounded up to a multiple of 256 bytes
- Allocations <= 64 KB are rounded up to a multiple of 4 KB
- Allocations <= 128 KB are rounded up to 128 KB
- All other allocations are rounded up to a boundary of 4 MB

Requirements

Header: Declared in xmem.h.