DXGKARG_BUILDPAGINGBUFFER structure

The DXGKARG_BUILDPAGINGBUFFER structure describes parameters for building a paging buffer that is used in a memory-transfer operation.

Syntax


typedef struct _DXGKARG_BUILDPAGINGBUFFER {
  VOID                             *pDmaBuffer;
  UINT                             DmaSize;
  VOID                             *pDmaBufferPrivateData;
  UINT                             DmaBufferPrivateDataSize;
  DXGK_BUILDPAGINGBUFFER_OPERATION Operation;
  UINT                             MultipassOffset;
  union {
    struct {
      HANDLE             hAllocation;
      UINT               TransferOffset;
      SIZE_T             TransferSize;
      struct {
        UINT SegmentId;
        union {
          LARGE_INTEGER SegmentAddress;
          MDL           *pMdl;
        };
      } Source;
      struct {
        UINT SegmentId;
        union {
          LARGE_INTEGER SegmentAddress;
          MDL           *pMdl;
        };
      } Destination;
      DXGK_TRANSFERFLAGS Flags;
      UINT               MdlOffset;
    } Transfer;
    struct {
      HANDLE hAllocation;
      SIZE_T FillSize;
      UINT   FillPattern;
      struct {
        UINT          SegmentId;
        LARGE_INTEGER SegmentAddress;
      } Destination;
    } Fill;
    struct {
      HANDLE                   hAllocation;
      DXGK_DISCARDCONTENTFLAGS Flags;
      UINT                     SegmentId;
      PHYSICAL_ADDRESS         SegmentAddress;
    } DiscardContent;
    struct {
      UINT             SegmentId;
      PHYSICAL_ADDRESS PhysicalAddress;
    } ReadPhysical;
    struct {
      UINT             SegmentId;
      PHYSICAL_ADDRESS PhysicalAddress;
    } WritePhysical;
    struct {
      HANDLE                hDevice;
      HANDLE                hAllocation;
      UINT                  SegmentId;
      SIZE_T                OffsetInPages;
      SIZE_T                NumberOfPages;
      PMDL                  pMdl;
      DXGK_MAPAPERTUREFLAGS Flags;
      ULONG                 MdlOffset;
    } MapApertureSegment;
    struct {
      HANDLE           hDevice;
      HANDLE           hAllocation;
      UINT             SegmentId;
      SIZE_T           OffsetInPages;
      SIZE_T           NumberOfPages;
      PHYSICAL_ADDRESS DummyPage;
    } UnmapApertureSegment;
    struct {
      HANDLE             hAllocation;
      UINT               TransferOffset;
      SIZE_T             TransferSize;
      struct {
        UINT SegmentId;
        union {
          LARGE_INTEGER SegmentAddress;
          MDL           *pMdl;
        };
      } Source;
      struct {
        UINT SegmentId;
        union {
          LARGE_INTEGER SegmentAddress;
          MDL           *pMdl;
        };
      } Destination;
      DXGK_TRANSFERFLAGS Flags;
      UINT               SwizzlingRangeId;
      UINT               SwizzlingRangeData;
    } SpecialLockTransfer;
#if (DXGKDDI_INTERFACE_VERSION >= DXGKDDI_INTERFACE_VERSION_WIN8)
    struct {
      HANDLE hAllocation;
      struct {
        UINT                    SegmentId;
        union {
          LARGE_INTEGER SegmentAddress;
          MDL           *pMdl;
        };
        PVOID                   VirtualAddress;
#if (DXGKDDI_INTERFACE_VERSION >= DXGKDDI_INTERFACE_VERSION_WDDM2_0)
        D3DGPU_VIRTUAL_ADDRESS  GpuVirtualAddress;
#endif 
      } Destination;
    } InitContextResource;
#endif 
#if (DXGKDDI_INTERFACE_VERSION >= DXGKDDI_INTERFACE_VERSION_WDDM2_0)
    DXGK_BUILDPAGINGBUFFER_TRANSFERVIRTUAL         TransferVirtual;
    DXGK_BUILDPAGINGBUFFER_FILLVIRTUAL             FillVirtual;
    DXGK_BUILDPAGINGBUFFER_UPDATEPAGETABLE         UpdatePageTable;
    DXGK_BUILDPAGINGBUFFER_FLUSHTLB                FlushTlb;
    DXGK_BUILDPAGINGBUFFER_COPYPAGETABLEENTRIES    CopyPageTableEntries;
    DXGK_BUILDPAGINGBUFFER_UPDATECONTEXTALLOCATION UpdateContextAllocation;
    DXGK_BUILDPAGINGBUFFER_NOTIFYRESIDENCY         NotifyResidency;
#endif 
    struct {
      UINT Reserved[64];
    } Reserved;
  };
  HANDLE                           hSystemContext;
#if (DXGKDDI_INTERFACE_VERSION >= DXGKDDI_INTERFACE_VERSION_WDDM2_0)
  D3DGPU_VIRTUAL_ADDRESS           DmaBufferGpuVirtualAddress;
#endif 
} DXGKARG_BUILDPAGINGBUFFER;

