docs/specs/ppc-spapr-hcalls.rst | 22 ++++++++--------- docs/system/ppc/pseries.rst | 43 +++++++++++++++++---------------- 2 files changed, 33 insertions(+), 32 deletions(-)
From: Leonardo Garcia <lagarcia@br.ibm.com>
Signed-off-by: Leonardo Garcia <lagarcia@br.ibm.com>
---
docs/specs/ppc-spapr-hcalls.rst | 22 ++++++++---------
docs/system/ppc/pseries.rst | 43 +++++++++++++++++----------------
2 files changed, 33 insertions(+), 32 deletions(-)
diff --git a/docs/specs/ppc-spapr-hcalls.rst b/docs/specs/ppc-spapr-hcalls.rst
index 28daf9734a..b4a18a01e6 100644
--- a/docs/specs/ppc-spapr-hcalls.rst
+++ b/docs/specs/ppc-spapr-hcalls.rst
@@ -1,13 +1,12 @@
+======================
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)
-<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.
+a set of hypervisor calls (a.k.a. hcalls) defined in the Linux on Power
+Architecture Reference ([LoPAR]_) document. 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.
@@ -18,8 +17,8 @@ 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 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
@@ -44,8 +43,8 @@ Returns:
``H_PARAMETER``: Unknown token.
-H_LOGICAL_MEMOP (0xf001)
-^^^^^^^^^^^^^^^^^^^^^^^^
+``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
@@ -98,3 +97,4 @@ Returns:
``H_SUCCESS``: Success.
``H_PARAMETER``: Invalid argument.
+
diff --git a/docs/system/ppc/pseries.rst b/docs/system/ppc/pseries.rst
index 72e315eff6..ead33e6764 100644
--- a/docs/system/ppc/pseries.rst
+++ b/docs/system/ppc/pseries.rst
@@ -1,19 +1,18 @@
+===================================
pSeries family boards (``pseries``)
===================================
-The Power machine para-virtualized environment described by the `Linux on Power
-Architecture Reference document (LoPAR)
-<https://openpowerfoundation.org/wp-content/uploads/2020/07/LoPAR-20200812.pdf>`_
-is called pSeries. This environment is also known as sPAPR, System p guests, or
-simply Power Linux guests (although it is capable of running other operating
-systems, such as AIX).
+The Power machine para-virtualized environment described by the Linux on Power
+Architecture Reference ([LoPAR]_) document is called pSeries. This environment
+is also known as sPAPR, System p guests, or simply Power Linux guests (although
+it is capable of running other operating systems, such as AIX).
Even though pSeries is designed to behave as a guest environment, it is also
capable of acting as a hypervisor OS, providing, on that role, nested
virtualization capabilities.
Supported devices
------------------
+=================
* Multi processor support for many Power processors generations: POWER7,
POWER7+, POWER8, POWER8NVL, POWER9, and Power10. Support for POWER5+ exists,
@@ -26,12 +25,12 @@ Supported devices
* PCIe device pass through.
Missing devices
----------------
+===============
* SPICE support.
Firmware
---------
+========
`SLOF <https://github.com/aik/SLOF>`_ (Slimline Open Firmware) is an
implementation of the `IEEE 1275-1994, Standard for Boot (Initialization
@@ -42,14 +41,14 @@ QEMU includes a prebuilt image of SLOF which is updated when a more recent
version is required.
Build directions
-----------------
+================
.. code-block:: bash
./configure --target-list=ppc64-softmmu && make
Running instructions
---------------------
+====================
Someone can select the pSeries machine type by running QEMU with the following
options:
@@ -59,7 +58,7 @@ options:
qemu-system-ppc64 -M pseries <other QEMU arguments>
sPAPR devices
--------------
+=============
The sPAPR specification defines a set of para-virtualized devices, which are
also supported by the pSeries machine in QEMU and can be instantiated with the
@@ -102,11 +101,9 @@ device, or specify one with an ID
NVRAM device with ``-global spapr-nvram.drive=pfid``.
sPAPR specification
-^^^^^^^^^^^^^^^^^^^
+-------------------
-The main source of documentation on the sPAPR standard is the `Linux on Power
-Architecture Reference document (LoPAR)
-<https://openpowerfoundation.org/wp-content/uploads/2020/07/LoPAR-20200812.pdf>`_.
+The main source of documentation on the sPAPR standard is the [LoPAR]_ document.
However, documentation specific to QEMU's implementation of the specification
can also be found in QEMU documentation:
@@ -124,7 +121,7 @@ Other documentation available in QEMU docs directory:
(``/docs/specs/ppc-spapr-uv-hcalls.txt``).
Switching between the KVM-PR and KVM-HV kernel module
------------------------------------------------------
+=====================================================
Currently, there are two implementations of KVM on Power, ``kvm_hv.ko`` and
``kvm_pr.ko``.
@@ -139,7 +136,7 @@ possible to switch between the two modes with the ``kvm-type`` parameter:
instead.
KVM-PR
-^^^^^^
+------
KVM-PR uses the so-called **PR**\ oblem state of the PPC CPUs to run the guests,
i.e. the virtual machine is run in user mode and all privileged instructions
@@ -166,7 +163,7 @@ In order to run KVM-PR guests with POWER9 processors, someone will need to start
QEMU with ``kernel_irqchip=off`` command line option.
KVM-HV
-^^^^^^
+------
KVM-HV uses the hypervisor mode of more recent Power processors, that allow
access to the bare metal hardware directly. Although POWER7 had this capability,
@@ -188,7 +185,7 @@ CPUs generations, e.g. you can run a POWER7 guest on a POWER8 host by using
``-cpu POWER8,compat=power7`` as parameter to QEMU.
Modules support
----------------
+===============
As noticed in the sections above, each module can run in a different
environment. The following table shows with which environment each module can
@@ -231,8 +228,12 @@ nested. Combinations not shown in the table are not available.
.. [3] Introduced on Power10 machines.
Maintainer contact information
-------------------------------
+==============================
Cédric Le Goater <clg@kaod.org>
Daniel Henrique Barboza <danielhb413@gmail.com>
+
+.. [LoPAR] `Linux on Power Architecture Reference document (LoPAR) revision
+ 2.9 <https://openpowerfoundation.org/wp-content/uploads/2020/07/LoPAR-20200812.pdf>`_.
+
--
2.33.1
On 1/5/22 19:08, lagarcia@linux.ibm.com wrote: > From: Leonardo Garcia <lagarcia@br.ibm.com> > > Signed-off-by: Leonardo Garcia <lagarcia@br.ibm.com> Reviewed-by: Cédric Le Goater <clg@kaod.org> One comment below. Thanks, C. > --- > docs/specs/ppc-spapr-hcalls.rst | 22 ++++++++--------- > docs/system/ppc/pseries.rst | 43 +++++++++++++++++---------------- > 2 files changed, 33 insertions(+), 32 deletions(-) > > diff --git a/docs/specs/ppc-spapr-hcalls.rst b/docs/specs/ppc-spapr-hcalls.rst > index 28daf9734a..b4a18a01e6 100644 > --- a/docs/specs/ppc-spapr-hcalls.rst > +++ b/docs/specs/ppc-spapr-hcalls.rst > @@ -1,13 +1,12 @@ > +====================== > 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) > -<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. > +a set of hypervisor calls (a.k.a. hcalls) defined in the Linux on Power > +Architecture Reference ([LoPAR]_) document. 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. > > @@ -18,8 +17,8 @@ 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 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 > @@ -44,8 +43,8 @@ Returns: > > ``H_PARAMETER``: Unknown token. > > -H_LOGICAL_MEMOP (0xf001) > -^^^^^^^^^^^^^^^^^^^^^^^^ > +``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 > @@ -98,3 +97,4 @@ Returns: > ``H_SUCCESS``: Success. > > ``H_PARAMETER``: Invalid argument. > + > diff --git a/docs/system/ppc/pseries.rst b/docs/system/ppc/pseries.rst > index 72e315eff6..ead33e6764 100644 > --- a/docs/system/ppc/pseries.rst > +++ b/docs/system/ppc/pseries.rst > @@ -1,19 +1,18 @@ > +=================================== > pSeries family boards (``pseries``) > =================================== > > -The Power machine para-virtualized environment described by the `Linux on Power > -Architecture Reference document (LoPAR) > -<https://openpowerfoundation.org/wp-content/uploads/2020/07/LoPAR-20200812.pdf>`_ > -is called pSeries. This environment is also known as sPAPR, System p guests, or > -simply Power Linux guests (although it is capable of running other operating > -systems, such as AIX). > +The Power machine para-virtualized environment described by the Linux on Power > +Architecture Reference ([LoPAR]_) document is called pSeries. This environment > +is also known as sPAPR, System p guests, or simply Power Linux guests (although > +it is capable of running other operating systems, such as AIX). > > Even though pSeries is designed to behave as a guest environment, it is also > capable of acting as a hypervisor OS, providing, on that role, nested > virtualization capabilities. > > Supported devices > ------------------ > +================= > > * Multi processor support for many Power processors generations: POWER7, > POWER7+, POWER8, POWER8NVL, POWER9, and Power10. Support for POWER5+ exists, pseries with 970, 970MP, POWER5+ CPUs are supported now (TCG only). POWER7 on KVM has an uncertain status. > @@ -26,12 +25,12 @@ Supported devices > * PCIe device pass through. > > Missing devices > ---------------- > +=============== > > * SPICE support. > > Firmware > --------- > +======== > > `SLOF <https://github.com/aik/SLOF>`_ (Slimline Open Firmware) is an > implementation of the `IEEE 1275-1994, Standard for Boot (Initialization > @@ -42,14 +41,14 @@ QEMU includes a prebuilt image of SLOF which is updated when a more recent > version is required. > > Build directions > ----------------- > +================ > > .. code-block:: bash > > ./configure --target-list=ppc64-softmmu && make > > Running instructions > --------------------- > +==================== > > Someone can select the pSeries machine type by running QEMU with the following > options: > @@ -59,7 +58,7 @@ options: > qemu-system-ppc64 -M pseries <other QEMU arguments> > > sPAPR devices > -------------- > +============= > > The sPAPR specification defines a set of para-virtualized devices, which are > also supported by the pSeries machine in QEMU and can be instantiated with the > @@ -102,11 +101,9 @@ device, or specify one with an ID > NVRAM device with ``-global spapr-nvram.drive=pfid``. > > sPAPR specification > -^^^^^^^^^^^^^^^^^^^ > +------------------- > > -The main source of documentation on the sPAPR standard is the `Linux on Power > -Architecture Reference document (LoPAR) > -<https://openpowerfoundation.org/wp-content/uploads/2020/07/LoPAR-20200812.pdf>`_. > +The main source of documentation on the sPAPR standard is the [LoPAR]_ document. > However, documentation specific to QEMU's implementation of the specification > can also be found in QEMU documentation: > > @@ -124,7 +121,7 @@ Other documentation available in QEMU docs directory: > (``/docs/specs/ppc-spapr-uv-hcalls.txt``). > > Switching between the KVM-PR and KVM-HV kernel module > ------------------------------------------------------ > +===================================================== > > Currently, there are two implementations of KVM on Power, ``kvm_hv.ko`` and > ``kvm_pr.ko``. > @@ -139,7 +136,7 @@ possible to switch between the two modes with the ``kvm-type`` parameter: > instead. > > KVM-PR > -^^^^^^ > +------ > > KVM-PR uses the so-called **PR**\ oblem state of the PPC CPUs to run the guests, > i.e. the virtual machine is run in user mode and all privileged instructions > @@ -166,7 +163,7 @@ In order to run KVM-PR guests with POWER9 processors, someone will need to start > QEMU with ``kernel_irqchip=off`` command line option. > > KVM-HV > -^^^^^^ > +------ > > KVM-HV uses the hypervisor mode of more recent Power processors, that allow > access to the bare metal hardware directly. Although POWER7 had this capability, > @@ -188,7 +185,7 @@ CPUs generations, e.g. you can run a POWER7 guest on a POWER8 host by using > ``-cpu POWER8,compat=power7`` as parameter to QEMU. > > Modules support > ---------------- > +=============== > > As noticed in the sections above, each module can run in a different > environment. The following table shows with which environment each module can > @@ -231,8 +228,12 @@ nested. Combinations not shown in the table are not available. > .. [3] Introduced on Power10 machines. > > Maintainer contact information > ------------------------------- > +============================== > > Cédric Le Goater <clg@kaod.org> > > Daniel Henrique Barboza <danielhb413@gmail.com> > + > +.. [LoPAR] `Linux on Power Architecture Reference document (LoPAR) revision > + 2.9 <https://openpowerfoundation.org/wp-content/uploads/2020/07/LoPAR-20200812.pdf>`_. > + >
© 2016 - 2024 Red Hat, Inc.