Intel HAXM Windows 构建与测试实战指南:从 Visual Studio/EWDK 编译到测试驱动加载

原创2026-10-03 21:42:591,391 阅读

Intel HAXM Windows 构建与测试实战指南:从 Visual Studio/EWDK 编译到测试驱动加载

本文以 Intel HAXM 官方 Windows 手册 docs/manual-windows.md 为骨架,结合仓库中 platforms/windows/ 的工程文件与 HaxmLoader/ 驱动加载工具的源码实现,完整讲解在 Windows 主机上从零构建内核驱动 IntelHaxm.sys、搭建测试签名环境、加载卸载测试驱动并采集调试日志的端到端流程。读完本文,你将掌握 Visual Studio 与 EWDK 两套构建方式、Debug/Release 与 x64/Win32 的取舍、Windows 10 下彻底禁用 Hyper-V 的注意事项,以及不依赖 INF 文件直接驱动内核模块的 HaxmLoader 工具用法。

一、构建前的环境准备:两套可选工具链

Windows 平台构建 HAXM 内核驱动有两种官方支持的路径,两者对工具链的要求完全不同,可按手头环境任选其一。

方式 A:Visual Studio 2017 工具链

使用 Visual Studio 图形化构建时,需要安装 Visual Studio 2017,并至少勾选以下两个工作负载组件:

  • Universal Windows Platform development(通用 Windows 平台开发)
  • Desktop development with C++(使用 C++ 的桌面开发)

同时还需单独安装两个独立 SDK:

关键约束:Windows SDK 的版本号/构建号必须与 WDK 严格匹配。 这是新手最容易踩的坑:Visual Studio 2017 自带安装的 Windows 10 SDK(撰写手册时版本为 1709,构建号 10.0.16299)往往不是最新版本;如果打算使用较新的 WDK(手册撰写时为版本 1803),则需要手动下载并安装与之匹配的 Windows 10 SDK(版本 1803,构建号 10.0.17134)。SDK 与 WDK 版本不匹配时,WDK 的驱动构建目标(WindowsKernelModeDriver10.0 平台工具集)会无法正确解析内核头文件与库路径。

方式 B:Enterprise WDK(EWDK)工具链

EWDK 是一条无需完整安装 Visual Studio 的轻量路径,适合 CI 或纯命令行环境:

从仓库的实际工程文件看,EWDK 路径的可行性有直接证据:platforms/windows/haxm.sln 中的驱动工程 haxm-windows.vcxproj 使用 WindowsKernelModeDriver10.0 平台工具集,并声明了 TargetVersion=Windows7,说明其面向 Windows 7 及以后的驱动模型,恰好与手册中"产物可在 Windows 7 及以后运行"的描述相互印证。

二、构建步骤:两种方式的完整命令与配置选择

方式 A:在 Visual Studio 2017 中构建

  1. 在 Visual Studio 2017 中打开解决方案文件 platforms\windows\haxm.sln。
  2. 选择 Debug 或 Release 配置:
    • Debug 配置还会使用测试证书对驱动进行签名;
    • Release 配置不做签名。
  3. 选择 x64 或 Win32 平台。
  4. 直接生成解决方案。

关于签名差异,可以在工程文件中找到实现依据:haxm-windows.vcxproj 在四个 Release 配置节中均设置了 <SignMode>Off</SignMode>(见第 44、55 行),而 Debug 配置未关闭签名,从而默认执行测试签名;同时 Release 配置还额外开启了 WholeProgramOptimization(链接期优化),这正是"Release 是面向发布优化的驱动"的工程落地。

该解决方案包含三个子项目(见 haxm.sln 第 14–18 行):

  • haxm-core:与平台无关的虚拟化核心引擎(编译为静态库 haxlib.lib,被驱动工程链接);
  • haxm-windows:Windows 内核驱动本体(产物为 IntelHaxm.sys);
  • haxm-tests:针对核心模块的测试工程。

