xref: /qemu/docs/specs/ppc-spapr-hcalls.rst (revision 9277d81f5c2c6f4d0b5e47c8476eb7ee7e5c0beb)
1c73e3771SBenjamin HerrenschmidtWhen used with the "pseries" machine type, QEMU-system-ppc64 implements
2c73e3771SBenjamin Herrenschmidta set of hypervisor calls using a subset of the server "PAPR" specification
3c73e3771SBenjamin Herrenschmidt(IBM internal at this point), which is also what IBM's proprietary hypervisor
4c73e3771SBenjamin Herrenschmidtadheres too.
5c73e3771SBenjamin Herrenschmidt
6c73e3771SBenjamin HerrenschmidtThe subset is selected based on the requirements of Linux as a guest.
7c73e3771SBenjamin Herrenschmidt
8c73e3771SBenjamin HerrenschmidtIn addition to those calls, we have added our own private hypervisor
9c73e3771SBenjamin Herrenschmidtcalls which are mostly used as a private interface between the firmware
10c73e3771SBenjamin Herrenschmidtrunning in the guest and QEMU.
11c73e3771SBenjamin Herrenschmidt
12c73e3771SBenjamin HerrenschmidtAll those hypercalls start at hcall number 0xf000 which correspond
13*9277d81fSVille Skyttäto an implementation specific range in PAPR.
14c73e3771SBenjamin Herrenschmidt
15c73e3771SBenjamin Herrenschmidt- H_RTAS (0xf000)
16c73e3771SBenjamin Herrenschmidt
17c73e3771SBenjamin HerrenschmidtRTAS is a set of runtime services generally provided by the firmware
18c73e3771SBenjamin Herrenschmidtinside the guest to the operating system. It predates the existence
19c73e3771SBenjamin Herrenschmidtof hypervisors (it was originally an extension to Open Firmware) and
20c73e3771SBenjamin Herrenschmidtis still used by PAPR to provide various services that aren't performance
21c73e3771SBenjamin Herrenschmidtsensitive.
22c73e3771SBenjamin Herrenschmidt
23c73e3771SBenjamin HerrenschmidtWe currently implement the RTAS services in QEMU itself. The actual RTAS
24c73e3771SBenjamin Herrenschmidt"firmware" blob in the guest is a small stub of a few instructions which
25c73e3771SBenjamin Herrenschmidtcalls our private H_RTAS hypervisor call to pass the RTAS calls to QEMU.
26c73e3771SBenjamin Herrenschmidt
27c73e3771SBenjamin HerrenschmidtArguments:
28c73e3771SBenjamin Herrenschmidt
29c73e3771SBenjamin Herrenschmidt  r3 : H_RTAS (0xf000)
30c73e3771SBenjamin Herrenschmidt  r4 : Guest physical address of RTAS parameter block
31c73e3771SBenjamin Herrenschmidt
32c73e3771SBenjamin HerrenschmidtReturns:
33c73e3771SBenjamin Herrenschmidt
340546b8c2SStefan Weil  H_SUCCESS   : Successfully called the RTAS function (RTAS result
35c73e3771SBenjamin Herrenschmidt                will have been stored in the parameter block)
36c73e3771SBenjamin Herrenschmidt  H_PARAMETER : Unknown token
37c73e3771SBenjamin Herrenschmidt
38c73e3771SBenjamin Herrenschmidt- H_LOGICAL_MEMOP (0xf001)
39c73e3771SBenjamin Herrenschmidt
40c73e3771SBenjamin HerrenschmidtWhen the guest runs in "real mode" (in powerpc lingua this means
41c73e3771SBenjamin Herrenschmidtwith MMU disabled, ie guest effective == guest physical), it only
42c73e3771SBenjamin Herrenschmidthas access to a subset of memory and no IOs.
43c73e3771SBenjamin Herrenschmidt
4467cc32ebSVeres LajosPAPR provides a set of hypervisor calls to perform cacheable or
4567cc32ebSVeres Lajosnon-cacheable accesses to any guest physical addresses that the
46c73e3771SBenjamin Herrenschmidtguest can use in order to access IO devices while in real mode.
47c73e3771SBenjamin Herrenschmidt
48c73e3771SBenjamin HerrenschmidtThis is typically used by the firmware running in the guest.
49c73e3771SBenjamin Herrenschmidt
50c73e3771SBenjamin HerrenschmidtHowever, doing a hypercall for each access is extremely inefficient
51c73e3771SBenjamin Herrenschmidt(even more so when running KVM) when accessing the frame buffer. In
52c73e3771SBenjamin Herrenschmidtthat case, things like scrolling become unusably slow.
53c73e3771SBenjamin Herrenschmidt
54c73e3771SBenjamin HerrenschmidtThis hypercall allows the guest to request a "memory op" to be applied
55c73e3771SBenjamin Herrenschmidtto memory. The supported memory ops at this point are to copy a range
56c73e3771SBenjamin Herrenschmidtof memory (supports overlap of source and destination) and XOR which
57c73e3771SBenjamin Herrenschmidtis used by our SLOF firmware to invert the screen.
58c73e3771SBenjamin Herrenschmidt
59c73e3771SBenjamin HerrenschmidtArguments:
60c73e3771SBenjamin Herrenschmidt
61c73e3771SBenjamin Herrenschmidt  r3: H_LOGICAL_MEMOP (0xf001)
62c73e3771SBenjamin Herrenschmidt  r4: Guest physical address of destination
63c73e3771SBenjamin Herrenschmidt  r5: Guest physical address of source
64c73e3771SBenjamin Herrenschmidt  r6: Individual element size
65c73e3771SBenjamin Herrenschmidt        0 = 1 byte
66c73e3771SBenjamin Herrenschmidt        1 = 2 bytes
67c73e3771SBenjamin Herrenschmidt        2 = 4 bytes
68c73e3771SBenjamin Herrenschmidt        3 = 8 bytes
69c73e3771SBenjamin Herrenschmidt  r7: Number of elements
70c73e3771SBenjamin Herrenschmidt  r8: Operation
71c73e3771SBenjamin Herrenschmidt        0 = copy
72c73e3771SBenjamin Herrenschmidt        1 = xor
73c73e3771SBenjamin Herrenschmidt
74c73e3771SBenjamin HerrenschmidtReturns:
75c73e3771SBenjamin Herrenschmidt
76c73e3771SBenjamin Herrenschmidt  H_SUCCESS   : Success
77c73e3771SBenjamin Herrenschmidt  H_PARAMETER : Invalid argument
78c73e3771SBenjamin Herrenschmidt
79