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

[Raghavendra K T <raghavendra.kt@linux.vnet.ibm.com>]

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@linux.vnet.ibm.com>
>>
>> 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@linux.vnet.ibm.com>
>> ---
>> 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.