方式 B:EWDK 命令行构建

在 EWDK 环境中依次执行以下命令(X:\path\to\... 替换为实际路径):

cd X:\path\to\EWDK\
LaunchBuildEnv.cmd
cd X:\path\to\haxm\
cd platforms\windows
X:\path\to\nuget.exe restore
msbuild haxm.sln /p:Configuration="Debug" /p:Platform="x64"

msbuild 参数的含义与变体:

参数 说明
/p:Configuration="Debug" 使用 Release 可构建适合发布、经过优化的驱动;注意 Release 配置不会用测试证书签名,无法直接用于测试签名加载
/p:Platform="x64" 改用 Win32 可构建运行于 32 位 Windows 的 32 位驱动
/t:rebuild 附加此参数执行干净重建,否则为增量构建

nuget.exe restore 的作用是还原 packages.haxm-core.config 与 packages.haxm-tests.config 中声明的 NuGet 依赖包。

产物路径

构建成功后,驱动二进制 IntelHaxm.sys 将生成于:

X:\path\to\haxm\platforms\windows\build\out\x64\{Debug,Release}\

若使用 Platform="Win32",则对应:

X:\path\to\haxm\platforms\windows\build\out\Win32\{Debug,Release}\

该路径与工程文件中的输出目录配置一致:haxm-windows.vcxproj 第 75 行将 OutDir 定义为 $(SolutionDir)build\out\$(Platform)\$(Configuration)\,TARGETNAME 定义为 IntelHaxm,共同决定了产物的位置与名称。构建出的驱动可在 Windows 7 及以后的系统中运行。

三、测试环境要求:CPU 与操作系统门槛

以下是对测试环境(运行驱动的机器)的要求,它不必与构建环境是同一台机器。

  1. 支持 Intel VT-x 且带 Extended Page Tables(EPT)的 Intel CPU
    • Intel 官网有满足该条件的 CPU 列表可供查询。作为经验法则,任意一代 Intel Core i3、i5、i7 或 i9 都满足要求。
    • EPT 是 Intel VT-x 的进阶特性。支持 EPT 的 CPU 通常也支持 Unrestricted Guest(UG),后者是 VT-x 的另一项进阶特性。
    • 很老(2010 年之前)的 CPU,例如 Intel Core 2 Duo,实现的是早期版本 VT-x,不含 EPT 与 UG。HAXM 仍可能在它们上面运行,但驱动中用于非 EPT、非 UG 模式的遗留代码存在被移除的可能,不推荐依赖。
  2. Windows 7 或以后;32 位与 64 位 Windows 均支持
    • 在嵌套虚拟化场景(Windows 本身作为另一台 Hypervisor 的客户机)中运行 HAXM 也许可行,但该场景未被充分测试,不保证稳定。

从仓库源码看,Windows 驱动在 platforms/windows/ 下被组织为"平台适配层 + 内核模块"结构:hax_entry.c 中的 DriverEntry 创建 \Device\HAX 设备对象(NT_DEVICE_NAME,第 43 行)并通过 IoCreateDeviceSecure 按 SDDL 安全描述符(第 50–51 行)限制访问权限:System 与 Administrators 拥有全部权限,Authenticated Users 仅可读写执行。随后初始化 CPU 信息与虚拟化模块(hax_host_init),并注册 IRP_MJ_CREATE、IRP_MJ_CLOSE、IRP_MJ_DEVICE_CONTROL 等分发例程。设备控制入口 HaxIoControl 再按设备扩展类型将 IOCTL 路由到 HaxDeviceControl(全局设备)、HaxVmControl(VM 设备)与 HaxVcpuControl(VCPU 设备),其中 VCPU 设备/VM 设备由 components.c 按 \Device\hax_vm%02d、\Device\hax_vm%02d_vcpu%02d 的命名格式动态创建(第 38–41 行)。这意味着:只有支持 VT-x 的 Intel 平台才能真正跑通这些内核路径,因此测试前对 CPU 特性的确认十分必要。

