[PATCH] Documentation/kvm : Add documentation on Hypercalls

[PATCH] Documentation/kvm : Add documentation on Hypercalls

[Raghavendra K T]

From: Raghavendra K T <raghavendra.kt@linux.vnet.ibm.com> 

Thanks Alex for KVM_HC_FEATURES inputs and Jan for VAPIC_POLL_IRQ 

Signed-off-by: Raghavendra K T <raghavendra.kt@linux.vnet.ibm.com>
---
diff --git a/Documentation/virtual/kvm/hypercalls.txt b/Documentation/virtual/kvm/hypercalls.txt
new file mode 100644
index 0000000..c79335a
--- /dev/null
+++ b/Documentation/virtual/kvm/hypercalls.txt
@@ -0,0 +1,46 @@
+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
+Architecture: x86
+Purpose: Trigger guest exit so that the host can check for pending
+interrupts on reentry.
+
+2. KVM_HC_MMU_OP
+------------------------
+Value: 2
+Architecture: x86
+Status: deprecated.
+Purpose: Support MMU operations such as writing to PTE,
+flushing TLB, release PT.
+
+3. KVM_HC_FEATURES
+------------------------
+Value: 3
+Architecture: PPC
+Status: active
+Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid
+used to enumerate which hypercalls are available. On PPC, either device tree
+based lookup ( which is also what EPAPR dictates) OR KVM specific enumeration
+mechanism (which is this hypercall) can be used.
+
+4. KVM_HC_PPC_MAP_MAGIC_PAGE
+------------------------
+Value: 4
+Architecture: PPC
+Status: active
+Purpose: To enable communication between the hypervisor and guest there is a
+shared page that contains parts of supervisor visible register state.
+The guest can map this shared page to access its supervisor register through
+memory using this hypercall.
+
+TODO:
+1. more information on input and output needed?
+2. Add more detail to purpose of hypercalls.

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

[Randy Dunlap]

On 05/31/2012 01:01 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 
> 
> Signed-off-by: Raghavendra K T <raghavendra.kt@linux.vnet.ibm.com>
> ---
> diff --git a/Documentation/virtual/kvm/hypercalls.txt b/Documentation/virtual/kvm/hypercalls.txt
> new file mode 100644
> index 0000000..c79335a
> --- /dev/null
> +++ b/Documentation/virtual/kvm/hypercalls.txt
> @@ -0,0 +1,46 @@
> +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
> +Architecture: x86


No "Status", does that imply "Active" ?

> +Purpose: Trigger guest exit so that the host can check for pending
> +interrupts on reentry.
> +
> +2. KVM_HC_MMU_OP
> +------------------------
> +Value: 2
> +Architecture: x86
> +Status: deprecated.
> +Purpose: Support MMU operations such as writing to PTE,
> +flushing TLB, release PT.
> +
> +3. KVM_HC_FEATURES
> +------------------------
> +Value: 3
> +Architecture: PPC
> +Status: active
> +Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid
> +used to enumerate which hypercalls are available. On PPC, either device tree
> +based lookup ( which is also what EPAPR dictates) OR KVM specific enumeration
> +mechanism (which is this hypercall) can be used.
> +
> +4. KVM_HC_PPC_MAP_MAGIC_PAGE
> +------------------------
> +Value: 4
> +Architecture: PPC
> +Status: active
> +Purpose: To enable communication between the hypervisor and guest there is a
> +shared page that contains parts of supervisor visible register state.
> +The guest can map this shared page to access its supervisor register through
> +memory using this hypercall.
> +
> +TODO:
> +1. more information on input and output needed?
> +2. Add more detail to purpose of hypercalls.
> 
> --


-- 
~Randy

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

[H. Peter Anvin]

On 05/31/2012 01:01 AM, Raghavendra K T wrote:
> +
> +TODO:
> +1. more information on input and output needed?
> +2. Add more detail to purpose of hypercalls.
> 

1. definitely, including the hypercall ABI.

	-hpa

-- 
H. Peter Anvin, Intel Open Source Technology Center
I work for Intel.  I don't speak on their behalf.

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

