From d55b123d141c78cc0d965243c543a7274810da33 Mon Sep 17 00:00:00 2001 From: Leonardo Garcia Date: Fri, 17 Dec 2021 17:57:13 +0100 Subject: docs: Rename ppc-spapr-hcalls.txt to ppc-spapr-hcalls.rst. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Leonardo Garcia Reviewed-by: Daniel Henrique Barboza Message-Id: <7f13e40e05ddb411697b0777b0e37757f76905e9.1638982486.git.lagarcia@br.ibm.com> Signed-off-by: Cédric Le Goater --- docs/specs/ppc-spapr-hcalls.rst | 100 ++++++++++++++++++++++++++++++++++++++++ docs/specs/ppc-spapr-hcalls.txt | 100 ---------------------------------------- 2 files changed, 100 insertions(+), 100 deletions(-) create mode 100644 docs/specs/ppc-spapr-hcalls.rst delete mode 100644 docs/specs/ppc-spapr-hcalls.txt (limited to 'docs/specs') diff --git a/docs/specs/ppc-spapr-hcalls.rst b/docs/specs/ppc-spapr-hcalls.rst new file mode 100644 index 0000000000..28daf9734a --- /dev/null +++ b/docs/specs/ppc-spapr-hcalls.rst @@ -0,0 +1,100 @@ +sPAPR hypervisor calls +---------------------- + +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) +`_. +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 +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) +^^^^^^^^^^^^^^^ + +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 +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. + +Returns: + + ``H_SUCCESS``: Successfully called the RTAS function (RTAS result will have + been stored in the parameter block). + + ``H_PARAMETER``: Unknown token. + +H_LOGICAL_MEMOP (0xf001) +^^^^^^^^^^^^^^^^^^^^^^^^ + +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. + +This is typically used by the firmware running in the guest. + +However, doing a hypercall for each access is extremely inefficient +(even more so when running KVM) when accessing the frame buffer. In +that case, things like scrolling become unusably slow. + +This hypercall allows the guest to request a "memory op" to be applied +to memory. The supported memory ops at this point are to copy a range +of memory (supports overlap of source and destination) and XOR which +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, 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. diff --git a/docs/specs/ppc-spapr-hcalls.txt b/docs/specs/ppc-spapr-hcalls.txt deleted file mode 100644 index 28daf9734a..0000000000 --- a/docs/specs/ppc-spapr-hcalls.txt +++ /dev/null @@ -1,100 +0,0 @@ -sPAPR hypervisor calls ----------------------- - -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) -`_. -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 -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) -^^^^^^^^^^^^^^^ - -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 -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. - -Returns: - - ``H_SUCCESS``: Successfully called the RTAS function (RTAS result will have - been stored in the parameter block). - - ``H_PARAMETER``: Unknown token. - -H_LOGICAL_MEMOP (0xf001) -^^^^^^^^^^^^^^^^^^^^^^^^ - -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. - -This is typically used by the firmware running in the guest. - -However, doing a hypercall for each access is extremely inefficient -(even more so when running KVM) when accessing the frame buffer. In -that case, things like scrolling become unusably slow. - -This hypercall allows the guest to request a "memory op" to be applied -to memory. The supported memory ops at this point are to copy a range -of memory (supports overlap of source and destination) and XOR which -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, 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. -- cgit v1.2.3