Export (0) Print
Expand All
Expand Minimize

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_WIN7)
    struct {
      HANDLE                 hAllocation;
      SIZE_T                 AllocationOffsetInBytes;
      SIZE_T                 TransferOffsetInBytes;
      SIZE_T                 TransferSizeInBytes;
      D3DGPU_VIRTUAL_ADDRESS SourceVirtualAddress;
      D3DGPU_VIRTUAL_ADDRESS DestinationVirtualAddress;
      DXGK_TRANSFERFLAGS2    Flags;
      UINT                   SwizzlingRangeId;
      UINT                   SwizzlingRangeData;
    } TransferVirtual;
    struct {
      HANDLE                 hAllocation;
      SIZE_T                 AllocationOffsetInBytes;
      SIZE_T                 FillSizeInBytes;
      UINT                   FillPattern;
      D3DGPU_VIRTUAL_ADDRESS DestinationVirtualAddress;
    } FillVirtual;
#endif 
#if (DXGKDDI_INTERFACE_VERSION >= DXGKDDI_INTERFACE_VERSION_WIN8)
    struct {
      HANDLE hAllocation;
      struct {
        UINT  SegmentId;
        union {
          LARGE_INTEGER SegmentAddress;
          MDL           *pMdl;
        };
        PVOID VirtualAddress;
      } Destination;
    } InitContextResource;
#endif 
    struct {
      UINT Reserved[64];
    } Reserved;
  };
  HANDLE                           hSystemContext;
} 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. This member can be one of the following values.

ValueMeaning

DXGK_OPERATION_TRANSFER

Perform a transfer operation that moves the content of an allocation from one location to another.

DXGK_OPERATION_FILL

Fill an allocation with a specified pattern.

DXGK_OPERATION_DISCARD_CONTENT

Notifies the driver that an allocation is discarded from the allocation's current location in a memory segment (that is, the allocation is evicted and not copied back to system memory).

DXGK_OPERATION_READ_PHYSICAL

Perform a read-physical operation that reads from a specified physical memory address.

DXGK_OPERATION_WRITE_PHYSICAL

Perform a write-physical operation that writes to a specified physical memory address.

DXGK_OPERATION_MAP_APERTURE_SEGMENT

Perform a map-aperture-segment operation that maps a memory descriptor list (MDL) into a range of an aperture segment.

DXGK_OPERATION_UNMAP_APERTURE_SEGMENT

Perform an unmap-aperture-segment operation that unmaps a previously mapped range of an aperture segment.

DXGK_OPERATION_SPECIAL_LOCK_TRANSFER

Perform a special transfer operation that moves the content of an allocation from one location to another. In this operation, the content of the allocation is transferred from or to the alternate virtual address that was set up for the allocation (that is, when the pfnLockCb function was called with the UseAlternateVA bit-field flag set).

DXGK_OPERATION_VIRTUAL_TRANSFER

Reserved for system use. Do not use in your driver. This value is supported beginning with Windows 7.

DXGK_OPERATION_VIRTUAL_FILL

Reserved for system use. Do not use in your driver. This value is supported beginning with Windows 7.

DXGK_OPERATION_INIT_CONTEXT_RESOURCE

Perform an context initialization operation for a GPU context or device-specific context. This value is supported beginning with Windows 8.

Note  The display miniport driver allocates context resources by calling DxgkCbCreateContextAllocation.

 

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.

TransferVirtual

A structure that is reserved for future use.

hAllocation

Reserved for future use.

AllocationOffsetInBytes

Reserved for future use.

TransferOffsetInBytes

Reserved for future use.

TransferSizeInBytes

Reserved for future use.

SourceVirtualAddress

Reserved for future use.

DestinationVirtualAddress

Reserved for future use.

Flags

Reserved for future use.

SwizzlingRangeId

Reserved for future use.

SwizzlingRangeData

Reserved for future use.

FillVirtual

A structure that is reserved for future use.

hAllocation

Reserved for future use.

AllocationOffsetInBytes

Reserved for future use.

FillSizeInBytes

Reserved for future use.

FillPattern

Reserved for future use.

DestinationVirtualAddress

Reserved for future use.

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.

Reserved

A structure that is reserved for future use.

Reserved

An array of 32-bit values that are reserved for future use.

hSystemContext

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

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

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft