whpx 0.1.0

Idiomatic Rust Bindings of Windows Hypervisor Platform
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# Rust Windows Hypervisor Platform

This crate serves as the safe and idiomatic wrapper of [Windows Hypervisor Platform API](https://learn.microsoft.com/en-us/virtualization/api/hypervisor-platform/hypervisor-platform) and also [Hypervisor Instruction Emulator API](https://learn.microsoft.com/en-us/virtualization/api/hypervisor-instruction-emulator/hypervisor-instruction-emulator).

This crate supports `#![no_std]` and does not incur any static WHPX-related DLL imports. All WHPX APIs shall be dynamically imported with `LoadLibraryA` and `GetProcAddress`. As such, the binary executable file can run on older systems like Windows 7 and even Windows XP, allowing your VMM to choose other solutions to run your guests.

Side note: if you wish to run your VMM with `std` in older platforms such as Windows XP, you should import [YY-Thunks](https://github.com/Chuyu-Team/YY-Thunks) repository or its rust crate [thunk-rs](https://crates.io/crates/thunk-rs) so that aggresive DLL imports such as `api-ms-win-core-sync-l1-2-0` will be mitigated. \
Note that the [thunk-rs](https://crates.io/crates/thunk-rs) crate is not published by the original [YY-Thunks](https://github.com/Chuyu-Team/YY-Thunks) authors, so it may not be up-to-date.

Currently, this crate only supports virtualizing x64 guests.

This crate incurs the following static imports. All of them are compatible with Windows XP:
| API Name | DLL | Usage Purpose |
|---|---|---|
| `LoadLibraryA` | `kernel32.dll` | Loads `WinHvPlatform.dll` and `WinHvEmulation.dll` into the program. |
| `GetProcAddress` | `kernel32.dll` | Gets function pointers of all WHPX APIs. |
| `GetLastError` | `kernel32.dll` | Gets the error code of last failed API call. |
| `FormatMessageW` | `kernel32.dll` | Implements the `Display` trait of `HResult` type. |
| `LocalFree` | `kernel32.dll` | Frees the buffer allocated by `FormatMessageW` API. |
| `VirtualAlloc` | `kernel32.dll` | Allocates pages that can be used for guest memories. |
| `VirtualFree` | `kernel32.dll` | Frees pages that can be used for guest memories. |

## Example

This crate provides a simple example called `ioemu`. To run it:
```
cargo run --example ioemu
```
If you check the import directory of `ioemu.exe`, you can notice that there aren't any `WinHvPlatform.dll` and `WinHvEmulation.dll` imports.

## License

This crate is licensed under the [MIT License](./license.txt).