ID3D12CommandQueue::CopyPageMappingsX Method

Manipulates the GPU page tables on the GPU timeline. It can be called on graphics and DMA command queues, but not compute queues.

Syntax

public:
HRESULT CopyPageMappingsX(
         D3D12_GPU_VIRTUAL_ADDRESS DestinationAddress,
         UINT NumRanges,
         const D3D12XBOX_PAGE_MAPPING_RANGE *pRanges,
         D3D12_GPU_VIRTUAL_ADDRESS SourcePagePoolAddress,
         UINT SourcePagePoolPageCount,
         D3D12XBOX_PAGE_MAPPING_FLAGS Flags
)

Parameters

DestinationAddress
Type: D3D12_GPU_VIRTUAL_ADDRESS

[in] The destination address as a D3D12_GPU_VIRTUAL_ADDRESS (UINT64).

NumRanges
Type: UINT

[in] The number of mapping ranges.

pRanges
Type: D3D12XBOX_PAGE_MAPPING_RANGE *

[in] A pointer to an array of length NumRanges of D3D12XBOX_PAGE_MAPPING_RANGE structures, which specify how the ranges are to be interpreted using the D3D12XBOX_PAGE_MAPPING_RANGE_TYPE enum.

SourcePagePoolAddress
Type: D3D12_GPU_VIRTUAL_ADDRESS

[in] The source address as a D3D12_GPU_VIRTUAL_ADDRESS (UINT64).

If no mapping ranges with range types D3D12XBOX_PAGE_MAPPING_RANGE_TYPE_INCREMENTING_PAGE_INDICES or D3D12XBOX_PAGE_MAPPING_RANGE_TYPE_CONSTANT_PAGE_INDEX are set, then the SourcePagePoolAddress and SourcePagePoolPageCount parameters can both be 0. Otherwise, both SourcePagePoolAddress and SourcePagePoolPageCount must be nonzero, and SourcePagePoolPageAddress must be 64KB aligned.

SourcePagePoolPageCount
Type: UINT

[in] The source page count.

Flags
Type: D3D12XBOX_PAGE_MAPPING_FLAGS

[in] Flags that specify additional details about how pages are mapped.

Return value

Type: HRESULT

One of the Direct3D 12 return codes.

Remarks

This method is analogous to usage of MapTitlePhysicalPages and D3DMapEsramMemory, except the source pages are taken from an existing mapping instead of page number lists. The API copies 64KB page mappings from a source location to a destination location within the GPU page tables. CPU page tables are unmodified by this API. During each call to CopyPageMappingsX, the GPU pipeline is flushed before page table updates are performed, and the GPU TLB caches are flushed following the page table updates.

The intended usage scenario for CopyPageMappingsX is as follows:

At initialization time, prepare a “source page pool”, which will serve as the source of the page mapping copies.
1. Reserve a virtual memory range for the source page pool using VirtualAlloc with MEM_GRAPHICS | MEM_LARGE_PAGES | MEM_RESERVE for the AllocationType parameter.
2. If using system memory pages, allocate system memory pages using AllocateTitlePhysicalPages.
3. Map the system memory pages to the reserved address range using MapTitlePhysicalPages, and/or map ESRAM pages to the reserved address range using D3DMapEsramMemory.
For each resource whose mappings need to be updated at runtime:
1. Use the XG library to compute the size of the resource in 64KB pages.
2. Reserve a virtual memory range for the resource using VirtualAlloc with MEM_GRAPHICS | MEM_LARGE_PAGES | MEM_RESERVE for the AllocationType parameter.
3. Create a placement resource API object by passing the resource’s reserved virtual address to CreatePlacedResourceX.
At runtime, when mappings need to be updated, call CopyPageMappingsX on the command queue, copying mappings from the source page pool to the reserved address range of the resource.

Each copy operation can be a combination of multiple contiguous mapping ranges performed across the destination address range. Each mapping range, described with a D3D12XBOX_PAGE_MAPPING_RANGE struct, specifies by type a page range within the source page pool, null mappings, or an instruction to skip the range.

Note that it is not valid to unmap the source page pool after creating GPU page mappings with CopyPageMappingsX. It is the title’s responsibility to ensure that as long as copied mappings are in use, the source page pool pages must be mapped and not freed for reuse elsewhere. CopyPageMappingsX does not take any type of reference count or lock on the source pages.

The benefits of using CopyPageMappingsX are its performance, and it allows for a mix of system, ESRAM, and null mappings in a single call (provided that the source page pool has a combination of established system and ESRAM mappings). Also, usage of a predefined source page pool helps ensure that the physical pages aren’t accidentally released before the GPU does the mappings.

The cost of using this API is that the source page pool needs to be established ahead of time.

Requirements

Header: Declared in d3d12_x.h.

Library: Use d3d12_x.lib.