DXGKETW_ALLOCATIONFLAGS structure

Used in the DXGKETW_CREATEALLOCATIONEVENT.Flags member to identify properties for an allocation.

Syntax

typedef struct _DXGKETW_ALLOCATIONFLAGS {
  union {
    struct {
      UINT CpuVisible;
      UINT PermanentSysMem;
      UINT Cached;
      UINT Protected;
      UINT ExistingSysMem;
      UINT ExistingKernelSysMem;
      UINT FromEndOfSegment;
      UINT Swizzled;
      UINT Overlay;
      UINT Capture;
      UINT UseAlternateVA;
      UINT SynchronousPaging;
      UINT LinkMirrored;
      UINT LinkInstanced;
      UINT Reserved;
      UINT Privileged;
      UINT PinnedBackingStore;
      UINT PagingBuffer;
      UINT Shareable;
      UINT Primary;
      UINT ManagedPrimary;
    };
    UINT   Value;
  };
} DXGKETW_ALLOCATIONFLAGS;

Members

• CpuVisible
  A UINT value that specifies whether the allocation is directly accessible by the CPU. The display miniport driver must set this flag for the user-mode display driver to successfully call the pfnLockCb function on the allocation. If this flag is not set on the allocation, pfnLockCb returns an error.

  Note that only the process that created a shared allocation can lock that allocation.

• PermanentSysMem
  A UINT value that specifies whether a copy of the allocation should be kept in system memory even when the content is located in a memory segment. By default, a surface system memory backing store is lost when transferring an allocation to a memory segment. When the PermanentSysMem flag is specified and the allocation is evicted from a memory segment, the content of the allocation is discarded and not paged out if the allocation is not dirty (that is, the allocation was not the target of a write operation since it was paged in).

  A call to pfnLockCb on the allocation always returns the system memory backing store for the allocation. If the allocation is located in a memory segment when the user-mode display driver calls pfnLockCb, the memory segment resource for the allocation is updated with the new content. This update appears, to the display miniport driver, as a regular paging operation through the DxgkDdiBuildPagingBuffer function. Note that if the display miniport driver requires a minimal region size or alignment for a paging operation, this requirement should be reflected in the region that is being locked. When the driver sets PermanentSysMem, the driver must also set the CpuVisible member. The driver must not set PermanentSysMem on the primary surface.

• Cached
  A UINT value that specifies whether the allocation backing store should be allocated as cached memory; by default, the allocation backing store is stored as write-combined memory. When a cached-memory allocation is used in a segment that is not cache coherent (for example, a memory segment or AGP segment), the video memory manager ensures coherency for the content of the allocation by flushing it from the processor's cache at the appropriate time.

  When the driver sets Cached and also sets the ExistingSysMem or ExistingKernelSysMem member, the driver indicates to the video memory manager that the existing memory was mapped cacheable. If the existing memory was mapped cacheable but the driver fails to set the Cached member, the video memory manager cannot ensure data coherency, and corruption occurs. The driver should set the Cached member for an allocation that is to be read by the application or the user-mode display driver. The driver should never set the Cached member for a write-only allocation.

  When the driver sets this member, the driver must also set the CpuVisible member. The driver must not set Cached on the primary surface.

• Protected
  A UINT value that specifies whether the allocation backing store should be allocated in kernel memory instead of user address space to protect the allocation from potential direct CPU access by an application. The driver cannot set this member in combination with the PermanentSysMem, ExistingSysMem, or ExistingKernelSysMem member. The driver must not set Protected on the primary surface.

• ExistingSysMem
  A UINT value that specifies whether the video memory manager should use the existing system memory range as a backing store for the allocation. The system memory range must be a valid user-mode address for the current process for the size of the allocation. The system memory range must also be page aligned and must be a page multiple in size.

  If the system memory range is a cacheable virtual address, the driver should set the Cached member to inform the video memory manager to ensure cache coherency on the allocation. If the Cached member is not specified, the video memory manager determines that the system memory range is uncacheable, write combined, or cacheable; however, in this situation, the driver either ensures cache coherency or determines that cache coherency is not an issue for the specified usage.

  Note that this type of allocation implicitly has the same lock semantics as an allocation in which the PermanentSysMem member is set.

  The driver cannot set ExistingSysMem in combination with the PermanentSysMem, Protected, or ExistingKernelSysMem member. The driver must not set ExistingSysMem on the primary surface.