[Jan Kiszka]

On 2012-05-31 19:44, Randy Dunlap wrote:
> On 05/31/2012 01:01 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 
>>
>> Signed-off-by: Raghavendra K T <raghavendra.kt@linux.vnet.ibm.com>
>> ---
>> diff --git a/Documentation/virtual/kvm/hypercalls.txt b/Documentation/virtual/kvm/hypercalls.txt
>> new file mode 100644
>> index 0000000..c79335a
>> --- /dev/null
>> +++ b/Documentation/virtual/kvm/hypercalls.txt
>> @@ -0,0 +1,46 @@
>> +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
>> +Architecture: x86
> 
> 
> No "Status", does that imply "Active" ?

It should actually state that this call is in use.

Jan

-- 
Siemens AG, Corporate Technology, CT T DE IT 1
Corporate Competence Center Embedded Linux

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

[H. Peter Anvin]

On 05/31/2012 11:55 AM, Jan Kiszka wrote:
>>
>> No "Status", does that imply "Active" ?
> 
> It should actually state that this call is in use.
> 

It might be nice to point out when a call was introduced, and for
deprecated calls, when it was deprecated.

	-hpa

-- 
H. Peter Anvin, Intel Open Source Technology Center
I work for Intel.  I don't speak on their behalf.

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

[Rob Landley]

On 05/31/2012 12:46 PM, H. Peter Anvin wrote:
> On 05/31/2012 01:01 AM, Raghavendra K T wrote:
>> +
>> +TODO:
>> +1. more information on input and output needed?
>> +2. Add more detail to purpose of hypercalls.
>>
> 
> 1. definitely, including the hypercall ABI.
> 
> 	-hpa
> 

I was wondering about that. It looks like
Documentation/virtual/kvm/api.txt might cover some of that already in
section 5, but it doesn't look complete...

Also, could I get a 00-INDEX file for this directory explaining what
these individual files are? I think "api.txt" is supposed to be
host-side API for controlling a guest VM (from userspace via ioctls,
looks like), and hypercalls.txt is guest-side API for poking the host.
How someone would write host-side code that _responds_ to a hypercall, I
have no idea.  (It goes in the host kernel?)

Rob



-- 
GNU/Linux isn't: Linux=GPLv2, GNU=GPLv3+, they can't share code.
Either it's "mere aggregation", or a license violation.  Pick one.

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

[Raghavendra K T]

On 05/31/2012 11:14 PM, Randy Dunlap wrote:
> On 05/31/2012 01:01 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
>>
>> Signed-off-by: Raghavendra K T<raghavendra.kt@linux.vnet.ibm.com>
>> ---
>> diff --git a/Documentation/virtual/kvm/hypercalls.txt b/Documentation/virtual/kvm/hypercalls.txt
>> new file mode 100644
>> index 0000000..c79335a
>> --- /dev/null
>> +++ b/Documentation/virtual/kvm/hypercalls.txt
>> @@ -0,0 +1,46 @@
>> +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
>> +Architecture: x86
>
>
> No "Status", does that imply "Active" ?
>

Oh! It was unintentionally left out. will add that.

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

[Raghavendra K T]

On 06/04/2012 09:30 AM, Rob Landley wrote:
> On 05/31/2012 12:46 PM, H. Peter Anvin wrote:
>> On 05/31/2012 01:01 AM, Raghavendra K T wrote:
>>> +
>>> +TODO:
>>> +1. more information on input and output needed?
>>> +2. Add more detail to purpose of hypercalls.
>>>
>>
>> 1. definitely, including the hypercall ABI.
>>
>> 	-hpa
>>
>
> I was wondering about that. It looks like
> Documentation/virtual/kvm/api.txt might cover some of that already in
> section 5, but it doesn't look complete...
>
> Also, could I get a 00-INDEX file for this directory explaining what
> these individual files are? I think "api.txt" is supposed to be
> host-side API for controlling a guest VM (from userspace via ioctls,
> looks like),

