1sPAPR hypervisor calls
2----------------------
3
4When used with the ``pseries`` machine type, ``qemu-system-ppc64`` implements
5a set of hypervisor calls (a.k.a. hcalls) defined in the `Linux on Power
6Architecture Reference document (LoPAR)
7<https://cdn.openpowerfoundation.org/wp-content/uploads/2020/07/LoPAR-20200812.pdf>`_.
8This document is a subset of the Power Architecture Platform Reference (PAPR+)
9specification (IBM internal only), which is what PowerVM, the IBM proprietary
10hypervisor, adheres to.
11
12The subset in LoPAR is selected based on the requirements of Linux as a guest.
13
14In addition to those calls, we have added our own private hypervisor
15calls which are mostly used as a private interface between the firmware
16running in the guest and QEMU.
17
18All those hypercalls start at hcall number 0xf000 which correspond
19to an implementation specific range in PAPR.
20
21H_RTAS (0xf000)
22^^^^^^^^^^^^^^^
23
24RTAS stands for Run-Time Abstraction Sercies and is a set of runtime services
25generally provided by the firmware inside the guest to the operating system. It
26predates the existence of hypervisors (it was originally an extension to Open
27Firmware) and is still used by PAPR and LoPAR to provide various services that
28are not performance sensitive.
29
30We currently implement the RTAS services in QEMU itself. The actual RTAS
31"firmware" blob in the guest is a small stub of a few instructions which
32calls our private H_RTAS hypervisor call to pass the RTAS calls to QEMU.
33
34Arguments:
35
36  ``r3``: ``H_RTAS (0xf000)``
37
38  ``r4``: Guest physical address of RTAS parameter block.
39
40Returns:
41
42  ``H_SUCCESS``: Successfully called the RTAS function (RTAS result will have
43  been stored in the parameter block).
44
45  ``H_PARAMETER``: Unknown token.
46
47H_LOGICAL_MEMOP (0xf001)
48^^^^^^^^^^^^^^^^^^^^^^^^
49
50When the guest runs in "real mode" (in powerpc terminology this means with MMU
51disabled, i.e. guest effective address equals to guest physical address), it
52only has access to a subset of memory and no I/Os.
53
54PAPR and LoPAR provides a set of hypervisor calls to perform cacheable or
55non-cacheable accesses to any guest physical addresses that the
56guest can use in order to access IO devices while in real mode.
57
58This is typically used by the firmware running in the guest.
59
60However, doing a hypercall for each access is extremely inefficient
61(even more so when running KVM) when accessing the frame buffer. In
62that case, things like scrolling become unusably slow.
63
64This hypercall allows the guest to request a "memory op" to be applied
65to memory. The supported memory ops at this point are to copy a range
66of memory (supports overlap of source and destination) and XOR which
67is used by our SLOF firmware to invert the screen.
68
69Arguments:
70
71  ``r3 ``: ``H_LOGICAL_MEMOP (0xf001)``
72
73  ``r4``: Guest physical address of destination.
74
75  ``r5``: Guest physical address of source.
76
77  ``r6``: Individual element size, defined by the binary logarithm of the
78  desired size. Supported values are:
79
80    ``0`` = 1 byte
81
82    ``1`` = 2 bytes
83
84    ``2`` = 4 bytes
85
86    ``3`` = 8 bytes
87
88  ``r7``: Number of elements.
89
90  ``r8``: Operation. Supported values are:
91
92    ``0``: copy
93
94    ``1``: xor
95
96Returns:
97
98  ``H_SUCCESS``: Success.
99
100  ``H_PARAMETER``: Invalid argument.
101