To ensure proper support for interrupts, two conditions must be met before a hypervisor may allow a guest OS running in a virtual machine to directly control a physical device that sends MSIs: First, each virtual hart must have a guest interrupt file assigned to it, giving each its own apparent IMSIC within the virtual machine. Second, interrupts from the device must be signaled by wire through an APLIC that can translate these interrupts into MSIs, or the system must have an IOMMU that can translate the addresses of MSI memory writes made by the device itself.

If a guest OS directly controls a device capable of sending MSIs, it will naturally configure MSIs at the device with the guest physical addresses the OS sees for the IMSICs of its virtual harts, not knowing that these addresses are only virtual. When the device performs a memory write for an MSI, the destination address of this write must be translated by the IOMMU from the guest physical address assigned by the guest OS into the true physical address of the target guest interrupt file, using a translation table supplied by the hypervisor.

By design, the translation an IOMMU must do for device MSIs is fundamentally no different than the address translation the IOMMU already must perform for other memory accesses from the same device, converting guest physical addresses into true physical addresses. Because each virtual hart is assigned a dedicated, physical guest interrupt file that is indistinguishable from a true supervisor-level interrupt file, no translation is needed for the data of an MSI write, which specifies the interrupt’s identity number in the target interrupt file.

When it is necessary to move a virtual hart from one physical hart to another, if the virtual hart uses a guest interrupt file, the specific guest interrupt file assigned to it must change from the one in use at the old physical hart to a different one at the new physical hart. Because each guest interrupt file is physically tied to a single physical hart, a virtual hart cannot bring its guest interrupt file with it when it moves.

The process of migrating a virtual hart from one guest interrupt file to another is more complex than moving most other state held by the virtual hart. After the destination guest interrupt file has been chosen at the new physical hart, the following steps are recommended:

Resuming execution of the virtual hart at the new physical hart is not recommended until the entire interrupt file has been fully migrated.

Like for supervisor level, the Advanced Interrupt Architecture optionally allows major VS-level interrupts to be configured by software to intermix in priority with VS-level external interrupts. As documented in Interrupts at supervisor level, interrupt priorities for supervisor level are configured by the iprio array accessed indirectly through CSRs siselect and sireg. The siselect addresses for the iprio array registers are 0x30-0x3F.

VS level has its own vsiselect and vsireg, but unlike supervisor level, there are no registers at vsiselect addresses 0x30-0x3F. When vsiselect has a value in the range 0x30-0x3F, an attempt from VS-mode to access sireg (really vsireg) causes a virtual instruction exception. To give a virtual hart the illusion of an array of iprio registers accessed through siselect and sireg, a hypervisor must emulate the VS-level iprio array when accesses to sireg from VS-mode cause virtual instruction traps.

Instead of a physical VS-level iprio array, a separate hardware mechanism is provided for configuring the priorities of a subset of interrupts for VS level, using hypervisor CSRs hviprio1 and hviprio2. The subset of major interrupt numbers whose priority may be configured in hardware are these:

For interrupts directed to VS level, software-configurable priorities are not supported in hardware for standard local interrupts in the range 32-48.

Registers hviprio1 and hviprio2 have these formats:

hviprio1:

hviprio2:

Each priority number in hviprio1 and hviprio2 is a WARL unsigned integer field that is either read-only zero or implements a minimum of IPRIOLEN bits or 6 bits, whichever is larger, and preferably all 8 bits. Implementations may freely choose which priority number fields are read-only zeros, but all other fields must implement the same number of integer bits. A minimal implementation of these CSRs has them both be read-only zeros.

A hypervisor can choose to employ registers hviprio1 and hviprio2 when emulating the (virtual) supervisor-level iprio array accessed indirectly through siselect and sireg (really vsiselect and vsireg) for a virtual hart. For interrupts not in the subset supported by hviprio1 and hviprio2, the priority number bytes in the emulated iprio array can be read-only zeros.

If a hypervisor really must emulate configurability of priority for interrupts beyond the subset supported by hviprio1 and hviprio2, it can do so with extra effort by setting bit VTI of CSR hvictl, described in the next subsection.

Assuming a virtual hart does not need configurable priority for major interrupts beyond the subset supported in hardware by hviprio1 and hviprio2, a hypervisor can assert interrupts to the virtual hart using CSRs hvien (Hypervisor Virtual-Interrupt-Enable) and hvip (Hypervisor Virtual-Interrupt-Pending bits). These CSRs affect interrupts for VS level much the same way that mvien and mvip do for supervisor level, as explained in Interrupt filtering and virtual interrupts for supervisor level.

Each bit of registers hvien and hvip corresponds with an interrupt number in the range 0-63. Bits 12:0 of hvien are reserved and must be read-only zeros, while bits 12:0 of hvip are defined by the H extension. Specifically, bits 10, 6, and 2 of hvip are writable bits that correspond to VS-level external interrupts (VSEIP), VS-level timer interrupts (VSTIP), and VS-level software interrupts (VSSIP), respectively.

