Muokkaa

Jaa

MCDM kernel-mode driver implementation guidelines

  • Artikkeli

This article provides guidance on how to write the kernel-mode driver (KMD) portion of a Microsoft Compute Only Driver (MCDM) driver, also referred to as a compute-only driver.

See also the following articles:

Driver INF file

MCDM devices belong to the ComputeAccelerator class, which needs to be specified in the driver's INF file:

[Version]
...
Class=ComputeAccelerator
ClassGuid={F01A9D53-3FF6-48D2-9F97-C8A7004BE10C}
...

Driver initialization

An MCDM driver must supply a DriverEntry function that performs the following steps:

Driver function support requirements

An MCDM driver exposes the functions that it implements in the DRIVER_INITIALIZATION_DATA structure.

Minimum required support

At a minimum, an MCDM driver must supply the following device driver interface (DDI) functions:

CPU host aperture support

If CPU host aperture is supported, pointers to the following functions must also be provided:

For more information, see CPU host aperture.

Physical addressing support

If physical addressing is used, pointers to the following functions must also be provided:

GPU virtual addressing support

If GPU virtual addressing is used, pointers to the following functions must also be provided:

IoMmu isolation support

If IoMmu isolation is supported, pointers to the following functions must also be provided:

For optional link adapter support, a pointer to the following function must also be provided:

Power management support

For optional power management support, pointers to the following functions must also be provided:

Power management support is required on Modern Standby or Connected Standby systems.

For more information, see GPU power management of idle states and active power.

Surprise removal support

For optional surprise removal support, pointers to the following functions must also be provided:

Cancel support

For optional cancel support, pointers to the following functions must also be provided:

Interface support

For optional interface support, pointers to the following functions must also be provided:

Hardware scheduling support

For optional hardware scheduling support, pointers to the following functions must also be provided:

UpdateAllocationProperty support

For optional UpdateAllocationProperty support, pointers to the following functions must also be provided:

Escape support

For optional escape support, pointers to the following functions must also be provided:

Event Tracing for Windows support

For optional ETW support, pointers to the following functions must also be provided:

Child device support

For optional child device support, pointers to the following functions must also be provided:

Power consumption reporting support

For optional power consumption reporting support, pointers to the following functions must also be provided:

Command submission validation

For optional command submission validation, pointers to the following functions must also be provided:

IOCTL support

For optional IOCTL support, a pointer to the following function can be provided:

DxgkDdiDispatchIoRequest

Prohibited functions

The following DDIs must not be provided in an MCDM driver:

  • DxgkDdiAcquireSwizzlingRange
  • DxgkDdiCheckMultiPlaneOverlaySupport
  • DxgkDdiCheckMultiPlaneOverlaySupport2
  • DxgkDdiCheckMultiPlaneOverlaySupport3
  • DxgkDdiCommitVidPn
  • DxgkDdiControlDiagnosticReporting
  • DxgkDdiControlInterrupt
  • DxgkDdiControlInterrupt2
  • DxgkDdiControlModeBehavior
  • DxgkDdiCreateOverlay
  • DxgkDdiCreatePeriodicFrameNotification
  • DxgkDdiCreateProtectedSession
  • DxgkDdiDestroyOverlay
  • DxgkDdiDestroyPeriodicFrameNotification
  • DxgkDdiDestroyProtectedSession
  • DxgkDdiDisplayDetectControl
  • DxgkDdiEnumVidPnCofuncModality
  • DxgkDdiExchangePreStartInfo
  • DxgkDdiFlipOverlay
  • DxgkDdiGetMultiPlaneOverlayCaps
  • DxgkDdiGetPostCompositionCaps
  • DxgkDdiGetScanLine
  • DxgkDdiIsSupportedVidPn
  • DxgkDdiNotifyAcpiEvent
  • DxgkDdiNotifyFocusPresent
  • DxgkDdiPostMultiPlaneOverlayPresent
  • DxgkDdiPresent
  • DxgkDdiQueryConnectionChange
  • DxgkDdiQueryCurrentFence

WDDM 1.x functions

