Windows显示驱动（WDDM）编程初步（1）

欢迎转载【作者：张佩】【原文：http://www.yiiyee.cn/Blog/wddm1/】

WDDM Frame

Windows显示驱动从Vista开始，使用新的WDDM编程框架，称为Windows Display Driver  Model。也有一种最初的名称是LDDM，L代表Longhorn，但后来微软在所有产品线上都不再使用Longhorn代号，故而改成现在的名称。虽然在有些地方还能看到LDDM的说法，但应理解成旧文档的遗存，不应该做概念上的区分。

WDDM框架是一种典型的小端口（miniport）驱动框架。NT系统中的所有小端口框架，都是基于WDM框架来实现的，但小端口框架对外提供了更高级的接口，以简化编程的难度，并提高稳定性。如下图所示，中间的WDDM是系统提供的编程框架，我们基于这个框架，编写里面的小端口驱动，也就是显示驱动。

显示驱动类型

现在的显卡设备，可以按照功能将它分成显示和计算两类。大部分的显卡是用来连接显示器显示图片和动画用的，也有些显卡主要确实用来做科学计算用的。显卡处理器（GPU）对浮点运算有较强的能力，而主机处理器（CPU）处理浮点运算的能力较弱。而在科学计算领域，浮点运算是非常重要的内容，所以工业界就想到利用GPU进行科学运算。

应该说，所有的显卡都既能够支持显示，又能够支持运算。只是看它偏向哪个方面，为哪个功能做优化罢了。对于偏重计算的显卡，就不必配置多个显示接口，图像处理的模块就不用很高级；相反，对于图形功能偏重的显卡，它就必须要大数据带宽，大显存，支持多种类型的接口，能够实现锯齿优化等等。

针对我们的驱动来讲，如果一个显示驱动，既支持显卡的显示功能，又支持运算功能，称为全功能驱动（Complete function）；如果只支持显示，不支持运算，就是Display Only驱动；如果只支持运算，不支持显示功能，就是Render Only驱动。

微软在Win8的系统上，为所有不同类型的显卡，编写了Display Only和Render Only驱动。在未安装厂商驱动或者厂商驱动被破坏、禁用的情况下，系统会默认选择使用Display Only驱动来显示桌面内容。但一般系统不会选择安装Render Only驱动，那样就什么都看不到了。Render Only驱动的具体应用场景，我到目前还没有看到。可能在Render Only的数据服务器显卡上会被运用。

我的这份显示驱动初步教材，就是基于微软公开的Display Only驱动项目KMDOD来写的。不会涉及数据Render部分。其实可以很方便地把一个Display only的驱动拓展到Complete驱动，在讲完所有内容后，会有一小部分内容做介绍。

KMDOD项目可以从MSDN代码网站上下载到，地址：http://code.msdn.microsoft.com/Kernel-mode-display-only-49adea58

初始化

如果不更改编译配置，WDDM驱动的默认启动函数是DriverEntry。这是驱动对象初始化的地方，一般对于小端口驱动而言，它需要调用框架的初始化函数。WDDM框架的初始化函数是DxgkInitializeDisplayOnlyDriver。从内核编程好帮手WDK中，可以找到它的声明：

NTSTATUS DxgkInitializeDisplayOnlyDriver(
  _In_  PDRIVER_OBJECT DriverObject,
  _In_  PUNICODE_STRING RegistryPath,
  _In_  PKMDDOD_INITIALIZATION_DATA KmdDodInitializationData
);

初始化函数会完成驱动对象的初始化，所以前面两个参数是入口函数的输入参数。在全文最后的实验章节中，会介绍如何查看驱动对象，就能够比较清晰地看到WDDM框架对显示驱动对象所进行的初始化作业了。此外，初始化函数还要完成显示驱动相关的初始化。显示驱动传入一个函数结构体参数，类型是KMDDOD_INITIALIZATION_DATA，结构体里面包含的是显示驱动向框架提供的一系列回调函数（Callback Function）。框架会在合适的时候调用这些回调函数，完成对应功能。

结构体定义如下：

InitializationData

 KMDOD项目没有实现结构体中列举的所有回调函数，所以它不能支持WDDM提供的全部和Display相关的功能。比如D3D用户程序通过DC句柄和显示驱动进行交互的escape回调函数，这里就没有实现。对于没有实现的回调函数，在结构体中的对应函数指针应被初始化为NULL。

