docs/specs/ppc-spapr-hcalls.rst

   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.