四、测试环境的一次性设置:测试签名与系统引导选项

以下步骤用于准备可安装测试签名版 IntelHaxm.sys(即用 Debug 配置构建、带测试证书签名的驱动)的环境。

4.1 关闭 Hyper-V 并开启测试模式

  1. 打开提升权限(以管理员身份运行)的命令提示符。
  2. 执行 bcdedit /set hypervisorlaunchtype off。
    • 注意:在某些 Windows 10 系统上,仅此命令不足以彻底关闭 Hyper-V,需要配合第 4.3 节的方法。
  3. 执行 bcdedit /set testsigning on。
  4. 重启系统。

4.2 安装测试证书

  1. 将 IntelHaxm.cer 从构建环境复制到测试环境(若两者不是同一台机器)。该文件由 Debug 构建配置与 IntelHaxm.sys 一同生成。
  2. 在测试环境中打开提升权限的命令提示符,执行:
certmgr /add X:\path\to\IntelHaxm.cer /s /r localMachine root

该命令将测试证书加入本机"受信任的根证书颁发机构"存储,使内核可以校验测试签名。

  1. (可选)安装 DebugView 以捕获 HAXM 的调试输出。

4.3 Windows 10 上彻底禁用 Hyper-V 的专项处理

Windows 10 的某些高级功能会阻止 Hyper-V 被完全关闭,典型如:

  • Device Guard(尤其是其 Hypervisor-protected code integrity,HVCI,即基于虚拟化的代码完整性)
  • Credential Guard(凭据保护)

只要上述任一功能处于启用状态,Hyper-V 实际上也是开启的,即使 Windows 在界面上可能显示已关闭。

微软发布的 Device Guard and Credential Guard hardware readiness tool 可以连同 Hyper-V 一起禁用这些功能,步骤如下(以下假设工具版本为 3.6):

  1. 下载该工具的最新版本。
  2. 解压。
  3. 打开提升权限(以管理员身份运行)的命令提示符。
  4. 执行:
@powershell -ExecutionPolicy RemoteSigned -Command "X:\path\to\dgreadiness_v3.6\DG_Readiness_Tool_v3.6.ps1 -Disable"
  1. 重启。

五、用 HaxmLoader 加载与卸载测试驱动

HaxmLoader 是一个小型工具,可以在不使用 INF 文件的情况下加载和卸载测试签名的驱动。它可从项目 Releases 页面下载,也可以使用 Visual Studio 或 EWDK 自行构建 HaxmLoader/HaxmLoader.sln(见 HaxmLoader.vcxproj,其仅编译单个源文件 haxm_loader.c,支持 Debug/Release × Win32/x64 四种组合,工具集为 v141,即对应 VS2017 环境)。

5.1 工作原理:内核驱动与 Windows 服务控制管理器

内核模式驱动(如 HAXM)在 Windows 中由**服务控制管理器(Service Control Manager,SCM)**作为服务统一管理。每个这样的服务都有:唯一名称、对应的驱动文件、运行状态。例如:

  • 当 HAXM 安装程序将正式签名的驱动安装到 C:\Windows\System32\drivers\IntelHaxm.sys 时,会同时为其创建名为 intelhaxm 的服务,该服务在开机时启动;
  • HaxmLoader 以类似方式工作:加载测试驱动时,它创建一个临时服务并启动它;卸载测试驱动时,它先停止服务再删除该服务。

这一设计在源码中有完整印证:haxm_loader.c 第 39–41 行定义了三个服务相关常量:

#define SERVICE_NAME_RELEASE L"IntelHaxm"     // 正式发布驱动对应的服务
#define SERVICE_NAME         L"IntelHaxmTest" // 测试驱动对应的临时服务
#define SERVICE_DISPLAY_NAME L"Intel HAXM Test Service"