• ExistingKernelSysMem
  A UINT value that specifies whether the video memory manager should use the existing system memory range as a backing store for the allocation. The system memory range must be a valid kernel-mode address that is aligned on a page and a page multiple in size.

  If the system memory range is a cacheable virtual address, the driver should set the Cached member to inform the video memory manager to ensure cache coherency on the allocation. If the Cached member is not specified, the video memory manager determines that the system memory range is uncacheable, write combined, or cacheable; however, in this situation, the driver either ensures cache coherency or determines that cache coherency is not an issue for the specified usage.

  Note that this type of allocation implicitly has the same lock semantics as an allocation in which the PermanentSysMem member is set.

  The driver cannot set ExistingKernelSysMem in combination with the PermanentSysMem, Protected, or ExistingSysMem member. The driver must not set ExistingKernelSysMem on the primary surface.

• FromEndOfSegment
  A UINT value that specifies whether the allocation should be allocated from the end of a segment during paging. The video memory manager scans a segment address space and looks for room for the allocation from the end of the segment instead of scanning from the start of the segment (which is the default behavior). However, the hinted and preferred segment information takes precedent over this flag.

• Swizzled
  A UINT value that specifies whether the allocation is swizzled and requires special support by the video memory manager to lock the allocation. For more information about swizzled allocations, see Locking Swizzled Allocations.

• Overlay
  A UINT value that specifies whether the allocation is for an overlay operation. Overlay allocations are pinned in memory, and the video memory manager cannot evict them unless the Timeout Detection and Recovery (TDR) process, Plug and Play (PnP) stop, or level three synchronization occurs. Note that before level three synchronization occurs, overlays are typically destroyed. By default, overlay allocations are limited and cannot occupy more than the last 20 percent of a segment. If an overlay allocation is allocated in an aperture segment, the display miniport driver should limit the size of any other allocation that uses that aperture segment as an eviction segment to 80 percent of the segment size. The display miniport driver indicates that an allocation can use a segment for eviction by specifying the appropriate bit for the segment in the EvictionSegmentSet member of the DXGK_ALLOCATIONINFO structure for the allocation. If the display miniport driver does not limit the size of another allocation, the video memory manager cannot evict that allocation through the segment because the pinned allocation (that is, the overlay allocation) occupies the area that is required for eviction. In this case, the content of the other allocation that is being evicted is lost, and the application that owns the lost allocation can no longer render with that allocation.

• Capture
  A UINT value that specifies whether the allocation is used for a capture operation. Capture allocations are pinned in memory similarly to overlay allocations. Therefore, the issues that apply to overlay allocations also apply to capture allocations. For more information about these issues, see the description of the Overlay flag. Note that before level three synchronization occurs, captures are typically stopped.

• UseAlternateVA
  A UINT value that specifies whether the primary allocation can be locked. UseAlternateVA is valid only for the primary allocation. If UseAlternateVA is specified for any other allocation, the allocation is not created. When a primary allocation is created by using UseAlternateVA, a swizzling range for the primary allocation is set up when the allocation is created.

• SynchronousPaging
  A UINT value that specifies whether the allocation should be paged in synchronously. If the display miniport driver sets this bit for an allocation, the video memory manager will wait until the allocation is no longer busy (that is, the video memory manager will wait until the graphics processing unit (GPU) reports all of the fences that reference the allocation) before the video memory manager submits a paging buffer that references the allocation.

  Similarly, the video memory manager will wait for a paging operation on a synchronous allocation to complete before the video memory manager allows the driver to submit a non-paging direct memory access (DMA) buffer.

• LinkMirrored
  A UINT value that specifies whether a single instance of an allocation should be replicated across all physical adapters in a logical adapter (that is, a link). The video memory manager calls the driver to page in and evict the allocation on all physical adapters with a single shared backing store in system memory.

• LinkInstanced
  A UINT value that specifies whether different instances of an allocation will be paged in and evicted from all physical adapters in a logical adapter (that is, a link). One system memory backing store exists per physical adapter in a logical adapter.

• Reserved
  Reserved for system use and should be set to zero.

• Privileged
  Reserved for system use and should be set to zero.

• PinnedBackingStore
  Reserved for system use and should be set to zero.

• PagingBuffer
  Reserved for system use and should be set to zero.

• Shareable
  Reserved for system use and should be set to zero.

• Primary
  Reserved for system use and should be set to zero.

• ManagedPrimary
  Reserved for system use and should be set to zero.

• Value
  A member in the union that DXGKETW_ALLOCATIONFLAGS contains that can hold a 32-bit value that identifies properties of the allocation.

Remarks

The display miniport driver specifies these flags for the video memory manager in the DXGK_ALLOCATIONINFOFLAGS structure.

Requirements

Minimum supported client	Windows 8 Release Preview
Minimum supported server	Windows Server 2012
Header	Dxetwevt.h (include Dxetwevt.h)

See also

DXGK_ALLOCATIONINFOFLAGS

DxgkDdiBuildPagingBuffer

pfnLockCb

 

 

Send comments about this topic to Microsoft

Build date: 7/11/2012