hcs-rs

Rust wrapper of Host Compute Service API

Overview

This project is a collection of Rust libraries that wrap functionality exposed by the Host Compute Service.

HCS (Host Compute Service for short) APIs are part of the Windows 10 SDK.

Public documentation for the HCS is yet to be released.

Requirements

For this wrapper to build properly, the following requirements need to be met by the building machine:

• Windows 10 SDK.
  • By default, RS5 (10.0.17763.0) API surface is always built.
  • Optionally, 19H1 (10.0.18362.0) can be included through feature 19h1.
• amd64 architecture.

Wrapped Windows 10 SDK APIs

Note: This section includes the paths in the Windows SDK for the header and lib files based on the default installation path c:\Program Files (x86)\Windows Kits\10. Note: This section shows paths specific to Windows SDK version 10.0.18362.0

The relevant Windows 10 SDK files that this project is wrapping are:

• 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

All of the above are serviced through the Windows Service Host Compute Service, from executable C:\Windows\System32\vmcompute.exe.

The C bindings in this crate will remain private and not public to external code. Only the Rust idiomatic wrappers are exposed.

The following table describes the relevant Windows 10 SDK files that this project is wrapping and how they relate to each module:

Features

Crates.io version notes

NOTE: All versions from 0.2.1 and below have been yanked on purpose. Please use the git repo directly for latest active changes, or 0.2.2 as the oldest "stable" version.

This section briefly describes all published crates.io versions of this project, ordered from latest to oldest.

• 0.9.1 Jan 6, 2020
  • Fixed readme's crates.io version notes dates
  • Fixed documentation for HdvPciDevice
• 0.9.0 Jan 5, 2020
  • Breaking changes
    • HdvPciDeviceBase::hook_device_interface_callbacks now expects parameter device to be a immutable reference instead of it being moved. This to ensure callers do not mistakenly drop the only reference to the device instance they might have
  • Added convenient HdvHost::hook_device_interface_callbacks
• 0.8.0 Jan 4, 2020
  • Breaking changes
    • set_callback functions are no longer unsafe
    • HdvPciDeviceBase::hook_device_interface_callbacks now expects parameter device to be moved instead of a mutable reference
  • Refactored callbacks to make them safe to use even if the object is moved (by using a Box member)
  • Updated code to catch panic stack unwind on C-style callbacks on an attempt to make them safer
• 0.7.0 Dec 31, 2019
  • Breaking changes
    • Removed HdvPciDevice callback trait functions unsafe attribute. Even though it assumes it should not panic, it lead to confusion when the whole function was marked as unsafe
    • Reworked the way callbacks are done in the computecore utilities to make it simpler, and do not require a trait object of the closure
• 0.6.0 Dec 17, 2019
  • Breaking changes
    • Mark HdvPciDevice callback trait functions as unsafe, due to its assumption that they should not panic
• 0.5.1 Dec 16, 2019
  • Added #[derive(Clone)] to HdvPciDeviceBase and HdvPciDeviceBaseWrapper.
• 0.5.0 Dec 12, 2019
  • Breaking changes
    • Added unsafe to the functions that expect a callback or some kind of assumption that the provided reference outlives the internal details. It used to not be marked as unsafe, but after seeing several bugs due to getting wrong the lifetime (and Rust compiler not being able to understand it correctly)
  • Fixed wrong schema name for vmbfs_root_path
• 0.4.0 Dec 12, 2019
  • Fixed documentation of utilities
  • Added a few more utilities to hypervdevicevirtualization
  • Breaking changes
    • Fixed up callback on utilities to expect a reference to a closure's trait object
    • Renamed get_handle to handle and get_handle_policy to handle_policy
• 0.3.0 Dec 11, 2019
  • Breaking changes
    • hypervdevicevirtualization safe wrappers for reading and writing guest memory now use slices instead of vectors directly
      • In particular, read used to return a newly allocated buffer with the read memory. Now, it reads it directly into the supplied byte slice
    • Introduction of feature utilities to separate all the higher abstract Rust abstraction on top of the basic safe wrappers
    • Safe wrapper enumerate_compute_systems now supports an optional query parameter
  • Added utilities around hypervdevicevirtualization APIs
• 0.2.2 Dec 10, 2019
  • Removes unnecessary ispresent bindings
  • Gets a functional schema JSON object model finalized
  • Proper use of features for conditionally compiling support for different windows releases (as of now, only 19h1)
  • Guard schema model behind a schema feature
  • Enable feature bindings that exposes the raw bindings to the APIs (by default they are private to the crate)
  • Updated dependency to winutils_rs to get a fix for WideString CoTaskMemFree/LocalFree wrappers
  • This is the "oldest" version with a somewhat stable state, as well as cleaned up from unnecessary stuff
• 0.2.1 Dec 10, 2019
  • Use extern "system" instead of extern "C"
  • Make sure function pointers are wrapped on an Option, to allow for null function pointers
  • SCHEMA NOT COMPLETELY TESTED/FUNCTIONAL
  • YANKED, INCOMPLETE/WRONG IMPLEMENTATION; NOT ADVISED TO USE
• 0.2.0 Dec 9, 2019
  • Second version, with basic safe wrappers on top of computecore
  • HCS schema model implementation
  • Updated hypervdevicevirtualization to include newer changes
  • SCHEMA NOT COMPLETELY TESTED/FUNCTIONAL
  • YANKED, INCOMPLETE/WRONG IMPLEMENTATION; NOT ADVISED TO USE
  • Hardcoded dependency to Windows 10 SDK version 10.0.18362.0
    • Make the strict build-time lookup of exports library files opt-in through an environment variable
• 0.1.0 Jan 8, 2019
  • First version, with very limited functionality
  • Bindings to the C APIs exposed as thin safe wrappers
  • Lacking a lot of safe abstractions
  • Hardcoded dependency to Windows 10 SDK version 10.0.17763.0
  • YANKED, INCOMPLETE/WRONG IMPLEMENTATION; NOT ADVISED TO USE