Members

pDmaBuffer

[in/out] A virtual address to the first available byte in the paging buffer. When the driver is first called with a new paging buffer, this virtual address is aligned on 4 KB. The driver tightly packs operations in the paging buffer until the paging buffer is full and then uses a new paging buffer. Therefore, if the graphics processing unit (GPU) requires a specific alignment for a paging-buffer submission, the driver should enforce this alignment by padding the operations that it writes to the paging buffer. Before the DxgkDdiBuildPagingBuffer function returns, the driver should update pDmaBuffer to point past the last byte that is written to the paging buffer.

DmaSize

[in/out] The size, in bytes, of the paging buffer that pDmaBuffer specifies.

pDmaBufferPrivateData

[in/out] A pointer to a driver-resident private data structure that is associated with the direct memory access (DMA) buffer (that is, paging buffer) that pDmaBuffer specifies.

DmaBufferPrivateDataSize

[in/out] The number of bytes that remain in the private data structure that pDmaBufferPrivateData points to for the current operation.

Operation

[in] A DXGK_BUILDPAGINGBUFFER_OPERATION-typed value that indicates the type of memory operation to perform.

MultipassOffset

[in/out] A UINT value that specifies the progress of the paging operation if multiple paging buffers are required. The driver sets this value to indicate a split into multiple paging buffers for more than one transfer operation. For example, the driver can store the page number that was last transferred for a paged-based transfer.

Transfer

[in] A structure that describes the transfer operation.

hAllocation

[in] A handle to the allocation that the driver's DxgkDdiCreateAllocation function previously returned in the hAllocation member of a DXGK_ALLOCATIONINFO structure, which is part of the DXGKARG_CREATEALLOCATION structure's pAllocationInfo member. The allocation handle points to a buffer that contains private driver data for the transfer.

TransferOffset

[in] The offset, in bytes, of the first page within the allocation that is transferred. This offset is applied only to a location that a segment location describes. This offset does not apply to an MDL description of a memory range. If the driver requires more than one paging buffer to complete the transfer (that is, the driver returns STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER from its DxgkDdiBuildPagingBuffer function), TransferOffset is the same for each call to DxgkDdiBuildPagingBuffer for this transfer.

TransferSize

[in] The size, in bytes, of the memory information to transfer.

Source

[in] A structure that describes the source allocation. This structure contains a SegmentId member and a union that contains either an offset into a segment of the source allocation (SegmentAddress) or a pointer to an MDL for the source (pMdl).

SegmentId

[in] The identifier of a segment within the source allocation, or zero if the source allocation is described by the pMdl member of the union that Source contains.

SegmentAddress

[in] The source segment address, if the SegmentId member of Source is nonzero. The DirectX graphics kernel subsystem computes the segment address as the sum of the segment offset and the base address of the segment: SegmentAddress = SegmentOffset + Segment.BaseAddr.

pMdl

[in] A pointer to a buffer that contains the MDL structure that describes the system memory pages for the source, if the SegmentId member of Source is zero.

Destination

[in] A structure that describes the destination allocation. This structure contains a SegmentId member and a union that contains either an offset into a segment of the destination allocation (SegmentAddress) or a pointer to an MDL for the destination (pMdl).

SegmentId

