MCDM KM 驱动程序实现指南

  • 项目

本文提供了有关如何编写 Microsoft 仅限计算驱动程序的内核模式驱动程序部分的指导， (MCDM) 驱动程序（也称为仅计算驱动程序）。

另请参阅以下文章：

驱动程序 INF 文件

MCDM 设备属于 ComputeAccelerator 类，需要在 INF 文件中指定：

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

驱动程序初始化

仅限计算的驱动程序必须提供执行以下步骤的 DriverEntry 函数：

驱动程序函数支持要求

仅计算驱动程序公开它在 DRIVER_INITIALIZATION_DATA 结构中实现的函数。

所需的最低支持

仅限计算的驱动程序至少必须提供以下设备驱动程序接口 (DDI) 函数：

CPU 主机光圈支持

如果支持 CPU 主机光圈，则还必须提供指向以下函数的指针：

有关详细信息，请参阅 CPU 主机光圈。

物理寻址支持

如果使用物理寻址，还必须提供指向以下函数的指针：

GPU 虚拟寻址支持

如果使用 GPU 虚拟寻址，还必须提供指向以下函数的指针：

IoMmu 隔离支持

如果支持 IoMmu 隔离，还必须提供指向以下函数的指针：

对于可选的链接适配器支持，还必须提供指向以下函数的指针：

电源管理支持

对于可选的电源管理支持，还必须提供指向以下函数的指针：

注意：新式待机或连接待机系统需要电源管理支持。

有关详细信息，请参阅 空闲状态和活动电源的 GPU 电源管理。

意外删除支持

对于可选的意外删除支持，还必须提供指向以下函数的指针：

取消支持

对于可选的取消支持，还必须提供指向以下函数的指针：

接口支持

对于可选接口支持，还必须提供指向以下函数的指针：

硬件计划支持

对于可选的硬件计划支持，还必须提供指向以下函数的指针：

UpdateAllocationProperty 支持

对于可选的 UpdateAllocationProperty 支持，还必须提供指向以下函数的指针：

  • DxgkDdiValidateUpdateAllocationProperty

转义支持

对于可选的转义支持，还必须提供指向以下函数的指针：

Windows 事件跟踪支持

对于可选的 ETW 支持，还必须提供指向以下函数的指针：

子设备支持

对于可选的子设备支持，还必须提供指向以下函数的指针：

功耗报告支持

对于可选的功耗报告支持，还必须提供指向以下函数的指针：

命令提交验证

对于可选的命令提交验证，还必须提供指向以下函数的指针：

IOCTL 支持

对于可选的 IOCTL 支持，可以提供指向以下函数的指针：

DxgkDdiDispatchIoRequest

禁止的函数

MCDM 驱动程序中不得提供以下 DDI：

  • 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 函数

以下函数仅用于 WDDM 1.x 驱动程序：

  • DxgkDdiQueryDiagnosticTypesSupport
  • DxgkDdiQueryVidPnHWCapability
  • DxgkDdiRecommendFunctionalVidPn
  • DxgkDdiRecommendMonitorModes
  • DxgkDdiRecommendVidPnTopology
  • DxgkDdiReleaseSwizzlingRange
  • DxgkDdiRenderGdi
  • DxgkDdiRenderKm
  • DxgkDdiSetDisplayPrivateDriverFormat
  • DxgkDdiSetPalette
  • DxgkDdiSetPointerPosition
  • DxgkDdiSetPointerShape
  • DxgkDdiSetPowerPState (驱动程序不应报告任何 P 状态电源组件)
  • DxgkDdiSetTargetAdjustedColorimetry
  • DxgkDdiSetTargetAdjustedColorimetry2
  • DxgkDdiSetTargetAnalogCopyProtection
  • DxgkDdiSetTargetContentType
  • DxgkDdiSetTargetGamma
  • DxgkDdiSetTimingsFromVidPn
  • DxgkDdiSetVideoProtectedRegion
  • DxgkDdiSetVidPnSourceAddress
  • DxgkDdiSetVidPnSourceAddressWithMultiPlaneOverlay
  • DxgkDdiSetVidPnSourceAddressWithMultiPlaneOverlay2
  • DxgkDdiSetVidPnSourceAddressWithMultiPlaneOverlay3
  • DxgkDdiSetVidPnSourceVisibility
  • DxgkDdiStopCapture
  • DxgkDdiStopDeviceAndReleasePostDisplayOwnership
  • DxgkDdiSubmitRender
  • DxgkDdiSystemDisplayEnable
  • DxgkDdiSystemDisplayWrite
  • DxgkDdiUpdateActiveVidPnPresentPath
  • DxgkDdiUpdateMonitorLinkInfo
  • DxgkDdiUpdateOverlay

