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