Protected Execution Facility

Introduction

Protected Execution Facility (PEF) is an architectural change forPOWER 9 that enables Secure Virtual Machines (SVMs). DD2.3 chips(PVR=0x004e1203) or greater will be PEF-capable. A new ISA releasewill include the PEF RFC02487 changes.

When enabled, PEF adds a new higher privileged mode, called Ultravisormode, to POWER architecture. Along with the new mode there is newfirmware called the Protected Execution Ultravisor (or Ultravisorfor short). Ultravisor mode is the highest privileged mode in POWERarchitecture.

Privilege States
Problem
Supervisor
Hypervisor
Ultravisor

PEF protects SVMs from the hypervisor, privileged users, and otherVMs in the system. SVMs are protected while at rest and can only beexecuted by an authorized machine. All virtual machines utilizehypervisor services. The Ultravisor filters calls between the SVMsand the hypervisor to assure that information does not accidentallyleak. All hypercalls except H_RANDOM are reflected to the hypervisor.H_RANDOM is not reflected to prevent the hypervisor from influencingrandom values in the SVM.

To support this there is a refactoring of the ownership of resourcesin the CPU. Some of the resources which were previously hypervisorprivileged are now ultravisor privileged.

Hardware

The hardware changes include the following:

  • There is a new bit in the MSR that determines whether the currentprocess is running in secure mode, MSR(S) bit 41. MSR(S)=1, processis in secure mode, MSR(s)=0 process is in normal mode.

  • The MSR(S) bit can only be set by the Ultravisor.

  • HRFID cannot be used to set the MSR(S) bit. If the hypervisor needsto return to a SVM it must use an ultracall. It can determine ifthe VM it is returning to is secure.

  • There is a new Ultravisor privileged register, SMFCTRL, which has anenable/disable bit SMFCTRL(E).

  • The privilege of a process is now determined by three MSR bits,MSR(S, HV, PR). In each of the tables below the modes are listedfrom least privilege to highest privilege. The higher privilegemodes can access all the resources of the lower privilege modes.

    Secure Mode MSR Settings

    SHVPRPrivilege
    101Problem
    100Privileged(OS)
    110Ultravisor
    111Reserved

    Normal Mode MSR Settings

    SHVPRPrivilege
    001Problem
    000Privileged(OS)
    010Hypervisor
    011Problem (Host)

  • Memory is partitioned into secure and normal memory. Only processesthat are running in secure mode can access secure memory.

  • The hardware does not allow anything that is not running secure toaccess secure memory. This means that the Hypervisor cannot accessthe memory of the SVM without using an ultracall (asking theUltravisor). The Ultravisor will only allow the hypervisor to seethe SVM memory encrypted.

  • I/O systems are not allowed to directly address secure memory. Thislimits the SVMs to virtual I/O only.

  • The architecture allows the SVM to share pages of memory with thehypervisor that are not protected with encryption. However, thissharing must be initiated by the SVM.

  • When a process is running in secure mode all hypercalls(syscall lev=1) go to the Ultravisor.

  • When a process is in secure mode all interrupts go to theUltravisor.

  • The following resources have become Ultravisor privileged andrequire an Ultravisor interface to manipulate:

    • Processor configurations registers (SCOMs).
    • Stop state information.
    • The debug registers CIABR, DAWR, and DAWRX when SMFCTRL(D) is set.If SMFCTRL(D) is not set they do not work in secure mode. When set,reading and writing requires an Ultravisor call, otherwise thatwill cause a Hypervisor Emulation Assistance interrupt.
    • PTCR and partition table entries (partition table is in securememory). An attempt to write to PTCR will cause a HypervisorEmulation Assitance interrupt.
    • LDBAR (LD Base Address Register) and IMC (In-Memory Collection)non-architected registers. An attempt to write to them will cause aHypervisor Emulation Assistance interrupt.
    • Paging for an SVM, sharing of memory with Hypervisor for an SVM.(Including Virtual Processor Area (VPA) and virtual I/O).

Software/Microcode

