[PATCH] KVM: Update documentation to include detailed ENABLE_CAP description

[PATCH] KVM: Update documentation to include detailed ENABLE_CAP description

[Alexander Graf]

We have an ioctl that enables capabilities individually, but no description
on what exactly happens when we enable a capability using this ioctl.

This patch adds documentation for capability enabling in a new section
of the API documentation.

Signed-off-by: Alexander Graf <agraf@suse.de>
---
 Documentation/virtual/kvm/api.txt |   48 +++++++++++++++++++++++++++++++++++++
 1 files changed, 48 insertions(+), 0 deletions(-)

diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
index 2d510b6..8757366 100644
--- a/Documentation/virtual/kvm/api.txt
+++ b/Documentation/virtual/kvm/api.txt
@@ -1653,3 +1653,51 @@ developer registration required to access it).
 		char padding[256];
 	};
 };
+
+6. Capabilities that can be enabled
+
+There are certain capabilities that change the behavior of the virtual CPU when
+enabled. To enable them, please see section 4.37. Below you can find a list of
+capabilities and what their effect on the vCPU is when enabling them.
+
+The following information is provided along with the description:
+
+  Architectures: which instruction set architectures provide this ioctl.
+      x86 includes both i386 and x86_64.
+
+  Parameters: what parameters are accepted by the capability.
+
+  Returns: the return value.  General error numbers (EBADF, ENOMEM, EINVAL)
+      are not detailed, but errors with specific meanings are.
+
+6.1 KVM_CAP_PPC_OSI
+
+Architectures: ppc
+Parameters: none
+Returns: 0 on success; -1 on error
+
+This capaobility enables interception of OSI hypercalls that otherwise would
+be treated as normal system calls to be injected into the guest. OSI hypercalls
+were invented by Mac-on-Linux to have a standardized communication mechanism
+between the guest and the host.
+
+When this capability is enabled, KVM_EXIT_OSI can occur.
+
+6.2 KVM_CAP_PPC_PAPR
+
+Architectures: ppc
+Parameters: none
+Returns: 0 on success; -1 on error
+
+This capability enables interception of PAPR hypercalls. PAPR hypercalls are
+done using the hypercall instruction "sc 1".
+
+It also sets the guest privilege level to "supervisor" mode. Usually the guest
+runs in "hypervisor" privilege mode with a few missing features.
+
+In addition to the above, it changes the semantics of SDR1. In this mode, the
+HTAB address part of SDR1 contains an HVA instead of a GPA, as PAPR keeps the
+HTAB invisible to the guest.
+
+When this capability is enabled, KVM_EXIT_PAPR_HCALL can occur.
+
-- 
1.6.0.2

[PATCH] KVM: Update documentation to include detailed ENABLE_CAP description

[Alexander Graf]

We have an ioctl that enables capabilities individually, but no description
on what exactly happens when we enable a capability using this ioctl.

This patch adds documentation for capability enabling in a new section
of the API documentation.

Signed-off-by: Alexander Graf <agraf@suse.de>
---
 Documentation/virtual/kvm/api.txt |   48 +++++++++++++++++++++++++++++++++++++
 1 files changed, 48 insertions(+), 0 deletions(-)

diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
index 2d510b6..8757366 100644
--- a/Documentation/virtual/kvm/api.txt
+++ b/Documentation/virtual/kvm/api.txt
@@ -1653,3 +1653,51 @@ developer registration required to access it).
 		char padding[256];
 	};
 };
+
+6. Capabilities that can be enabled
+
+There are certain capabilities that change the behavior of the virtual CPU when
+enabled. To enable them, please see section 4.37. Below you can find a list of
+capabilities and what their effect on the vCPU is when enabling them.
+
+The following information is provided along with the description:
+
+  Architectures: which instruction set architectures provide this ioctl.
+      x86 includes both i386 and x86_64.
+
+  Parameters: what parameters are accepted by the capability.
+
+  Returns: the return value.  General error numbers (EBADF, ENOMEM, EINVAL)
+      are not detailed, but errors with specific meanings are.
+
+6.1 KVM_CAP_PPC_OSI
+
+Architectures: ppc
+Parameters: none
+Returns: 0 on success; -1 on error
+
+This capaobility enables interception of OSI hypercalls that otherwise would
+be treated as normal system calls to be injected into the guest. OSI hypercalls
+were invented by Mac-on-Linux to have a standardized communication mechanism
+between the guest and the host.
+
+When this capability is enabled, KVM_EXIT_OSI can occur.
+
+6.2 KVM_CAP_PPC_PAPR
+
+Architectures: ppc
+Parameters: none
+Returns: 0 on success; -1 on error
+
+This capability enables interception of PAPR hypercalls. PAPR hypercalls are
+done using the hypercall instruction "sc 1".
+
+It also sets the guest privilege level to "supervisor" mode. Usually the guest
+runs in "hypervisor" privilege mode with a few missing features.
+
+In addition to the above, it changes the semantics of SDR1. In this mode, the
+HTAB address part of SDR1 contains an HVA instead of a GPA, as PAPR keeps the
+HTAB invisible to the guest.
+
+When this capability is enabled, KVM_EXIT_PAPR_HCALL can occur.
+
-- 
1.6.0.2

