| 1 | ====================== |
| 2 | sPAPR hypervisor calls |
| 3 | ====================== |
| 4 | |
| 5 | When used with the ``pseries`` machine type, ``qemu-system-ppc64`` implements |
| 6 | a set of hypervisor calls (a.k.a. hcalls) defined in the Linux on Power |
| 7 | Architecture Reference ([LoPAR]_) document. This document is a subset of the |
| 8 | Power Architecture Platform Reference (PAPR+) specification (IBM internal only), |
| 9 | which is what PowerVM, the IBM proprietary hypervisor, adheres to. |
| 10 | |
| 11 | The subset in LoPAR is selected based on the requirements of Linux as a guest. |
| 12 | |
| 13 | In addition to those calls, we have added our own private hypervisor |
| 14 | calls which are mostly used as a private interface between the firmware |
| 15 | running in the guest and QEMU. |
| 16 | |
| 17 | All those hypercalls start at hcall number 0xf000 which correspond |
| 18 | to an implementation specific range in PAPR. |
| 19 | |
| 20 | ``H_RTAS (0xf000)`` |
| 21 | =================== |
| 22 | |
| 23 | RTAS stands for Run-Time Abstraction Sercies and is a set of runtime services |
| 24 | generally provided by the firmware inside the guest to the operating system. It |
| 25 | predates the existence of hypervisors (it was originally an extension to Open |
| 26 | Firmware) and is still used by PAPR and LoPAR to provide various services that |
| 27 | are not performance sensitive. |
| 28 | |
| 29 | We 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 |
| 31 | calls our private H_RTAS hypervisor call to pass the RTAS calls to QEMU. |
| 32 | |
| 33 | Arguments: |
| 34 | |
| 35 | ``r3``: ``H_RTAS (0xf000)`` |
| 36 | |
| 37 | ``r4``: Guest physical address of RTAS parameter block. |
| 38 | |
| 39 | Returns: |
| 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 | |
| 49 | When the guest runs in "real mode" (in powerpc terminology this means with MMU |
| 50 | disabled, i.e. guest effective address equals to guest physical address), it |
| 51 | only has access to a subset of memory and no I/Os. |
| 52 | |
| 53 | PAPR and LoPAR provides a set of hypervisor calls to perform cacheable or |
| 54 | non-cacheable accesses to any guest physical addresses that the |
| 55 | guest can use in order to access IO devices while in real mode. |
| 56 | |
| 57 | This is typically used by the firmware running in the guest. |
| 58 | |
| 59 | However, doing a hypercall for each access is extremely inefficient |
| 60 | (even more so when running KVM) when accessing the frame buffer. In |
| 61 | that case, things like scrolling become unusably slow. |
| 62 | |
| 63 | This hypercall allows the guest to request a "memory op" to be applied |
| 64 | to memory. The supported memory ops at this point are to copy a range |
| 65 | of memory (supports overlap of source and destination) and XOR which |
| 66 | is used by our SLOF firmware to invert the screen. |
| 67 | |
| 68 | Arguments: |
| 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 | |
| 95 | Returns: |
| 96 | |
| 97 | ``H_SUCCESS``: Success. |
| 98 | |
| 99 | ``H_PARAMETER``: Invalid argument. |