查询适配器信息要求

如前所述，仅计算驱动程序必须支持 DxgkDdiQueryAdapterInfo。

必须支持以下 DXGK_QUERYADAPTERINFOTYPE 类型：

支持以下DXGK_QUERYADAPTERINFOTYPE类型是可选的：

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

如果报告了一个或多个无效内存块，则必须支持以下DXGK_QUERYADAPTERINFOTYPE：

  • DXGKQAITYPE_SEGMENTMEMORYSTATE

如果支持 GPUVA，则必须支持以下DXGK_QUERYADAPTERINFOTYPE：

  • DXGKQAITYPE_GPUMMUCAPS
  • DXGKQAITYPE_PAGETABLELEVELDESC

如果报告的电源组件数大于零，则必须支持以下DXGK_QUERYADAPTERINFOTYPE：

  • DXGKQAITYPE_POWERCOMPONENTINFO

如果设置了 IoMmuSecureModeSupported 上限，则必须支持以下DXGK_QUERYADAPTERINFOTYPE：

  • DXGKQAITYPE_FRAMEBUFFERSAVESIZE
  • DXGKQAITYPE_HARDWARERESERVEDRANGES

不得支持以下DXGK_QUERYADAPTERINFOTYPE：

  • 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

驱动程序功能要求

必须将以下 DXGK_DRIVERCAPS 结构成员设置为适当的值：

成员 备注
HighestAcceptableAddress 如果此地址小于驱动程序加载期间存在的系统内存的最高物理地址，则加载将失败。
InterruptMessageNumber 根据需要设置。
SchedulingCaps 请参阅 SchedulingCaps 要求。
MemoryManagementCaps 请参阅 MemoryManagementCaps 要求。
GpuEngineTopology 将 NbAsymetricProcessingNodes 设置为支持的 GPU 引擎数。
WDDMVersion 必须设置为 DXGKDDI_WDDMv2_6 或更高版本。
PreemptionCaps 将 GraphicsPreemptionGranularity 适当设置为硬件支持的级别。 至少应尝试支持数据包级抢占;即已计划但尚未开始执行的取消排队数据包。 将 ComputePreemptionGranularity 设置为除 D3DKMDT_COMPUTE_PREEMPTION_NONE 以外的任何内容。
SupportPerEngineTDR 必须设置为 TRUE。 请参阅 Windows 8 及更高版本中的 TDR 更改。
SupportRuntimePowerManagement 根据需要设置。 请参阅 空闲状态和可用电源的 GPU 电源管理。
SupportSurpriseRemovalInHibernation 如果驱动程序支持在休眠时意外删除，则设置为 TRUE;否则，请根据需要进行设置。 请参阅 DXGKDDI_NOTIFY_SURPRISE_REMOVAL。
HybridDiscrete 必须设置为 FALSE。
HybridIntegrated 必须设置为 FALSE。
InternalGpuVirtualAddressRangeStart 根据需要设置。 如果不支持 GpuVA，请将 设置为零。 如果支持 GpuVA，则此值指定在分配内部资源供 OS 内部使用时 OS 将使用的 VA 范围的开头。
InternalGpuVirtualAddressRangeEnd 根据需要设置。 如果不支持 GpuVA，请将 设置为零。 如果支持 GpuVA，则此值指定在分配内部资源供 OS 内部使用时 OS 将使用的 VA 范围的末尾。 如果起始值和结束值均为零，则操作系统将使用整个可用 VA 范围。
SupportSurpriseRemoval 根据需要设置。 如果驱动程序即使在休眠之外也支持意外删除，则设置为 TRUE。 请参阅 DXGKDDI_NOTIFY_SURPRISE_REMOVAL。
ComputeOnly 必须设置为 TRUE。 必须实现此标志。

