API 実装、ハイパーバイザー、およびシステムのプロセッサの機能を照会します。
構文
//
// Platform capabilities
//
typedef enum WHV_CAPABILITY_CODE
{
// Capabilities of the API implementation
WHvCapabilityCodeHypervisorPresent = 0x00000000,
WHvCapabilityCodeFeatures = 0x00000001,
WHvCapabilityCodeExtendedVmExits = 0x00000002,
#if defined(_AMD64_)
WHvCapabilityCodeExceptionExitBitmap = 0x00000003,
WHvCapabilityCodeX64MsrExitBitmap = 0x00000004,
#endif
WHvCapabilityCodeGpaRangePopulateFlags = 0x00000005,
WHvCapabilityCodeSchedulerFeatures = 0x00000006,
// Capabilities of the system's processor
WHvCapabilityCodeProcessorVendor = 0x00001000,
WHvCapabilityCodeProcessorFeatures = 0x00001001,
WHvCapabilityCodeProcessorClFlushSize = 0x00001002,
#if defined(_AMD64_)
WHvCapabilityCodeProcessorXsaveFeatures = 0x00001003,
#endif
WHvCapabilityCodeProcessorClockFrequency = 0x00001004,
#if defined(_AMD64_)
WHvCapabilityCodeInterruptClockFrequency = 0x00001005,
#endif
WHvCapabilityCodeProcessorFeaturesBanks = 0x00001006,
WHvCapabilityCodeProcessorFrequencyCap = 0x00001007,
WHvCapabilityCodeSyntheticProcessorFeaturesBanks = 0x00001008,
#if defined(_AMD64_)
WHvCapabilityCodeProcessorPerfmonFeatures = 0x00001009,
#endif
WHvCapabilityCodePhysicalAddressWidth = 0x0000100A,
#if defined(_AMD64_)
// Nested-virtualization related capabilities
WHvCapabilityCodeVmxBasic = 0x00002000,
WHvCapabilityCodeVmxPinbasedCtls = 0x00002001,
WHvCapabilityCodeVmxProcbasedCtls = 0x00002002,
WHvCapabilityCodeVmxExitCtls = 0x00002003,
WHvCapabilityCodeVmxEntryCtls = 0x00002004,
WHvCapabilityCodeVmxMisc = 0x00002005,
WHvCapabilityCodeVmxCr0Fixed0 = 0x00002006,
WHvCapabilityCodeVmxCr0Fixed1 = 0x00002007,
WHvCapabilityCodeVmxCr4Fixed0 = 0x00002008,
WHvCapabilityCodeVmxCr4Fixed1 = 0x00002009,
WHvCapabilityCodeVmxVmcsEnum = 0x0000200A,
WHvCapabilityCodeVmxProcbasedCtls2 = 0x0000200B,
WHvCapabilityCodeVmxEptVpidCap = 0x0000200C,
WHvCapabilityCodeVmxTruePinbasedCtls = 0x0000200D,
WHvCapabilityCodeVmxTrueProcbasedCtls = 0x0000200E,
WHvCapabilityCodeVmxTrueExitCtls = 0x0000200F,
WHvCapabilityCodeVmxTrueEntryCtls = 0x00002010,
#elif defined (_ARM64_)
WHvCapabilityCodeGicLpiIntIdBits = 0x00002011,
WHvCapabilityCodeMaxSveVectorLength = 0x00002012,
#endif
} WHV_CAPABILITY_CODE;
//
// Return values for WHvCapabilityCodeFeatures
//
typedef union WHV_CAPABILITY_FEATURES
{
struct
{
UINT64 PartialUnmap : 1;
#if defined(_AMD64_)
UINT64 LocalApicEmulation : 1;
UINT64 Xsave : 1;
#else
UINT64 ReservedArm0 : 2;
#endif
UINT64 DirtyPageTracking : 1;
UINT64 SpeculationControl : 1;
#if defined(_AMD64_)
UINT64 ApicRemoteRead : 1;
#else
UINT64 ReservedArm1 : 1;
#endif
UINT64 IdleSuspend : 1;
UINT64 VirtualPciDeviceSupport : 1;
UINT64 IommuSupport : 1;
UINT64 VpHotAddRemove : 1;
UINT64 DeviceAccessTracking : 1;
#if defined(_AMD64_)
UINT64 ReservedX640 : 1;
#else
UINT64 Arm64Support : 1;
#endif
UINT64 Reserved : 52;
};
UINT64 AsUINT64;
} WHV_CAPABILITY_FEATURES;
//
// Return values for WHvCapabilityCodeExtendedVmExits and input buffer for
// WHvPartitionPropertyCodeExtendedVmExits
//
typedef union WHV_EXTENDED_VM_EXITS
{
struct
{
#if defined(_AMD64_)
UINT64 X64CpuidExit : 1; // WHvRunVpExitReasonX64CPUID supported
UINT64 X64MsrExit : 1; // WHvRunVpExitX64ReasonMSRAccess supported
UINT64 ExceptionExit : 1; // WHvRunVpExitReasonException supported
UINT64 X64RdtscExit : 1; // WHvRunVpExitReasonX64Rdtsc supported
UINT64 X64ApicSmiExitTrap : 1; // WHvRunVpExitReasonX64ApicSmiTrap supported
#else
UINT64 ReservedArm0 : 5;
#endif
UINT64 HypercallExit : 1; // WHvRunVpExitReasonHypercall supported
#if defined(_AMD64_)
UINT64 X64ApicInitSipiExitTrap : 1; // WHvRunVpExitReasonX64ApicInitSipiTrap supported
UINT64 X64ApicWriteLint0ExitTrap : 1; // WHvRunVpExitReasonX64ApicWriteTrap supported
UINT64 X64ApicWriteLint1ExitTrap : 1; // WHvRunVpExitReasonX64ApicWriteTrap supported
UINT64 X64ApicWriteSvrExitTrap : 1; // WHvRunVpExitReasonX64ApicWriteTrap supported
#else
UINT64 ReservedArm1 : 4;
#endif
UINT64 UnknownSynicConnection : 1; // WHvRunVpExitReasonHypercall supported for unknown synic connection to HvSignalEvent
UINT64 RetargetUnknownVpciDevice : 1; // WHvRunVpExitReasonHypercall supported for unknown device to HvRetargetDeviceInterrupt
#if defined(_AMD64_)
UINT64 X64ApicWriteLdrExitTrap : 1; // WHvRunVpExitReasonX64ApicWriteTrap supported
UINT64 X64ApicWriteDfrExitTrap : 1; // WHvRunVpExitReasonX64ApicWriteTrap supported
#else
UINT64 ReservedArm2 : 2;
#endif
UINT64 GpaAccessFaultExit : 1; // WHvRunVpExitReasonMemoryAccess supported for second-level page faults
UINT64 Reserved : 49;
};
UINT64 AsUINT64;
} WHV_EXTENDED_VM_EXITS;
//
// Return values for WHvCapabilityCodeProcessorVendor
//
typedef enum WHV_PROCESSOR_VENDOR
{
WHvProcessorVendorAmd = 0x0000,
WHvProcessorVendorIntel = 0x0001,
WHvProcessorVendorHygon = 0x0002,
WHvProcessorVendorArm = 0x0010,
} WHV_PROCESSOR_VENDOR;
//
// Return values for WHvCapabilityCodeProcessorFeatures
//
#if defined(_AMD64_)
typedef union WHV_X64_PROCESSOR_FEATURES
{
struct
{
UINT64 Sse3Support : 1;
UINT64 LahfSahfSupport : 1;
UINT64 Ssse3Support : 1;
UINT64 Sse4_1Support : 1;
UINT64 Sse4_2Support : 1;
UINT64 Sse4aSupport : 1;
UINT64 XopSupport : 1;
UINT64 PopCntSupport : 1;
UINT64 Cmpxchg16bSupport : 1;
UINT64 Altmovcr8Support : 1;
UINT64 LzcntSupport : 1;
UINT64 MisAlignSseSupport : 1;
UINT64 MmxExtSupport : 1;
UINT64 Amd3DNowSupport : 1;
UINT64 ExtendedAmd3DNowSupport : 1;
UINT64 Page1GbSupport : 1;
UINT64 AesSupport : 1;
UINT64 PclmulqdqSupport : 1;
UINT64 PcidSupport : 1;
UINT64 Fma4Support : 1;
UINT64 F16CSupport : 1;
UINT64 RdRandSupport : 1;
UINT64 RdWrFsGsSupport : 1;
UINT64 SmepSupport : 1;
UINT64 EnhancedFastStringSupport : 1;
UINT64 Bmi1Support : 1;
UINT64 Bmi2Support : 1;
UINT64 Reserved1 : 2;
UINT64 MovbeSupport : 1;
UINT64 Npiep1Support : 1;
UINT64 DepX87FPUSaveSupport : 1;
UINT64 RdSeedSupport : 1;
UINT64 AdxSupport : 1;
UINT64 IntelPrefetchSupport : 1;
UINT64 SmapSupport : 1;
UINT64 HleSupport : 1;
UINT64 RtmSupport : 1;
UINT64 RdtscpSupport : 1;
UINT64 ClflushoptSupport : 1;
UINT64 ClwbSupport : 1;
UINT64 ShaSupport : 1;
UINT64 X87PointersSavedSupport : 1;
UINT64 InvpcidSupport : 1;
UINT64 IbrsSupport : 1;
UINT64 StibpSupport : 1;
UINT64 IbpbSupport : 1;
UINT64 UnrestrictedGuestSupport : 1;
UINT64 SsbdSupport : 1;
UINT64 FastShortRepMovSupport : 1;
UINT64 Reserved3 : 1;
UINT64 RdclNo : 1;
UINT64 IbrsAllSupport : 1;
UINT64 Reserved4 : 1;
UINT64 SsbNo : 1;
UINT64 RsbANo : 1;
UINT64 Reserved5 : 1;
UINT64 RdPidSupport : 1;
UINT64 UmipSupport : 1;
UINT64 MdsNoSupport : 1;
UINT64 MdClearSupport : 1;
UINT64 TaaNoSupport : 1;
UINT64 TsxCtrlSupport : 1;
UINT64 Reserved6 : 1;
};
UINT64 AsUINT64;
} WHV_X64_PROCESSOR_FEATURES, WHV_PROCESSOR_FEATURES;
typedef union WHV_PROCESSOR_XSAVE_FEATURES
{
struct
{
UINT64 XsaveSupport : 1;
UINT64 XsaveoptSupport : 1;
UINT64 AvxSupport : 1;
UINT64 Avx2Support : 1;
UINT64 FmaSupport : 1;
UINT64 MpxSupport : 1;
UINT64 Avx512Support : 1;
UINT64 Avx512DQSupport : 1;
UINT64 Avx512CDSupport : 1;
UINT64 Avx512BWSupport : 1;
UINT64 Avx512VLSupport : 1;
UINT64 XsaveCompSupport : 1;
UINT64 XsaveSupervisorSupport : 1;
UINT64 Xcr1Support : 1;
UINT64 Avx512BitalgSupport : 1;
UINT64 Avx512IfmaSupport : 1;
UINT64 Avx512VBmiSupport : 1;
UINT64 Avx512VBmi2Support : 1;
UINT64 Avx512VnniSupport : 1;
UINT64 GfniSupport : 1;
UINT64 VaesSupport : 1;
UINT64 Avx512VPopcntdqSupport : 1;
UINT64 VpclmulqdqSupport : 1;
UINT64 Avx512Bf16Support : 1;
UINT64 Avx512Vp2IntersectSupport : 1;
UINT64 Avx512Fp16Support : 1;
UINT64 XfdSupport : 1;
UINT64 AmxTileSupport : 1;
UINT64 AmxBf16Support : 1;
UINT64 AmxInt8Support : 1;
UINT64 AvxVnniSupport : 1;
UINT64 AvxIfmaSupport : 1;
UINT64 AvxNeConvertSupport : 1;
UINT64 AvxVnniInt8Support : 1;
UINT64 AvxVnniInt16Support : 1;
UINT64 Avx10_1_256Support : 1;
UINT64 Avx10_1_512Support : 1;
UINT64 AmxFp16Support : 1;
UINT64 Reserved : 26;
};
UINT64 AsUINT64;
} WHV_PROCESSOR_XSAVE_FEATURES, *PWHV_PROCESSOR_XSAVE_FEATURES;
#elif defined(_ARM64_)
typedef union WHV_ARM64_PROCESSOR_FEATURES
{
struct
{
//
// Bits for features reported by ID_AA64MMFR0_EL1
//
UINT64 Asid16:1; // 16 bits ASID.
UINT64 TGran16:1; // Indicated support for 16KB memory translation granule.
UINT64 TGran64:1; // Indicated support for 64KB memory translation granule.
//
// Bits for features reported by ID_AA64MMFR1_EL1
//
UINT64 Haf:1; // Hardware updates to Access flag.
UINT64 Hdbs:1; // Hardware updates to Dirty state.
UINT64 Pan:1; // Privileged access never (ARMv8.1).
UINT64 AtS1E1:1; // AT S1E1RP and AT S1E1WP supported.
//
// Bits for features reported by ID_AA64MMFR2_EL1
//
UINT64 Uao:1; // PSTATE override of Unprivileged Load/Store (ARMv8.2)
//
// Bits for features reported by ID_AA64PFR0_EL1
//
UINT64 El0Aarch32:1; // If Aarch32 is supported at El0.
UINT64 Fp:1; // Floating point support.
UINT64 FpHp:1; // Floating point half-precision support.
UINT64 AdvSimd:1; // AdvSIMD is implemented.
UINT64 AdvSimdHp:1; // AdvSIMD with half precision floating point support.
UINT64 GicV3V4:1; // System register interface to versions 3 and 4 of the GIC CPU interface is implemented.
UINT64 GicV41:1; // System register interface to version 4.1 of the GIC CPU interface is implemented.
UINT64 Ras:1; // Ras
//
// Bits for features reported by ID_AA64DFR0_EL1
//
UINT64 PmuV3:1; // PMUv3 implemented.
UINT64 PmuV3ArmV81:1; // PMUv3 for Armv8.1 implemented.
UINT64 PmuV3ArmV84:1; // PMUv3 for Armv8.4 implemented.
UINT64 PmuV3ArmV85:1; // PMUv3 for Armv8.5 implemented.
//
// Bits for features reported by ID_AA64ISAR0_EL1
//
UINT64 Aes:1; // AES(AESE, AESD, AESMC, AESIMC) instructions.
UINT64 PolyMul:1; // Polynomial multiply instructions PMULL/PMULL2
UINT64 Sha1:1; // Sha1 instructions implemented.
UINT64 Sha256:1; // Sha256 instructions implemented.
UINT64 Sha512:1; // Sha512 instructions implemented.
UINT64 Crc32:1; // CRC instructions implemented.
UINT64 Atomic:1; // Atomic instructions implemented.
UINT64 Rdm:1; // SQRDMLAH, SQRDMLSH instructions implemented.
UINT64 Sha3:1; // Sha3 instructions implemented.
UINT64 Sm3:1; // SM3 instructions implemented.
UINT64 Sm4:1; // SM4 instructions implemented.
UINT64 Dp:1; // UDOT and SDOT Dot product instructions implemented.
UINT64 Fhm:1; // FMLAL and FMLSL instructions implemented.
//
// Bits for features reported by ID_AA64ISAR1_EL1
//
UINT64 DcCvap:1; // Clean data cache by address to point of persistence.
UINT64 DcCvadp:1; // Clean data cache by address to point of deep persistence.
//
// Pointer authentication using QARMA algo.
//
UINT64 ApaBase:1; // HaveEnhancedPAC, HaveEnhancedPAC2 return false
UINT64 ApaEp:1; // HaveEnhancedPAC -> true, HaveEnhancedPAC2 -> false.
UINT64 ApaEp2:1; // HaveEnhancedPAC -> false, HaveEnhancedPAC2 -> true, HaveFPAC -> false, HaveFPACCombined -> false.
UINT64 ApaEp2Fp:1; // HaveEnhancedPAC -> false, HaveEnahancedPAC2 -> true, HaveFPAC -> true, HaveFPACCombined -> false.
UINT64 ApaEp2Fpc:1; // HaveEnhancedPAC -> false, HaveEnahancedPAC2 -> true, HaveFPAC -> true, HaveFPACCombined -> true.
UINT64 Jscvt:1; // FJCVTZS instruction implemented. Support for JS conversion from double to integer.
UINT64 Fcma:1; // Complex number instructions(FCMLA and FCADD) instructions are implemented.
UINT64 RcpcV83:1; // ARMv8.3-RCPC. LDAPR* instructions.
UINT64 RcpcV84:1; // ARMv8.4-RCPC. LDAPUR* and STLUR* instructions.
UINT64 Gpa:1; // Generic code authentication using QARMA algo.
//
// Features reported by CTR_EL0
//
UINT64 L1ipPipt:1; // If L1 Instruction cache is PIPT.
//
// Features reported by DCZID_EL0
//
UINT64 DzPermitted:1; // Data zero instructions permitted.
UINT64 Ssbs:1; // FEAT_SSBS (Speculative Store Bypass Safe): ID_AA64PFR1_EL1.SSBS >= 0b0001
UINT64 SsbsRw:1; // FEAT_SSBS2 (Speculative Store Bypass Safe):ID_AA64PFR1_EL1.SSBS >= 0b0010
UINT64 Reserved49:1; // Unused
UINT64 Reserved50:1; // Unused
UINT64 Reserved51:1; // Unused
UINT64 Reserved52:1; // Unused
UINT64 Csv2:1; // FEAT_CSV2 (Cache Speculation Variant 2): ID_AA64PFR0_EL1.CSV2 >= 0b0001
UINT64 Csv3:1; // FEAT_CSV3 (Cache Speculation Variant 3): ID_AA64PFR0_EL1.CSV3 >= 0b0001
UINT64 Sb:1; // FEAT_SB (Speculation Barrier): ID_AA64ISAR1_EL1.SB >= 0b0001
UINT64 Idc:1; // CTR_EL0.IDC == 0b1
UINT64 Dic:1; // CTR_EL0.DIC == 0b1
UINT64 TlbiOs:1; // FEAT_TLBIOS (TLB invalidate instructions in Outer Shareable domain): ID_AA64ISAR0_EL1.TLB >= 0b0001
UINT64 TlbiOsRange:1; // FEAT_TLBIRANGE (TLB invalidate range instructions): ID_AA64ISAR0_EL1.TLB >= 0b0010
UINT64 FlagsM:1; // ID_AA64ISAR0_EL1.TS >= 0b0001
UINT64 FlagsM2:1; // ID_AA64ISAR0_EL1.TS >= 0b0010
UINT64 Bf16:1; // FEAT_BF16 (AArch64 BFloat16 instructions): ID_AA64ISAR1_EL1.BF16 >= 0b0001
UINT64 Ebf16:1; // FEAT_EBF16 (AArch64 Extended BFloat16 instructions): ID_AA64ISAR1_EL1.BF16 >= 0b0010
};
UINT64 AsUINT64;
} WHV_ARM64_PROCESSOR_FEATURES, WHV_PROCESSOR_FEATURES;
#endif
//
// WHvGetCapability output buffer
//
typedef union WHV_CAPABILITY
{
BOOL HypervisorPresent;
WHV_CAPABILITY_FEATURES Features;
WHV_EXTENDED_VM_EXITS ExtendedVmExits;
WHV_PROCESSOR_VENDOR ProcessorVendor;
WHV_PROCESSOR_FEATURES ProcessorFeatures;
WHV_SYNTHETIC_PROCESSOR_FEATURES_BANKS SyntheticProcessorFeaturesBanks;
UINT8 ProcessorClFlushSize;
UINT64 ProcessorClockFrequency;
WHV_PROCESSOR_FEATURES_BANKS ProcessorFeaturesBanks;
WHV_ADVISE_GPA_RANGE_POPULATE_FLAGS GpaRangePopulateFlags;
WHV_CAPABILITY_PROCESSOR_FREQUENCY_CAP ProcessorFrequencyCap;
WHV_SCHEDULER_FEATURES SchedulerFeatures;
UINT32 PhysicalAddressWidth;
UINT64 NestedFeatureRegister;
#if defined(_AMD64_)
WHV_PROCESSOR_XSAVE_FEATURES ProcessorXsaveFeatures;
UINT64 InterruptClockFrequency;
WHV_PROCESSOR_PERFMON_FEATURES ProcessorPerfmonFeatures;
WHV_X64_MSR_EXIT_BITMAP X64MsrExitBitmap;
UINT64 ExceptionExitBitmap;
#elif defined (_ARM64_)
UINT32 GicLpiIntIdBits;
UINT32 MaxSveVectorLength;
#endif
} WHV_CAPABILITY;
HRESULT
WINAPI
WHvGetCapability(
_In_ WHV_CAPABILITY_CODE CapabilityCode,
_Out_writes_bytes_to_(CapabilityBufferSizeInBytes, *WrittenSizeInBytes) VOID* CapabilityBuffer,
_In_ UINT32 CapabilityBufferSizeInBytes,
_Out_opt_ UINT32* WrittenSizeInBytes
);
Parameters
CapabilityCode
クエリを実行する機能を指定します。
CapabilityBuffer
機能の値を受け取る出力バッファーを指定します。
WHvCapabilityCodeHypervisorPresent機能を使用して、Windowsハイパーバイザーがホスト上で実行されているかどうか、およびプラットフォーム API の機能を使用して VM パーティションを作成できるかどうかを判断できます。
WHvCapabilityCodeFeatures機能は、API 実装がサポートするオプションのプラットフォーム機能のセットをWHV_CAPABILITY_FEATURES値として返します。 各ビットは、特定の機能が使用可能かどうかを示します。呼び出し元は、対応する機能に依存する前に、この機能に対してクエリを実行し、関連するビットを確認する必要があります。
WHvCapabilityCodeExtendedVmExits機能の場合、バッファーには、仮想プロセッサの実行を停止するように構成できる追加の終了理由を指定するビット フィールドが含まれています (WHvRunVirtualProcessorを参照)。
プロセッサ のプロパティに対して返される値は、システム上の物理プロセッサの機能に基づいています (つまり、ルート パーティションの対応するプロパティを照会することによって取得されます)。
CapabilityBufferSizeInBytes
出力バッファーのサイズをバイト単位で指定します。 現在定義されている機能のセットの場合、出力バッファーは 64 ビット値を保持するのに十分な大きさにする必要があります。
WrittenSizeInBytes
CapabilityBufferの書き込みサイズをバイト単位で受け取ります。
戻り値
関数が成功した場合、戻り値は S_OK。
この関数は、不明な機能が要求された場合に WHV_E_UNKNOWN_CAPABILITY を返します。 要求された機能に対応する機能は、システムで使用できないものとして扱う必要があります。
Remarks
プラットフォーム機能は、呼び出し元がハイパーバイザーのプロパティと機能、API 実装、およびアプリケーションが実行されているハードウェア プラットフォームのプロパティと機能を照会するための一般的な方法です。 プラットフォーム API では、これらの機能を使用して、API の拡張機能の可用性と、現在のシステム上のプロセッサがサポートする機能のセットを公開します。 アプリケーションは、対応する API を呼び出すか、VM でプロセッサ機能を使用できるようにする前に、機能の可用性を照会する必要があります。
現在のシステムが Arm64 で Windows Hypervisor Platform をサポートしているかどうかを確認するには、WHvCapabilityCodeFeatures で WHvGetCapability を呼び出し、返された WHV_CAPABILITY_FEATURES 値の Arm64Support ビットをテストします。
Arm64Support ビットは、プラットフォームが使用可能な Arm64 システムでのみ定義および設定されるため、呼び出し元は最初にハイパーバイザーがWHvCapabilityCodeHypervisorPresentに存在することを確認してから、プラットフォーム API を使用する前にArm64Support確認する必要があります。
Requirements
| 要件 | 価値 |
|---|---|
| サポートされている最小Windows | Windows 10バージョン 1803 (x64);Windows 11、バージョン 24H2、ビルド 26100.3915 (Arm64) |
| Header | WinHvPlatform.h |
| 図書館 | WinHvPlatform.lib |
| DLL | WinHvPlatform.dll |
| Architecture | x64、Arm64 |