Patchwork [13/14] KVM: Clarify KVM_{SET, GET}_ONE_REG error code documentation

login
register
mail settings
Submitter Dave Martin
Date April 12, 2019, 4:28 p.m.
Message ID <1555086498-26691-14-git-send-email-Dave.Martin@arm.com>
Download mbox | patch
Permalink /patch/772029/
State New
Headers show

Comments

Dave Martin - April 12, 2019, 4:28 p.m.
The current error code documentation for KVM_GET_ONE_REG and
KVM_SET_ONE_REG could be read as implying that all architectures
implement these error codes, or that KVM guararntees which error
code is returned in a particular situation.

Because this is not really the case, this patch waters down the
documentation explicitly to remove such guarantees.

EPERM is marked as arm64-specific, since for now arm64 really is
the only architecture that yields this error code for the
finalization-required case.  Keeping this as a distinct error code
is useful however for debugging due to the statefulness of the API
in this instance.

No functional change.

Suggested-by: Andrew Jones <drjones@redhat.com>
Fixes: 395f562f2b4c ("KVM: Document errors for KVM_GET_ONE_REG and KVM_SET_ONE_REG")
Fixes: 50036ad06b7f ("KVM: arm64/sve: Document KVM API extensions for SVE")
Signed-off-by: Dave Martin <Dave.Martin@arm.com>
---
 Documentation/virtual/kvm/api.txt | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)
Andrew Jones - April 15, 2019, 3:21 p.m.
On Fri, Apr 12, 2019 at 05:28:17PM +0100, Dave Martin wrote:
> The current error code documentation for KVM_GET_ONE_REG and
> KVM_SET_ONE_REG could be read as implying that all architectures
> implement these error codes, or that KVM guararntees which error

guarantees