DriverInstall(第 176 行起)的执行链路是:校验驱动文件存在 → 调用 DriverUninstall 清理既有服务 → OpenSCManagerW 打开服务管理器 → CreateServiceW 以 SERVICE_KERNEL_DRIVER 类型创建临时服务 → StartServiceW 启动服务;DriverUninstall(第 125 行起)则先 StopService 停止 IntelHaxm(正式服务)与 IntelHaxmTest(测试服务),再 DeleteService 删除测试服务。此外,IsTokenElevated(第 63 行起)在 wmain 入口(第 264 行起)强制校验管理员权限——没有提升权限时程序会直接打印 Please run HaxmLoader as Administrators. 并退出。

5.2 加载测试驱动

  1. 打开提升权限的命令提示符。
  2. 确保当前没有其他 HAXM 驱动被加载:
    • 若 sc query intelhaxm 显示 intelhaxm 服务状态为 RUNNING,必须先停止它:sc stop intelhaxm;
    • 否则,若之前加载过测试驱动,先卸载:HaxmLoader.exe -u。
  3. 加载测试驱动:
HaxmLoader.exe -i X:\path\to\IntelHaxm.sys
  • HaxmLoader 可以从任意文件夹加载驱动,因此无需先把测试驱动复制到 C:\Windows\System32\drivers\。

参数格式与 -i/-u 两种模式在 haxm_loader.c 的 PrintUsage(第 254–262 行)与 wmain 的参数解析分支(第 283–294 行)中定义:-i <sys_file_path> 安装并启动驱动,-u 卸载驱动。

5.3 卸载测试驱动

  1. 打开提升权限的命令提示符。
  2. 执行 HaxmLoader.exe -u。
  3. (可选)如需恢复原始的正式签名驱动(即 C:\Windows\System32\drivers\IntelHaxm.sys),执行 sc start intelhaxm 重新启动 intelhaxm 服务。

5.4 与正式安装路径的对照

HaxmLoader 的"临时服务 + 手动加载"模式,与仓库中 NSIS 安装器 HaxmSetup.nsi 的正式安装路径形成了清晰的对照:正式安装通过安装脚本注册 intelhaxm 服务并设置为开机启动,而开发调试时则用 HaxmLoader 动态创建/销毁 IntelHaxmTest 服务,避免反复安装卸载 INF 包。理解这两条路径,有助于排查"驱动加载失败 / 服务状态异常"类问题。

六、捕获驱动日志:DebugView 的使用

HAXM 驱动的内核调试输出通过 DPRINT 类机制输出,可用 Sysinternals 的 DebugView 捕获:

  1. 以管理员身份启动 DebugView(Dbgview.exe)。
  2. 在 Capture 菜单中,勾选除 Log Boot 以外的所有选项。DebugView 随即开始捕获所有内核模式驱动的调试输出。
  3. 为过滤掉非 HAXM 的日志,进入 Edit > Filter/Highlight...,在 Include 输入框中填写 hax*,点击 OK。

此后 DebugView 将只显示匹配 hax* 的日志行。注意:只有 Debug 构建的驱动才会输出调试日志,Release 构建通常会剥离或关闭调试打印,若期望看到日志请使用 Debug 配置产物。

七、仓库相关资源速查

围绕本手册涉及的构建与测试链路,可在仓库中进一步深入以下文件:

结语

Windows 平台的 HAXM 开发流程可归纳为"两条构建路径、一次环境配置、一个小工具":用 Visual Studio 或 EWDK 产出带测试签名的 IntelHaxm.sys,通过 bcdedit 关闭 Hyper-V 并开启测试签名,再借助 HaxmLoader 以临时服务方式完成驱动的加载、调试与卸载,最后用 DebugView 按 hax* 过滤采集内核日志。掌握这条链路后,无论是驱动级联调、虚拟化引擎迭代还是排障,都能在 Windows 测试机上快速闭环。

登录后查看全文
haxm