The following functions are used for WDDM 1.x drivers only:

  • DxgkDdiQueryDiagnosticTypesSupport
  • DxgkDdiQueryVidPnHWCapability
  • DxgkDdiRecommendFunctionalVidPn
  • DxgkDdiRecommendMonitorModes
  • DxgkDdiRecommendVidPnTopology
  • DxgkDdiReleaseSwizzlingRange
  • DxgkDdiRenderGdi
  • DxgkDdiRenderKm
  • DxgkDdiSetDisplayPrivateDriverFormat
  • DxgkDdiSetPalette
  • DxgkDdiSetPointerPosition
  • DxgkDdiSetPointerShape
  • DxgkDdiSetPowerPState (the driver shouldn't report any P-state power components)
  • DxgkDdiSetTargetAdjustedColorimetry
  • DxgkDdiSetTargetAdjustedColorimetry2
  • DxgkDdiSetTargetAnalogCopyProtection
  • DxgkDdiSetTargetContentType
  • DxgkDdiSetTargetGamma
  • DxgkDdiSetTimingsFromVidPn
  • DxgkDdiSetVideoProtectedRegion
  • DxgkDdiSetVidPnSourceAddress
  • DxgkDdiSetVidPnSourceAddressWithMultiPlaneOverlay
  • DxgkDdiSetVidPnSourceAddressWithMultiPlaneOverlay2
  • DxgkDdiSetVidPnSourceAddressWithMultiPlaneOverlay3
  • DxgkDdiSetVidPnSourceVisibility
  • DxgkDdiStopCapture
  • DxgkDdiStopDeviceAndReleasePostDisplayOwnership
  • DxgkDdiSubmitRender
  • DxgkDdiSystemDisplayEnable
  • DxgkDdiSystemDisplayWrite
  • DxgkDdiUpdateActiveVidPnPresentPath
  • DxgkDdiUpdateMonitorLinkInfo
  • DxgkDdiUpdateOverlay

Query adapter info requirements

As previously stated, a compute-only driver must support DxgkDdiQueryAdapterInfo.

The following DXGK_QUERYADAPTERINFOTYPE types must be supported:

Support for the following DXGK_QUERYADAPTERINFOTYPE types is optional:

  • DXGK_ADAPTER_PERFDATA
  • DXGK_ADAPTER_PERFDATACAPS
  • DXGKQAITYPE_UMDRIVERPRIVATE
  • DXGKQAITYPE_PHYSICALADAPTERCAPS
  • DXGK_NODE_PERFDATA
  • DXGK_GPUVERSION

If one or more invalid memory blocks were reported, the following DXGK_QUERYADAPTERINFOTYPE must be supported:

  • DXGKQAITYPE_SEGMENTMEMORYSTATE

If GPUVA is supported, the following DXGK_QUERYADAPTERINFOTYPE must be supported:

  • DXGKQAITYPE_GPUMMUCAPS
  • DXGKQAITYPE_PAGETABLELEVELDESC

If the number of power components reported is greater than zero, the following DXGK_QUERYADAPTERINFOTYPE must be supported:

  • DXGKQAITYPE_POWERCOMPONENTINFO

If the IoMmuSecureModeSupported cap is set, the following DXGK_QUERYADAPTERINFOTYPE must be supported:

  • DXGKQAITYPE_FRAMEBUFFERSAVESIZE
  • DXGKQAITYPE_HARDWARERESERVEDRANGES

The following DXGK_QUERYADAPTERINFOTYPE must not be supported:

  • DXGKQAITYPE_DEVICE_TYPE_CAPS
  • DXGKQAITYPE_DISPLAY_DRIVERCAPS_EXTENSION
  • DXGKQAITYPE_DISPLAYID_DESCRIPTOR
  • DXGKQAITYPE_INTEGRATED_DISPLAY_DESCRIPTOR
  • DXGKQAITYPE_INTEGRATED_DISPLAY_DESCRIPTOR2
  • DXGKQAITYPE_POWERCOMPONENTPSTATEINFO
  • DXGKQAITYPE_PREFERREDGPUNODE
  • DXGKQAITYPE_QUERYCOLORIMETRYOVERRIDES
  • DXGKQAITYPE_QUERYSEGMENT
  • DXGKQAITYPE_QUERYSEGMENT2
  • DXGKQAITYPE_QUERYSEGMENT3
  • DXGKQAITYPE_UEFIFRAMEBUFFERRANGES

Driver capability requirements

The following DXGK_DRIVERCAPS structure members must be set to appropriate values:

Member Notes
HighestAcceptableAddress If this address is less than the highest physical address of the system memory that is present during driver load, the load will fail.
InterruptMessageNumber Set as appropriate.
SchedulingCaps See SchedulingCaps requirements.
MemoryManagementCaps See MemoryManagementCaps requirements.
GpuEngineTopology Set NbAsymetricProcessingNodes to the number supported GPU engines.
WDDMVersion Must be set to DXGKDDI_WDDMv2_6 or later.
PreemptionCaps Set GraphicsPreemptionGranularity appropriately to the level supported by the hardware. At a minimum, you should attempt to support packet-level preemption for dequeue packets that are scheduled but haven't yet started executing. Set ComputePreemptionGranularity to anything other than D3DKMDT_COMPUTE_PREEMPTION_NONE.
SupportPerEngineTDR Must be set to TRUE. See TDR Changes in Windows 8 and later.
SupportRuntimePowerManagement Set as appropriate. See GPU power management of idle states and active power.
SupportSurpriseRemovalInHibernation Set to TRUE if the driver supports surprise removal when in hibernation; otherwise set as appropriate. See DXGKDDI_NOTIFY_SURPRISE_REMOVAL.
HybridDiscrete Must be set to FALSE.
HybridIntegrated Must be set to FALSE.
InternalGpuVirtualAddressRangeStart Set as appropriate. If GpuVA isn't supported, set to zero. If GpuVA is supported, this value specifies the start of the VA range that the OS will use when allocating internal resources for OS internal use.
InternalGpuVirtualAddressRangeEnd Set as appropriate. If GpuVA isn't supported, set to zero. If GpuVA is supported, this value specifies the end of the VA range that the OS will use when allocating internal resources for OS internal use. If both the start and end values are zero, the OS will use the entire available VA range.
SupportSurpriseRemoval Set as appropriate. Set to TRUE if the driver supports surprise removal even outside of hibernation. See DXGKDDI_NOTIFY_SURPRISE_REMOVAL.
ComputeOnly Must be set to TRUE. This flag must be implemented.

The following DXGK_DRIVERCAPS structure members must be set to zero or FALSE, accordingly:

  • MaxAllocationListSlotId
  • ApertureSegmentCommitLimit
  • MaxPointerWidth
  • MaxPointerHeight
  • PointerCaps
  • NumberOfSwizzlingRanges
  • MaxOverlays
  • GammaRampCaps
  • ColorTransformCaps
  • PresentationCaps
  • MaxQueuedFlipOnVSync
  • FlipCaps
  • SupportNonVGA
  • SupportSmoothRotation
  • SupportDirectFlip
  • SupportMultiPlaneOverlay
  • MaxOverlayPlanes
  • SupportMultiPlaneOverlayImmediateFlip
  • CursorScaledWithMultiPlaneOverlayPlane0
  • HybridAcpiChainingRequired
  • MaxQueuedMultiPlaneOverlayFlipVSync
  • SupportContextlessPresent
  • Detachable

SchedulingCaps requirements

The following DXGK_DRIVERCAPS.SchedulingCaps structure members must be set to appropriate values:

Member Notes
MultiEngineAware Must be set to TRUE. See GPU Preemption.
VSyncPowerSaveAware Must be set to FALSE.
PreemptionAware Must be set to TRUE. See GPU Preemption.
NoDmaPatching Must be set to FALSE.
CancelCommandAware Set as appropriate. See DXGKDDI_CANCELCOMMAND.
No64BitAtomics Set as appropriate. See Context Monitoring.
LowIrqlPreemptCommand Set to TRUE. The OS will call the driver's DxgkDdiPreemptCommand at low IRQL.
HwQueuePacketCap Reserved; set to zero.

MemoryManagementCaps requirements

The following DXGK_DRIVERCAPS.MemoryManagementCaps structure members must be set to appropriate values:

Member Notes
OutOfOrderLock Must be set to FALSE.
DedicatedPagingEngine Must be set to FALSE.
PagingEngineCanSwizzle Must be set to FALSE.
SectionBackedPrimary Must be set to FALSE.
CrossAdapterResource Set as appropriate. See Using Cross Adapter Resources in a Hybrid System.
VirtualAddressingSupported Set as appropriate. See GPU Virtual Memory In WDDM 2.0. If this member is set, the driver must also set GpuMmuSupported and/or IoMmuSupported.
GpuMmuSupported Set as appropriate. See GpuMmu Model.
IoMmuSupported Set as appropriate. This cap is set when the device shares page tables with the CPU (shared virtual memory (SVM)). See IoMmu Model.
ReplicateGdiContent Must be set to FALSE.
NonCpuVisiblePrimary Must be set to FALSE.
ParavirtualizationSupported MCDM host drivers that support the virtualization of the device through the GPU partitioning interface (GPU-P with SR-IOV) should set this field to FALSE. All other cases (drivers for physical machines without GPU-P support or guest drivers of vGPUs that have been exposed through GPU-P) should set this field to TRUE.
IoMmuSecureModeSupported Set as appropriate. If this cap is set TRUE, the driver supports IoMmu isolation (the device has a dedicated page table for the IoMmu unit). If this cap is set FALSE, the device can't be used in the "secure" virtual machines (Windows Sandbox or MDAG).
DisableSelfRefreshVRAMInS3 Set as appropriate.

Memory Management

Virtual addressing is required. Physical addressing support might be enabled in the future.

Devices aren't required to support a memory aperture.

Only linear memory-space segments and linear aperture-space segments are supported.