> code is returned in a particular situation.
> 
> Because this is not really the case, this patch waters down the
> documentation explicitly to remove such guarantees.
> 
> EPERM is marked as arm64-specific, since for now arm64 really is
> the only architecture that yields this error code for the
> finalization-required case.  Keeping this as a distinct error code
> is useful however for debugging due to the statefulness of the API
> in this instance.
> 
> No functional change.
> 
> Suggested-by: Andrew Jones <drjones@redhat.com>
> Fixes: 395f562f2b4c ("KVM: Document errors for KVM_GET_ONE_REG and KVM_SET_ONE_REG")
> Fixes: 50036ad06b7f ("KVM: arm64/sve: Document KVM API extensions for SVE")
> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> ---
>  Documentation/virtual/kvm/api.txt | 14 +++++++++-----
>  1 file changed, 9 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
> index b115b23..74c51c7 100644
> --- a/Documentation/virtual/kvm/api.txt
> +++ b/Documentation/virtual/kvm/api.txt
> @@ -1873,8 +1873,10 @@ Parameters: struct kvm_one_reg (in)
>  Returns: 0 on success, negative value on failure
>  Errors:
>    ENOENT:   no such register
> -  EPERM:    register access forbidden for architecture-dependent reasons
> -  EINVAL:   other errors, such as bad size encoding for a known register
> +  EINVAL:   invalid register ID, or no such register
> +  EPERM:    (arm64) register access not allowed before vcpu finalization
> +(These error codes are indicative only: do not rely on a specific error
> +code being returned in a specific situation.)
>  
>  struct kvm_one_reg {
>         __u64 id;
> @@ -2258,10 +2260,12 @@ Architectures: all
>  Type: vcpu ioctl
>  Parameters: struct kvm_one_reg (in and out)
>  Returns: 0 on success, negative value on failure
> -Errors:
> +Errors include:
>    ENOENT:   no such register
> -  EPERM:    register access forbidden for architecture-dependent reasons
> -  EINVAL:   other errors, such as bad size encoding for a known register
> +  EINVAL:   invalid register ID, or no such register
> +  EPERM:    (arm64) register access not allowed before vcpu finalization
> +(These error codes are indicative only: do not rely on a specific error
> +code being returned in a specific situation.)
>  
>  This ioctl allows to receive the value of a single register implemented
>  in a vcpu. The register to read is indicated by the "id" field of the
> -- 
> 2.1.4
>

Reviewed-by: Andrew Jones <drjones@redhat.com>
Dave Martin - April 16, 2019, 12:42 p.m.
On Mon, Apr 15, 2019 at 05:21:32PM +0200, Andrew Jones wrote:
> On Fri, Apr 12, 2019 at 05:28:17PM +0100, Dave Martin wrote:
> > The current error code documentation for KVM_GET_ONE_REG and
> > KVM_SET_ONE_REG could be read as implying that all architectures
> > implement these error codes, or that KVM guararntees which error
> 
> guarantees
> 
> > code is returned in a particular situation.
> > 
> > Because this is not really the case, this patch waters down the
> > documentation explicitly to remove such guarantees.
> > 
> > EPERM is marked as arm64-specific, since for now arm64 really is
> > the only architecture that yields this error code for the
> > finalization-required case.  Keeping this as a distinct error code
> > is useful however for debugging due to the statefulness of the API
> > in this instance.
> > 
> > No functional change.
> > 
> > Suggested-by: Andrew Jones <drjones@redhat.com>
> > Fixes: 395f562f2b4c ("KVM: Document errors for KVM_GET_ONE_REG and KVM_SET_ONE_REG")
> > Fixes: 50036ad06b7f ("KVM: arm64/sve: Document KVM API extensions for SVE")
> > Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> > ---
> >  Documentation/virtual/kvm/api.txt | 14 +++++++++-----
> >  1 file changed, 9 insertions(+), 5 deletions(-)
> > 
> > diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
> > index b115b23..74c51c7 100644
> > --- a/Documentation/virtual/kvm/api.txt
> > +++ b/Documentation/virtual/kvm/api.txt
> > @@ -1873,8 +1873,10 @@ Parameters: struct kvm_one_reg (in)
> >  Returns: 0 on success, negative value on failure
> >  Errors:
> >    ENOENT:   no such register
> > -  EPERM:    register access forbidden for architecture-dependent reasons
> > -  EINVAL:   other errors, such as bad size encoding for a known register
> > +  EINVAL:   invalid register ID, or no such register
> > +  EPERM:    (arm64) register access not allowed before vcpu finalization
> > +(These error codes are indicative only: do not rely on a specific error
> > +code being returned in a specific situation.)
> >  
> >  struct kvm_one_reg {
> >         __u64 id;
> > @@ -2258,10 +2260,12 @@ Architectures: all
> >  Type: vcpu ioctl
> >  Parameters: struct kvm_one_reg (in and out)
> >  Returns: 0 on success, negative value on failure
> > -Errors:
> > +Errors include:
> >    ENOENT:   no such register
> > -  EPERM:    register access forbidden for architecture-dependent reasons
> > -  EINVAL:   other errors, such as bad size encoding for a known register
> > +  EINVAL:   invalid register ID, or no such register
> > +  EPERM:    (arm64) register access not allowed before vcpu finalization
> > +(These error codes are indicative only: do not rely on a specific error
> > +code being returned in a specific situation.)
> >  
> >  This ioctl allows to receive the value of a single register implemented
> >  in a vcpu. The register to read is indicated by the "id" field of the
> > -- 
> > 2.1.4
> >
> 
> Reviewed-by: Andrew Jones <drjones@redhat.com>

Thanks
---Dave

Patch

diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt
index b115b23..74c51c7 100644
--- a/Documentation/virtual/kvm/api.txt
+++ b/Documentation/virtual/kvm/api.txt
@@ -1873,8 +1873,10 @@  Parameters: struct kvm_one_reg (in)
 Returns: 0 on success, negative value on failure
 Errors:
   ENOENT:   no such register
-  EPERM:    register access forbidden for architecture-dependent reasons
-  EINVAL:   other errors, such as bad size encoding for a known register
+  EINVAL:   invalid register ID, or no such register
+  EPERM:    (arm64) register access not allowed before vcpu finalization
+(These error codes are indicative only: do not rely on a specific error
+code being returned in a specific situation.)
 
 struct kvm_one_reg {
        __u64 id;
@@ -2258,10 +2260,12 @@  Architectures: all
 Type: vcpu ioctl
 Parameters: struct kvm_one_reg (in and out)
 Returns: 0 on success, negative value on failure
-Errors:
+Errors include:
   ENOENT:   no such register
-  EPERM:    register access forbidden for architecture-dependent reasons
-  EINVAL:   other errors, such as bad size encoding for a known register
+  EINVAL:   invalid register ID, or no such register
+  EPERM:    (arm64) register access not allowed before vcpu finalization
+(These error codes are indicative only: do not rely on a specific error
+code being returned in a specific situation.)
 
 This ioctl allows to receive the value of a single register implemented
 in a vcpu. The register to read is indicated by the "id" field of the