hcs-rs

Host Compute Service API的Rust包装器

概述

该项目是一组Rust库，用于封装由Host Compute Service暴露的功能。

HCS（Host Compute Service的简称）API是Windows 10 SDK的一部分。

HCS的公共文档尚未发布。

要求

为了正确构建此包装器，构建机器需要满足以下要求

• Windows 10 SDK。
  • 默认情况下，RS5（10.0.17763.0）API界面始终构建。
  • 可选地，可以通过功能19h1包含19H1（10.0.18362.0）。
• amd64 架构。

封装的Windows 10 SDK API

注意：本节包含基于默认安装路径 c:\Program Files (x86)\Windows Kits\10的Windows SDK头文件和lib文件路径。 注意：本节显示特定于Windows SDK版本10.0.18362.0的路径。

该项目封装的相关Windows 10 SDK文件包括

• C:\Program Files (x86)\Windows Kits\10\Include\10.0.18362.0\um\computecore.h
• C:\Program Files (x86)\Windows Kits\10\Include\10.0.18362.0\um\computedefs.h
• C:\Program Files (x86)\Windows Kits\10\Include\10.0.18362.0\um\computenetwork.h
• C:\Program Files (x86)\Windows Kits\10\Include\10.0.18362.0\um\computestorage.h
• C:\Program Files (x86)\Windows Kits\10\Include\10.0.18362.0\um\hypervdevicevirtualization.h
• C:\Program Files (x86)\Windows Kits\10\Lib\10.0.18362.0\um\x64\computecore.lib
• C:\Program Files (x86)\Windows Kits\10\Lib\10.0.18362.0\um\x64\computenetwork.lib
• C:\Program Files (x86)\Windows Kits\10\Lib\10.0.18362.0\um\x64\computestorage.lib
• C:\Program Files (x86)\Windows Kits\10\Lib\10.0.18362.0\um\x64\vmdevicehost.lib
• C:\Windows\System32\computecore.dll
• C:\Windows\System32\computenetwork.dll
• C:\Windows\System32\computestorage.dll
• C:\Windows\System32\vmdevicehost.dll

所有这些都通过Windows服务Host Compute Service提供服务，从可执行文件C:\Windows\System32\vmcompute.exe。

本crate中的C绑定将保持私有，不对外部代码公开。只暴露Rust风格的封装器。

以下表格描述了该项目所封装的相关Windows 10 SDK文件以及它们与每个模块的关系

特性

Crates.io版本说明

注意：所有从0.2.1及以下版本都有意撤回。请直接使用git仓库以获取最新活动更改，或使用0.2.2作为最旧的“稳定”版本。

本节简要描述了从最新到最旧的已发布的crates.io 版本。

• 0.9.1 2020年1月6日
  • 修复了readme的crates.io版本说明日期
  • 修复了HdvPciDevice
    的文档
• 0.9.0 2020年1月5日
  • 重大更改
    • HdvPciDeviceBase::hook_device_interface_callbacks现在期望参数device为不可变引用，而不是移动它。这样做是为了确保调用者不会错误地丢弃他们可能拥有的device实例的唯一引用
  • 添加了方便的HdvHost::hook_device_interface_callbacks
• 0.8.0 2020年1月4日
  • 重大更改
    • set_callback函数不再为unsafe
    • HdvPciDeviceBase::hook_device_interface_callbacks现在期望参数device为移动，而不是可变引用
  • 重构了回调，使它们在使用对象被移动时也能安全使用（通过使用Box成员）
  • 更新代码以捕获C样式回调上的panic堆回溯，以使它们更安全
• 0.7.0 2019年12月31日
  • 重大更改
    • 删除了HdvPciDevice回调trait函数的unsafe属性。尽管它假设它不应该panic，但它导致整个函数被标记为unsafe时产生了混淆
    • 重新设计了computecore实用工具中的回调方式，使其更简单，不需要闭包的trait对象
• 0.6.0 2019年12月17日
  • 重大更改
    • 标记 HdvPciDevice 回调特征函数作为 unsafe，因为它假设它们不应该崩溃
• 0.5.1 2019年12月16日
  • 将 #[derive(Clone)] 添加到 HdvPciDeviceBase 和 HdvPciDeviceBaseWrapper。
• 0.5.0 2019年12月12日
  • 重大更改
    • 将 unsafe 添加到期望回调或假设提供的引用超出内部细节的函数中。它曾经没有被标记为 unsafe，但鉴于由于错误的生存期（以及 Rust 编译器无法正确理解它）导致出现几个错误
  • 修复了 vmbfs_root_path 的错误模式名称
• 0.4.0 2019年12月12日
  • 修复了工具文档
  • 向 hypervdevicevirtualization 添加了一些额外的工具
  • 重大更改
    • 修复了工具回调，以期望一个闭包特征对象的引用
    • 将 get_handle 重命名为 handle，将 get_handle_policy 重命名为 handle_policy
• 0.3.0 2019年12月11日
  • 重大更改
    • hypervdevicevirtualization 用于读取和写入虚拟机内存的安全包装现在使用切片而不是直接使用向量
      • 特别是，读取曾经返回一个包含读取内存的新分配缓冲区。现在，它直接读取到提供的字节切片中
    • 引入了 utilities 功能，以分离所有基于基本安全包装的更高抽象的 Rust 抽象
    • 安全包装 enumerate_compute_systems 现在支持一个可选查询参数
  • 添加了围绕 hypervdevicevirtualization API 的工具
• 0.2.2 2019年12月10日
  • 删除了不必要的 ispresent 绑定
  • 功能化模式 JSON 对象模型已最终确定
  • 通过环境变量启用功能，以条件编译对不同 Windows 版本的支持（目前仅为 19h1）
  • 在 schema 功能后面保护模式模型
  • 启用功能 bindings，它公开了 API 的原始绑定（默认情况下它们对 crate 是私有的）
  • 将依赖项更新到 winutils_rs，以获取 WideString CoTaskMemFree/LocalFree 包装的修复
  • 这是“最老”的版本，状态相对稳定，以及清理了不必要的物品
• 0.2.1 2019年12月10日
  • 使用 extern "system" 而不是 extern "C"
  • 确保函数指针在 Option 中包装，以允许空函数指针
  • 模式没有完全测试/功能
  • 已删除，不完整/实现错误；不建议使用
• 0.2.0 2019年12月9日
  • 第二个版本，在 computecore 上添加了基本的安全包装
  • HCS 模式模型实现
  • 将 hypervdevicevirtualization 更新到包括最新的更改
  • 模式没有完全测试/功能
  • 已删除，不完整/实现错误；不建议使用
  • 将对 Windows 10 SDK 版本 10.0.18362.0 的依赖项设置为硬编码
    • 通过环境变量使严格的构建时查找导出库文件成为可选操作
• 0.1.0 2019年1月8日
  • 第一个版本，功能非常有限
  • 将 C API 的绑定公开为瘦安全包装
  • 缺少许多安全抽象
  • 将对 Windows 10 SDK 版本 10.0.17763.0 的依赖项设置为硬编码
  • 已删除，不完整/实现错误；不建议使用