The software changes include:

  • SVMs are created from normal VM using (open source) tooling suppliedby IBM.
  • All SVMs start as normal VMs and utilize an ultracall, UV_ESM(Enter Secure Mode), to make the transition.
  • When the UV_ESM ultracall is made the Ultravisor copies the VM intosecure memory, decrypts the verification information, and checks theintegrity of the SVM. If the integrity check passes the Ultravisorpasses control in secure mode.
  • The verification information includes the pass phrase for theencrypted disk associated with the SVM. This pass phrase is givento the SVM when requested.
  • The Ultravisor is not involved in protecting the encrypted disk ofthe SVM while at rest.
  • For external interrupts the Ultravisor saves the state of the SVM,and reflects the interrupt to the hypervisor for processing.For hypercalls, the Ultravisor inserts neutral state into allregisters not needed for the hypercall then reflects the call tothe hypervisor for processing. The H_RANDOM hypercall is performedby the Ultravisor and not reflected.
  • For virtual I/O to work bounce buffering must be done.
  • The Ultravisor uses AES (IAPM) for protection of SVM memory. IAPMis a mode of AES that provides integrity and secrecy concurrently.
  • The movement of data between normal and secure pages is coordinatedwith the Ultravisor by a new HMM plug-in in the Hypervisor.

The Ultravisor offers new services to the hypervisor and SVMs. Theseare accessed through ultracalls.

Terminology

  • Hypercalls: special system calls used to request services fromHypervisor.
  • Normal memory: Memory that is accessible to Hypervisor.
  • Normal page: Page backed by normal memory and available toHypervisor.
  • Shared page: A page backed by normal memory and available to boththe Hypervisor/QEMU and the SVM (i.e page has mappings in SVM andHypervisor/QEMU).
  • Secure memory: Memory that is accessible only to Ultravisor andSVMs.
  • Secure page: Page backed by secure memory and only available toUltravisor and SVM.
  • SVM: Secure Virtual Machine.
  • Ultracalls: special system calls used to request services fromUltravisor.

Ultravisor calls API

This section describes Ultravisor calls (ultracalls) needed tosupport Secure Virtual Machines (SVM)s and Paravirtualized KVM. Theultracalls allow the SVMs and Hypervisor to request services from theUltravisor such as accessing a register or memory region that can onlybe accessed when running in Ultravisor-privileged mode.

The specific service needed from an ultracall is specified in registerR3 (the first parameter to the ultracall). Other parameters to theultracall, if any, are specified in registers R4 through R12.

Return value of all ultracalls is in register R3. Other output valuesfrom the ultracall, if any, are returned in registers R4 through R12.The only exception to this register usage is theUV_RETURNultracall described below.

Each ultracall returns specific error codes, applicable in the contextof the ultracall. However, like with the PowerPC Architecture PlatformReference (PAPR), if no specific error code is defined for aparticular situation, then the ultracall will fallback to an erroneousparameter-position based code. i.e U_PARAMETER, U_P2, U_P3 etcdepending on the ultracall parameter that may have caused the error.

Some ultracalls involve transferring a page of data between Ultravisorand Hypervisor. Secure pages that are transferred from secure memoryto normal memory may be encrypted using dynamically generated keys.When the secure pages are transferred back to secure memory, they maybe decrypted using the same dynamically generated keys. Generation andmanagement of these keys will be covered in a separate document.

For now this only covers ultracalls currently implemented and beingused by Hypervisor and SVMs but others can be added here when itmakes sense.

The full specification for all hypercalls/ultracalls will eventuallybe made available in the public/OpenPower version of the PAPRspecification.

Note

If PEF is not enabled, the ultracalls will be redirected to theHypervisor which must handle/fail the calls.

Ultracalls used by Hypervisor

This section describes the virtual memory management ultracalls usedby the Hypervisor to manage SVMs.

UV_PAGE_OUT

Encrypt and move the contents of a page from secure memory to normalmemory.
Syntax
uint64_tultracall(constuint64_tUV_PAGE_OUT,uint16_tlpid,/* LPAR ID */uint64_tdest_ra,/* real address of destination page */uint64_tsrc_gpa,/* source guest-physical-address */uint8_tflags,/* flags */uint64_torder)/* page size order */
Return values

