diff options
| -rw-r--r-- | docs/specs/ppc-spapr-hcalls.txt | 92 |
1 files changed, 57 insertions, 35 deletions
diff --git a/docs/specs/ppc-spapr-hcalls.txt b/docs/specs/ppc-spapr-hcalls.txt index 93fe3da..28daf97 100644 --- a/docs/specs/ppc-spapr-hcalls.txt +++ b/docs/specs/ppc-spapr-hcalls.txt @@ -1,9 +1,15 @@ -When used with the "pseries" machine type, QEMU-system-ppc64 implements -a set of hypervisor calls using a subset of the server "PAPR" specification -(IBM internal at this point), which is also what IBM's proprietary hypervisor -adheres too. +sPAPR hypervisor calls +---------------------- -The subset is selected based on the requirements of Linux as a guest. +When used with the ``pseries`` machine type, ``qemu-system-ppc64`` implements +a set of hypervisor calls (a.k.a. hcalls) defined in the `Linux on Power +Architecture Reference document (LoPAR) +<https://cdn.openpowerfoundation.org/wp-content/uploads/2020/07/LoPAR-20200812.pdf>`_. +This document is a subset of the Power Architecture Platform Reference (PAPR+) +specification (IBM internal only), which is what PowerVM, the IBM proprietary +hypervisor, adheres to. + +The subset in LoPAR is selected based on the requirements of Linux as a guest. In addition to those calls, we have added our own private hypervisor calls which are mostly used as a private interface between the firmware @@ -12,13 +18,14 @@ running in the guest and QEMU. All those hypercalls start at hcall number 0xf000 which correspond to an implementation specific range in PAPR. -- H_RTAS (0xf000) +H_RTAS (0xf000) +^^^^^^^^^^^^^^^ -RTAS is a set of runtime services generally provided by the firmware -inside the guest to the operating system. It predates the existence -of hypervisors (it was originally an extension to Open Firmware) and -is still used by PAPR to provide various services that aren't performance -sensitive. +RTAS stands for Run-Time Abstraction Sercies and is a set of runtime services +generally provided by the firmware inside the guest to the operating system. It +predates the existence of hypervisors (it was originally an extension to Open +Firmware) and is still used by PAPR and LoPAR to provide various services that +are not performance sensitive. We currently implement the RTAS services in QEMU itself. The actual RTAS "firmware" blob in the guest is a small stub of a few instructions which @@ -26,22 +33,25 @@ calls our private H_RTAS hypervisor call to pass the RTAS calls to QEMU. Arguments: - r3 : H_RTAS (0xf000) - r4 : Guest physical address of RTAS parameter block + ``r3``: ``H_RTAS (0xf000)`` + + ``r4``: Guest physical address of RTAS parameter block. Returns: - H_SUCCESS : Successfully called the RTAS function (RTAS result - will have been stored in the parameter block) - H_PARAMETER : Unknown token + ``H_SUCCESS``: Successfully called the RTAS function (RTAS result will have + been stored in the parameter block). -- H_LOGICAL_MEMOP (0xf001) + ``H_PARAMETER``: Unknown token. -When the guest runs in "real mode" (in powerpc lingua this means -with MMU disabled, ie guest effective == guest physical), it only -has access to a subset of memory and no IOs. +H_LOGICAL_MEMOP (0xf001) +^^^^^^^^^^^^^^^^^^^^^^^^ -PAPR provides a set of hypervisor calls to perform cacheable or +When the guest runs in "real mode" (in powerpc terminology this means with MMU +disabled, i.e. guest effective address equals to guest physical address), it +only has access to a subset of memory and no I/Os. + +PAPR and LoPAR provides a set of hypervisor calls to perform cacheable or non-cacheable accesses to any guest physical addresses that the guest can use in order to access IO devices while in real mode. @@ -58,21 +68,33 @@ is used by our SLOF firmware to invert the screen. Arguments: - r3: H_LOGICAL_MEMOP (0xf001) - r4: Guest physical address of destination - r5: Guest physical address of source - r6: Individual element size - 0 = 1 byte - 1 = 2 bytes - 2 = 4 bytes - 3 = 8 bytes - r7: Number of elements - r8: Operation - 0 = copy - 1 = xor + ``r3 ``: ``H_LOGICAL_MEMOP (0xf001)`` + + ``r4``: Guest physical address of destination. + + ``r5``: Guest physical address of source. + + ``r6``: Individual element size, defined by the binary logarithm of the + desired size. Supported values are: + + ``0`` = 1 byte + + ``1`` = 2 bytes + + ``2`` = 4 bytes + + ``3`` = 8 bytes + + ``r7``: Number of elements. + + ``r8``: Operation. Supported values are: + + ``0``: copy + + ``1``: xor Returns: - H_SUCCESS : Success - H_PARAMETER : Invalid argument + ``H_SUCCESS``: Success. + ``H_PARAMETER``: Invalid argument. |