Documentation/powerpc/ultravisor.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2 .. _ultravisor:
   3
   4 ============================
   5 Protected Execution Facility
   6 ============================
   7
   8 .. contents::
   9     :depth: 3
  10
  11 .. sectnum::
  12     :depth: 3
  13
  14 Protected Execution Facility
  15 ############################
  16
  17     Protected Execution Facility (PEF) is an architectural change for
  18     POWER 9 that enables Secure Virtual Machines (SVMs). DD2.3 chips
  19     (PVR=0x004e1203) or greater will be PEF-capable. A new ISA release
  20     will include the PEF RFC02487 changes.
  21
  22     When enabled, PEF adds a new higher privileged mode, called Ultravisor
  23     mode, to POWER architecture. Along with the new mode there is new
  24     firmware called the Protected Execution Ultravisor (or Ultravisor
  25     for short). Ultravisor mode is the highest privileged mode in POWER
  26     architecture.
  27
  28         +------------------+
  29         | Privilege States |
  30         +==================+
  31         |  Problem         |
  32         +------------------+
  33         |  Supervisor      |
  34         +------------------+
  35         |  Hypervisor      |
  36         +------------------+
  37         |  Ultravisor      |
  38         +------------------+
  39
  40     PEF protects SVMs from the hypervisor, privileged users, and other
  41     VMs in the system. SVMs are protected while at rest and can only be
  42     executed by an authorized machine. All virtual machines utilize
  43     hypervisor services. The Ultravisor filters calls between the SVMs
  44     and the hypervisor to assure that information does not accidentally
  45     leak. All hypercalls except H_RANDOM are reflected to the hypervisor.
  46     H_RANDOM is not reflected to prevent the hypervisor from influencing
  47     random values in the SVM.
  48
  49     To support this there is a refactoring of the ownership of resources
  50     in the CPU. Some of the resources which were previously hypervisor
  51     privileged are now ultravisor privileged.
  52
  53 Hardware
  54 ========
  55
  56     The hardware changes include the following:
  57
  58     * There is a new bit in the MSR that determines whether the current
  59       process is running in secure mode, MSR(S) bit 41. MSR(S)=1, process
  60       is in secure mode, MSR(s)=0 process is in normal mode.
  61
  62     * The MSR(S) bit can only be set by the Ultravisor.
  63
  64     * HRFID cannot be used to set the MSR(S) bit. If the hypervisor needs
  65       to return to a SVM it must use an ultracall. It can determine if
  66       the VM it is returning to is secure.
  67
  68     * There is a new Ultravisor privileged register, SMFCTRL, which has an
  69       enable/disable bit SMFCTRL(E).
  70
  71     * The privilege of a process is now determined by three MSR bits,
  72       MSR(S, HV, PR). In each of the tables below the modes are listed
  73       from least privilege to highest privilege. The higher privilege
  74       modes can access all the resources of the lower privilege modes.
  75
  76       **Secure Mode MSR Settings**
  77
  78       +---+---+---+---------------+
  79       | S | HV| PR|Privilege      |
  80       +===+===+===+===============+
  81       | 1 | 0 | 1 | Problem       |
  82       +---+---+---+---------------+
  83       | 1 | 0 | 0 | Privileged(OS)|
  84       +---+---+---+---------------+
  85       | 1 | 1 | 0 | Ultravisor    |
  86       +---+---+---+---------------+
  87       | 1 | 1 | 1 | Reserved      |
  88       +---+---+---+---------------+
  89
  90       **Normal Mode MSR Settings**
  91
  92       +---+---+---+---------------+
  93       | S | HV| PR|Privilege      |
  94       +===+===+===+===============+
  95       | 0 | 0 | 1 | Problem       |
  96       +---+---+---+---------------+
  97       | 0 | 0 | 0 | Privileged(OS)|
  98       +---+---+---+---------------+
  99       | 0 | 1 | 0 | Hypervisor    |
 100       +---+---+---+---------------+
 101       | 0 | 1 | 1 | Problem (Host)|
 102       +---+---+---+---------------+
 103
 104     * Memory is partitioned into secure and normal memory. Only processes
 105       that are running in secure mode can access secure memory.
 106
 107     * The hardware does not allow anything that is not running secure to
 108       access secure memory. This means that the Hypervisor cannot access
 109       the memory of the SVM without using an ultracall (asking the
 110       Ultravisor). The Ultravisor will only allow the hypervisor to see
 111       the SVM memory encrypted.
 112
 113     * I/O systems are not allowed to directly address secure memory. This
 114       limits the SVMs to virtual I/O only.
 115
 116     * The architecture allows the SVM to share pages of memory with the
 117       hypervisor that are not protected with encryption. However, this
 118       sharing must be initiated by the SVM.
 119
 120     * When a process is running in secure mode all hypercalls
 121       (syscall lev=1) go to the Ultravisor.
 122
 123     * When a process is in secure mode all interrupts go to the
 124       Ultravisor.
 125
 126     * The following resources have become Ultravisor privileged and
 127       require an Ultravisor interface to manipulate:
 128
 129       * Processor configurations registers (SCOMs).
 130
 131       * Stop state information.
 132
 133       * The debug registers CIABR, DAWR, and DAWRX when SMFCTRL(D) is set.
 134         If SMFCTRL(D) is not set they do not work in secure mode. When set,
 135         reading and writing requires an Ultravisor call, otherwise that
 136         will cause a Hypervisor Emulation Assistance interrupt.
 137
 138       * PTCR and partition table entries (partition table is in secure
 139         memory). An attempt to write to PTCR will cause a Hypervisor
 140         Emulation Assitance interrupt.
 141
 142       * LDBAR (LD Base Address Register) and IMC (In-Memory Collection)
 143         non-architected registers. An attempt to write to them will cause a
 144         Hypervisor Emulation Assistance interrupt.
 145
 146       * Paging for an SVM, sharing of memory with Hypervisor for an SVM.
 147         (Including Virtual Processor Area (VPA) and virtual I/O).
 148
 149
 150 Software/Microcode
 151 ==================
 152
 153     The software changes include:
 154
 155     * SVMs are created from normal VM using (open source) tooling supplied
 156       by IBM.
 157
 158     * All SVMs start as normal VMs and utilize an ultracall, UV_ESM
 159       (Enter Secure Mode), to make the transition.
 160
 161     * When the UV_ESM ultracall is made the Ultravisor copies the VM into
 162       secure memory, decrypts the verification information, and checks the
 163       integrity of the SVM. If the integrity check passes the Ultravisor
 164       passes control in secure mode.
 165
 166     * The verification information includes the pass phrase for the
 167       encrypted disk associated with the SVM. This pass phrase is given
 168       to the SVM when requested.
 169
 170     * The Ultravisor is not involved in protecting the encrypted disk of
 171       the SVM while at rest.
 172
 173     * For external interrupts the Ultravisor saves the state of the SVM,
 174       and reflects the interrupt to the hypervisor for processing.
 175       For hypercalls, the Ultravisor inserts neutral state into all
 176       registers not needed for the hypercall then reflects the call to
 177       the hypervisor for processing. The H_RANDOM hypercall is performed
 178       by the Ultravisor and not reflected.
 179
 180     * For virtual I/O to work bounce buffering must be done.
 181
 182     * The Ultravisor uses AES (IAPM) for protection of SVM memory. IAPM
 183       is a mode of AES that provides integrity and secrecy concurrently.
 184
 185     * The movement of data between normal and secure pages is coordinated
 186       with the Ultravisor by a new HMM plug-in in the Hypervisor.
 187
 188     The Ultravisor offers new services to the hypervisor and SVMs. These
 189     are accessed through ultracalls.
 190
 191 Terminology
 192 ===========
 193
 194     * Hypercalls: special system calls used to request services from
 195       Hypervisor.
 196
 197     * Normal memory: Memory that is accessible to Hypervisor.
 198
 199     * Normal page: Page backed by normal memory and available to
 200       Hypervisor.
 201
 202     * Shared page: A page backed by normal memory and available to both
 203       the Hypervisor/QEMU and the SVM (i.e page has mappings in SVM and
 204       Hypervisor/QEMU).
 205
 206     * Secure memory: Memory that is accessible only to Ultravisor and
 207       SVMs.
 208
 209     * Secure page: Page backed by secure memory and only available to
 210       Ultravisor and SVM.
 211
 212     * SVM: Secure Virtual Machine.
 213
 214     * Ultracalls: special system calls used to request services from
 215       Ultravisor.
 216
 217
 218 Ultravisor calls API
 219 ####################
 220
 221     This section describes Ultravisor calls (ultracalls) needed to
 222     support Secure Virtual Machines (SVM)s and Paravirtualized KVM. The
 223     ultracalls allow the SVMs and Hypervisor to request services from the
 224     Ultravisor such as accessing a register or memory region that can only
 225     be accessed when running in Ultravisor-privileged mode.
 226
 227     The specific service needed from an ultracall is specified in register
 228     R3 (the first parameter to the ultracall). Other parameters to the
 229     ultracall, if any, are specified in registers R4 through R12.
 230
 231     Return value of all ultracalls is in register R3. Other output values
 232     from the ultracall, if any, are returned in registers R4 through R12.
 233     The only exception to this register usage is the ``UV_RETURN``
 234     ultracall described below.
 235
 236     Each ultracall returns specific error codes, applicable in the context
 237     of the ultracall. However, like with the PowerPC Architecture Platform
 238     Reference (PAPR), if no specific error code is defined for a
 239     particular situation, then the ultracall will fallback to an erroneous
 240     parameter-position based code. i.e U_PARAMETER, U_P2, U_P3 etc
 241     depending on the ultracall parameter that may have caused the error.
 242
 243     Some ultracalls involve transferring a page of data between Ultravisor
 244     and Hypervisor.  Secure pages that are transferred from secure memory
 245     to normal memory may be encrypted using dynamically generated keys.
 246     When the secure pages are transferred back to secure memory, they may
 247     be decrypted using the same dynamically generated keys. Generation and
 248     management of these keys will be covered in a separate document.
 249
 250     For now this only covers ultracalls currently implemented and being
 251     used by Hypervisor and SVMs but others can be added here when it
 252     makes sense.
 253
 254     The full specification for all hypercalls/ultracalls will eventually
 255     be made available in the public/OpenPower version of the PAPR
 256     specification.
 257
 258     **Note**
 259
 260     If PEF is not enabled, the ultracalls will be redirected to the
 261     Hypervisor which must handle/fail the calls.
 262
 263 Ultracalls used by Hypervisor
 264 =============================
 265
 266     This section describes the virtual memory management ultracalls used
 267     by the Hypervisor to manage SVMs.
 268
 269 UV_PAGE_OUT
 270 -----------
 271
 272     Encrypt and move the contents of a page from secure memory to normal
 273     memory.
 274
 275 Syntax
 276 ~~~~~~
 277
 278 .. code-block:: c
 279
 280         uint64_t ultracall(const uint64_t UV_PAGE_OUT,
 281                 uint16_t lpid,          /* LPAR ID */
 282                 uint64_t dest_ra,       /* real address of destination page */
 283                 uint64_t src_gpa,       /* source guest-physical-address */
 284                 uint8_t  flags,         /* flags */
 285                 uint64_t order)         /* page size order */
 286
 287 Return values
 288 ~~~~~~~~~~~~~
 289
 290     One of the following values:
 291
 292         * U_SUCCESS     on success.
 293         * U_PARAMETER   if ``lpid`` is invalid.
 294         * U_P2          if ``dest_ra`` is invalid.
 295         * U_P3          if the ``src_gpa`` address is invalid.
 296         * U_P4          if any bit in the ``flags`` is unrecognized
 297         * U_P5          if the ``order`` parameter is unsupported.
 298         * U_FUNCTION    if functionality is not supported.
 299         * U_BUSY        if page cannot be currently paged-out.
 300
 301 Description
 302 ~~~~~~~~~~~
 303
 304     Encrypt the contents of a secure-page and make it available to
 305     Hypervisor in a normal page.
 306
 307     By default, the source page is unmapped from the SVM's partition-
 308     scoped page table. But the Hypervisor can provide a hint to the
 309     Ultravisor to retain the page mapping by setting the ``UV_SNAPSHOT``
 310     flag in ``flags`` parameter.
 311
 312     If the source page is already a shared page the call returns
 313     U_SUCCESS, without doing anything.
 314
 315 Use cases
 316 ~~~~~~~~~
 317
 318     #. QEMU attempts to access an address belonging to the SVM but the
 319        page frame for that address is not mapped into QEMU's address
 320        space. In this case, the Hypervisor will allocate a page frame,
 321        map it into QEMU's address space and issue the ``UV_PAGE_OUT``
 322        call to retrieve the encrypted contents of the page.
 323
 324     #. When Ultravisor runs low on secure memory and it needs to page-out
 325        an LRU page. In this case, Ultravisor will issue the
 326        ``H_SVM_PAGE_OUT`` hypercall to the Hypervisor. The Hypervisor will
 327        then allocate a normal page and issue the ``UV_PAGE_OUT`` ultracall
 328        and the Ultravisor will encrypt and move the contents of the secure
 329        page into the normal page.
 330
 331     #. When Hypervisor accesses SVM data, the Hypervisor requests the
 332        Ultravisor to transfer the corresponding page into a insecure page,
 333        which the Hypervisor can access. The data in the normal page will
 334        be encrypted though.
 335
 336 UV_PAGE_IN
 337 ----------
 338
 339     Move the contents of a page from normal memory to secure memory.
 340
 341 Syntax
 342 ~~~~~~
 343
 344 .. code-block:: c
 345
 346         uint64_t ultracall(const uint64_t UV_PAGE_IN,
 347                 uint16_t lpid,          /* the LPAR ID */
 348                 uint64_t src_ra,        /* source real address of page */
 349                 uint64_t dest_gpa,      /* destination guest physical address */
 350                 uint64_t flags,         /* flags */
 351                 uint64_t order)         /* page size order */
 352
 353 Return values
 354 ~~~~~~~~~~~~~
 355
 356     One of the following values:
 357
 358         * U_SUCCESS     on success.
 359         * U_BUSY        if page cannot be currently paged-in.
 360         * U_FUNCTION    if functionality is not supported
 361         * U_PARAMETER   if ``lpid`` is invalid.
 362         * U_P2          if ``src_ra`` is invalid.
 363         * U_P3          if the ``dest_gpa`` address is invalid.
 364         * U_P4          if any bit in the ``flags`` is unrecognized
 365         * U_P5          if the ``order`` parameter is unsupported.
 366
 367 Description
 368 ~~~~~~~~~~~
 369
 370     Move the contents of the page identified by ``src_ra`` from normal
 371     memory to secure memory and map it to the guest physical address
 372     ``dest_gpa``.
 373
 374     If `dest_gpa` refers to a shared address, map the page into the
 375     partition-scoped page-table of the SVM.  If `dest_gpa` is not shared,
 376     copy the contents of the page into the corresponding secure page.
 377     Depending on the context, decrypt the page before being copied.
 378
 379     The caller provides the attributes of the page through the ``flags``
 380     parameter. Valid values for ``flags`` are:
 381
 382         * CACHE_INHIBITED
 383         * CACHE_ENABLED
 384         * WRITE_PROTECTION
 385
 386     The Hypervisor must pin the page in memory before making
 387     ``UV_PAGE_IN`` ultracall.
 388
 389 Use cases
 390 ~~~~~~~~~
 391
 392     #. When a normal VM switches to secure mode, all its pages residing
 393        in normal memory, are moved into secure memory.
 394
 395     #. When an SVM requests to share a page with Hypervisor the Hypervisor
 396        allocates a page and informs the Ultravisor.
 397
 398     #. When an SVM accesses a secure page that has been paged-out,
 399        Ultravisor invokes the Hypervisor to locate the page. After
 400        locating the page, the Hypervisor uses UV_PAGE_IN to make the
 401        page available to Ultravisor.
 402
 403 UV_PAGE_INVAL
 404 -------------
 405
 406     Invalidate the Ultravisor mapping of a page.
 407
 408 Syntax
 409 ~~~~~~
 410
 411 .. code-block:: c
 412
 413         uint64_t ultracall(const uint64_t UV_PAGE_INVAL,
 414                 uint16_t lpid,          /* the LPAR ID */
 415                 uint64_t guest_pa,      /* destination guest-physical-address */
 416                 uint64_t order)         /* page size order */
 417
 418 Return values
 419 ~~~~~~~~~~~~~
 420
 421     One of the following values:
 422
 423         * U_SUCCESS     on success.
 424         * U_PARAMETER   if ``lpid`` is invalid.
 425         * U_P2          if ``guest_pa`` is invalid (or corresponds to a secure
 426                         page mapping).
 427         * U_P3          if the ``order`` is invalid.
 428         * U_FUNCTION    if functionality is not supported.
 429         * U_BUSY        if page cannot be currently invalidated.
 430
 431 Description
 432 ~~~~~~~~~~~
 433
 434     This ultracall informs Ultravisor that the page mapping in Hypervisor
 435     corresponding to the given guest physical address has been invalidated
 436     and that the Ultravisor should not access the page. If the specified
 437     ``guest_pa`` corresponds to a secure page, Ultravisor will ignore the
 438     attempt to invalidate the page and return U_P2.
 439
 440 Use cases
 441 ~~~~~~~~~
 442
 443     #. When a shared page is unmapped from the QEMU's page table, possibly
 444        because it is paged-out to disk, Ultravisor needs to know that the
 445        page should not be accessed from its side too.
 446
 447
 448 UV_WRITE_PATE
 449 -------------
 450
 451     Validate and write the partition table entry (PATE) for a given
 452     partition.
 453
 454 Syntax
 455 ~~~~~~
 456
 457 .. code-block:: c
 458
 459         uint64_t ultracall(const uint64_t UV_WRITE_PATE,
 460                 uint32_t lpid,          /* the LPAR ID */
 461                 uint64_t dw0            /* the first double word to write */
 462                 uint64_t dw1)           /* the second double word to write */
 463
 464 Return values
 465 ~~~~~~~~~~~~~
 466
 467     One of the following values:
 468
 469         * U_SUCCESS     on success.
 470         * U_BUSY        if PATE cannot be currently written to.
 471         * U_FUNCTION    if functionality is not supported.
 472         * U_PARAMETER   if ``lpid`` is invalid.
 473         * U_P2          if ``dw0`` is invalid.
 474         * U_P3          if the ``dw1`` address is invalid.
 475         * U_PERMISSION  if the Hypervisor is attempting to change the PATE
 476                         of a secure virtual machine or if called from a
 477                         context other than Hypervisor.
 478
 479 Description
 480 ~~~~~~~~~~~
 481
 482     Validate and write a LPID and its partition-table-entry for the given
 483     LPID.  If the LPID is already allocated and initialized, this call
 484     results in changing the partition table entry.
 485
 486 Use cases
 487 ~~~~~~~~~
 488
 489     #. The Partition table resides in Secure memory and its entries,
 490        called PATE (Partition Table Entries), point to the partition-
 491        scoped page tables for the Hypervisor as well as each of the
 492        virtual machines (both secure and normal). The Hypervisor
 493        operates in partition 0 and its partition-scoped page tables
 494        reside in normal memory.
 495
 496     #. This ultracall allows the Hypervisor to register the partition-
 497        scoped and process-scoped page table entries for the Hypervisor
 498        and other partitions (virtual machines) with the Ultravisor.
 499
 500     #. If the value of the PATE for an existing partition (VM) changes,
 501        the TLB cache for the partition is flushed.
 502
 503     #. The Hypervisor is responsible for allocating LPID. The LPID and
 504        its PATE entry are registered together.  The Hypervisor manages
 505        the PATE entries for a normal VM and can change the PATE entry
 506        anytime. Ultravisor manages the PATE entries for an SVM and
 507        Hypervisor is not allowed to modify them.
 508
 509 UV_RETURN
 510 ---------
 511
 512     Return control from the Hypervisor back to the Ultravisor after
 513     processing an hypercall or interrupt that was forwarded (aka
 514     *reflected*) to the Hypervisor.
 515
 516 Syntax
 517 ~~~~~~
 518
 519 .. code-block:: c
 520
 521         uint64_t ultracall(const uint64_t UV_RETURN)
 522
 523 Return values
 524 ~~~~~~~~~~~~~
 525
 526      This call never returns to Hypervisor on success.  It returns
 527      U_INVALID if ultracall is not made from a Hypervisor context.
 528
 529 Description
 530 ~~~~~~~~~~~
 531
 532     When an SVM makes an hypercall or incurs some other exception, the
 533     Ultravisor usually forwards (aka *reflects*) the exceptions to the
 534     Hypervisor.  After processing the exception, Hypervisor uses the
 535     ``UV_RETURN`` ultracall to return control back to the SVM.
 536
 537     The expected register state on entry to this ultracall is:
 538
 539     * Non-volatile registers are restored to their original values.
 540     * If returning from an hypercall, register R0 contains the return
 541       value (**unlike other ultracalls**) and, registers R4 through R12
 542       contain any output values of the hypercall.
 543     * R3 contains the ultracall number, i.e UV_RETURN.
 544     * If returning with a synthesized interrupt, R2 contains the
 545       synthesized interrupt number.
 546
 547 Use cases
 548 ~~~~~~~~~
 549
 550     #. Ultravisor relies on the Hypervisor to provide several services to
 551        the SVM such as processing hypercall and other exceptions. After
 552        processing the exception, Hypervisor uses UV_RETURN to return
 553        control back to the Ultravisor.
 554
 555     #. Hypervisor has to use this ultracall to return control to the SVM.
 556
 557
 558 UV_REGISTER_MEM_SLOT
 559 --------------------
 560
 561     Register an SVM address-range with specified properties.
 562
 563 Syntax
 564 ~~~~~~
 565
 566 .. code-block:: c
 567
 568         uint64_t ultracall(const uint64_t UV_REGISTER_MEM_SLOT,
 569                 uint64_t lpid,          /* LPAR ID of the SVM */
 570                 uint64_t start_gpa,     /* start guest physical address */
 571                 uint64_t size,          /* size of address range in bytes */
 572                 uint64_t flags          /* reserved for future expansion */
 573                 uint16_t slotid)        /* slot identifier */
 574
 575 Return values
 576 ~~~~~~~~~~~~~
 577
 578     One of the following values:
 579
 580         * U_SUCCESS     on success.
 581         * U_PARAMETER   if ``lpid`` is invalid.
 582         * U_P2          if ``start_gpa`` is invalid.
 583         * U_P3          if ``size`` is invalid.
 584         * U_P4          if any bit in the ``flags`` is unrecognized.
 585         * U_P5          if the ``slotid`` parameter is unsupported.
 586         * U_PERMISSION  if called from context other than Hypervisor.
 587         * U_FUNCTION    if functionality is not supported.
 588
 589
 590 Description
 591 ~~~~~~~~~~~
 592
 593     Register a memory range for an SVM.  The memory range starts at the
 594     guest physical address ``start_gpa`` and is ``size`` bytes long.
 595
 596 Use cases
 597 ~~~~~~~~~
 598
 599
 600     #. When a virtual machine goes secure, all the memory slots managed by
 601        the Hypervisor move into secure memory. The Hypervisor iterates
 602        through each of memory slots, and registers the slot with
 603        Ultravisor.  Hypervisor may discard some slots such as those used
 604        for firmware (SLOF).
 605
 606     #. When new memory is hot-plugged, a new memory slot gets registered.
 607
 608
 609 UV_UNREGISTER_MEM_SLOT
 610 ----------------------
 611
 612     Unregister an SVM address-range that was previously registered using
 613     UV_REGISTER_MEM_SLOT.
 614
 615 Syntax
 616 ~~~~~~
 617
 618 .. code-block:: c
 619
 620         uint64_t ultracall(const uint64_t UV_UNREGISTER_MEM_SLOT,
 621                 uint64_t lpid,          /* LPAR ID of the SVM */
 622                 uint64_t slotid)        /* reservation slotid */
 623
 624 Return values
 625 ~~~~~~~~~~~~~
 626
 627     One of the following values:
 628
 629         * U_SUCCESS     on success.
 630         * U_FUNCTION    if functionality is not supported.
 631         * U_PARAMETER   if ``lpid`` is invalid.
 632         * U_P2          if ``slotid`` is invalid.
 633         * U_PERMISSION  if called from context other than Hypervisor.
 634
 635 Description
 636 ~~~~~~~~~~~
 637
 638     Release the memory slot identified by ``slotid`` and free any
 639     resources allocated towards the reservation.
 640
 641 Use cases
 642 ~~~~~~~~~
 643
 644     #. Memory hot-remove.
 645
 646
 647 UV_SVM_TERMINATE
 648 ----------------
 649
 650     Terminate an SVM and release its resources.
 651
 652 Syntax
 653 ~~~~~~
 654
 655 .. code-block:: c
 656
 657         uint64_t ultracall(const uint64_t UV_SVM_TERMINATE,
 658                 uint64_t lpid,          /* LPAR ID of the SVM */)
 659
 660 Return values
 661 ~~~~~~~~~~~~~
 662
 663     One of the following values:
 664
 665         * U_SUCCESS     on success.
 666         * U_FUNCTION    if functionality is not supported.
 667         * U_PARAMETER   if ``lpid`` is invalid.
 668         * U_INVALID     if VM is not secure.
 669         * U_PERMISSION  if not called from a Hypervisor context.
 670
 671 Description
 672 ~~~~~~~~~~~
 673
 674     Terminate an SVM and release all its resources.
 675
 676 Use cases
 677 ~~~~~~~~~
 678
 679     #. Called by Hypervisor when terminating an SVM.
 680
 681
 682 Ultracalls used by SVM
 683 ======================
 684
 685 UV_SHARE_PAGE
 686 -------------
 687
 688     Share a set of guest physical pages with the Hypervisor.
 689
 690 Syntax
 691 ~~~~~~
 692
 693 .. code-block:: c
 694
 695         uint64_t ultracall(const uint64_t UV_SHARE_PAGE,
 696                 uint64_t gfn,   /* guest page frame number */
 697                 uint64_t num)   /* number of pages of size PAGE_SIZE */
 698
 699 Return values
 700 ~~~~~~~~~~~~~
 701
 702     One of the following values:
 703
 704         * U_SUCCESS     on success.
 705         * U_FUNCTION    if functionality is not supported.
 706         * U_INVALID     if the VM is not secure.
 707         * U_PARAMETER   if ``gfn`` is invalid.
 708         * U_P2          if ``num`` is invalid.
 709
 710 Description
 711 ~~~~~~~~~~~
 712
 713     Share the ``num`` pages starting at guest physical frame number ``gfn``
 714     with the Hypervisor. Assume page size is PAGE_SIZE bytes. Zero the
 715     pages before returning.
 716
 717     If the address is already backed by a secure page, unmap the page and
 718     back it with an insecure page, with the help of the Hypervisor. If it
 719     is not backed by any page yet, mark the PTE as insecure and back it
 720     with an insecure page when the address is accessed. If it is already
 721     backed by an insecure page, zero the page and return.
 722
 723 Use cases
 724 ~~~~~~~~~
 725
 726     #. The Hypervisor cannot access the SVM pages since they are backed by
 727        secure pages. Hence an SVM must explicitly request Ultravisor for
 728        pages it can share with Hypervisor.
 729
 730     #. Shared pages are needed to support virtio and Virtual Processor Area
 731        (VPA) in SVMs.
 732
 733
 734 UV_UNSHARE_PAGE
 735 ---------------
 736
 737     Restore a shared SVM page to its initial state.
 738
 739 Syntax
 740 ~~~~~~
 741
 742 .. code-block:: c
 743
 744         uint64_t ultracall(const uint64_t UV_UNSHARE_PAGE,
 745                 uint64_t gfn,   /* guest page frame number */
 746                 uint73 num)     /* number of pages of size PAGE_SIZE*/
 747
 748 Return values
 749 ~~~~~~~~~~~~~
 750
 751     One of the following values:
 752
 753         * U_SUCCESS     on success.
 754         * U_FUNCTION    if functionality is not supported.
 755         * U_INVALID     if VM is not secure.
 756         * U_PARAMETER   if ``gfn`` is invalid.
 757         * U_P2          if ``num`` is invalid.
 758
 759 Description
 760 ~~~~~~~~~~~
 761
 762     Stop sharing ``num`` pages starting at ``gfn`` with the Hypervisor.
 763     Assume that the page size is PAGE_SIZE. Zero the pages before
 764     returning.
 765
 766     If the address is already backed by an insecure page, unmap the page
 767     and back it with a secure page. Inform the Hypervisor to release
 768     reference to its shared page. If the address is not backed by a page
 769     yet, mark the PTE as secure and back it with a secure page when that
 770     address is accessed. If it is already backed by an secure page zero
 771     the page and return.
 772
 773 Use cases
 774 ~~~~~~~~~
 775
 776     #. The SVM may decide to unshare a page from the Hypervisor.
 777
 778
 779 UV_UNSHARE_ALL_PAGES
 780 --------------------
 781
 782     Unshare all pages the SVM has shared with Hypervisor.
 783
 784 Syntax
 785 ~~~~~~
 786
 787 .. code-block:: c
 788
 789         uint64_t ultracall(const uint64_t UV_UNSHARE_ALL_PAGES)
 790
 791 Return values
 792 ~~~~~~~~~~~~~
 793
 794     One of the following values:
 795
 796         * U_SUCCESS     on success.
 797         * U_FUNCTION    if functionality is not supported.
 798         * U_INVAL       if VM is not secure.
 799
 800 Description
 801 ~~~~~~~~~~~
 802
 803     Unshare all shared pages from the Hypervisor. All unshared pages are
 804     zeroed on return. Only pages explicitly shared by the SVM with the
 805     Hypervisor (using UV_SHARE_PAGE ultracall) are unshared. Ultravisor
 806     may internally share some pages with the Hypervisor without explicit
 807     request from the SVM.  These pages will not be unshared by this
 808     ultracall.
 809
 810 Use cases
 811 ~~~~~~~~~
 812
 813     #. This call is needed when ``kexec`` is used to boot a different
 814        kernel. It may also be needed during SVM reset.
 815
 816 UV_ESM
 817 ------
 818
 819     Secure the virtual machine (*enter secure mode*).
 820
 821 Syntax
 822 ~~~~~~
 823
 824 .. code-block:: c
 825
 826         uint64_t ultracall(const uint64_t UV_ESM,
 827                 uint64_t esm_blob_addr, /* location of the ESM blob */
 828                 unint64_t fdt)          /* Flattened device tree */
 829
 830 Return values
 831 ~~~~~~~~~~~~~
 832
 833     One of the following values:
 834
 835         * U_SUCCESS     on success (including if VM is already secure).
 836         * U_FUNCTION    if functionality is not supported.
 837         * U_INVALID     if VM is not secure.
 838         * U_PARAMETER   if ``esm_blob_addr`` is invalid.
 839         * U_P2          if ``fdt`` is invalid.
 840         * U_PERMISSION  if any integrity checks fail.
 841         * U_RETRY       insufficient memory to create SVM.
 842         * U_NO_KEY      symmetric key unavailable.
 843
 844 Description
 845 ~~~~~~~~~~~
 846
 847     Secure the virtual machine. On successful completion, return
 848     control to the virtual machine at the address specified in the
 849     ESM blob.
 850
 851 Use cases
 852 ~~~~~~~~~
 853
 854     #. A normal virtual machine can choose to switch to a secure mode.
 855
 856 Hypervisor Calls API
 857 ####################
 858
 859     This document describes the Hypervisor calls (hypercalls) that are
 860     needed to support the Ultravisor. Hypercalls are services provided by
 861     the Hypervisor to virtual machines and Ultravisor.
 862
 863     Register usage for these hypercalls is identical to that of the other
 864     hypercalls defined in the Power Architecture Platform Reference (PAPR)
 865     document.  i.e on input, register R3 identifies the specific service
 866     that is being requested and registers R4 through R11 contain
 867     additional parameters to the hypercall, if any. On output, register
 868     R3 contains the return value and registers R4 through R9 contain any
 869     other output values from the hypercall.
 870
 871     This document only covers hypercalls currently implemented/planned
 872     for Ultravisor usage but others can be added here when it makes sense.
 873
 874     The full specification for all hypercalls/ultracalls will eventually
 875     be made available in the public/OpenPower version of the PAPR
 876     specification.
 877
 878 Hypervisor calls to support Ultravisor
 879 ======================================
 880
 881     Following are the set of hypercalls needed to support Ultravisor.
 882
 883 H_SVM_INIT_START
 884 ----------------
 885
 886     Begin the process of converting a normal virtual machine into an SVM.
 887
 888 Syntax
 889 ~~~~~~
 890
 891 .. code-block:: c
 892
 893         uint64_t hypercall(const uint64_t H_SVM_INIT_START)
 894
 895 Return values
 896 ~~~~~~~~~~~~~
 897
 898     One of the following values:
 899
 900         * H_SUCCESS      on success.
 901
 902 Description
 903 ~~~~~~~~~~~
 904
 905     Initiate the process of securing a virtual machine. This involves
 906     coordinating with the Ultravisor, using ultracalls, to allocate
 907     resources in the Ultravisor for the new SVM, transferring the VM's
 908     pages from normal to secure memory etc. When the process is
 909     completed, Ultravisor issues the H_SVM_INIT_DONE hypercall.
 910
 911 Use cases
 912 ~~~~~~~~~
 913
 914      #. Ultravisor uses this hypercall to inform Hypervisor that a VM
 915         has initiated the process of switching to secure mode.
 916
 917
 918 H_SVM_INIT_DONE
 919 ---------------
 920
 921     Complete the process of securing an SVM.
 922
 923 Syntax
 924 ~~~~~~
 925
 926 .. code-block:: c
 927
 928         uint64_t hypercall(const uint64_t H_SVM_INIT_DONE)
 929
 930 Return values
 931 ~~~~~~~~~~~~~
 932
 933     One of the following values:
 934
 935         * H_SUCCESS             on success.
 936         * H_UNSUPPORTED         if called from the wrong context (e.g.
 937                                 from an SVM or before an H_SVM_INIT_START
 938                                 hypercall).
 939
 940 Description
 941 ~~~~~~~~~~~
 942
 943     Complete the process of securing a virtual machine. This call must
 944     be made after a prior call to ``H_SVM_INIT_START`` hypercall.
 945
 946 Use cases
 947 ~~~~~~~~~
 948
 949     On successfully securing a virtual machine, the Ultravisor informs
 950     Hypervisor about it. Hypervisor can use this call to finish setting
 951     up its internal state for this virtual machine.
 952
 953
 954 H_SVM_PAGE_IN
 955 -------------
 956
 957     Move the contents of a page from normal memory to secure memory.
 958
 959 Syntax
 960 ~~~~~~
 961
 962 .. code-block:: c
 963
 964         uint64_t hypercall(const uint64_t H_SVM_PAGE_IN,
 965                 uint64_t guest_pa,      /* guest-physical-address */
 966                 uint64_t flags,         /* flags */
 967                 uint64_t order)         /* page size order */
 968
 969 Return values
 970 ~~~~~~~~~~~~~
 971
 972     One of the following values:
 973
 974         * H_SUCCESS     on success.
 975         * H_PARAMETER   if ``guest_pa`` is invalid.
 976         * H_P2          if ``flags`` is invalid.
 977         * H_P3          if ``order`` of page is invalid.
 978
 979 Description
 980 ~~~~~~~~~~~
 981
 982     Retrieve the content of the page, belonging to the VM at the specified
 983     guest physical address.
 984
 985     Only valid value(s) in ``flags`` are:
 986
 987         * H_PAGE_IN_SHARED which indicates that the page is to be shared
 988           with the Ultravisor.
 989
 990         * H_PAGE_IN_NONSHARED indicates that the UV is not anymore
 991           interested in the page. Applicable if the page is a shared page.
 992
 993     The ``order`` parameter must correspond to the configured page size.
 994
 995 Use cases
 996 ~~~~~~~~~
 997
 998     #. When a normal VM becomes a secure VM (using the UV_ESM ultracall),
 999        the Ultravisor uses this hypercall to move contents of each page of
