この API は、Windows April 2018 Update 以降で使用できます。
次の図は、サード パーティのアーキテクチャの概要を示しています。
次のセクションでは、 WinHvPlatform.hを介して公開される Windows ハイパーバイザー プラットフォーム API の定義について説明します。
WinHvPlatform.dll (System32 フォルダーにあります) は、HRESULT エラー コードを返す C スタイルの Windows API 関数のセットをエクスポートします。 ヘッダーは Windows SDK パッケージで発行されます。
プラットフォーム機能
| 機能 | Description |
|---|---|
| WHvGetCapability | プラットフォーム機能は、呼び出し元がハイパーバイザーのプロパティと機能、API 実装、およびアプリケーションが実行されているハードウェア プラットフォームのプロパティと機能を照会するための一般的な方法です。 プラットフォーム API では、これらの機能を使用して、API の拡張機能の可用性と、現在のシステム上のプロセッサがサポートする機能のセットを公開します。 |
現在のシステムが Arm64 で Windows Hypervisor Platform をサポートしているかどうかを確認するには、WHvCapabilityCodeFeatures で WHvGetCapability を呼び出し、返された WHV_CAPABILITY_FEATURES 値の Arm64Support ビットをテストします。
パーティションの作成、セットアップ、および削除
| 機能 | Description |
|---|---|
| WHvCreatePartition | パーティションを作成すると、新しいパーティション オブジェクトが作成されます。 パーティションの追加のプロパティはパーティション オブジェクトに格納され、ハイパーバイザーでパーティションを作成するときに適用されます。 |
| WHvSetupPartition | パーティションを設定すると、実際のパーティションがハイパーバイザーに作成されます。 パーティションの初期プロパティの構成を除き、パーティションの作成後にパーティションに対して他の操作を実行する前に、パーティションを設定する必要があります。 |
| WHvDeletePartition | パーティションを削除すると、パーティション オブジェクトが破棄され、パーティションで使用されていたすべてのリソースが解放されます。 |
パーティションのプロパティ
パーティションプロパティは、呼び出し元がパーティションの特性を照会および構成するためのメカニズムを提供します。 プロパティのクエリを実行すると、そのプロパティの現在の値が返されます。このプロパティは、ハイパーバイザーと API 実装によって決定される既定値を提供します。この既定値は、そのプロパティが呼び出し元によって以前に変更されていない場合に備えます。
パーティション プロパティを使用して構成できる機能の可用性は、ハイパーバイザー、API 実装、およびシステム上の物理プロセッサの機能によって異なります。 アプリケーションでは、プロパティの構成を試みる前に、対応する機能を確認する必要があります。
いくつかのプロパティ (たとえば、パーティションで使用できるプロセッサ機能を構成するプロパティ) は、パーティションの作成時とパーティション内の仮想プロセッサの実行前にのみ変更できます。 パーティションの実行が開始された後にこれらのプロパティを変更しようとすると、操作が失敗します。
パーティション プロパティの詳細については、「パーティション プロパティのデータ型」を参照してください。
| 機能 | Description |
|---|---|
| WHvGetPartitionProperty | プロパティのクエリを実行すると、そのプロパティの現在の値が返されます。このプロパティは、ハイパーバイザーと API 実装によって決定される既定値を提供します。この既定値は、そのプロパティが呼び出し元によって以前に変更されていない場合に備えます。 |
| WHvSetPartitionProperty | パーティションのプロパティの構成を設定します。 |
パーティションのリセットと移行
パーティションは初期状態にリセットでき、実行中のパーティションはホスト間で移行できます。 移行は、移行元ホストで開始され、移行先ホストで受け入れられ、ソース ホストで完了または取り消された複数ステップのプロセスです。
| 機能 | Description |
|---|---|
| WHvResetPartition | パーティションを初期状態にリセットします。 |
| WHvStartPartitionMigration | ソース ホスト上のパーティションの移行を開始します。 |
| WHvAcceptPartitionMigration | 移行先ホストで移行中のパーティションを受け入れます。 |
| WHvCompletePartitionMigration | ソース ホストでのパーティションの移行を完了します。 |
| WHvCancelPartitionMigration | ソース ホストで進行中のパーティションの移行を中止します。 |
VM メモリ管理
VM パーティションの物理アドレス空間 (GPA 領域) は、仮想化スタックのユーザー モード プロセスで割り当てられたメモリを使用して設定されます。 仮想化スタックは、標準のWindowsメモリ管理機能 (VirtualAlloc など) を使用して必要なメモリを割り当てるか、ファイルをプロセスにマップし、これらのリージョンのアドレスを使用してメモリをパーティションの GPA 領域にマップします。
メモリ データ型の詳細については、「メモリ データ型」を参照してください。
| 機能 | Description |
|---|---|
| WHvMapGpaRange | パーティションの GPA 領域で範囲のマッピングを作成すると、呼び出し元のプロセス内のリージョンがその範囲のバッキング メモリとして設定されます。 この操作は、指定された GPA ページの以前のマッピングを置き換えます。 |
| WHvMapGpaRange2 | パーティションのゲスト物理アドレス空間の範囲を、指定されたホスト プロセスのメモリにマップします。 |
| WHvUnmapGpaRange | 以前にマップされた GPA 範囲をマップ解除すると、メモリ範囲がパーティションで使用できなくなります。 仮想プロセッサが範囲にアクセスすると、メモリ アクセスが終了します。 |
| WHvAdviseGpaRange | 1 つ以上のゲスト物理アドレス範囲をバッキングするメモリに関するヒントをハイパーバイザーに提供します。 |
| WHvReadGpaRange | パーティションのゲスト物理アドレス空間から最大 WHV_READ_WRITE_GPA_RANGE_MAX_SIZE バイトを読み取ります。 |
| WHvWriteGpaRange | パーティションのゲスト物理アドレス空間に最大 WHV_READ_WRITE_GPA_RANGE_MAX_SIZE バイトを書き込みます。 |
| WHvTranslateGva | パーティション内の仮想プロセッサによって使用される仮想アドレスを変換すると、仮想化スタックは、変換の結果を使用して、パーティションの GPA 空間内の命令のメモリ オペランドを読み書きする I/O 操作のプロセッサ命令をエミュレートできます。 |
| WHvQueryGpaRangeDirtyBitmap | GPA 領域の範囲を照会して、その範囲の最後のクエリ以降にゲストが変更したページを決定します。 |
仮想プロセッサの実行
VM の仮想プロセッサは、ハイパーバイザーの新しい統合スケジューラを使用して実行されます。 仮想プロセッサを実行するには、仮想化スタック プロセスのスレッドがブロック呼び出しを発行して、ハイパーバイザーで仮想プロセッサを実行します。 この呼び出しは、仮想プロセッサが仮想化スタックで処理する必要がある操作を実行したとき、または仮想化スタックが終了を要求したときに返されます。
仮想プロセッサを処理するスレッドは、次の基本的な操作を実行します。
- パーティションに仮想プロセッサを作成します。
- 保留中の割り込みとイベントをプロセッサに挿入する仮想プロセッサの状態を設定します。
- 仮想プロセッサを実行します。
- 仮想プロセッサの実行から復帰したら、プロセッサの状態を照会し、プロセッサの実行を停止させる操作を処理します。
- 仮想プロセッサがまだアクティブな場合は、手順 2 に戻ってプロセッサの実行を続行します。
- パーティション内の仮想プロセッサを削除します。
仮想プロセッサの状態には、ハードウェア レジスタと、仮想化スタックが仮想プロセッサに挿入する割り込みが含まれます。
| 機能 | Description |
|---|---|
| WHvCreateVirtualProcessor | この関数は、パーティションに新しい仮想プロセッサを作成します。 仮想プロセッサのインデックスは、プロセッサの APIC ID を設定するために使用されます。 |
| WHvCreateVirtualProcessor2 | オプションの作成時プロパティを使用して、パーティション内に新しい仮想プロセッサを作成します。 |
| 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 構造体で提供されます。 |
| インターセプトの登録 | インターセプトされたシステム・レジスタ・アクセスによって引き起こされる Arm64 出口に関する情報は、 WHV_REGISTER_CONTEXT 構造体で提供されます。 |
| Arm64 リセット | 仮想プロセッサ リセット要求によって発生する Arm64 出口に関する情報は、 WHV_ARM64_RESET_CONTEXT 構造体で提供されます。 |
仮想プロセッサ レジスタ
基になるアーキテクチャによって定義された状態 (汎用レジスタなど) とハイパーバイザーによって定義された追加の状態の両方を含む仮想プロセッサの状態には、これらの関数を使用してアクセスできます。
レジスタの詳細については、「仮想プロセッサ レジスタの名前と値」を参照してください。
| 機能 | Description |
|---|---|
| WHvGetVirtualProcessorRegisters | この関数を使用すると、仮想化スタックによって個々のレジスタのセットに対してクエリを実行できます。 |
| WHvGetVirtualProcessorXsaveState | この関数を使用すると、仮想プロセッサの XSAVE 状態に対してクエリを実行できます。 非推奨。 WHvGetVirtualProcessorState を使用します。 |
| WHvSetVirtualProcessorRegisters | この関数を使用すると、仮想化スタックによって個々のレジスタのセットを設定できます。 |
| WHvSetVirtualProcessorXsaveState | この関数を使用すると、仮想プロセッサの XSAVE 状態を設定できます。 廃止; WHvSetVirtualProcessorState を使用します。 |
割り込みコントローラーの仮想化
必要に応じて、ハイパーバイザー プラットフォームはローカル APIC 割り込みコントローラーをエミュレートできます。 APIC が必要な仮想マシンの場合、プラットフォームの組み込みエミュレーションを使用すると最高のパフォーマンスが得られます。 Arm64 では、パーティションがセットアップされる前に構成されたエミュレートされた割り込みコントローラー (GIC) をパーティションで使用する必要があります。 詳細については、WHvSetupPartitionを参照してください。
この機能を有効にすると、これらの関数を使用して仮想割り込みを要求したり、割り込みコントローラーの状態を照会および設定したりできます。
| 機能 | Description |
|---|---|
| WHvRequestInterrupt | 仮想割り込みを要求します。 |
| WHvGetInterruptTargetVpSet | 割り込み先を一連のターゲット仮想プロセッサに解決します。 |
| WHvGetVirtualProcessorInterruptControllerState | 仮想プロセッサの割り込みコントローラーの状態を取得します。 非推奨。 WHvGetVirtualProcessorState を使用します。 |
| WHvGetVirtualProcessorInterruptControllerState2 | 標準の外部状態形式で仮想プロセッサの割り込みコントローラーの状態を取得します。 非推奨。 WHvGetVirtualProcessorState を使用します。 |
| WHvSetVirtualProcessorInterruptControllerState | 仮想プロセッサの割り込みコントローラーの状態を設定します。 廃止; WHvSetVirtualProcessorState を使用します。 |
| WHvSetVirtualProcessorInterruptControllerState2 | 仮想プロセッサの割り込みコントローラーの状態を標準の外部状態形式で設定します。 廃止; WHvSetVirtualProcessorState を使用します。 |
仮想プロセッサの状態
個々のレジスタに加えて、仮想プロセッサの保存された状態をカテゴリ別に照会および設定でき、仮想プロセッサが観察する CPUID の結果を照会できます。
| 機能 | Description |
|---|---|
| WHvGetVirtualProcessorState | 仮想プロセッサから保存された状態のカテゴリを取得します。 |
| WHvSetVirtualProcessorState | 仮想プロセッサに保存された状態のカテゴリを設定します。 |
| WHvGetVirtualProcessorCpuidOutput | 仮想プロセッサが特定のリーフについて観察する CPUID の結果を返します。 |
合成割り込みコントローラー (SynIC)
これらの関数は、合成割り込みコントローラー (SynIC) イベントとメッセージを仮想プロセッサに配信します。
| 機能 | Description |
|---|---|
| WHvSignalVirtualProcessorSynicEvent | 仮想プロセッサ上の合成割り込みコントローラー イベント フラグを通知します。 |
| WHvPostVirtualProcessorSynicMessage | 合成割り込みコントローラー メッセージを仮想プロセッサに投稿します。 |
カウンター
これらの関数を使用して、さまざまなハイパーバイザー プラットフォーム カウンターのクエリを実行できます。
| 機能 | Description |
|---|---|
| WHvGetPartitionCounters | この関数を使用すると、パーティションのカウンターのクエリを実行できます。 |
| WHvGetVirtualProcessorCounters | この関数を使用すると、仮想プロセッサのカウンターのクエリを実行できます。 |
ドアベル
ドアベルを使用すると、ゲストが指定した値を指定したゲスト物理アドレスに書き込むときに、Windows イベント オブジェクトを介して仮想化スタックに通知できます。
Note
ドアベル関数は非推奨です。 代わりに、 WHvNotificationPortTypeDoorbell の種類の通知ポートを使用します ( 通知ポートを参照)。
doorbell データ型の詳細については、「Doorbell データ型」を参照してください。
| 機能 | Description |
|---|---|
| WHvRegisterPartitionDoorbellEvent | ゲストが指定されたゲスト物理アドレスに書き込むときに通知されるイベントを登録します。 廃止; WHvCreateNotificationPort を使用します。 |
| WHvUnregisterPartitionDoorbellEvent | 以前に登録されたパーティション ドアベル イベントの登録を解除します。 廃止; WHvDeleteNotificationPort を使用します。 |
トリガー
トリガーは、ホスト イベント オブジェクトが通知されたときに、事前に構成された割り込みまたはイベントをパーティションに配信します。
トリガー データ型の詳細については、以下を参照してください。
| 機能 | Description |
|---|---|
| WHvCreateTrigger | ホスト イベントが通知されたときに、事前に構成された割り込みまたはイベントをパーティションに配信するトリガー オブジェクトを作成します。 |
| WHvUpdateTriggerParameters | 既存のトリガー オブジェクトのパラメーターを更新します。 |
| WHvDeleteTrigger | パーティションからトリガー オブジェクトを削除します。 |
通知ポート
通知ポートは、パーティションが一致するイベントを生成するときに、Windows イベント オブジェクトに通知します。
通知ポートのデータ型の詳細については、「通知ポートのデータ型」を参照してください。
| 機能 | Description |
|---|---|
| WHvCreateNotificationPort | パーティションで一致するイベントが生成されたときに、Windows イベント オブジェクトに通知する通知ポートを作成します。 |
| WHvSetNotificationPortProperty | 既存の通知ポートのプロパティを設定します。 |
| WHvDeleteNotificationPort | 通知ポートを削除します。 |
仮想 PCI (VPCI) デバイス
Windowsハイパーバイザー プラットフォームは、物理 PCI デバイスを仮想 PCI (VPCI) デバイスとしてパーティションに割り当てることができます。 これらの関数は、バッキング リソースの割り当て、VPCI デバイスの作成と削除、プロパティと通知の照会、MMIO 範囲のマッピング、電源状態の管理、レジスタへのアクセスを行います。
VPCI データ型の詳細については、「仮想 PCI データ型」を参照してください。
| 機能 | Description |
|---|---|
| WHvAllocateVpciResource | 仮想デバイスをバックアップするために仮想 PCI (VPCI) リソースを割り当てます。 |
| WHvCreateVpciDevice | 仮想 PCI (VPCI) デバイスを作成し、そのリソースをパーティションに割り当てます。 |
| WHvDeleteVpciDevice | 仮想 PCI (VPCI) デバイスを破棄し、そのリソースを解放します。 |
| WHvGetVpciDeviceProperty | 仮想 PCI (VPCI) デバイスのプロパティを取得します。 |
| WHvGetVpciDeviceNotification | 仮想 PCI (VPCI) デバイスの次の保留中の通知を取得します。 |
| WHvMapVpciDeviceMmioRanges | 仮想 PCI (VPCI) デバイスの MMIO 範囲を呼び出し元のプロセスにマップします。 |
| WHvUnmapVpciDeviceMmioRanges | 仮想 PCI (VPCI) デバイスの MMIO 範囲を呼び出し元のプロセスからマップ解除します。 |
| WHvSetVpciDevicePowerState | 仮想 PCI (VPCI) デバイスの電源状態を変更します。 |
| WHvReadVpciDeviceRegister | 仮想 PCI (VPCI) デバイスの構成スペースまたは MMIO レジスタを読み取ります。 |
| WHvWriteVpciDeviceRegister | 仮想 PCI (VPCI) デバイスの構成スペースまたは MMIO レジスタを書き込みます。 |
仮想 PCI (VPCI) デバイス割り込み
これらの関数は、MSI のマップ、マップ解除、再ターゲット、要求、クエリを実行し、割り当てられた仮想 PCI デバイスの割り込みを MSI-X します。
| 機能 | Description |
|---|---|
| WHvMapVpciDeviceInterrupt | 割り当てられた仮想 PCI デバイスの MSI または MSI-X 割り込みをマップし、MSI アドレスとデータをデバイスにプログラムに返します。 |
| WHvUnmapVpciDeviceInterrupt | 割り当てられた仮想 PCI デバイスの割り当て済み割り込みを削除します。 |
| WHvRetargetVpciDeviceInterrupt | 割り当てられた仮想 PCI デバイスの以前にマップされた割り込みのターゲット ベクターとプロセッサ セットを変更します。 |
| WHvRequestVpciDeviceInterrupt | 割り当てられた仮想 PCI デバイスを所有するパーティションに論理割り込みを配信します。 |
| WHvGetVpciDeviceInterruptTarget | 割り当てられた仮想 PCI デバイスの割り当て済み割り込みの現在のベクトルとプロセッサ セットを照会します。 |