From patchwork Wed Jan 12 11:55:24 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?C=C3=A9dric_Le_Goater?= X-Patchwork-Id: 1579080 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by bilbo.ozlabs.org (Postfix) with ESMTPS id 4JYnC943T3z9s0r for ; Wed, 12 Jan 2022 23:37:41 +1100 (AEDT) Received: from localhost ([::1]:56028 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n7csl-0006vK-9R for incoming@patchwork.ozlabs.org; Wed, 12 Jan 2022 07:37:39 -0500 Received: from eggs.gnu.org ([209.51.188.92]:60646) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n7cEw-0006To-EA; Wed, 12 Jan 2022 06:56:30 -0500 Received: from mx0a-001b2d01.pphosted.com ([148.163.156.1]:20112) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n7cEn-0007V8-OZ; Wed, 12 Jan 2022 06:56:30 -0500 Received: from pps.filterd (m0098410.ppops.net [127.0.0.1]) by mx0a-001b2d01.pphosted.com (8.16.1.2/8.16.1.2) with SMTP id 20CAuV37006856; Wed, 12 Jan 2022 11:56:13 GMT Received: from ppma03ams.nl.ibm.com (62.31.33a9.ip4.static.sl-reverse.com [169.51.49.98]) by mx0a-001b2d01.pphosted.com with ESMTP id 3dhwp723c5-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Wed, 12 Jan 2022 11:56:13 +0000 Received: from pps.filterd (ppma03ams.nl.ibm.com [127.0.0.1]) by ppma03ams.nl.ibm.com (8.16.1.2/8.16.1.2) with SMTP id 20CBmJB9027661; Wed, 12 Jan 2022 11:56:10 GMT Received: from b06cxnps4074.portsmouth.uk.ibm.com (d06relay11.portsmouth.uk.ibm.com [9.149.109.196]) by ppma03ams.nl.ibm.com with ESMTP id 3df289tmfg-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Wed, 12 Jan 2022 11:56:10 +0000 Received: from d06av24.portsmouth.uk.ibm.com (d06av24.portsmouth.uk.ibm.com [9.149.105.60]) by b06cxnps4074.portsmouth.uk.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id 20CBu7me40370592 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 12 Jan 2022 11:56:07 GMT Received: from d06av24.portsmouth.uk.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id 788534207E; Wed, 12 Jan 2022 11:56:07 +0000 (GMT) Received: from d06av24.portsmouth.uk.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id 35C524207D; Wed, 12 Jan 2022 11:56:07 +0000 (GMT) Received: from smtp.tlslab.ibm.com (unknown [9.101.4.1]) by d06av24.portsmouth.uk.ibm.com (Postfix) with SMTP; Wed, 12 Jan 2022 11:56:07 +0000 (GMT) Received: from yukon.ibmuc.com (unknown [9.171.70.95]) by smtp.tlslab.ibm.com (Postfix) with ESMTP id 7D1BE2201C6; Wed, 12 Jan 2022 12:56:06 +0100 (CET) From: =?utf-8?q?C=C3=A9dric_Le_Goater?= To: qemu-ppc@nongnu.org, qemu-devel@nongnu.org Subject: [PULL 07/34] docs: Clarifications and formatting changes in ppc docs. Date: Wed, 12 Jan 2022 12:55:24 +0100 Message-Id: <20220112115551.987666-8-clg@kaod.org> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20220112115551.987666-1-clg@kaod.org> References: <20220112115551.987666-1-clg@kaod.org> X-TM-AS-GCONF: 00 X-Proofpoint-GUID: m6gGAhl98ZQbbHfvRJb8o01S0qhwlFV8 X-Proofpoint-ORIG-GUID: m6gGAhl98ZQbbHfvRJb8o01S0qhwlFV8 X-Proofpoint-UnRewURL: 0 URL was un-rewritten MIME-Version: 1.0 X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.205,Aquarius:18.0.790,Hydra:6.0.425,FMLib:17.11.62.513 definitions=2022-01-12_04,2022-01-11_01,2021-12-02_01 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 suspectscore=0 adultscore=0 clxscore=1034 priorityscore=1501 malwarescore=0 phishscore=0 lowpriorityscore=0 impostorscore=0 mlxscore=0 mlxlogscore=999 spamscore=0 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2110150000 definitions=main-2201120075 Received-SPF: softfail client-ip=148.163.156.1; envelope-from=clg@kaod.org; helo=mx0a-001b2d01.pphosted.com X-Spam_score_int: -11 X-Spam_score: -1.2 X-Spam_bar: - X-Spam_report: (-1.2 / 5.0 requ) BAYES_00=-1.9, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_SOFTFAIL=0.665, T_SPF_HELO_TEMPERROR=0.01 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Leonardo Garcia , Peter Maydell , Richard Henderson , =?utf-8?q?C=C3=A9dric_Le_?= =?utf-8?q?Goater?= Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" From: Leonardo Garcia Signed-off-by: Leonardo Garcia Reviewed-by: Cédric Le Goater Message-Id: <3b228af4785241c7fb4a2c70f0c495d2a9adea83.1641405872.git.lagarcia@br.ibm.com> Signed-off-by: Cédric Le Goater --- docs/specs/ppc-spapr-hcalls.rst | 21 ++++++++--------- docs/system/ppc/pseries.rst | 42 ++++++++++++++++----------------- 2 files changed, 31 insertions(+), 32 deletions(-) diff --git a/docs/specs/ppc-spapr-hcalls.rst b/docs/specs/ppc-spapr-hcalls.rst index 28daf9734a8e..6cdcef20265e 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) -`_. -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 diff --git a/docs/system/ppc/pseries.rst b/docs/system/ppc/pseries.rst index 16394fa5218b..16893248151f 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) -`_ -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 `_ (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 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) -`_. +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 @@ -264,8 +261,11 @@ enabled, whether or not the guest has actually entered secure mode. Maintainer contact information ------------------------------- +============================== Cédric Le Goater Daniel Henrique Barboza + +.. [LoPAR] `Linux on Power Architecture Reference document (LoPAR) revision + 2.9 `_.