第一个参数Version用来标识你所编写的显示驱动使用哪个版本的WDDM。WDDM一共有四个版本：1.0（Vista & Vista SP1）；1.1（Win7）；1.2（Win8）；1.3（Win Blue）。KMDOD这个项目中使用的是Win8版本：DXGKDDI_INTERFACE_VERSION_WIN8。

为了完成结构体初始化，我们要首先实现这些函数。在具体列举实现代码之前，把这些回调函数做一个简单的分类和介绍是有必要的。

Pnp和power函数

所有现代的物理设备都必须处理Pnp和Power事件。Pnp事件对应了设备插拔、开始、移除、停止等，以及作为总线设备需要提供的子设备（显示器）枚举等；Power事件对应上电、掉电操作，以及查询设备是否运行进行电源操作。

另外把卸载回调函数也归入其中。卸载函数在驱动被停止，没有任何外部模块引用的时候，系统会尝试将驱动卸载，这时候卸载回调被调用。

InitialData.DxgkDdiAddDevice                    = BddDdiAddDevice;
InitialData.DxgkDdiStartDevice                  = BddDdiStartDevice;
InitialData.DxgkDdiStopDevice                   = BddDdiStopDevice;
InitialData.DxgkDdiStopDeviceAndReleasePostDisplayOwnership = BddDdiStopDeviceAndReleasePostDisplayOwnership;
InitialData.DxgkDdiResetDevice                  = BddDdiResetDevice;
InitialData.DxgkDdiRemoveDevice                 = BddDdiRemoveDevice;
InitialData.DxgkDdiQueryChildRelations          = BddDdiQueryChildRelations;
InitialData.DxgkDdiQueryChildStatus             = BddDdiQueryChildStatus;
InitialData.DxgkDdiQueryDeviceDescriptor        = BddDdiQueryDeviceDescriptor;
InitialData.DxgkDdiSetPowerState                = BddDdiSetPowerState;
InitialData.DxgkDdiUnload                       = BddDdiUnload; 
InitialData.DxgkDdiQueryAdapterInfo             = BddDdiQueryAdapterInfo;

显示函数

显卡驱动的主要功能是配置物理设备，让它能够输出图片和动画到外部显示设备上。和这个功能相关的函数有很多，它包括对鼠标位置的更新，显示器Mode的枚举和设置等函数：

    InitialData.DxgkDdiSetPointerPosition           = BddDdiSetPointerPosition;
    InitialData.DxgkDdiSetPointerShape              = BddDdiSetPointerShape;
    InitialData.DxgkDdiIsSupportedVidPn             = BddDdiIsSupportedVidPn;
    InitialData.DxgkDdiRecommendFunctionalVidPn     = BddDdiRecommendFunctionalVidPn;
    InitialData.DxgkDdiEnumVidPnCofuncModality      = BddDdiEnumVidPnCofuncModality;
    InitialData.DxgkDdiSetVidPnSourceVisibility     = BddDdiSetVidPnSourceVisibility;
    InitialData.DxgkDdiCommitVidPn                  = BddDdiCommitVidPn;
    InitialData.DxgkDdiUpdateActiveVidPnPresentPath = BddDdiUpdateActiveVidPnPresentPath;
    InitialData.DxgkDdiRecommendMonitorModes        = BddDdiRecommendMonitorModes;

硬件操作

最后是和物理设备交互的一些函数，首先是中断处理函数，然后有获取设备属性，读写设备帧内存、显示桌面内容（Present）等函数。

InitialData.DxgkDdiDpcRoutine                   = BddDdiDpcRoutine;
InitialData.DxgkDdiInterruptRoutine             = BddDdiInterruptRoutine;
InitialData.DxgkDdiQueryVidPnHWCapability       = BddDdiQueryVidPnHWCapability;
InitialData.DxgkDdiPresentDisplayOnly           = BddDdiPresentDisplayOnly;
InitialData.DxgkDdiSystemDisplayEnable          = BddDdiSystemDisplayEnable;
InitialData.DxgkDdiSystemDisplayWrite           = BddDdiSystemDisplayWrite;

功能函数

这部分是显示驱动作为一个驱动来讲，它所实现的一般意义上的功能支持函数。这部分我只列了一个，是用户程序和内核驱动交互用的IO控制函数。