api.txt has  plenty of information apart from  features which are 
related to guest side api (generally  controls / knows PV features 
available, that may also involve host query of guest cpuid).
and capability (of) related to host.

  and hypercalls.txt is guest-side API for poking the host.

hypercall can be used to take some actions (as needed by guest / 
exchange information)


> How someone would write host-side code that _responds_ to a hypercall, I
> have no idea.  (It goes in the host kernel?)
>
> Rob
>

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

[Alexander Graf]

On 02.08.2012, at 09:08, Raghavendra K T <raghavendra.kt@linux.vnet.ibm.com> wrote:

> On 08/01/2012 11:55 PM, Marcelo Tosatti wrote:
>> On Wed, Aug 01, 2012 at 04:19:01PM +0530, Raghavendra K T wrote:
>>> On 08/01/2012 08:37 AM, Marcelo Tosatti wrote:
>>>> On Tue, Jul 24, 2012 at 02:23:59PM +0530, 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>
>>>>> ---
> [...]
>>>>> +
>>>>> + 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.
>>>> 
>>>> It depends on the hypercall. It happens that current hypercalls use
>>>> the four registers, but its not an ABI (hyper-v hypercalls uses r8, for example).
>>>> 
>>> 
>>> Okay, agree. I did not know about hyper-v. Above one is for X86 and
>>> KVM  (and not X86 / hyper-v). So I should remove ABI and probably say,
>> 
>> Just say "Linux x86 Hypercall", yeah.
>> 
> 
> Ok, Thanks Marcelo.will respin patches with the changes you suggested.
> 
> Also I would  like add Alex's description on ppc hypercalls
> into Documentation/virtual/kvm/ppc-pv.txt with Alex from/sob or
> suggested-by in a separate patch unless I see any objection to that.
> 

Yeah, don't stall this on me :)

Alex

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

[Raghavendra K T]

On 08/01/2012 11:55 PM, Marcelo Tosatti wrote:
> On Wed, Aug 01, 2012 at 04:19:01PM +0530, Raghavendra K T wrote:
>> On 08/01/2012 08:37 AM, Marcelo Tosatti wrote:
>>> On Tue, Jul 24, 2012 at 02:23:59PM +0530, 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>
>>>> ---
[...]
>>>> +
>>>> + 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.
>>>
>>> It depends on the hypercall. It happens that current hypercalls use
>>> the four registers, but its not an ABI (hyper-v hypercalls uses r8, for example).
>>>
>>
>> Okay, agree. I did not know about hyper-v. Above one is for X86 and
>> KVM  (and not X86 / hyper-v). So I should remove ABI and probably say,
>
> Just say "Linux x86 Hypercall", yeah.
>

Ok, Thanks Marcelo.will respin patches with the changes you suggested.

Also I would  like add Alex's description on ppc hypercalls
into Documentation/virtual/kvm/ppc-pv.txt with Alex from/sob or
suggested-by in a separate patch unless I see any objection to that.

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

[Marcelo Tosatti]

On Wed, Aug 01, 2012 at 04:19:01PM +0530, Raghavendra K T wrote:
> On 08/01/2012 08:37 AM, Marcelo Tosatti wrote:
> >On Tue, Jul 24, 2012 at 02:23:59PM +0530, 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.
> >
> >vmcall.
> 
> How is this:
>  KVM Hypercalls have a three-byte sequence of vmcall instruction. But
> The hypervisor can replace it with the instructions that are guaranteed
> to be supported.
> 
> (Related question: Is it not that vmcall instruction is patched by 0f
> 01 09 vmmcall instruction sequence for amd?. 

Yes, it is.

Linux guest binary contains the Intel vmcall instruction, which is
patched on AMD to vmmcall.

> So I think we need to
> change documentation I referred from arch/x86/include/asm/kvm_para.h.
> It should be vmcall / vmmcall instead of vmrun and vmmrun)

Yes.