One of the following values:

  • U_SUCCESS on success.
  • U_PARAMETER iflpid is invalid.
  • U_P2 ifdest_ra is invalid.
  • U_P3 if thesrc_gpa address is invalid.
  • U_P4 if any bit in theflags is unrecognized
  • U_P5 if theorder parameter is unsupported.
  • U_FUNCTION if functionality is not supported.
  • U_BUSY if page cannot be currently paged-out.
Description

Encrypt the contents of a secure-page and make it available toHypervisor in a normal page.

By default, the source page is unmapped from the SVM’s partition-scoped page table. But the Hypervisor can provide a hint to theUltravisor to retain the page mapping by setting theUV_SNAPSHOTflag inflags parameter.

If the source page is already a shared page the call returnsU_SUCCESS, without doing anything.

Use cases
  1. QEMU attempts to access an address belonging to the SVM but thepage frame for that address is not mapped into QEMU’s addressspace. In this case, the Hypervisor will allocate a page frame,map it into QEMU’s address space and issue theUV_PAGE_OUTcall to retrieve the encrypted contents of the page.
  2. When Ultravisor runs low on secure memory and it needs to page-outan LRU page. In this case, Ultravisor will issue theH_SVM_PAGE_OUT hypercall to the Hypervisor. The Hypervisor willthen allocate a normal page and issue theUV_PAGE_OUT ultracalland the Ultravisor will encrypt and move the contents of the securepage into the normal page.
  3. When Hypervisor accesses SVM data, the Hypervisor requests theUltravisor to transfer the corresponding page into a insecure page,which the Hypervisor can access. The data in the normal page willbe encrypted though.

UV_PAGE_IN

Move the contents of a page from normal memory to secure memory.
Syntax
uint64_tultracall(constuint64_tUV_PAGE_IN,uint16_tlpid,/* the LPAR ID */uint64_tsrc_ra,/* source real address of page */uint64_tdest_gpa,/* destination guest physical address */uint64_tflags,/* flags */uint64_torder)/* page size order */
Return values

One of the following values:

  • U_SUCCESS on success.
  • U_BUSY if page cannot be currently paged-in.
  • U_FUNCTION if functionality is not supported
  • U_PARAMETER iflpid is invalid.
  • U_P2 ifsrc_ra is invalid.
  • U_P3 if thedest_gpa address is invalid.
  • U_P4 if any bit in theflags is unrecognized
  • U_P5 if theorder parameter is unsupported.
Description

Move the contents of the page identified bysrc_ra from normalmemory to secure memory and map it to the guest physical addressdest_gpa.

Ifdest_gpa refers to a shared address, map the page into thepartition-scoped page-table of the SVM. Ifdest_gpa is not shared,copy the contents of the page into the corresponding secure page.Depending on the context, decrypt the page before being copied.

The caller provides the attributes of the page through theflagsparameter. Valid values forflags are:

  • CACHE_INHIBITED
  • CACHE_ENABLED
  • WRITE_PROTECTION

The Hypervisor must pin the page in memory before makingUV_PAGE_IN ultracall.

Use cases
  1. When a normal VM switches to secure mode, all its pages residingin normal memory, are moved into secure memory.
  2. When an SVM requests to share a page with Hypervisor the Hypervisorallocates a page and informs the Ultravisor.
  3. When an SVM accesses a secure page that has been paged-out,Ultravisor invokes the Hypervisor to locate the page. Afterlocating the page, the Hypervisor uses UV_PAGE_IN to make thepage available to Ultravisor.

UV_PAGE_INVAL

Invalidate the Ultravisor mapping of a page.
Syntax
uint64_tultracall(constuint64_tUV_PAGE_INVAL,uint16_tlpid,/* the LPAR ID */uint64_tguest_pa,/* destination guest-physical-address */uint64_torder)/* page size order */
Return values

One of the following values:

  • U_SUCCESS on success.
  • U_PARAMETER iflpid is invalid.
  • U_P2 ifguest_pa is invalid (or corresponds to a secure
    page mapping).
  • U_P3 if theorder is invalid.
  • U_FUNCTION if functionality is not supported.
  • U_BUSY if page cannot be currently invalidated.
