UMDEtwLogMapAllocation function (umdprovider.h)

Describes how a Microsoft DirectX graphics kernel subsystem (Dxgkrnl.sys) memory allocation, or a portion of the allocation, is being used.

Syntax

void UMDEtwLogMapAllocation(
  ULONGLONG                  hD3DAllocation,
  ULONGLONG                  hDxgAllocation,
  ULONGLONG                  Offset,
  ULONGLONG                  Size,
  UMDETW_ALLOCATION_USAGE    Usage,
  UMDETW_ALLOCATION_SEMANTIC Semantic
);

Parameters

hD3DAllocation

A handle to the Direct3D allocation.

For Direct3D 10 user-mode drivers, the handle will be the value of the hResource parameter of the CreateResource(D3D10) function. For Direct3D 9 user-mode drivers, the handle will be the value of the pResource parameter that the driver returns in the CreateResource function.

The driver can set this value to NULL if it uses allocations internally.

hDxgAllocation

A handle to the DirectX graphics kernel subsystem (Dxgkrnl.sys) allocation that the Direct3D allocation is mapped to.

Offset

The starting address, in bytes, of the Direct3D allocation within the Dxgkrnl allocation.

Size

The size, in bytes, of the Direct3D allocation within the Dxgkrnl allocation.

Usage

A UMDETW_ALLOCATION_USAGE structure that indicates the reason for this mapping.

Semantic

If the allocation is used internally by the user-mode driver, this is a UMDETW_ALLOCATION_SEMANTIC structure that indicates what the allocation is used for.

Return value

None

Remarks

The user-mode display driver must completely account for the video memory it allocates, so it must call this function to log an event every time the allocation changes.

Examples of when to call this function are:

• A Direct3D allocation is packed into a DirectX graphics kernel subsystem (Dxgkrnl.sys) allocation.
• A Dxgkrnl allocation is created as a scratch surface. In this case, set the hD3DAllocation parameter to NULL.

UMDEtwLogMapAllocation is defined inline in Umdprovider.h as:

FORCEINLINE void LogMapAllocation(BOOLEAN Enter,
                    ULONGLONG hD3DAllocation,
                    ULONGLONG hDxgAllocation,
                    ULONGLONG Offset,
                    ULONGLONG Size,
                    UMDETW_ALLOCATION_USAGE Usage,
                    UMDETW_ALLOCATION_SEMANTIC Semantic)
{
    if (Enabled)
    {   
        EVENT_DATA_DESCRIPTOR Descriptors[6];
        
        // Create a description of the event
        EventDataDescCreate(&Descriptors[0], &hD3DAllocation, 8);
        EventDataDescCreate(&Descriptors[1], &hDxgAllocation, 8);
        EventDataDescCreate(&Descriptors[2], &Offset, 8);
        EventDataDescCreate(&Descriptors[3], &Size, 8);
        EventDataDescCreate(&Descriptors[4], &Usage, 4);
        EventDataDescCreate(&Descriptors[5], &Semantic, 4);

        // Log the event
        EventWrite(
            RegHandle,
            Enter ? (InRundown ? &RundownAllocationEvent : &MapAllocationEvent) : &UnmapAllocationEvent,
            sizeof(Descriptors) / sizeof(Descriptors[0]),
            Descriptors
        );
    }
}

FORCEINLINE void UMDEtwLogMapAllocation(ULONGLONG hD3DAllocation,
                            ULONGLONG hDxgAllocation,
                            ULONGLONG Offset,
                            ULONGLONG Size,
                            UMDETW_ALLOCATION_USAGE Usage,
                            UMDETW_ALLOCATION_SEMANTIC Semantic)
{
    LogMapAllocation(TRUE,
                     hD3DAllocation,
                     hDxgAllocation,
                     Offset,
                     Size,
                     Usage,
                     Semantic);
}

Requirements

Requirement	Value
Minimum supported client	Windows 8
Minimum supported server	Windows Server 2012
Target Platform	Desktop
Header	umdprovider.h (include Umdprovider.h)

See also

CreateResource

CreateResource(D3D10)

UMDETW_ALLOCATION_SEMANTIC

UMDETW_ALLOCATION_USAGE