1000        the VM from normal memory to secure memory.
1001
1002     #. Ultravisor uses this hypercall to ask Hypervisor to provide a page
1003        in normal memory that can be shared between the SVM and Hypervisor.
1004
1005     #. Ultravisor uses this hypercall to page-in a paged-out page. This
1006        can happen when the SVM touches a paged-out page.
1007
1008     #. If SVM wants to disable sharing of pages with Hypervisor, it can
1009        inform Ultravisor to do so. Ultravisor will then use this hypercall
1010        and inform Hypervisor that it has released access to the normal
1011        page.
1012
1013 H_SVM_PAGE_OUT
1014 ---------------
1015
1016     Move the contents of the page to normal memory.
1017
1018 Syntax
1019 ~~~~~~
1020
1021 .. code-block:: c
1022
1023         uint64_t hypercall(const uint64_t H_SVM_PAGE_OUT,
1024                 uint64_t guest_pa,      /* guest-physical-address */
1025                 uint64_t flags,         /* flags (currently none) */
1026                 uint64_t order)         /* page size order */
1027
1028 Return values
1029 ~~~~~~~~~~~~~
1030
1031     One of the following values:
1032
1033         * H_SUCCESS     on success.
1034         * H_PARAMETER   if ``guest_pa`` is invalid.
1035         * H_P2          if ``flags`` is invalid.
1036         * H_P3          if ``order`` is invalid.
1037
1038 Description
1039 ~~~~~~~~~~~
1040
1041     Move the contents of the page identified by ``guest_pa`` to normal
1042     memory.
1043
1044     Currently ``flags`` is unused and must be set to 0. The ``order``
1045     parameter must correspond to the configured page size.
1046
1047 Use cases
1048 ~~~~~~~~~
1049
1050     #. If Ultravisor is running low on secure pages, it can move the
1051        contents of some secure pages, into normal pages using this
1052        hypercall. The content will be encrypted.
1053
1054 References
1055 ##########
1056
1057 .. [1] `Supporting Protected Computing on IBM Power Architecture <https://developer.ibm.com/articles/l-support-protected-computing/>`_