この API は、Windows April 2018 Update 以降で使用できます。
次の図は、サード パーティのアーキテクチャの概要を示しています。
次のセクションでは、 WinHvPlatform.hを介して公開される Windows ハイパーバイザー プラットフォーム API の定義について説明します。
WinHvPlatform.dll (System32 フォルダーにあります) は、HRESULT エラー コードを返す C スタイルの Windows API 関数のセットをエクスポートします。 ヘッダーは Windows SDK パッケージで発行されます。
プラットフォーム機能
| 機能 | Description |
|---|---|
| WHvGetCapability | プラットフォーム機能は、呼び出し元がハイパーバイザーのプロパティと機能、API 実装、およびアプリケーションが実行されているハードウェア プラットフォームのプロパティと機能を照会するための一般的な方法です。 プラットフォーム API では、これらの機能を使用して、API の拡張機能の可用性と、現在のシステム上のプロセッサがサポートする機能のセットを公開します。 |
パーティションの作成、セットアップ、および削除
| 機能 | Description |
|---|---|
| WHvCreatePartition | パーティションを作成すると、新しいパーティション オブジェクトが作成されます。 パーティションの追加のプロパティはパーティション オブジェクトに格納され、ハイパーバイザーでパーティションを作成するときに適用されます。 |
| WHvSetupPartition | パーティションを設定すると、実際のパーティションがハイパーバイザーに作成されます。 パーティションの初期プロパティの構成を除き、パーティションの作成後にパーティションに対して他の操作を実行する前に、パーティションを設定する必要があります。 |
| WHvDeletePartition | パーティションを削除すると、パーティション オブジェクトが破棄され、パーティションで使用されていたすべてのリソースが解放されます。 |
パーティションのプロパティ
パーティションプロパティは、呼び出し元がパーティションの特性を照会および構成するためのメカニズムを提供します。 プロパティのクエリを実行すると、そのプロパティの現在の値が返されます。このプロパティは、ハイパーバイザーと API 実装によって決定される既定値を提供します。この既定値は、そのプロパティが呼び出し元によって以前に変更されていない場合に備えます。
パーティション プロパティを使用して構成できる機能の可用性は、ハイパーバイザー、API 実装、およびシステム上の物理プロセッサの機能によって異なります。 アプリケーションでは、プロパティの構成を試みる前に、対応する機能を確認する必要があります。
いくつかのプロパティ (たとえば、パーティションで使用できるプロセッサ機能を構成するプロパティ) は、パーティションの作成時と、パーティション内で仮想プロセッサを実行する前にのみ変更できます。 パーティションの実行が開始された後にこれらのプロパティを変更しようとすると、操作が失敗します。
パーティション プロパティの詳細については、「パーティション プロパティのデータ型」を参照してください。
| 機能 | Description |
|---|---|
| WHvGetPartitionProperty | プロパティのクエリを実行すると、そのプロパティの現在の値が返されます。このプロパティは、ハイパーバイザーと API 実装によって決定される既定値を提供します。この既定値は、そのプロパティが呼び出し元によって以前に変更されていない場合に備えます。 |
| WHvSetPartitionProperty | この関数は、パーティション プロパティの構成を設定します。 |
VM メモリ管理
VM パーティションの物理アドレス空間 (GPA 領域) は、仮想化スタックのユーザー モード プロセスで割り当てられたメモリを使用して設定されます。 つまり、仮想化スタックは、Windows の標準メモリ管理機能 (VirtualAlloc など) を使用して必要なメモリを割り当てるか、ファイルをプロセスにマップし、これらの領域にアドレスを使用してこのメモリをパーティションの GPA 領域にマップします。
| 機能 | Description |
|---|---|
| WHvMapGpaRange | パーティションの GPA 領域で範囲のマッピングを作成すると、呼び出し元のプロセス内のリージョンがその範囲のバッキング メモリとして設定されます。 この操作は、指定された GPA ページの以前のマッピングを置き換えます。 |
| WHvUnmapGpaRange | 以前にマップされた GPA 範囲をマップ解除すると、メモリ範囲がパーティションで使用できなくなります。 仮想プロセッサが範囲にアクセスすると、メモリ アクセスが終了します。 |
| WHvTranslateGva | パーティション内の仮想プロセッサによって使用される仮想アドレスを変換すると、仮想化スタックは、変換の結果を使用して、パーティションの GPA 空間内の命令のメモリ オペランドを読み書きする I/O 操作のプロセッサ命令をエミュレートできます。 |
| WHvQueryGpaRangeDirtyBitmap | 範囲の最後のクエリ以降にゲストによって変更されたページを特定するために、GPA 領域の範囲を照会する。 |
仮想プロセッサの実行
VM の仮想プロセッサは、ハイパーバイザーの新しい統合スケジューラを使用して実行されます。 仮想プロセッサを実行するには、仮想化スタックのプロセス内のスレッドがブロック呼び出しを発行してハイパーバイザーで仮想プロセッサを実行します。呼び出しは、仮想化スタックでの処理を必要とする仮想プロセッサの操作または仮想化スタックによる要求のために返されます。
仮想プロセッサを処理するスレッドは、次の基本的な操作を実行します。
- パーティションに仮想プロセッサを作成します。
- 保留中の割り込みとイベントをプロセッサに挿入する仮想プロセッサの状態を設定します。
- 仮想プロセッサを実行します。
- 仮想プロセッサの実行から復帰したら、プロセッサの状態を照会し、プロセッサの実行を停止させる操作を処理します。
- 仮想プロセッサがまだアクティブな場合は、手順 2 に戻ってプロセッサの実行を続行します。
- パーティション内の仮想プロセッサを削除します。
仮想プロセッサの状態には、ハードウェア レジスタと、仮想化スタックが仮想プロセッサに挿入する割り込みが含まれます。
| 機能 | Description |
|---|---|
| WHvCreateVirtualProcessor | この関数は、パーティションに新しい仮想プロセッサを作成します。 仮想プロセッサのインデックスは、プロセッサの APIC ID を設定するために使用されます。 |
| WHvDeleteVirtualProcessor | この関数は、パーティション内の仮想プロセッサを削除します。 |
| WHvRunVirtualProcessor | この関数は、仮想プロセッサを実行します (つまり、ゲスト コードを実行できます)。 この関数の呼び出しは、仮想プロセッサが仮想化スタックで処理する必要がある操作 (マップされていないかアクセスできない GPA 空間のメモリなど) を実行するか、仮想化スタックが関数の終了 (仮想プロセッサの割り込みを挿入したり、VM の状態を変更したりするなど) を明示的に要求するまで、同期的にブロックされます。 |
| WHvCancelRunVirtualProcessor | 仮想プロセッサの実行を取り消すと、アプリケーションは、別のスレッドで仮想プロセッサを実行し、そのスレッドにコントロールを返す呼び出しを中止できます。 仮想化スタックでは、VM の状態を変更したり、プロセッサにイベントを挿入したりする必要がある場合に備えて、この関数を使用して仮想プロセッサの制御を仮想化スタックに戻すことができます。 |
終了コンテキスト
WHvRunVirtualProcessor関数の終了に関する詳細な理由と追加情報は、出口のコンテキスト構造を受け取る関数の出力バッファーに戻ります。 このコンテキスト バッファーで提供されるデータは個々の終了の理由に固有であり、単純な終了の理由からバッファーが使用されていない可能性があります (RunVpExitLegacyFpError と RunVpExitInvalidVpRegisterValue)。
| 構造体 | Description |
|---|---|
| 終了コンテキスト | いくつかの終了理由のコンテキスト構造は、出口の原因となったプロセッサー命令に関する情報と、出口時の仮想プロセッサーの状態に関する情報を提供するデータの共通定義を共有します。 |
| メモリ アクセス | マップされていないかアクセスできないメモリ位置に仮想プロセッサがアクセスすることによって発生する出口に関する情報は、 WHV_MEMORY_ACCESS_CONTEXT 構造体によって提供されます。 |
| I/O ポート アクセス | I/O ポート命令 (IN、OUT、INS、および OUTS) を実行している仮想プロセッサによって発生する出口に関する情報は、 WHV_X64_IO_PORT_ACCESS_CONTEXT 構造体で提供されます。 |
| MSR Access | RDMSR 命令または WRMSR 命令を使用してモデル固有のレジスタ (MSR) にアクセスする仮想プロセッサによって発生する出口に関する情報は、 WHV_X64_MSR_ACCESS_CONTEXT 構造で提供されます。 |
| CPUID アクセス | CPUID 命令を実行する仮想プロセッサによって発生する出口に関する情報は、 WHV_X64_CPUID_ACCESS_CONTEXT 構造体で提供されます。 |
| 仮想プロセッサの例外 | 仮想プロセッサによって生成された例外に関する情報は、 WHV_VP_EXCEPTION_CONTEXT 構造体で提供されます。 |
| 割り込みウィンドウ | プロセッサの割り込み禁止状態が特定の割り込みの配信を許可する場合に、仮想プロセッサによって発生する出口に関する情報。 |
| サポートされていない機能 | サポートされていない機能の終了は、仮想プロセッサがハイパーバイザーによって適切に仮想化されていないアーキテクチャの機能にアクセスすることによって発生します。 |
| 実行が取り消されました | ホスト・システムが原因で発生した出口に関する情報は、 WHV_RUN_VP_CANCELLED_CONTEXT 構造で提供されます。 |
| RDTSC(P) | RDTSC(P) 命令を実行する仮想プロセッサによって発生する出口に関する情報は、 WHV_X64_RDTSC_CONTEXT 構造体で提供されます。 |
仮想プロセス レジスタ
基になるアーキテクチャによって定義された状態 (汎用レジスタなど) とハイパーバイザーによって定義された追加の状態の両方を含む仮想プロセッサの状態は、これらの関数を介してアクセスできます。
レジスタの詳細については、「仮想プロセッサ レジスタの名前と値」を参照してください。
| 機能 | Description |
|---|---|
| WHvGetVirtualProcessorRegisters | この関数を使用すると、仮想化スタックによって個々のレジスタのセットに対してクエリを実行できます。 |
| WHvGetVirtualProcessorXsaveState | この関数を使用すると、仮想プロセッサの XSAVE 状態に対してクエリを実行できます。 |
| WHvSetVirtualProcessorRegisters | この関数を使用すると、仮想化スタックによって個々のレジスタのセットを設定できます。 |
| WHvSetVirtualProcessorXsaveState | この関数を使用すると、仮想プロセッサの XSAVE 状態を設定できます。 |
割り込みコントローラーの仮想化
必要に応じて、ハイパーバイザー プラットフォームはローカル APIC 割り込みコントローラーをエミュレートできます。 APIC が必要な仮想マシンの場合、プラットフォームの組み込みエミュレーションを使用すると、最適なパフォーマンスが得られます。
この機能を有効にすると、これらの関数を使用して APIC 状態のクエリと設定を行い、仮想割り込みを要求できます。
| 機能 | Description |
|---|---|
| WHvGetVirtualProcessorInterruptControllerState | 仮想プロセッサの割り込みコントローラーの状態を照会します。 |
| WHvRequestInterrupt | 割り込みを要求します。 |
| WHvSetVirtualProcessorInterruptControllerState | 仮想プロセッサの割り込みコントローラーの状態を設定します。 |
カウンター
これらの関数を使用して、さまざまなハイパーバイザー プラットフォーム カウンターのクエリを実行できます。
| 機能 | Description |
|---|---|
| WHvGetPartitionCounters | この関数を使用すると、パーティションのカウンターのクエリを実行できます。 |
| WHvGetVirtualProcessorCounters | この関数を使用すると、仮想プロセッサのカウンターのクエリを実行できます。 |