The following applies only to the CSR bits for interrupt numbers 13-63: When a bit in hideleg is one, then the same bit position in vsip is an alias for the corresponding bit in sip. Else, when a bit in hideleg is zero and the matching bit in hvien is one, the same bit position in vsip is an alias for the corresponding bit in hvip. A bit in vsip is read-only zero when the corresponding bits in hideleg and hvien are both zero. The combined effects of hideleg and hvien on vsip and vsie are summarized in Table 1.

For interrupt numbers 13-63, a bit in vsie is writable if and only if the corresponding bit is set in either hideleg or hvien. When an interrupt is delegated by hideleg, the writable bit in vsie is an alias of the corresponding bit in sie; else it is an independent writable bit. The H extension specifies when bits 12:0 of vsie are aliases of bits in hie. As usual, bits that are not writable in vsie must be read-only zeros.

If a bit of hideleg is zero and the corresponding bit in hvien is changed from zero to one, then the value of the matching bit in vsie becomes UNSPECIFIED. Likewise, if a bit of hvien is one and the corresponding bit in hideleg is changed from one to zero, the value of the matching bit in vsie again becomes UNSPECIFIED.

For interrupt numbers 13-63, implementations may freely choose which bits of hvien are writable and which bits are read-only zero or one. If such a bit in hvien is read-only zero (preventing the virtual interrupt from being enabled), the same bit should be read-only zero in hvip. All other bits for interrupts 13-63 must be writable in hvip.

CSR hvictl (Hypervisor Virtual Interrupt Control) provides further flexibility for injecting interrupts into VS level in situations not fully supported by the facilities described thus far, but only with more active involvement of the hypervisor. A hypervisor must use hvictl for any of the following:

The format of hvictl is:

All other bits of hvictl are reserved and read as zeros.

When bit VTI (Virtual Trap Interrupt control) = 1, attempts from VS-mode to explicitly access CSRs sip and sie (or, for RV32 only, siph and sieh) cause a virtual instruction exception. Furthermore, for any given CSR, if there is some circumstance in which a write to the register may cause a bit of vsip to change from one to zero, excluding bit 9 for external interrupts (SEIP), then when VTI = 1, a virtual instruction exception is raised also for any attempt by the guest to write this register. Both the value being written to the CSR and the value of vsip (before or after) are ignored for determining whether to raise the exception. (Hence a write would not actually need to change a bit of vsip from one to zero for the exception to be raised.) In particular, if register vstimecmp is implemented (from extension Sstc), then attempts from VS-mode to write to stimecmp (or, for RV32 only, stimecmph) cause a virtual instruction exception when VTI = 1.

All hvictl fields together can affect the value of CSR vstopi (Virtual Supervisor Top Interrupt) and therefore the interrupt identity reported in vscause when an interrupt traps to VS-mode. IID is a WARL unsigned integer field with at least 6 implemented bits, while IPRIO is always the full 8 bits. If bits are implemented for IID, then all values 0 through are supported, and a write to hvictl sets IID equal to bits ( ):16 of the value written.

For a virtual interrupt specified for VS level by hvictl, if VTI = 1 and , field DPR (Default Priority Rank) determines the interrupt’s presumed default priority order relative to a (virtual) supervisor external interrupt (SEI), major identity 9, as follows:

When hvictl.IID = 9, DPR is ignored.

Read-only CSR vstopi is VSXLEN bits wide and has the same format as stopi:

vstopi returns information about the highest-priority interrupt for VS level, found from among these candidates (prefixed by + signs):

In the list above, all "supervisor" external interrupts are virtual, directed to VS level, having major code 9 at VS level.

When no interrupt candidates satisfy the conditions of the list above, vstopi is zero. Else, vstopi fields IID and IPRIO are determined by the highest-priority interrupt from among the candidates. The usual priority order for supervisor level applies, as specified by Effect of the supervisor-level iprio array on the priorities of interrupts taken in S-mode, except that priority numbers are taken from the candidate list above, not from the supervisor-level iprio array. Ties in nominal priority are broken as usual by the default priority order from The standard major interrupt codes, listed in default priority order, unless hvictl fields VTI = 1 and (last item in the candidate list above), in which case default priority order is determined solely by hvictl.DPR. If bit IPRIOM (IPRIO Mode) of hvictl is zero, IPRIO in vstopi is 1; else, if the priority number for the highest-priority candidate is within the range 1 to 255, IPRIO is that value; else, IPRIO is set to either 0 or 255 in the manner documented for stopi in Supervisor top interrupt CSR (stopi).

The Advanced Interrupt Architecture modifies the H extension such that an interrupt is pending at VS level if and only if vstopi is not zero. CSRs vsip and vsie do not by themselves determine whether a VS-level interrupt is pending, though they may do so indirectly through their effect on vstopi.

Whenever vstopi is not zero, if either the current privilege mode is VS-mode and the SIE bit in CSR vsstatus is one, or the current privilege mode is VU-mode, a trap is taken to VS-mode for the interrupt indicated by field IID of vstopi.

The Exception Code field of vscause must implement at least as many bits as needed to represent the largest value that field IID of vstopi can have for the given hart.