Re: [PATCH] Documentation/kvm : Add documentation on Hypercalls

[Raghavendra K T]

On 07/24/2012 05:43 PM, Alexander Graf wrote:
> On 07/24/2012 10:53 AM, Raghavendra K T wrote:
> > From: Raghavendra K T <raghavendra.kt@xxxxxxxxxxxxxxxxxx>
> >
> > Thanks Alex for KVM_HC_FEATURES inputs and Jan for VAPIC_POLL_IRQ,
> > and Peter (HPA) for suggesting hypercall ABI addition.
> >
> > Signed-off-by: Raghavendra K T <raghavendra.kt@xxxxxxxxxxxxxxxxxx>
> > ---
> > Please have a closer look at Hypercall ABI newly added
> >
> > Changes since last post:
> > - Added hypercall ABI (Peter)
> > - made KVM_HC_VAPIC_POLL_IRQ active explicitly (Randy)
> >
> > TODO: We need to add history details of each hypercall as suggested by
> > HPA,
> > which I could not trace easily. Hope it is easy for hypercall authors
> >
> > Documentation/virtual/hypercalls.txt | 71
> > ++++++++++++++++++++++++++++++++++
> > 1 files changed, 71 insertions(+), 0 deletions(-)
> > create mode 100644 Documentation/virtual/hypercalls.txt
> >
> > diff --git a/Documentation/virtual/hypercalls.txt
> > b/Documentation/virtual/hypercalls.txt
> > new file mode 100644
> > index 0000000..caffc08
> > --- /dev/null
> > +++ b/Documentation/virtual/hypercalls.txt
> > @@ -0,0 +1,71 @@
> > +Hypercall ABI:
> > +=============
> > +A brief look at calling conventions of X86, S390 and PPC
> > +X86:
> > + KVM Hypercalls have a three-byte sequence of either the vmrun or the
> > vmmrun
> > + instruction. The hypervisor can replace it with instructions that are
> > + guaranteed to be supported.
> > +
> > + Up to four arguments may be passed in rbx, rcx, rdx, and rsi
> > respectively.
> > + The hypercall number should be placed in rax and the return value
> > will be
> > + placed in rax. No other registers will be clobbered unless
> > explicitly stated
> > + by the particular hypercall.
> > +
> > +S390:
> > + R2-R7 are used for parameters 1-6. In addition, R1 is used for
> > hypercall
> > + number. The return value is written to R2.
> > +
> > + S390 uses diagnose instruction as hypercall (0x500) along with
> > hypercall
> > + number in R1.
> > +
> > + PoewerPC:
>
> PowerPC

Sorry for the typo.

> > + It uses R3-R10 and hypercall number in R11. R4-R11 are used as
> > output registers.
> > + Return value is placed in R3.
> > +
> > + KVM hypercalls uses 4 byte opcode, that are patched with
> > 'hypercall-instructions'
> > + property inside the device tree's /hypervisor node.
> > + For more information refer to Documentation/virtual/kvm/ppc-pv.txt
>
> What exactly is this document supposed to cover? We have 3 different
> hypercall ABIs in KVM on PowerPC:

Thanks for the detailed information on PPC hypercalls.
My intention was to cover KVM specific hypercalls here.

Patch is wrongly generated against Documentation/virtual/ instead of
Documentation/virtual/kvm will correct that.

Information you have provided should be very useful in understanding
PPC hypercalls. Do you wish to have (2), (3) below goto some doc?


> 1) KVM hypercalls (ePAPR)
>
> The ePAPR compliant hypercall implementation. This one is used for KVM
> specific hypercalls. All hypercalls get a KVM vendor prefix (42) and
> then the hypercall id. We also implement generic hypercalls here, like
> the ePAPR idle hcall. The instruction sequence for these is listed in
> the device tree, as you noted above. It's available on all targets.
>
> 2) PAPR hypercalls
>
> To run server PowerPC PAPR guests (-M pseries in QEMU), we need to
> handle PAPR hypercalls. These are the same hypercalls that pHyp, the
> POWER hypervisor implements. Some of them are handled in the kernel,
> some are handled in user space. This is only available on book3s_64.
>
> 3) OSI hypercalls
>
> In parallel to QEMU, there is another user of KVM on PowerPC:
> Mac-on-Linux. That project had its own hypercalls long before we came
> along with KVM, so to maintain compatibility we also support their
> hypercalls. All of these get forwarded to user space. This is only
> useful on book3s_32, but can be used with book3s_64 as well.
>
> > +
> > +KVM Hypercalls Documentation
> > +===========================
> > +The template for each hypercall is:
> > +1. Hypercall name, value.
> > +2. Architecture(s)
> > +3. Status (deprecated, obsolete, active)
> > +4. Purpose
> > +
> > +1. KVM_HC_VAPIC_POLL_IRQ
> > +------------------------
> > +Value: 1
>
> What are the value fields supposed to mean?

Value field is just #define value of the hypercall in header.
If that does not make much sense probably it can be dropped.

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/