以下 DXGK_DRIVERCAPS 结构成员必须相应地设置为零或 FALSE：

  • MaxAllocationListSlotId
  • ApertureSegmentCommitLimit
  • MaxPointerWidth
  • MaxPointerHeight
  • PointerCaps
  • NumberOfSwizzlingRanges
  • MaxOverlays
  • GammaRampCaps
  • ColorTransformCaps
  • PresentationCaps
  • MaxQueuedFlipOnVSync
  • FlipCaps
  • SupportNonVGA
  • SupportSmoothRotation
  • SupportDirectFlip
  • SupportMultiPlaneOverlay
  • MaxOverlayPlanes
  • SupportMultiPlaneOverlayImmediateFlip
  • CursorScaledWithMultiPlaneOverlayPlane0
  • HybridAcpiChainingRequired
  • MaxQueuedMultiPlaneOverlayFlipVSync
  • SupportContextlessPresent
  • 可分离电脑

SchedulingCaps 要求

以下 DXGK_DRIVERCAPS。SchedulingCaps 结构成员必须设置为适当的值：

成员 备注
MultiEngineAware 必须设置为 TRUE。 请参阅 GPU 抢占。
VSyncPowerSaveAware 必须设置为 FALSE。
PreemptionAware 必须设置为 TRUE。 请参阅 GPU 抢占。
NoDmaPatching 必须设置为 FALSE。
CancelCommandAware 根据需要设置。 请参阅 DXGKDDI_CANCELCOMMAND。
No64BitAtomics 根据需要设置。 请参阅 上下文监视。
LowIrqlPreemptCommand 设置为 TRUE。 操作系统将在低 IRQL 下调用驱动程序的 DxgkDdiPreemptCommand 。
HwQueuePacketCap 保留;设置为零。

MemoryManagementCaps 要求

以下 DXGK_DRIVERCAPS。MemoryManagementCaps 结构成员必须设置为适当的值：

成员 备注
OutOfOrderLock 必须设置为 FALSE。
DedicatedPagingEngine 必须设置为 FALSE。
PagingEngineCanSwizzle 必须设置为 FALSE。
SectionBackedPrimary 必须设置为 FALSE。
CrossAdapterResource 根据需要设置。 请参阅 在混合系统中使用跨适配器资源。
VirtualAddressingSupported 根据需要设置。 请参阅 WDDM 2.0 中的 GPU 虚拟内存。 如果设置了此成员，驱动程序还必须设置 GpuMmuSupported 和/或 IoMmuSupported。
GpuMmuSupported 根据需要设置。 请参阅 GpuMmu 模型。
IoMmuSupported 根据需要设置。 当设备与 CPU 共享页表 (共享虚拟内存 (SVM) ) 时，将设置此上限。 请参阅 IoMmu 模型。
ReplicateGdiContent 必须设置为 FALSE。
NonCpuVisiblePrimary 必须设置为 FALSE。
ParavirtualizationSupported 通过 GPU 分区接口 (GPU-P 和 SR-IOV) 支持设备虚拟化的 MCDM 主机驱动程序应将此字段设置为 FALSE。 所有其他情况下 (没有 GPU-P 支持的物理计算机的驱动程序，或者已通过 GPU-P) 公开的 vGPU 的来宾驱动程序，应将此字段设置为 TRUE。
IoMmuSecureModeSupported 根据需要设置。 如果此上限设置为 TRUE，则驱动程序支持 IoMmu 隔离， (设备具有 IoMmu 单元) 的专用页表。 如果此上限设置为 FALSE，则设备不能在“安全”虚拟机 (Windows 沙盒 或 MDAG) 中使用。
DisableSelfRefreshVRAMInS3 根据需要设置。

内存管理

需要虚拟寻址。 将来可能会启用物理寻址支持。

设备不需要支持内存光圈。

仅支持 线性内存空间段 和 线性光圈空间段 。