Description
This ultracall informs Ultravisor that the page mapping in Hypervisorcorresponding to the given guest physical address has been invalidatedand that the Ultravisor should not access the page. If the specifiedguest_pa corresponds to a secure page, Ultravisor will ignore theattempt to invalidate the page and return U_P2.
Use cases
  1. When a shared page is unmapped from the QEMU’s page table, possiblybecause it is paged-out to disk, Ultravisor needs to know that thepage should not be accessed from its side too.

UV_WRITE_PATE

Validate and write the partition table entry (PATE) for a givenpartition.
Syntax
uint64_tultracall(constuint64_tUV_WRITE_PATE,uint32_tlpid,/* the LPAR ID */uint64_tdw0/* the first double word to write */uint64_tdw1)/* the second double word to write */
Return values

One of the following values:

  • U_SUCCESS on success.
  • U_BUSY if PATE cannot be currently written to.
  • U_FUNCTION if functionality is not supported.
  • U_PARAMETER iflpid is invalid.
  • U_P2 ifdw0 is invalid.
  • U_P3 if thedw1 address is invalid.
  • U_PERMISSION if the Hypervisor is attempting to change the PATE
    of a secure virtual machine or if called from acontext other than Hypervisor.
Description
Validate and write a LPID and its partition-table-entry for the givenLPID. If the LPID is already allocated and initialized, this callresults in changing the partition table entry.
Use cases
  1. The Partition table resides in Secure memory and its entries,called PATE (Partition Table Entries), point to the partition-scoped page tables for the Hypervisor as well as each of thevirtual machines (both secure and normal). The Hypervisoroperates in partition 0 and its partition-scoped page tablesreside in normal memory.
  2. This ultracall allows the Hypervisor to register the partition-scoped and process-scoped page table entries for the Hypervisorand other partitions (virtual machines) with the Ultravisor.
  3. If the value of the PATE for an existing partition (VM) changes,the TLB cache for the partition is flushed.
  4. The Hypervisor is responsible for allocating LPID. The LPID andits PATE entry are registered together. The Hypervisor managesthe PATE entries for a normal VM and can change the PATE entryanytime. Ultravisor manages the PATE entries for an SVM andHypervisor is not allowed to modify them.

UV_RETURN

Return control from the Hypervisor back to the Ultravisor afterprocessing an hypercall or interrupt that was forwarded (akareflected) to the Hypervisor.
Syntax
uint64_tultracall(constuint64_tUV_RETURN)
Return values
This call never returns to Hypervisor on success. It returnsU_INVALID if ultracall is not made from a Hypervisor context.
Description

When an SVM makes an hypercall or incurs some other exception, theUltravisor usually forwards (akareflects) the exceptions to theHypervisor. After processing the exception, Hypervisor uses theUV_RETURN ultracall to return control back to the SVM.

The expected register state on entry to this ultracall is:

  • Non-volatile registers are restored to their original values.
  • If returning from an hypercall, register R0 contains the returnvalue (unlike other ultracalls) and, registers R4 through R12contain any output values of the hypercall.
  • R3 contains the ultracall number, i.e UV_RETURN.
  • If returning with a synthesized interrupt, R2 contains thesynthesized interrupt number.
Use cases
  1. Ultravisor relies on the Hypervisor to provide several services tothe SVM such as processing hypercall and other exceptions. Afterprocessing the exception, Hypervisor uses UV_RETURN to returncontrol back to the Ultravisor.
  2. Hypervisor has to use this ultracall to return control to the SVM.

UV_REGISTER_MEM_SLOT

Register an SVM address-range with specified properties.
Syntax
uint64_tultracall(constuint64_tUV_REGISTER_MEM_SLOT,uint64_tlpid,/* LPAR ID of the SVM */uint64_tstart_gpa,/* start guest physical address */uint64_tsize,/* size of address range in bytes */uint64_tflags/* reserved for future expansion */uint16_tslotid)/* slot identifier */
Return values

