Hypervisor Top Level Functional Specification February, 2017: Released Version 5.0a Abstract This document is the top-level functional specification (TLFS) of the fifth-generation Microsoft hypervisor. It specifies the hypervisor’s externally-visible behavior. The document assumes familiarity with the goals of the project and the high-level hypervisor architecture. This specification is provided under the Microsoft Open Specification Promise. For further details on the Microsoft Open Specification Promise, please refer to: http://www.microsoft.com/interop/osp/default.mspx. Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in these materials. Except as expressly provided in the Microsoft Open Specification Promise, the furnishing of these materials does not give you any license to these patents, trademarks, copyrights, or other intellectual property. Copyright Information This document is provided “as-is”. Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred. This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes. © 2016 Microsoft. All rights reserved. Microsoft, Windows, Windows NT, Windows Server, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. All other trademarks are property of their respective owners. Contents 1 INTRODUCTION ......................................................................................................................................... 1 1.1 SPECIFICATION STYLE ................................................................................................................................. 1 1.2 RESERVED VALUES ..................................................................................................................................... 1 1.3 REPORT ISSUES ........................................................................................................................................... 1 1.4 GLOSSARY ................................................................................................................................................... 1 1.5 SIMPLE SCALAR TYPES ............................................................................................................................... 2 1.6 HYPERCALL STATUS CODE ......................................................................................................................... 2 1.7 MEMORY ADDRESS SPACE TYPES .............................................................................................................. 2 1.8 STRUCTURES, ENUMERATIONS AND BIT FIELDS ......................................................................................... 3 1.9 ENDIANNESS ................................................................................................................................................ 3 1.10 POINTER NAMING CONVENTION .................................................................................................................. 3 2 FEATURE AND INTERFACE DISCOVERY ............................................................................................. 4 2.1 INTERFACE MECHANISMS ............................................................................................................................ 4 2.2 HYPERVISOR DISCOVERY ............................................................................................................................ 4 2.3 STANDARD HYPERVISOR CPUID LEAVES .................................................................................................. 4 2.4 MICROSOFT HYPERVISOR CPUID LEAVES ................................................................................................. 5 Hypervisor CPUID Leaf Range - 0x40000000 ............................................................................. 5 Hypervisor Vendor-Neutral Interface Identification - 0x40000001 ............................................ 5 Hypervisor System Identity .............................................................................................................. 6 Hypervisor Feature Identification - 0x40000003 .......................................................................... 7 Implementation Recommendations - 0x40000004 ...................................................................... 8 Hypervisor Implementation Limits - 0x40000005 ......................................................................... 9 Implementation Hardware Features - 0x40000006 ..................................................................... 9 Hypervisor CPU Management Features - 0x40000007 ............................................................ 10 Hypervisor SVM Features - 0x40000008 .................................................................................... 10 Nested Hypervisor Feature Identification - 0x40000009 ......................................................... 11 Hypervisor Nested Virtualization Features - 0x4000000A ........................................................ 12 2.5 VERSIONING ............................................................................................................................................... 12 2.6 REPORTING THE GUEST OS IDENTITY ...................................................................................................... 13 Encoding the Guest OS Identity MSR for Open Source Operating Systems ........................ 15 3 HYPERCALL INTERFACE ...................................................................................................................... 16 3.1 HYPERCALL OVERVIEW ............................................................................................................................. 16 3.2 HYPERCALL CLASSES ................................................................................................................................ 16 i Hypervisor Top Level Functional Specification v5.0a 3.3 HYPERCALL CONTINUATION ...................................................................................................................... 17 3.4 HYPERCALL ATOMICITY AND ORDERING ................................................................................................... 17 3.5 LEGAL HYPERCALL ENVIRONMENTS ......................................................................................................... 17 3.6 ALIGNMENT REQUIREMENTS ..................................................................................................................... 18 3.7 HYPERCALL INPUTS ................................................................................................................................... 18 Variable Sized Hypercall Input Headers ..................................................................................... 20 XMM Fast Hypercall Input (formerly “Extended Fast Hypercalls”) .......................................... 21 Volatile Registers ............................................................................................................................ 21 3.8 HYPERCALL OUTPUTS ............................................................................................................................... 22 XMM Fast Hypercall Output .......................................................................................................... 22 3.9 HYPERCALL DETAILS ................................................................................................................................. 23 3.10 HYPERCALL RESTRICTIONS ....................................................................................................................... 24 3.11 HYPERCALL STATUS CODES ..................................................................................................................... 24 Output Parameter Validity on Failed Hypercalls ........................................................................ 25 Ordering of Error Conditions ......................................................................................................... 25 Common Hypercall Status Codes ................................................................................................ 25 3.12 ESTABLISHING THE HYPERCALL INTERFACE ............................................................................................. 26 3.13 EXTENDED HYPERCALL INTERFACE .......................................................................................................... 27 HvExtCallQueryCapabilities .......................................................................................................... 27 4 PARTITION PROPERTIES ...................................................................................................................... 29 4.1 OVERVIEW .................................................................................................................................................. 29 4.2 PARTITION MANAGEMENT DATA TYPES .................................................................................................... 29 Partition IDs ....................................................................................................................................