InitialData.DxgkDdiDispatchIoRequest            = BddDdiDispatchIoRequest;

完整的初始化函数：

extern "C"
NTSTATUS
DriverEntry(
    _In_  DRIVER_OBJECT*  pDriverObject,
    _In_  UNICODE_STRING* pRegistryPath)
{
    PAGED_CODE();

    // Initialize DDI function pointers and dxgkrnl
    KMDDOD_INITIALIZATION_DATA InitialData = {0};

    InitialData.Version = DXGKDDI_INTERFACE_VERSION_WIN8;

    InitialData.DxgkDdiAddDevice = BddDdiAddDevice;
    //…… 其它的回调函数赋值过程，上面已全部列举，此处省略

    NTSTATUS Status = DxgkInitializeDisplayOnlyDriver(pDriverObject, pRegistryPath, &InitialData);
    if (!NT_SUCCESS(Status))
    {
        BDD_LOG_ERROR1("DxgkInitializeDisplayOnlyDriver failed with Status: 0x%I64x", Status);
    }

    return Status;
}

可选的扩展

初始化部分到此本来可以结束，继续讲下面的回调函数实现。但其实依然可以扩展一下，不熟悉WDM的读者可以跳过。针对所有的端口驱动框架都基于WDM来实现的这个事实，如果有的小端口驱动有必要想直接操作IRP的话，应该怎么实现呢？

其实非常简单。在DxgkInitializeDisplayOnlyDriver被调用过之后，驱动对象的初始化已经完成了。这时候我们可以对框架的分发函数进行Hook。

比如有一个很重要的功能，很多设备驱动都要做的。就是它希望自己能够得到系统关机的讯息。通过一般意义上的PNP和Power事件，是没有办法得到系统关机讯息的。办法是注册自己的IRP_MJ_SHUTDOWN分发函数来接收此讯息。

下面是简要的实现代码：

// 下面代码应在DxgkInitializeDisplayOnlyDriver被调用过后执行
pOldFunc = pDriverObject->MajorFunction[IRP_MJ_SHUTDOWN]; // 保存框架有可能已实现的函数
pDriverObject->MajorFunction[IRP_MJ_SHUTDOWN] = BddDdiShutdown;

// 此外还需要在StartDevice函数中调用IoRegisterShutdownNotificatin函数，本文不再继续演示

NTSTATUS BddDdiShutdown (PDEVICE_OBJECT pDev, PIRP irp)
{
	// do something you wanted here

	if (pOldFunc)
		return pOldFunc (pDev, irp);
	else
		return STATUS_SUCCESS;
}

回调函数实现

KMDOD项目定义了一个显示驱动类，来封装和实际功能相关的所有具体操作。这样一来，大部分回调函数的实现都比较简单。这个类是BASIC_DISPLAY_DRIVER，我们在第二节会具体地讲它。

生命周期

WDDM框架在设计的时候，是能够支持多个底层物理设备的。换句话说，如果系统中存在多个显卡设备，WDDM框架都能够很好地支持它们同时或者分别工作。作为这个支持的一部分，在PNP操作的起始，也就是AddDevice回调函数被调用的时候，框架要求显示驱动返回一个当前物理设备的Context，作为识别此物理设备的标识。

那么KMDOD也是可以支持多个显卡设备的，所以为每个设备创建一个BASIC_DISPLAY_DRIVER对象，作为Context返回给框架。框架在以后调用任何一个回调函数时，都会把这个Context作为其中的一个输入参数来使用。

WDDM Life

所以我们看，DriverEntry是驱动的开始，卸载函数是驱动的结束；AddDevice函数是设备工作的开始，RemoveDevice是设备结束工作的标识。我们可以用下面的框图来描述这个概念。

设备的Context作为一个标识物理显卡的变量，在设备的PNP周期里面一直运作着。当关机、设备禁用或者其他变故发生的时候，RemoveDevice回调被执行，显示驱动将负责删除它所创建的设备Context。

 

下面是AddDevice和RemoveDevice这两个回调函数的实现。