One of the following values:

  • U_SUCCESS on success.
  • U_PARAMETER iflpid is invalid.
  • U_P2 ifstart_gpa is invalid.
  • U_P3 ifsize is invalid.
  • U_P4 if any bit in theflags is unrecognized.
  • U_P5 if theslotid parameter is unsupported.
  • U_PERMISSION if called from context other than Hypervisor.
  • U_FUNCTION if functionality is not supported.
Description
Register a memory range for an SVM. The memory range starts at theguest physical addressstart_gpa and issize bytes long.
Use cases
  1. When a virtual machine goes secure, all the memory slots managed bythe Hypervisor move into secure memory. The Hypervisor iteratesthrough each of memory slots, and registers the slot withUltravisor. Hypervisor may discard some slots such as those usedfor firmware (SLOF).
  2. When new memory is hot-plugged, a new memory slot gets registered.

UV_UNREGISTER_MEM_SLOT

Unregister an SVM address-range that was previously registered usingUV_REGISTER_MEM_SLOT.
Syntax
uint64_tultracall(constuint64_tUV_UNREGISTER_MEM_SLOT,uint64_tlpid,/* LPAR ID of the SVM */uint64_tslotid)/* reservation slotid */
Return values

One of the following values:

  • U_SUCCESS on success.
  • U_FUNCTION if functionality is not supported.
  • U_PARAMETER iflpid is invalid.
  • U_P2 ifslotid is invalid.
  • U_PERMISSION if called from context other than Hypervisor.
Description
Release the memory slot identified byslotid and free anyresources allocated towards the reservation.
Use cases
  1. Memory hot-remove.

UV_SVM_TERMINATE

Terminate an SVM and release its resources.
Syntax
uint64_tultracall(constuint64_tUV_SVM_TERMINATE,uint64_tlpid,/* LPAR ID of the SVM */)
Return values

One of the following values:

  • U_SUCCESS on success.
  • U_FUNCTION if functionality is not supported.
  • U_PARAMETER iflpid is invalid.
  • U_INVALID if VM is not secure.
  • U_PERMISSION if not called from a Hypervisor context.
Description
Terminate an SVM and release all its resources.
Use cases
  1. Called by Hypervisor when terminating an SVM.

Ultracalls used by SVM

UV_SHARE_PAGE

Share a set of guest physical pages with the Hypervisor.
Syntax
uint64_tultracall(constuint64_tUV_SHARE_PAGE,uint64_tgfn,/* guest page frame number */uint64_tnum)/* number of pages of size PAGE_SIZE */
Return values

One of the following values:

  • U_SUCCESS on success.
  • U_FUNCTION if functionality is not supported.
  • U_INVALID if the VM is not secure.
  • U_PARAMETER ifgfn is invalid.
  • U_P2 ifnum is invalid.
Description

Share thenum pages starting at guest physical frame numbergfnwith the Hypervisor. Assume page size is PAGE_SIZE bytes. Zero thepages before returning.

If the address is already backed by a secure page, unmap the page andback it with an insecure page, with the help of the Hypervisor. If itis not backed by any page yet, mark the PTE as insecure and back itwith an insecure page when the address is accessed. If it is alreadybacked by an insecure page, zero the page and return.

Use cases
  1. The Hypervisor cannot access the SVM pages since they are backed bysecure pages. Hence an SVM must explicitly request Ultravisor forpages it can share with Hypervisor.
  2. Shared pages are needed to support virtio and Virtual Processor Area(VPA) in SVMs.

UV_UNSHARE_PAGE

Restore a shared SVM page to its initial state.
Syntax
uint64_tultracall(constuint64_tUV_UNSHARE_PAGE,uint64_tgfn,/* guest page frame number */uint73num)/* number of pages of size PAGE_SIZE*/
Return values

One of the following values:

  • U_SUCCESS on success.
  • U_FUNCTION if functionality is not supported.
  • U_INVALID if VM is not secure.
  • U_PARAMETER ifgfn is invalid.
  • U_P2 ifnum is invalid.
Description

Stop sharingnum pages starting atgfn with the Hypervisor.Assume that the page size is PAGE_SIZE. Zero the pages beforereturning.

If the address is already backed by an insecure page, unmap the pageand back it with a secure page. Inform the Hypervisor to releasereference to its shared page. If the address is not backed by a pageyet, mark the PTE as secure and back it with a secure page when thataddress is accessed. If it is already backed by an secure page zerothe page and return.

