ultravisor.rst 34 KB

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