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