docs: rSTify ppc-spapr-hcalls.txt

Signed-off-by: Leonardo Garcia <lagarcia@br.ibm.com>
Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com>
[ clg: - replaced lingua by terminology
       - add a new line at EOF ]
Message-Id: <e20319dcf0ec37bedd915c740c3813eb0e58ead4.1638982486.git.lagarcia@br.ibm.com>
Signed-off-by: Cédric Le Goater <clg@kaod.org>
This commit is contained in:
Leonardo Garcia 2021-12-17 17:57:13 +01:00 committed by Cédric Le Goater
parent 88581cc43b
commit d483f2b53a
1 changed files with 57 additions and 35 deletions

View File

@ -1,9 +1,15 @@
When used with the "pseries" machine type, QEMU-system-ppc64 implements sPAPR hypervisor calls
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.
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 In addition to those calls, we have added our own private hypervisor
calls which are mostly used as a private interface between the firmware 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 All those hypercalls start at hcall number 0xf000 which correspond
to an implementation specific range in PAPR. 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 RTAS stands for Run-Time Abstraction Sercies and is a set of runtime services
inside the guest to the operating system. It predates the existence generally provided by the firmware inside the guest to the operating system. It
of hypervisors (it was originally an extension to Open Firmware) and predates the existence of hypervisors (it was originally an extension to Open
is still used by PAPR to provide various services that aren't performance Firmware) and is still used by PAPR and LoPAR to provide various services that
sensitive. are not performance sensitive.
We currently implement the RTAS services in QEMU itself. The actual RTAS 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 "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: Arguments:
r3 : H_RTAS (0xf000) ``r3``: ``H_RTAS (0xf000)``
r4 : Guest physical address of RTAS parameter block
``r4``: Guest physical address of RTAS parameter block.
Returns: Returns:
H_SUCCESS : Successfully called the RTAS function (RTAS result ``H_SUCCESS``: Successfully called the RTAS function (RTAS result will have
will have been stored in the parameter block) been stored in the parameter block).
H_PARAMETER : Unknown token
- H_LOGICAL_MEMOP (0xf001) ``H_PARAMETER``: Unknown token.
When the guest runs in "real mode" (in powerpc lingua this means H_LOGICAL_MEMOP (0xf001)
with MMU disabled, ie guest effective == guest physical), it only ^^^^^^^^^^^^^^^^^^^^^^^^
has access to a subset of memory and no IOs.
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 non-cacheable accesses to any guest physical addresses that the
guest can use in order to access IO devices while in real mode. 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: Arguments:
r3: H_LOGICAL_MEMOP (0xf001) ``r3 ``: ``H_LOGICAL_MEMOP (0xf001)``
r4: Guest physical address of destination
r5: Guest physical address of source ``r4``: Guest physical address of destination.
r6: Individual element size
0 = 1 byte ``r5``: Guest physical address of source.
1 = 2 bytes
2 = 4 bytes ``r6``: Individual element size, defined by the binary logarithm of the
3 = 8 bytes desired size. Supported values are:
r7: Number of elements
r8: Operation ``0`` = 1 byte
0 = copy
1 = xor ``1`` = 2 bytes
``2`` = 4 bytes
``3`` = 8 bytes
``r7``: Number of elements.
``r8``: Operation. Supported values are:
``0``: copy
``1``: xor
Returns: Returns:
H_SUCCESS : Success ``H_SUCCESS``: Success.
H_PARAMETER : Invalid argument
``H_PARAMETER``: Invalid argument.