NTSTATUS
BddDdiAddDevice(
    _In_ DEVICE_OBJECT* pPhysicalDeviceObject,
    _Outptr_ PVOID*  ppDeviceContext)
{
    PAGED_CODE();

    if ((pPhysicalDeviceObject == NULL) ||
        (ppDeviceContext == NULL))
    {
        BDD_LOG_ERROR2("One of pPhysicalDeviceObject (0x%I64x), ppDeviceContext (0x%I64x) is NULL",
                        pPhysicalDeviceObject, ppDeviceContext);
        return STATUS_INVALID_PARAMETER;
    }
    *ppDeviceContext = NULL;

    BASIC_DISPLAY_DRIVER* pBDD = new(NonPagedPoolNx) BASIC_DISPLAY_DRIVER(pPhysicalDeviceObject);
    if (pBDD == NULL)
    {
        BDD_LOG_LOW_RESOURCE0("pBDD failed to be allocated");
        return STATUS_NO_MEMORY;
    }

    *ppDeviceContext = pBDD;

    return STATUS_SUCCESS;
}

NTSTATUS
BddDdiRemoveDevice(
    _In_  VOID* pDeviceContext)
{
    PAGED_CODE();

    BASIC_DISPLAY_DRIVER* pBDD = reinterpret_cast<BASIC_DISPLAY_DRIVER*>(pDeviceContext);

    if (pBDD)
    {
        delete pBDD;
        pBDD = NULL;
    }

    return STATUS_SUCCESS;
}

其它回调函数实现

其它回调函数的实现，这里仅仅以StartDevice为例讲解。函数原型定义如下：

NTSTATUS DxgkDdiStartDevice(
  _In_   const PVOID MiniportDeviceContext,
  _In_   PDXGK_START_INFO DxgkStartInfo,
  _In_   PDXGKRNL_INTERFACE DxgkInterface,
  _Out_  PULONG NumberOfVideoPresentSources,
  _Out_  PULONG NumberOfChildren
)

第一个参数即设备Context，毫无疑问，它就是我们刚刚在AddDevice中创建的BASIC_DISPLAY_DRIVER对象。所以我们第一步需要获取对象指针，并且调用到BASIC_DISPLAY_DRIVER里面的startDevice函数中去。其实现如下：

NTSTATUS
BddDdiStartDevice(
    _In_  VOID*              pDeviceContext,
    _In_  DXGK_START_INFO*   pDxgkStartInfo,
    _In_  DXGKRNL_INTERFACE* pDxgkInterface,
    _Out_ ULONG*             pNumberOfViews,
    _Out_ ULONG*             pNumberOfChildren)
{
    PAGED_CODE();
    BDD_ASSERT_CHK(pDeviceContext != NULL);

    BASIC_DISPLAY_DRIVER* pBDD = reinterpret_cast<BASIC_DISPLAY_DRIVER*>(pDeviceContext);
    return pBDD->StartDevice(pDxgkStartInfo, pDxgkInterface, pNumberOfViews, pNumberOfChildren);
}

其它的回调函数，实现方法和StartDevice很类似。唯一的区别是，如果StartDevice调用失败的话，也就是设备启动失败的话，道理上讲，很多后续的函数都不应该被调用，因为既然设备没有启动，就不应该有任何针对于它的动作存在。所以这些函数被调用的时候，很多都会先确认一下，设备是否处于启动状态（IsDriverActive），就是判断StartDevice是否执行成功。

版本历史：

V1.0：2013/7/23

30,063 total views, 4 views today