[in] The identifier of a segment within the destination allocation, or zero if the destination allocation is described by the pMdl member of the union that Destination contains.

SegmentAddress

[in] The destination segment address, if the SegmentId member of Destination is nonzero. The DirectX graphics kernel subsystem computes the segment address as the sum of the segment offset and the base address of the segment: SegmentAddress = SegmentOffset + Segment.BaseAddr.

pMdl

[in] A pointer to a buffer that contains the MDL structure that describes the system memory pages for the destination, if the SegmentId member of Destination is zero.

Flags

[in] A DXGK_TRANSFERFLAGS structure that identifies, in bit-field flags, the type of special-lock-transfer operation to perform.

MdlOffset

[in] The offset, in system memory pages, within the MDL structure that the pMdl member points to, to the first system memory page for the current operation. The driver can obtain the physical address of the first system memory page by calling the MmGetMdlPfnArray function as follows.


MmGetMdlPfnArray(pMdl)[MdlOffset];

Fill

[in] A structure that describes the fill operation.

hAllocation

[in] A handle to the allocation that contains content to fill.

FillSize

[in] The size, in bytes, of the memory information to fill.

FillPattern

[in] The pattern to fill the destination with. The video memory manager uses this information to initialize video memory to a specific pattern when an allocation without content is first paged in. In this case, no source exists for the fill request—only a destination exists.

Destination

[in] A structure that describes the destination allocation for the fill operation.

SegmentId

[in] The identifier of a segment within the destination allocation.

SegmentAddress

[in] The destination segment address. The DirectX graphics kernel subsystem computes the segment address as the sum of the segment offset and the base address of the segment: SegmentAddress = SegmentOffset + Segment.BaseAddr.

DiscardContent

[in] A structure that describes the discard-content operation.

hAllocation

[in] A handle to the allocation that contains content to discard.

Flags

[in] A DXGK_DISCARDCONTENTFLAGS structure that identifies, in bit-field flags, the type of discard-content operation to perform.

SegmentId

[in] The identifier of a segment within the allocation to discard content from.

SegmentAddress

[in] A PHYSICAL_ADDRESS data type (which is defined as LARGE_INTEGER) that indicates the segment address. The DirectX graphics kernel subsystem computes the segment address as the sum of the segment offset and the base address of the segment: SegmentAddress = SegmentOffset + Segment.BaseAddr. This location is where content is discarded from.

ReadPhysical

[in] A structure that describes the read-physical operation.

SegmentId

[in] The identifier of a segment that data is read from.

PhysicalAddress

[in] A PHYSICAL_ADDRESS data type (which is defined as LARGE_INTEGER) that indicates the physical address, within the segment that SegmentId specifies, where the data is read.

WritePhysical

[in] A structure that describes the write-physical operation.

SegmentId

[in] The identifier of a segment to which data is written.

PhysicalAddress

[in] A PHYSICAL_ADDRESS data type (which is defined as LARGE_INTEGER) that indicates the physical address, within the segment that SegmentId specifies, where the data is written.

MapApertureSegment

[in] A structure that describes the map-aperture-segment operation.

hDevice

[in] A handle to the device that owns the allocation that hAllocation specifies that is mapped into the aperture segment that SegmentId specifies.

For a shared allocation, hDevice is set to the device that the video memory manager determined to be the owner of the allocation.

hDevice is NULL for the primary allocation.

hAllocation

[in] A handle to the allocation that is mapped into the aperture segment that SegmentId specifies.

hAllocation is NULL when a DMA buffer is mapped into the aperture segment because DMA buffers are not explicitly created by the driver.

SegmentId

[in] The identifier of an aperture segment to configure.

OffsetInPages

[in] The offset, in pages, from the beginning of the segment to the first pages to map.

NumberOfPages

[in] The number of pages to map.

pMdl

[in] A pointer to a buffer that contains the MDL structure that describes the physical system memory pages to map into the aperture segment.

Flags

[in] A DXGK_MAPAPERTUREFLAGS structure that identifies, in bit-field flags, the type of map-aperture-segment operation to perform.

MdlOffset

[in] The offset, in system memory pages, within the MDL structure that the pMdl member points to, to the first system memory page for the current operation. The driver can obtain the physical address of the first system memory page by calling the MmGetMdlPfnArray function as follows.


