10 releases (breaking)
0.9.1 | Jan 6, 2020 |
---|---|
0.8.0 | Jan 5, 2020 |
0.7.0 | Dec 31, 2019 |
0.1.0 |
|
#106 in Windows APIs
310KB
6K
SLoC
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:
hcs-rs file | Overview | HCS API C Header file | .h path in SDK | .lib path in SDK |
---|---|---|---|---|
computedefs | Types and definitions used by the HCS APIs. | computedefs.h | C:\Program Files (x86)\Windows Kits\10\Include\10.0.18362.0\um\computedefs.h | C:\Program Files (x86)\Windows Kits\10\Lib\10.0.18362.0\um\x64\computedefs.lib |
computecore | APIs for the core HCS functionality to manage compute systems. | computecore.h | C:\Program Files (x86)\Windows Kits\10\Include\10.0.18362.0\um\computecore.h | C:\Program Files (x86)\Windows Kits\10\Lib\10.0.18362.0\um\x64\computecore.lib |
computenetwork | Types definitions and APIs to interact with the HCN (Host Compute Network). | computenetwork.h | C:\Program Files (x86)\Windows Kits\10\Include\10.0.18362.0\um\computenetwork.h | C:\Program Files (x86)\Windows Kits\10\Lib\10.0.18362.0\um\x64\computenetwork.lib |
computestorage | APIs for the HCS storage management. | computestorage.h | C:\Program Files (x86)\Windows Kits\10\Include\10.0.18362.0\um\computestorage.h | C:\Program Files (x86)\Windows Kits\10\Lib\10.0.18362.0\um\x64\computestorage.lib |
hypervdevicevirtualization | Types definitions and APIs for device emulation/virtualization. | hypervdevicevirtualization.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\vmdevicehost.lib |
Features
Feature | Notes |
---|---|
bindings |
By default, the raw C bindings to the SDK APIs are private to the crate. Using feature bindings makes them public for consumption on client code |
schema |
Includes all HCS/HCN schema JSON object model |
19h1 |
By default, the project has compatibility with RS5. Using feature 19h1 adds 19H1 specific updates to the APIs |
utilities |
Includes utility code that provides more Rust abstractions on top of the basic safe wrappers of the C bindings. By default, this crate only exposes the safe wrappers |
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 parameterdevice
to be a immutable reference instead of it being moved. This to ensure callers do not mistakenly drop the only reference to thedevice
instance they might have
- Added convenient
HdvHost::hook_device_interface_callbacks
- Breaking changes
- 0.8.0 Jan 4, 2020
- Breaking changes
set_callback
functions are no longerunsafe
HdvPciDeviceBase::hook_device_interface_callbacks
now expects parameterdevice
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
- Breaking changes
- 0.7.0 Dec 31, 2019
- Breaking changes
- Removed
HdvPciDevice
callback trait functionsunsafe
attribute. Even though it assumes it should not panic, it lead to confusion when the whole function was marked asunsafe
- Reworked the way callbacks are done in the computecore utilities to make it simpler, and do not require a trait object of the closure
- Removed
- Breaking changes
- 0.6.0 Dec 17, 2019
- Breaking changes
- Mark
HdvPciDevice
callback trait functions asunsafe
, due to its assumption that they should not panic
- Mark
- Breaking changes
- 0.5.1 Dec 16, 2019
- Added
#[derive(Clone)]
toHdvPciDeviceBase
andHdvPciDeviceBaseWrapper
.
- Added
- 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)
- Added
- Fixed wrong schema name for
vmbfs_root_path
- Breaking changes
- 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
tohandle
andget_handle_policy
tohandle_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
- hypervdevicevirtualization safe wrappers for reading and writing guest memory now use slices instead of vectors directly
- Added utilities around
hypervdevicevirtualization
APIs
- Breaking changes
- 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
Dependencies
~1–2MB
~31K SLoC