Re: [PATCH] KVM: Update documentation to include detailed

[Sasha Levin]

On Wed, 2011-08-31 at 10:58 +0200, Alexander Graf wrote:
> +This capaobility enables interception of OSI hypercalls that otherwise would
	capability

-- 

Sasha.

Re: [PATCH] KVM: Update documentation to include detailed ENABLE_CAP description

[Sasha Levin]

On Wed, 2011-08-31 at 10:58 +0200, Alexander Graf wrote:
> +This capaobility enables interception of OSI hypercalls that otherwise would
	capability

-- 

Sasha.

Re: [PATCH] KVM: Update documentation to include detailed ENABLE_CAP description

[Alexander Graf]

On 31.08.2011, at 14:52, Sasha Levin wrote:

> On Wed, 2011-08-31 at 10:58 +0200, Alexander Graf wrote:
>> +This capaobility enables interception of OSI hypercalls that otherwise would
> 	capability

Oops :). Avi, you pulled that one in already. Can you still change it in-tree (it's not gone to master yet, right?) or do you want me to send a typo fix patch on top?


Alex

Re: [PATCH] KVM: Update documentation to include detailed ENABLE_CAP description

[Alexander Graf]

On 31.08.2011, at 14:52, Sasha Levin wrote:

> On Wed, 2011-08-31 at 10:58 +0200, Alexander Graf wrote:
>> +This capaobility enables interception of OSI hypercalls that otherwise would
> 	capability

Oops :). Avi, you pulled that one in already. Can you still change it in-tree (it's not gone to master yet, right?) or do you want me to send a typo fix patch on top?


Alex

Re: [PATCH] KVM: Update documentation to include detailed ENABLE_CAP

[Avi Kivity]

On 08/31/2011 04:02 PM, Alexander Graf wrote:
> On 31.08.2011, at 14:52, Sasha Levin wrote:
>
> >  On Wed, 2011-08-31 at 10:58 +0200, Alexander Graf wrote:
> >>  +This capaobility enables interception of OSI hypercalls that otherwise would
> >  	capability
>
> Oops :). Avi, you pulled that one in already. Can you still change it in-tree (it's not gone to master yet, right?) or do you want me to send a typo fix patch on top?
>

I fixed it locally here, and no it wasn't pushed yet.

-- 
error compiling committee.c: too many arguments to function

Re: [PATCH] KVM: Update documentation to include detailed ENABLE_CAP description

[Avi Kivity]

On 08/31/2011 04:02 PM, Alexander Graf wrote:
> On 31.08.2011, at 14:52, Sasha Levin wrote:
>
> >  On Wed, 2011-08-31 at 10:58 +0200, Alexander Graf wrote:
> >>  +This capaobility enables interception of OSI hypercalls that otherwise would
> >  	capability
>
> Oops :). Avi, you pulled that one in already. Can you still change it in-tree (it's not gone to master yet, right?) or do you want me to send a typo fix patch on top?
>

I fixed it locally here, and no it wasn't pushed yet.

-- 
error compiling committee.c: too many arguments to function

Re: [PATCH] KVM: Update documentation to include detailed ENABLE_CAP description

[Alexander Graf]

On 31.08.2011, at 15:07, Avi Kivity wrote:

> On 08/31/2011 04:02 PM, Alexander Graf wrote:
>> On 31.08.2011, at 14:52, Sasha Levin wrote:
>> 
>> >  On Wed, 2011-08-31 at 10:58 +0200, Alexander Graf wrote:
>> >>  +This capaobility enables interception of OSI hypercalls that otherwise would
>> >  	capability
>> 
>> Oops :). Avi, you pulled that one in already. Can you still change it in-tree (it's not gone to master yet, right?) or do you want me to send a typo fix patch on top?
>> 
> 
> I fixed it locally here, and no it wasn't pushed yet.

Thanks! :)

Alex

Re: [PATCH] KVM: Update documentation to include detailed ENABLE_CAP description

[Alexander Graf]

On 31.08.2011, at 15:07, Avi Kivity wrote:

> On 08/31/2011 04:02 PM, Alexander Graf wrote:
>> On 31.08.2011, at 14:52, Sasha Levin wrote:
>> 
>> >  On Wed, 2011-08-31 at 10:58 +0200, Alexander Graf wrote:
>> >>  +This capaobility enables interception of OSI hypercalls that otherwise would
>> >  	capability
>> 
>> Oops :). Avi, you pulled that one in already. Can you still change it in-tree (it's not gone to master yet, right?) or do you want me to send a typo fix patch on top?
>> 
> 
> I fixed it locally here, and no it wasn't pushed yet.

Thanks! :)

Alex