> >>+
> >>+ 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.
> >
> >It depends on the hypercall. It happens that current hypercalls use
> >the four registers, but its not an ABI (hyper-v hypercalls uses r8, for example).
> >
> 
> Okay, agree. I did not know about hyper-v. Above one is for X86 and
> KVM  (and not X86 / hyper-v). So I should remove ABI and probably say,

Just say "Linux x86 Hypercall", yeah.

> KVM x86 Hypercall
> ==================
> 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.
> 
> --
> To unsubscribe from this list: send the line "unsubscribe kvm" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Raghavendra K T]

On 08/01/2012 08:37 AM, Marcelo Tosatti wrote:
> On Tue, Jul 24, 2012 at 02:23:59PM +0530, 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.
>
> vmcall.

How is this:
  KVM Hypercalls have a three-byte sequence of vmcall instruction. But
The hypervisor can replace it with the instructions that are guaranteed
to be supported.

(Related question: Is it not that vmcall instruction is patched by 0f
01 09 vmmcall instruction sequence for amd?. So I think we need to
change documentation I referred from arch/x86/include/asm/kvm_para.h.
It should be vmcall / vmmcall instead of vmrun and vmmrun)

>
>> +
>> + 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.
>
> It depends on the hypercall. It happens that current hypercalls use
> the four registers, but its not an ABI (hyper-v hypercalls uses r8, for example).
>

Okay, agree. I did not know about hyper-v. Above one is for X86 and
KVM  (and not X86 / hyper-v). So I should remove ABI and probably say,

KVM x86 Hypercall
==================
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.

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

[Marcelo Tosatti]

On Tue, Jul 24, 2012 at 02:23:59PM +0530, 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.

vmcall.

> +
> + 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.

It depends on the hypercall. It happens that current hypercalls use
the four registers, but its not an ABI (hyper-v hypercalls uses r8, for example).

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@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.

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

[Alexander Graf]

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

> +  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:

   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?


Alex

> +Architecture: x86
> +Status: active
> +Purpose: Trigger guest exit so that the host can check for pending
> +interrupts on reentry.
> +
> +2. KVM_HC_MMU_OP
> +------------------------
> +Value: 2
> +Architecture: x86
> +Status: deprecated.
> +Purpose: Support MMU operations such as writing to PTE,
> +flushing TLB, release PT.
> +
> +3. KVM_HC_FEATURES
> +------------------------
> +Value: 3
> +Architecture: PPC
> +Status: active
> +Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid
> +used to enumerate which hypercalls are available. On PPC, either device tree
> +based lookup ( which is also what EPAPR dictates) OR KVM specific enumeration
> +mechanism (which is this hypercall) can be used.
> +
> +4. KVM_HC_PPC_MAP_MAGIC_PAGE
> +------------------------
> +Value: 4
> +Architecture: PPC
> +Status: active
> +Purpose: To enable communication between the hypervisor and guest there is a
> +shared page that contains parts of supervisor visible register state.
> +The guest can map this shared page to access its supervisor register through
> +memory using this hypercall.
>

[PATCH] Documentation/kvm : Add documentation on Hypercalls

[Raghavendra K T]

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:
+  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
+
+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
+Architecture: x86
+Status: active
+Purpose: Trigger guest exit so that the host can check for pending
+interrupts on reentry.
+
+2. KVM_HC_MMU_OP
+------------------------
+Value: 2
+Architecture: x86
+Status: deprecated.
+Purpose: Support MMU operations such as writing to PTE,
+flushing TLB, release PT.
+
+3. KVM_HC_FEATURES
+------------------------
+Value: 3
+Architecture: PPC
+Status: active
+Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid
+used to enumerate which hypercalls are available. On PPC, either device tree
+based lookup ( which is also what EPAPR dictates) OR KVM specific enumeration
+mechanism (which is this hypercall) can be used.
+
+4. KVM_HC_PPC_MAP_MAGIC_PAGE
+------------------------
+Value: 4
+Architecture: PPC
+Status: active
+Purpose: To enable communication between the hypervisor and guest there is a
+shared page that contains parts of supervisor visible register state.
+The guest can map this shared page to access its supervisor register through
+memory using this hypercall.