《Windows显示驱动（WDDM）编程初步（1）》有27个想法

  1. Pingback： Windows显示驱动（WDDM）编程初步(1) - iew3c

  3. 你好！请教一个问题：我想把KMDOD的sample改造一下，使这个driver挂一个虚拟的display，这样OS以为有两个monitor（包括一个硬件monitor），请问这应该怎么做呢？非常感谢！

    回复

    1. 我没有做过这个。但我想，报子设备的时候，多报一个虚拟设备就可以了。你要在BddDdiQueryDeviceDescriptor函数中处理，在这个函数里面，你需要手动配置一个EDID。有进一步的情况，请让我知道。

      回复

  5. 楼主你好，最近想了解下显示方面的驱动。搜索来到这个帖子，对这方面有一点疑惑。
    对于不是显卡厂家的开发人员来说，这种驱动有什么意义呢？ 这些介绍是不是针对显卡厂家的显卡驱动开发人员来做的，别人的会可以用这方面的东西做出什么类型的应用来？ dxgkrnl.sys文件在WDDM中和其他的显卡驱动的关系是怎么样的？ dxgkrnl是不是最后会调用显卡厂家提供的显卡驱动？ 显卡厂家提供的显卡驱动必须遵循WDDM的框架规则才能让dxgkrnl.sys来调用？
    期待你的回复。

    回复

    1. 你好，回答如下：
      >>对于不是显卡厂家的开发人员来说，这种驱动有什么意义呢？
      每种显卡厂商的设备，都有自己的硬件设计，显卡的硬件设计是没有统一的硬件标准的（除了和系统的接口部分），所以总是由厂商提供显卡驱动。系统的display only驱动，或者本文所依赖的KMDOD驱动，都没有利用硬件加速，仅仅使用显卡进行显示。显示功能是使用了通用的接口，就是GPU总是把它Frame Buffer（简称FB）映射到系统的物理地址空间中，系统把要显示的内容Present到FB中。

      >>这些介绍是不是针对显卡厂家的显卡驱动开发人员来做的，别人的会可以用这方面的东西做出什么类型的应用来？
      有一些应用的，但不是很多。可以用来扩展桌面，我记得iDisplay这个软件，会安装一个WDDM驱动。

      >>dxgkrnl.sys文件在WDDM中和其他的显卡驱动的关系是怎么样的？ dxgkrnl是不是最后会调用显卡厂家提供的显卡驱动？ 显卡厂家提供的显卡驱动必须遵循WDDM的框架规则才能让dxgkrnl.sys来调用？
      dxgkrnl就是文章中讲的WDDM框架。它和小端口驱动的关系，文章中这幅图进行了描述，二者互有接口进行调用。

      回复
  6. Pingback： Windows显示驱动（WDDM）编程 (1) | Enterprise Just Builder

  7. 关于硬件加速跟3D交互显示的部分是怎么样的? 按你所说，diaplay_only是把 FB中的内送送出到显示器，那硬件加速跟3D交互显示是形成 FB中的内容的过程?

    回复

  8. 这个驱动sample我在虚拟机的串口win8上debug的时候，总是会出现黄色感叹号，显示：由于 Windows 无法加载这个设备所需的驱动程序,导致这个设备工作异常。

    回复

  10. 您好，张佩
    我有个需求，但没有显卡驱动经验，望给予指点：
    为的笔记本显卡是NVIDIA Quadro FX 2800M，这块显卡在win7和win8下的驱动有问题，就是会随时崩溃，黑屏，使用微软的base display adapter可以稳定使用，但不能接第二块屏，码农需要第二块屏，有什么方法可以改造显示驱动程序，能用起来第二块屏？linux下的Nouveau可以满足要求，但linux的Nvidia驱动同样容易崩溃。能否通过配置文件就实现为的需求？（配置base display adapter使之能支持双屏，或配置base display adapter使之不再崩溃）。
    另外，崩溃的原因可能是使用的显卡的高级特性，我采用NVIDIA windows下的早期驱动，再降低工作频率稳定性能勉强满足要求。

    回复

  11. 您好.老师,请问我怎么找不到那个 sample了,能够发给我一份么?我想做一个虚拟的显卡驱动,可以支持超高的分辨率显示…谢谢了

    回复

  14. 你好，请问我在BddDdiPresentDisplayOnly函数中能获取一些图片，该图片由应用程序发送的，我想知道发送该图片的应用程序进程ID，我该如何获取，在xddm框架中我通过EngGetCurrentProcessId就可以了，我在WDDM中使用psGetCurrentProcessId获取，但是返回值一直是4，表示的是system.exe这个进程，请问我该怎么做呢？谢谢！

    回复

  15. 你好，我想请教一下关于hook的问题。

    其实非常简单。在DxgkInitializeDisplayOnlyDriver被调用过之后，驱动对象的初始化已经完成了。这时候我们可以对框架的分发函数进行Hook。

    nvidia的小端驱动应该是nvlddmkm.sys，如何获得分发函数的地址了？
    比如一个游戏程序，想hook DxgkDdiCreateAllocation，游戏本身加载一个nt驱动，能在nt驱动里得到DxgkDdiCreateAllocation地址了？

    谢谢。

    回复

发表评论

电子邮件地址不会被公开。