Use cases
  1. The SVM may decide to unshare a page from the Hypervisor.

UV_UNSHARE_ALL_PAGES

Unshare all pages the SVM has shared with Hypervisor.
Syntax
uint64_tultracall(constuint64_tUV_UNSHARE_ALL_PAGES)
Return values

One of the following values:

  • U_SUCCESS on success.
  • U_FUNCTION if functionality is not supported.
  • U_INVAL if VM is not secure.
Description
Unshare all shared pages from the Hypervisor. All unshared pages arezeroed on return. Only pages explicitly shared by the SVM with theHypervisor (using UV_SHARE_PAGE ultracall) are unshared. Ultravisormay internally share some pages with the Hypervisor without explicitrequest from the SVM. These pages will not be unshared by thisultracall.
Use cases
  1. This call is needed whenkexec is used to boot a differentkernel. It may also be needed during SVM reset.

UV_ESM

Secure the virtual machine (enter secure mode).
Syntax
uint64_tultracall(constuint64_tUV_ESM,uint64_tesm_blob_addr,/* location of the ESM blob */unint64_tfdt)/* Flattened device tree */
Return values

One of the following values:

  • U_SUCCESS on success (including if VM is already secure).
  • U_FUNCTION if functionality is not supported.
  • U_INVALID if VM is not secure.
  • U_PARAMETER ifesm_blob_addr is invalid.
  • U_P2 iffdt is invalid.
  • U_PERMISSION if any integrity checks fail.
  • U_RETRY insufficient memory to create SVM.
  • U_NO_KEY symmetric key unavailable.
Description
Secure the virtual machine. On successful completion, returncontrol to the virtual machine at the address specified in theESM blob.
Use cases
  1. A normal virtual machine can choose to switch to a secure mode.

Hypervisor Calls API

This document describes the Hypervisor calls (hypercalls) that areneeded to support the Ultravisor. Hypercalls are services provided bythe Hypervisor to virtual machines and Ultravisor.

Register usage for these hypercalls is identical to that of the otherhypercalls defined in the Power Architecture Platform Reference (PAPR)document. i.e on input, register R3 identifies the specific servicethat is being requested and registers R4 through R11 containadditional parameters to the hypercall, if any. On output, registerR3 contains the return value and registers R4 through R9 contain anyother output values from the hypercall.

This document only covers hypercalls currently implemented/plannedfor Ultravisor usage but others can be added here when it makes sense.

The full specification for all hypercalls/ultracalls will eventuallybe made available in the public/OpenPower version of the PAPRspecification.

Hypervisor calls to support Ultravisor

Following are the set of hypercalls needed to support Ultravisor.

H_SVM_INIT_START

Begin the process of converting a normal virtual machine into an SVM.
Syntax
uint64_thypercall(constuint64_tH_SVM_INIT_START)
Return values

One of the following values:

  • H_SUCCESS on success.
  • H_STATE if the VM is not in a position to switch to secure.
Description
Initiate the process of securing a virtual machine. This involvescoordinating with the Ultravisor, using ultracalls, to allocateresources in the Ultravisor for the new SVM, transferring the VM’spages from normal to secure memory etc. When the process iscompleted, Ultravisor issues the H_SVM_INIT_DONE hypercall.
Use cases
  1. Ultravisor uses this hypercall to inform Hypervisor that a VMhas initiated the process of switching to secure mode.

H_SVM_INIT_DONE

Complete the process of securing an SVM.
Syntax
uint64_thypercall(constuint64_tH_SVM_INIT_DONE)
Return values

One of the following values:

  • H_SUCCESS on success.
  • H_UNSUPPORTED if called from the wrong context (e.g.
    from an SVM or before an H_SVM_INIT_STARThypercall).
  • H_STATE if the hypervisor could not successfully
    transition the VM to Secure VM.
Description
Complete the process of securing a virtual machine. This call mustbe made after a prior call toH_SVM_INIT_START hypercall.
Use cases
On successfully securing a virtual machine, the Ultravisor informsHypervisor about it. Hypervisor can use this call to finish settingup its internal state for this virtual machine.

