Vaibhav Jain's on August 28, 2019 1:23 am: > This doc patch provides an initial description of the hcall op-codes > that are used by Linux kernel running as a guest (LPAR) on top of > PowerVM or any other sPAPR compliant hyper-visor (e.g qemu). > > Apart from documenting the hcalls the doc-patch also provides a > rudimentary overview of how hcall ABI, how they are issued with the > Linux kernel and how information/control flows between the guest and > hypervisor. > > Signed-off-by: Vaibhav Jain <vaib...@linux.ibm.com> > --- > Change-log: > > Initial version of this doc-patch was posted and reviewed as part of > the patch-series "[PATCH v5 0/4] powerpc/papr_scm: Workaround for > failure of drc bind after kexec" > https://patchwork.ozlabs.org/patch/1136022/. Changes introduced on top > the original patch: > > * Replaced the of term PHYP with Hypervisor to indicate both > PowerVM/Qemu [Laurent] > * Emphasized that In/Out arguments to hcalls are in Big-endian format > [Laurent] > * Fixed minor word repetition, spell issues and grammatical error > [Michal, Mpe] > * Replaced various variant of term 'hcall' with a single > variant. [Mpe] > * Changed the documentation format from txt to ReST. [Mpe] > * Changed the name of documentation file to papr_hcalls.rst. [Mpe] > * Updated the section describing privileged operation by hypervisor > to be more accurate [Mpe]. > * Fixed up mention of register notation used for describing > hcalls. [Mpe] > * s/NVDimm/NVDIMM [Mpe] > * Added section on return values from hcall [Mpe] > * Described H_CONTINUE return-value for long running hcalls. > --- > Documentation/powerpc/papr_hcalls.rst | 200 ++++++++++++++++++++++++++ > 1 file changed, 200 insertions(+) > create mode 100644 Documentation/powerpc/papr_hcalls.rst > > diff --git a/Documentation/powerpc/papr_hcalls.rst > b/Documentation/powerpc/papr_hcalls.rst > new file mode 100644 > index 000000000000..7afc0310de29 > --- /dev/null > +++ b/Documentation/powerpc/papr_hcalls.rst > @@ -0,0 +1,200 @@ > +=========================== > +Hypercall Op-codes (hcalls) > +=========================== > + > +Overview > +========= > + > +Virtualization on 64-bit Power Book3S Platforms is based on the PAPR > +specification [1]_ which describes the run-time environment for a guest > +operating system and how it should interact with the hypervisor for > +privileged operations. Currently there are two PAPR compliant hypervisors: > + > +- **IBM PowerVM (PHYP)**: IBM's proprietary hypervisor that supports AIX, > + IBM-i and Linux as supported guests (termed as Logical Partitions > + or LPARS). It supports the full PAPR specification. > + > +- **Qemu/KVM**: Supports PPC64 linux guests running on a PPC64 linux host. > + Though it only implements a subset of PAPR specification called LoPAPR > [2]_. > + > +On PPC64 arch a guest kernel running on top of a PAPR hypervisor is called > +a *pSeries guest*. A pseries guest runs in a supervisor mode (HV=0) and must > +issue hypercalls to the hypervisor whenever it needs to perform an action > +that is hypervisor priviledged [3]_ or for other services managed by the > +hypervisor. > + > +Hence a Hypercall (hcall) is essentially a request by the pSeries guest > +asking hypervisor to perform a privileged operation on behalf of the guest. > The > +guest issues a with necessary input operands. The hypervisor after performing > +the privilege operation returns a status code and output operands back to the > +guest. > + > +HCALL ABI > +========= > +The ABI specification for a hcall between a pSeries guest and PAPR hypervisor > +is covered in section 14.5.3 of ref [2]_. Switch to the Hypervisor context > is > +done via the instruction **HVCS** that expects the Opcode for hcall is set > in *r3* > +and any in-arguments for the hcall are provided in registers *r4-r12* in > +Big-endian byte order. > + > +Once control is returns back to the guest after hypervisor has serviced the > +'HVCS' instruction the return value of the hcall is available in *r3* and any > +out values are returned in registers *r4-r12*. Again like in-arguments, all > the > +out value are in Big-endian byte order. > + > +Powerpc arch code provides convenient wrappers named **plpar_hcall_xxx** > defined > +in a arch specific header [4]_ to issue hcalls from the linux kernel > +running as pseries guest.
Thanks for this. Any chance you could replace the hcall convention in exception-64s.S with a link to this document, and add it in here? It needs a small fix or two as well, I think I put an ePAPR convention of r11 for number in there. Thanks, Nick