MmGetMdlPfnArray(pMdl)[MdlOffset];

UnmapApertureSegment

[in] A structure that describes the unmap-aperture-segment operation.

hDevice

[in] A handle to the device that owns the allocation that hAllocation specifies that is unmapped from the aperture segment that SegmentId specifies.

For a shared allocation, hDevice is set to the device that the video memory manager determined to be the owner of the allocation.

hDevice is NULL for the primary allocation.

hAllocation

[in] A handle to the allocation that is unmapped from the aperture segment that SegmentId specifies.

hAllocation is NULL when a DMA buffer is unmapped from the aperture segment because DMA buffers are not explicitly created by the driver.

SegmentId

[in] The identifier of an aperture segment to configure.

OffsetInPages

[in] The offset, in pages, from the beginning of the segment to the first pages to unmap.

NumberOfPages

[in] The number of pages to unmap.

DummyPage

[in] A PHYSICAL_ADDRESS data type (which is defined as LARGE_INTEGER) that indicates the physical address of the placeholder page where the driver should map the range that is unmapped.

SpecialLockTransfer

[in] A structure that describes the special-lock-transfer operation.

hAllocation

[in] A handle to the allocation that the driver's DxgkDdiCreateAllocation function previously returned in the hAllocation member of a DXGK_ALLOCATIONINFO structure, which is part of the DXGKARG_CREATEALLOCATION structure's pAllocationInfo member. The allocation handle points to a buffer that contains private driver data for the special-lock transfer.

TransferOffset

[in] The offset, in bytes, of the first page within the allocation that is transferred. This offset is applied only to a location that a segment location describes. This offset does not apply to an MDL description of a memory range. If the driver requires more than one paging buffer to complete the transfer (that is, the driver returns STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER from its DxgkDdiBuildPagingBuffer function), TransferOffset is the same for each call to DxgkDdiBuildPagingBuffer for this transfer.

TransferSize

[in] The size, in bytes, of the memory information to transfer.

Source

[in] A structure that describes the source allocation. This structure contains a SegmentId member and a union that contains either an offset into a segment of the source allocation (SegmentAddress) or a pointer to an MDL for the source (pMdl).

SegmentId

[in] The identifier of a segment within the source allocation, or zero if the source allocation is described by the pMdl member of the union that Source contains.

(unnamed union)

[in] A union that contains either an offset into a segment of the source allocation (SegmentAddress) or a pointer to an MDL for the source (pMdl).

SegmentAddress

[in] The source segment address, if the SegmentId member of Source is nonzero. The DirectX graphics kernel subsystem computes the segment address as the sum of the segment offset and the base address of the segment: SegmentAddress = SegmentOffset + Segment.BaseAddr.

pMdl

[in] A pointer to a buffer that contains the MDL structure that describes the system memory pages for the source, if the SegmentId member of Source is zero.

Destination

[in] A structure that describes the destination allocation. This structure contains a SegmentId member and a union that contains either an offset into a segment of the destination allocation (SegmentAddress) or a pointer to an MDL for the destination (pMdl).

SegmentId

[in] The identifier of a segment within the destination allocation, or zero if the destination allocation is described by the pMdl member of the union that Destination contains.

(unnamed union)

[in] A union that contains either an offset into a segment of the destination allocation (SegmentAddress) or a pointer to an MDL for the destination (pMdl).

SegmentAddress

[in] The destination segment address, if the SegmentId member of Destination is nonzero. The DirectX graphics kernel subsystem computes the segment address as the sum of the segment offset and the base address of the segment: SegmentAddress = SegmentOffset + Segment.BaseAddr.

pMdl

[in] A pointer to a buffer that contains the MDL structure that describes the system memory pages for the destination, if the SegmentId member of Destination is zero.

Flags

[in] A DXGK_TRANSFERFLAGS structure that identifies, in bit-field flags, the type of special-lock-transfer operation to perform.

SwizzlingRangeId

[in] A UINT value that identifies the swizzling range.

SwizzlingRangeData

[in] A UINT value that specifies swizzling range data.

InitContextResource

[in] A structure that describes the context initialization operation.