H_SVM_INIT_ABORT

Abort the process of securing an SVM.
Syntax
uint64_thypercall(constuint64_tH_SVM_INIT_ABORT)
Return values

One of the following values:

  • H_PARAMETER on successfully cleaning up the state,
    Hypervisor will return this value to theguest, to indicate that the underlyingUV_ESM ultracall failed.
  • H_STATE if called after a VM has gone secure (i.e
    H_SVM_INIT_DONE hypercall was successful).
  • H_UNSUPPORTED if called from a wrong context (e.g. from a
    normal VM).
Description

Abort the process of securing a virtual machine. This call mustbe made after a prior call toH_SVM_INIT_START hypercall andbefore a call toH_SVM_INIT_DONE.

On entry into this hypercall the non-volatile GPRs and FPRs areexpected to contain the values they had at the time the VM issuedthe UV_ESM ultracall. FurtherSRR0 is expected to contain theaddress of the instruction after theUV_ESM ultracall andSRR1the MSR value with which to return to the VM.

This hypercall will cleanup any partial state that was established forthe VM since the priorH_SVM_INIT_START hypercall, including pagingout pages that were paged-into secure memory, and issue theUV_SVM_TERMINATE ultracall to terminate the VM.

After the partial state is cleaned up, control returns to the VM(not Ultravisor), at the address specified inSRR0 with theMSR values set to the value inSRR1.

Use cases
If after a successful call toH_SVM_INIT_START, the Ultravisorencounters an error while securing a virtual machine, either dueto lack of resources or because the VM’s security information couldnot be validated, Ultravisor informs the Hypervisor about it.Hypervisor should use this call to clean up any internal state forthis virtual machine and return to the VM.

H_SVM_PAGE_IN

Move the contents of a page from normal memory to secure memory.
Syntax
uint64_thypercall(constuint64_tH_SVM_PAGE_IN,uint64_tguest_pa,/* guest-physical-address */uint64_tflags,/* flags */uint64_torder)/* page size order */
Return values

One of the following values:

  • H_SUCCESS on success.
  • H_PARAMETER ifguest_pa is invalid.
  • H_P2 ifflags is invalid.
  • H_P3 iforder of page is invalid.
Description

Retrieve the content of the page, belonging to the VM at the specifiedguest physical address.

Only valid value(s) inflags are:

  • H_PAGE_IN_SHARED which indicates that the page is to be sharedwith the Ultravisor.
  • H_PAGE_IN_NONSHARED indicates that the UV is not anymoreinterested in the page. Applicable if the page is a shared page.

Theorder parameter must correspond to the configured page size.

Use cases
  1. When a normal VM becomes a secure VM (using the UV_ESM ultracall),the Ultravisor uses this hypercall to move contents of each page ofthe VM from normal memory to secure memory.
  2. Ultravisor uses this hypercall to ask Hypervisor to provide a pagein normal memory that can be shared between the SVM and Hypervisor.
  3. Ultravisor uses this hypercall to page-in a paged-out page. Thiscan happen when the SVM touches a paged-out page.
  4. If SVM wants to disable sharing of pages with Hypervisor, it caninform Ultravisor to do so. Ultravisor will then use this hypercalland inform Hypervisor that it has released access to the normalpage.

H_SVM_PAGE_OUT

Move the contents of the page to normal memory.
Syntax
uint64_thypercall(constuint64_tH_SVM_PAGE_OUT,uint64_tguest_pa,/* guest-physical-address */uint64_tflags,/* flags (currently none) */uint64_torder)/* page size order */
Return values

One of the following values:

  • H_SUCCESS on success.
  • H_PARAMETER ifguest_pa is invalid.
  • H_P2 ifflags is invalid.
  • H_P3 iforder is invalid.
Description

Move the contents of the page identified byguest_pa to normalmemory.

Currentlyflags is unused and must be set to 0. Theorderparameter must correspond to the configured page size.

Use cases
  1. If Ultravisor is running low on secure pages, it can move thecontents of some secure pages, into normal pages using thishypercall. The content will be encrypted.