H Extension
Synopsis
This chapter describes the RISC-V hypervisor extension, which virtualizes the supervisor-level architecture to support the efficient hosting of guest operating systems atop a type-1 or type-2 hypervisor. The hypervisor extension changes supervisor mode into hypervisor-extended supervisor mode (HS-mode, or hypervisor mode for short), where a hypervisor or a hosting-capable operating system runs. The hypervisor extension also adds another stage of address translation, from guest physical addresses to supervisor physical addresses, to virtualize the memory and memory-mapped I/O subsystems for a guest operating system. HS-mode acts the same as S-mode, but with additional instructions and CSRs that control the new stage of address translation and support hosting a guest OS in virtual S-mode (VS-mode). Regular S-mode operating systems can execute without modification either in HS-mode or as VS-mode guests.
In HS-mode, an OS or hypervisor interacts with the machine through the same SBI as an OS normally does from S-mode. An HS-mode hypervisor is expected to implement the SBI for its VS-mode guest.
The hypervisor extension depends on an "I" base integer ISA with 32
x registers (RV32I or RV64I), not RV32E or RV64E, which have only 16 x
registers. CSR mtval must not be read-only zero, and standard
page-based address translation must be supported, either Sv32 for RV32,
or a minimum of Sv39 for RV64.
The hypervisor extension is enabled by setting bit 7 in the misa CSR, which corresponds to the letter H. RISC-V harts that implement the hypervisor extension are encouraged not to hardwire misa[7], so that the extension may be disabled.
|
The baseline privileged architecture is designed to simplify the use of classic virtualization techniques, where a guest OS is run at user-level, as the few privileged instructions can be easily detected and trapped. The hypervisor extension improves virtualization performance by reducing the frequency of these traps. The hypervisor extension has been designed to be efficiently emulable on platforms that do not implement the extension, by running the hypervisor in S-mode and trapping into M-mode for hypervisor CSR accesses and to maintain shadow page tables. The majority of CSR accesses for type-2 hypervisors are valid S-mode accesses so need not be trapped. Hypervisors can support nested virtualization analogously. |
Privilege Modes
The current virtualization mode, denoted V, indicates whether the hart is currently executing in a guest. When V=1, the hart is either in virtual S-mode (VS-mode), or in virtual U-mode (VU-mode) atop a guest OS running in VS-mode. When V=0, the hart is either in M-mode, in HS-mode, or in U-mode atop an OS running in HS-mode. The virtualization mode also indicates whether two-stage address translation is active (V=1) or inactive (V=0). Privilege modes with the hypervisor extension. lists the possible privilege modes of a RISC-V hart with the hypervisor extension.
Virtualization |
Nominal Privilege |
Abbreviation |
Name |
Two-Stage Translation |
0 |
U |
U-mode |
User mode |
Off |
1 |
U |
VU-mode |
Virtual user mode |
On |
For privilege modes U and VU, the nominal privilege mode is U, and for privilege modes HS and VS, the nominal privilege mode is S.
HS-mode is more privileged than VS-mode, and VS-mode is more privileged than VU-mode. VS-mode interrupts are globally disabled when executing in U-mode.
|
This description does not consider the possibility of U-mode or VU-mode interrupts and will be revised if an extension for user-level interrupts is adopted. |
Instructions
The following instructions are defined by this extension:
No synopsis available. |
|
No synopsis available. |
|
No synopsis available. |
|
No synopsis available. |
|
No synopsis available. |
|
No synopsis available. |
|
No synopsis available. |
|
No synopsis available. |
|
No synopsis available. |
|
No synopsis available. |
|
No synopsis available. |
|
No synopsis available. |
|
No synopsis available. |
|
No synopsis available. |
|
No synopsis available. |
Parameters
This extension has the following implementation options:
- GSTAGE_MODE_BARE
-
Type
boolean
Valid Values
boolean
Description
Whether or not writing mode=Bare is supported in the hgatp register.
- HCOUNTENABLE_EN
-
Type
array
Valid Values
32-element array of boolean
Description
Indicates which counters can delegated via hcounteren
An unimplemented counter cannot be specified, i.e., if HPM_COUNTER_EN[3] is false, it would be illegal to set HCOUNTENABLE_EN[3] to true.
- IGNORE_INVALID_VSATP_MODE_WRITES_WHEN_V_EQ_ZERO
-
Type
boolean
Valid Values
boolean
Description
Whether writes from M-mode, U-mode, or S-mode to vsatp with an illegal mode setting are ignored (as they are with satp), or if they are treated as WARL, leading to undpredictable behavior.
- MUTABLE_MISA_H
- NUM_EXTERNAL_GUEST_INTERRUPTS
-
Type
integer
Valid Values
1 to 63
Description
Number of supported virtualized guest interrupts
Corresponds to the
GEILENparameter in the RVI specs - REPORT_ENCODING_IN_VSTVAL_ON_ILLEGAL_INSTRUCTION
- REPORT_GPA_IN_TVAL_ON_INSTRUCTION_GUEST_PAGE_FAULT
-
Type
boolean
Valid Values
boolean
Description
Whether or not GPA >> 2 is written into htval/mtval2 when an instruction guest page fault occurs.
If false, 0 will be written into htval/mtval2 on an instruction guest page fault.
- REPORT_GPA_IN_TVAL_ON_INTERMEDIATE_GUEST_PAGE_FAULT
-
Type
boolean
Valid Values
boolean
Description
Whether or not GPA >> 2 is written into htval/mtval2 when a guest page fault occurs while walking a VS-mode page table.
If false, 0 will be written into htval/mtval2 on an intermediate guest page fault.
- REPORT_GPA_IN_TVAL_ON_LOAD_GUEST_PAGE_FAULT
-
Type
boolean
Valid Values
boolean
Description
Whether or not GPA >> 2 is written into htval/mtval2 when a load guest page fault occurs.
If false, 0 will be written into htval/mtval2 on a load guest page fault.
- REPORT_GPA_IN_TVAL_ON_STORE_AMO_GUEST_PAGE_FAULT
-
Type
boolean
Valid Values
boolean
Description
Whether or not GPA >> 2 is written into htval/mtval2 when a store/amo guest page fault occurs.
If false, 0 will be written into htval/mtval2 on a store/amo guest page fault.
- REPORT_VA_IN_VSTVAL_ON_BREAKPOINT
-
Type
boolean
Valid Values
boolean
Description
- REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_ACCESS_FAULT
- REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_MISALIGNED
-
Type
boolean
Valid Values
boolean
Description
When true, vstval is written with the virtual PC when an instruction fetch is misaligned.
When false, vstval is written with 0 when an instruction fetch is misaligned.
Note that when IALIGN=16 (i.e., when the C or one of the
Zc*extensions are implemented), it is impossible to generate a misaligned fetch, and so this parameter has no effect. - REPORT_VA_IN_VSTVAL_ON_INSTRUCTION_PAGE_FAULT
- REPORT_VA_IN_VSTVAL_ON_LOAD_ACCESS_FAULT
- REPORT_VA_IN_VSTVAL_ON_LOAD_MISALIGNED
- REPORT_VA_IN_VSTVAL_ON_LOAD_PAGE_FAULT
- REPORT_VA_IN_VSTVAL_ON_STORE_AMO_ACCESS_FAULT
- REPORT_VA_IN_VSTVAL_ON_STORE_AMO_MISALIGNED
- REPORT_VA_IN_VSTVAL_ON_STORE_AMO_PAGE_FAULT
- SV32X4_TRANSLATION
-
Type
boolean
Valid Values
boolean
Description
Whether or not Sv32x4 translation mode is supported.
- SV32_VSMODE_TRANSLATION
-
Type
boolean
Valid Values
boolean
Description
Whether or not Sv32 translation is supported in first-stage (VS-stage) translation.
- SV39X4_TRANSLATION
-
Type
boolean
Valid Values
boolean
Description
Whether or not Sv39x4 translation mode is supported.
- SV39_VSMODE_TRANSLATION
-
Type
boolean
Valid Values
boolean
Description
Whether or not Sv39 translation is supported in first-stage (VS-stage) translation.
- SV48X4_TRANSLATION
-
Type
boolean
Valid Values
boolean
Description
Whether or not Sv48x4 translation mode is supported.
- SV48_VSMODE_TRANSLATION
-
Type
boolean
Valid Values
boolean
Description
Whether or not Sv48 translation is supported in first-stage (VS-stage) translation.
- SV57X4_TRANSLATION
-
Type
boolean
Valid Values
boolean
Description
Whether or not Sv57x4 translation mode is supported.
- SV57_VSMODE_TRANSLATION
-
Type
boolean
Valid Values
boolean
Description
Whether or not Sv57 translation is supported in first-stage (VS-stage) translation.
- TINST_VALUE_ON_BREAKPOINT
-
Type
string
Valid Values
[always zero, custom]
Description
Value written into htinst/mtinst on a Breakpoint exception from VU/VS-mode.
Possible values: * "always zero": Always write the value zero * "custom": Write a custom value, which resuls in UNPREDICTABLE
- TINST_VALUE_ON_FINAL_INSTRUCTION_GUEST_PAGE_FAULT
-
Type
string
Valid Values
[always zero, always pseudoinstruction]
Description
Value to write into htval/mtval2 when there is a guest page fault on a final translation.
Possible values: * "always zero": Always write the value zero * "always pseudoinstruction": Always write the pseudoinstruction
- TINST_VALUE_ON_FINAL_LOAD_GUEST_PAGE_FAULT
-
Type
string
Valid Values
[always zero, always pseudoinstruction, always transformed standard instruction, custom]
Description
Value to write into htval/mtval2 when there is a guest page fault on a final translation.
Possible values: * "always zero": Always write the value zero * "always pseudoinstruction": Always write the pseudoinstruction * "always transformed standard instruction": Always write the transformation of the standard instruction encoding * "custom": A custom value, which will cause an UNPREDICTABLE event.
- TINST_VALUE_ON_FINAL_STORE_AMO_GUEST_PAGE_FAULT
-
Type
string
Valid Values
[always zero, always pseudoinstruction, always transformed standard instruction, custom]
Description
Value to write into htval/mtval2 when there is a guest page fault on a final translation.
Possible values: * "always zero": Always write the value zero * "always pseudoinstruction": Always write the pseudoinstruction * "always transformed standard instruction": Always write the transformation of the standard instruction encoding * "custom": A custom value, which will cause an UNPREDICTABLE event.
- TINST_VALUE_ON_INSTRUCTION_ADDRESS_MISALIGNED
-
Type
string
Valid Values
[always zero, custom]
Description
Value written into htinst/mtinst when there is an instruction address misaligned exception.
Possible values: * "always zero": Always write the value zero * "custom": Write a custom value, which resuls in UNPREDICTABLE
- TINST_VALUE_ON_LOAD_ACCESS_FAULT
-
Type
string
Valid Values
[always zero, always transformed standard instruction, custom]
Description
Value written into htinst/mtinst on an AccessFault exception from VU/VS-mode.
Possible values: * "always zero": Always write the value zero * "always transformed standard instruction": Always write a transformed standard instruction as defined by H * "custom": Write a custom value, which resuls in UNPREDICTABLE
- TINST_VALUE_ON_LOAD_ADDRESS_MISALIGNED
-
Type
string
Valid Values
[always zero, always transformed standard instruction, custom]
Description
Value written into htinst/mtinst on a VirtualInstruction exception from VU/VS-mode.
Possible values: * "always zero": Always write the value zero * "always transformed standard instruction": Always write a transformed standard instruction as defined by H * "custom": Write a custom value, which resuls in UNPREDICTABLE
- TINST_VALUE_ON_LOAD_PAGE_FAULT
-
Type
string
Valid Values
[always zero, always transformed standard instruction, custom]
Description
Value written into htinst/mtinst on a LoadPageFault exception from VU/VS-mode.
Possible values: * "always zero": Always write the value zero * "always transformed standard instruction": Always write a transformed standard instruction as defined by H * "custom": Write a custom value, which resuls in UNPREDICTABLE
- TINST_VALUE_ON_MCALL
-
Type
string
Valid Values
[always zero, custom]
Description
Value written into htinst/mtinst on a MCall exception from VU/VS-mode.
Possible values: * "always zero": Always write the value zero * "custom": Write a custom value, which resuls in UNPREDICTABLE
- TINST_VALUE_ON_SCALL
-
Type
string
Valid Values
[always zero, custom]
Description
Value written into htinst/mtinst on a SCall exception from VU/VS-mode.
Possible values: * "always zero": Always write the value zero * "custom": Write a custom value, which resuls in UNPREDICTABLE
- TINST_VALUE_ON_STORE_AMO_ACCESS_FAULT
-
Type
string
Valid Values
[always zero, always transformed standard instruction, custom]
Description
Value written into htinst/mtinst on an AccessFault exception from VU/VS-mode.
Possible values: * "always zero": Always write the value zero * "always transformed standard instruction": Always write a transformed standard instruction as defined by H * "custom": Write a custom value, which resuls in UNPREDICTABLE
- TINST_VALUE_ON_STORE_AMO_ADDRESS_MISALIGNED
-
Type
string
Valid Values
[always zero, always transformed standard instruction, custom]
Description
Value written into htinst/mtinst on a VirtualInstruction exception from VU/VS-mode.
Possible values: * "always zero": Always write the value zero * "always transformed standard instruction": Always write a transformed standard instruction as defined by H * "custom": Write a custom value, which resuls in UNPREDICTABLE
- TINST_VALUE_ON_STORE_AMO_PAGE_FAULT
-
Type
string
Valid Values
[always zero, always transformed standard instruction, custom]
Description
Value written into htinst/mtinst on a StoreAmoPageFault exception from VU/VS-mode.
Possible values: * "always zero": Always write the value zero * "always transformed standard instruction": Always write a transformed standard instruction as defined by H * "custom": Write a custom value, which resuls in UNPREDICTABLE
- TINST_VALUE_ON_UCALL
-
Type
string
Valid Values
[always zero, custom]
Description
Value written into htinst/mtinst on a UCall exception from VU/VS-mode.
Possible values: * "always zero": Always write the value zero * "custom": Write a custom value, which resuls in UNPREDICTABLE
- TINST_VALUE_ON_VIRTUAL_INSTRUCTION
-
Type
string
Valid Values
[always zero, custom]
Description
Value written into htinst/mtinst on a VirtualInstruction exception from VU/VS-mode.
Possible values: * "always zero": Always write the value zero * "custom": Write a custom value, which resuls in UNPREDICTABLE
- TINST_VALUE_ON_VSCALL
-
Type
string
Valid Values
[always zero, custom]
Description
Value written into htinst/mtinst on a VSCall exception from VU/VS-mode.
Possible values: * "always zero": Always write the value zero * "custom": Write a custom value, which resuls in UNPREDICTABLE
- TRAP_ON_ECALL_FROM_VS
-
Type
boolean
Valid Values
boolean
Description
Whether or not an ECALL-from-VS-mode causes a synchronous exception.
The spec states that implementations may handle ECALLs transparently without raising a trap, in which case the EEI must provide a builtin.
- VMID_WIDTH
-
Type
integer
Valid Values
0 to 14
Description
Number of bits supported in hgatp.VMID (i.e., the supported width of a virtual machine ID).
- VSXLEN
-
Type
integer
Valid Values
[32, 64, 3264]
Description
Set of XLENs supported in VS-mode. Can be one of:
-
32: VSXLEN is always 32
-
64: VSXLEN is always 64
-
3264: VSXLEN can be changed (via hstatus.VSXL) between 32 and 64
-
- VS_MODE_ENDIANESS
-
Type
string
Valid Values
[little, big, dynamic]
Description
Endianess of data in VS-mode. Can be one of:
-
little: M-mode data is always little endian
-
big: M-mode data is always big endian
-
dynamic: M-mode data can be either little or big endian, depending on the CSR field hstatus.VSBE
-
- VUXLEN
-
Type
integer
Valid Values
[32, 64, 3264]
Description
Set of XLENs supported in VU-mode. Can be one of:
-
32: VUXLEN is always 32
-
64: VUXLEN is always 64
-
3264: VUXLEN can be changed (via vsstatus.UXL) between 32 and 64
-
- VU_MODE_ENDIANESS
-
Type
string
Valid Values
[little, big, dynamic]
Description
Endianess of data in VU-mode. Can be one of:
-
little: M-mode data is always little endian
-
big: M-mode data is always big endian
-
dynamic: M-mode data can be either little or big endian, depending on the CSR field vsstatus.UBE
-