[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 017/102] docs: rSTify ppc-spapr-hcalls.txt
From: |
Cédric Le Goater |
Subject: |
[PULL 017/102] docs: rSTify ppc-spapr-hcalls.txt |
Date: |
Wed, 15 Dec 2021 18:02:32 +0100 |
From: Leonardo Garcia <lagarcia@br.ibm.com>
Signed-off-by: Leonardo Garcia <lagarcia@br.ibm.com>
Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com>
[ clg: replaced lingua by terminology ]
Message-Id:
<e20319dcf0ec37bedd915c740c3813eb0e58ead4.1638982486.git.lagarcia@br.ibm.com>
Signed-off-by: Cédric Le Goater <clg@kaod.org>
---
docs/specs/ppc-spapr-hcalls.txt | 92 ++++++++++++++++++++-------------
1 file changed, 57 insertions(+), 35 deletions(-)
diff --git a/docs/specs/ppc-spapr-hcalls.txt b/docs/specs/ppc-spapr-hcalls.txt
index 93fe3da91b16..72a768b5a038 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.
\ No newline at end of file
--
2.31.1
- [PULL 014/102] docs/system/ppc/powernv.rst: document KVM support status, (continued)
- [PULL 014/102] docs/system/ppc/powernv.rst: document KVM support status, Cédric Le Goater, 2021/12/15
- [PULL 018/102] docs: Rename ppc-spapr-hcalls.txt to ppc-spapr-hcalls.rst., Cédric Le Goater, 2021/12/15
- [PULL 019/102] Link new ppc-spapr-hcalls.rst file to pseries.rst., Cédric Le Goater, 2021/12/15
- [PULL 015/102] ppc/pnv.c: fix "system-id" FDT when -uuid is set, Cédric Le Goater, 2021/12/15
- [PULL 021/102] softfloat: Add flag specific to Inf - Inf, Cédric Le Goater, 2021/12/15
- [PULL 023/102] softfloat: Add flags specific to Inf / Inf and 0 / 0, Cédric Le Goater, 2021/12/15
- [PULL 026/102] softfloat: Add flag specific to signaling nans, Cédric Le Goater, 2021/12/15
- [PULL 027/102] target/ppc: Update float_invalid_op_addsub for new flags, Cédric Le Goater, 2021/12/15
- [PULL 025/102] softfloat: Add flag specific to convert non-nan to int, Cédric Le Goater, 2021/12/15
- [PULL 022/102] softfloat: Add flag specific to Inf * 0, Cédric Le Goater, 2021/12/15
- [PULL 017/102] docs: rSTify ppc-spapr-hcalls.txt,
Cédric Le Goater <=
- [PULL 024/102] softfloat: Add flag specific to sqrt(-x), Cédric Le Goater, 2021/12/15
- [PULL 028/102] target/ppc: Update float_invalid_op_mul for new flags, Cédric Le Goater, 2021/12/15
- [PULL 016/102] docs: Introducing pseries documentation., Cédric Le Goater, 2021/12/15
- [PULL 037/102] target/ppc: Update fmadd for new flags, Cédric Le Goater, 2021/12/15
- [PULL 031/102] target/ppc: Update float_invalid_cvt for new flags, Cédric Le Goater, 2021/12/15
- [PULL 020/102] softfloat: Extend float_exception_flags to 16 bits, Cédric Le Goater, 2021/12/15
- [PULL 035/102] target/ppc: Tidy inexact handling in do_fri, Cédric Le Goater, 2021/12/15
- [PULL 044/102] target/ppc: Update xsrqpi and xsrqpxp to new flags, Cédric Le Goater, 2021/12/15
- [PULL 034/102] target/ppc: Use FloatRoundMode in do_fri, Cédric Le Goater, 2021/12/15
- [PULL 041/102] target/ppc: Update do_frsp for new flags, Cédric Le Goater, 2021/12/15