Supported beginning with Windows 8.

hAllocation

[in] A handle to the context allocation that was created when the driver called DxgkCbCreateContextAllocation. The handle to this allocation is returned in the hAllocation member of the DXGKARGCB_CREATECONTEXTALLOCATION structure. The driver passes a pointer to this structure in the ContextAllocation parameter when it calls DxgkCbCreateContextAllocation.

Destination

[in] A structure that describes the destination context allocation. This structure contains a SegmentId member and a union that contains either an offset into a segment of the destination context allocation (SegmentAddress) or a pointer to an MDL for the destination (pMdl).

SegmentId

[in] The identifier of a segment within the destination context allocation, or zero if the destination context allocation is described by the pMdl member of the union that Destination contains.

(unnamed union)

[in] A union that contains either an offset into a segment of the destination context allocation (SegmentAddress) or a pointer to an MDL for the destination (pMdl).

SegmentAddress

[in] The destination segment address, if the SegmentId member of Destination is nonzero. The DirectX graphics kernel subsystem computes the segment address as the sum of the segment offset and the base address of the segment: SegmentAddress = SegmentOffset + Segment.BaseAddr.

pMdl

[in] A pointer to a buffer that contains the MDL structure that describes the system memory pages for the destination, if the SegmentId member of Destination is zero.

VirtualAddress

[in] The virtual address of the destination context allocation. This address is valid during the lifetime of the context allocation.

Follow procedures in Virtual addresses for destination context allocations in the DxgkCbCreateContextAllocation topic to ensure that the virtual address is valid.

TransferVirtual

A DXGK_BUILDPAGINGBUFFER_TRANSFERVIRTUAL structure that describes the operation used to transfer allocation content between locations in memory.

FillVirtual

A DXGK_BUILDPAGINGBUFFER_FILLVIRTUAL structure that describes the operation used to fill an allocation with a pattern.

UpdatePageTable

A DXGK_BUILDPAGINGBUFFER_UPDATEPAGETABLE structure that describes the operation used to update a page table.

FlushTlb

A DXGK_BUILDPAGINGBUFFER_FLUSHTLB structure that describes the operation used to flush the translation look-aside buffers.

CopyPageTableEntries

A DXGK_BUILDPAGINGBUFFER_COPYPAGETABLEENTRIES structure that describes the operation used copy page table entries from one location to another.

UpdateContextAllocation

A DXGK_BUILDPAGINGBUFFER_UPDATECONTEXTALLOCATION structure that describes the operation used to update the content of a context or device allocation.

NotifyResidency

A DXGK_BUILDPAGINGBUFFER_NOTIFYRESIDENCY structure that describes a residency allocation change operation.

Reserved

This member is reserved and should not be used.

Reserved

This member is reserved and should not be used.

hSystemContext

[in] A handle to the system context for the paging operation.

DmaBufferGpuVirtualAddress

Remarks

MDL is defined in the Windows Driver Model (WDM) documentation.

Requirements

Version

Supported starting with Windows Vista.

Header

D3dkmddi.h (include D3dkmddi.h)

See also

DXGK_ALLOCATIONINFO
DXGK_DISCARDCONTENTFLAGS
DXGK_MAPAPERTUREFLAGS
DXGK_TRANSFERFLAGS
DXGKARG_CREATEALLOCATION
DXGKARGCB_CREATECONTEXTALLOCATION
DxgkCbCreateContextAllocation
DxgkDdiBuildPagingBuffer
DxgkDdiCreateAllocation
MDL
MmGetMdlPfnArray
pfnLockCb
DXGK_BUILDPAGINGBUFFER_TRANSFERVIRTUAL
DXGK_BUILDPAGINGBUFFER_FILLVIRTUAL
DXGK_BUILDPAGINGBUFFER_UPDATEPAGETABLE
DXGK_BUILDPAGINGBUFFER_FLUSHTLB
DXGK_BUILDPAGINGBUFFER_COPYPAGETABLEENTRIES
DXGK_BUILDPAGINGBUFFER_NOTIFYRESIDENCY
DXGK_BUILDPAGINGBUFFER_UPDATECONTEXTALLOCATION

 

 

Send comments about this topic to Microsoft

Show: