From mboxrd@z Thu Jan 1 00:00:00 1970 From: Andrew Jones Subject: Re: [PATCH v7 26/27] KVM: Document errors for KVM_GET_ONE_REG and KVM_SET_ONE_REG Date: Thu, 4 Apr 2019 11:34:15 +0200 Message-ID: <20190404093415.kt6cvagteszwmyzi@kamzik.brq.redhat.com> References: <1553864452-15080-1-git-send-email-Dave.Martin@arm.com> <1553864452-15080-27-git-send-email-Dave.Martin@arm.com> <20190403202746.yoxwokr5uitli5q4@kamzik.brq.redhat.com> <20190404083526.GZ3567@e103592.cambridge.arm.com> Mime-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable Return-path: Received: from localhost (localhost [127.0.0.1]) by mm01.cs.columbia.edu (Postfix) with ESMTP id BF0444A3EF for ; Thu, 4 Apr 2019 05:34:22 -0400 (EDT) Received: from mm01.cs.columbia.edu ([127.0.0.1]) by localhost (mm01.cs.columbia.edu [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id dWEFsKPfmkaz for ; Thu, 4 Apr 2019 05:34:21 -0400 (EDT) Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mm01.cs.columbia.edu (Postfix) with ESMTPS id 6A4644A331 for ; Thu, 4 Apr 2019 05:34:21 -0400 (EDT) Content-Disposition: inline In-Reply-To: <20190404083526.GZ3567@e103592.cambridge.arm.com> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: kvmarm-bounces@lists.cs.columbia.edu Sender: kvmarm-bounces@lists.cs.columbia.edu To: Dave Martin Cc: Okamoto Takayuki , Christoffer Dall , Ard Biesheuvel , Marc Zyngier , Catalin Marinas , Will Deacon , Zhang Lei , Julien Grall , kvmarm@lists.cs.columbia.edu, linux-arm-kernel@lists.infradead.org List-Id: kvmarm@lists.cs.columbia.edu On Thu, Apr 04, 2019 at 09:35:26AM +0100, Dave Martin wrote: > On Wed, Apr 03, 2019 at 10:27:46PM +0200, Andrew Jones wrote: > > On Fri, Mar 29, 2019 at 01:00:51PM +0000, Dave Martin wrote: > > > KVM_GET_ONE_REG and KVM_SET_ONE_REG return some error codes that > > > are not documented (but hopefully not surprising either). To give > > > an indication of what these may mean, this patch adds brief > > > documentation. > > > = > > > Signed-off-by: Dave Martin > > > --- > > > Documentation/virtual/kvm/api.txt | 6 ++++++ > > > 1 file changed, 6 insertions(+) > > > = > > > diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtua= l/kvm/api.txt > > > index 2d4f7ce..cd920dd 100644 > > > --- a/Documentation/virtual/kvm/api.txt > > > +++ b/Documentation/virtual/kvm/api.txt > > > @@ -1871,6 +1871,9 @@ Architectures: all > > > Type: vcpu ioctl > > > Parameters: struct kvm_one_reg (in) > > > Returns: 0 on success, negative value on failure > > > +Errors: > > > + =A0ENOENT: =A0=A0no such register > > > + =A0EINVAL: =A0=A0other errors, such as bad size encoding for a know= n register > > > = > > > struct kvm_one_reg { > > > __u64 id; > > > @@ -2192,6 +2195,9 @@ Architectures: all > > > Type: vcpu ioctl > > > Parameters: struct kvm_one_reg (in and out) > > > Returns: 0 on success, negative value on failure > > > +Errors: > > > + =A0ENOENT: =A0=A0no such register > > > + =A0EINVAL: =A0=A0other errors, such as bad size encoding for a know= n register > > > = > > > This ioctl allows to receive the value of a single register implemen= ted > > > in a vcpu. The register to read is indicated by the "id" field of the > > > -- = > > > 2.1.4 > > > > > = > > Are we sure all architectures have these, and only these errors? A quick > > grep indicates not. I'm not sure we can document this easily here due to > > it addressing all architectures at once. Maybe we could add arch-specif= ic > > subsections, but I'm not sure it's worth it. > = > Error codes are generally indicative at best, and rarely mutually > exclusive in a given situation. > = > Writing a caveat to say that you shouldn't make assumptions about > precisely what error code will be returned in a given situation would > look odd: that really applies widely all over the kernel/user ABI, not > just here. > = > _Maybe_ everything is exhaustively correct in this file already, but > given the size of it, and the fact that many things are implemented > per-arch, the chance of this seems zero. > = > I could add "invalid register ID" for EINVAL. This allows some > ambiguity about which error code applies for a nonexistent register. > = > Alternatively, we could revert this documentation instead. Yeah, I vote we just drop this patch. It could add more confusion when people start here to determine what to grep and then, when grepping for it, can't find any occurrences, as would be the case for ENOENT on at least a couple arches. Thanks, drew > = > It seemed appropriate to document the EPERM error for finalization > ordering (added later), but since correct userspace code should never > see this maybe it's reasonable to leave it undocumented(?) > = > Cheers > ---Dave From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-9.0 required=3.0 tests=DKIMWL_WL_HIGH,DKIM_SIGNED, DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI, SIGNED_OFF_BY,SPF_PASS,URIBL_BLOCKED,USER_AGENT_NEOMUTT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1D109C10F0C for ; Thu, 4 Apr 2019 09:34:31 +0000 (UTC) Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id DD654217D4 for ; Thu, 4 Apr 2019 09:34:30 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=lists.infradead.org header.i=@lists.infradead.org header.b="ANzxk/4V" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org DD654217D4 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=linux-arm-kernel-bounces+infradead-linux-arm-kernel=archiver.kernel.org@lists.infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20170209; h=Sender: Content-Transfer-Encoding:Content-Type:Cc:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:In-Reply-To:MIME-Version:References: Message-ID:Subject:To:From:Date:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=fNlrAmrjziFTYtdCTaoFaC8grfFAPNSzmItd5htRj+U=; b=ANzxk/4VYr6SIY PoD4eJ5S6EzJI1HIVgliubn0Bp3A58rTfxsd+rJQnsXPdk6Rxg7WMlpeJ5BIeVNFgtjLCxjdzkHIn M0lOa8oT6xC7MZzlA2mcEMWCogBCBHg5BAcXjM/HsJ8yBWnP1RE0vfzkzALj6L1LAtNSMeJSqqdMq NPItlF5NbY/UB0IgdNLfbduzxDxD7M1rd2zFoPAr3oGB9iL3M1NKYJlt/PzOQEpX3NVromEK9PFOQ HgbZg273yjYPU9CN0j7PjWp/x2Th1CBJ7MxyY75pinPfM9t7q8CKU1j3TNGnfQaCLfo6P6+lCtAHC pWu7kIwVYuYNB7aLSRjA==; Received: from localhost ([127.0.0.1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.90_1 #2 (Red Hat Linux)) id 1hBylO-0002ro-6O; Thu, 04 Apr 2019 09:34:26 +0000 Received: from mx1.redhat.com ([209.132.183.28]) by bombadil.infradead.org with esmtps (Exim 4.90_1 #2 (Red Hat Linux)) id 1hBylL-0002r4-JD for linux-arm-kernel@lists.infradead.org; Thu, 04 Apr 2019 09:34:25 +0000 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 902FCC058CC0; Thu, 4 Apr 2019 09:34:20 +0000 (UTC) Received: from kamzik.brq.redhat.com (unknown [10.43.2.160]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2B3F9646C3; Thu, 4 Apr 2019 09:34:17 +0000 (UTC) Date: Thu, 4 Apr 2019 11:34:15 +0200 From: Andrew Jones To: Dave Martin Subject: Re: [PATCH v7 26/27] KVM: Document errors for KVM_GET_ONE_REG and KVM_SET_ONE_REG Message-ID: <20190404093415.kt6cvagteszwmyzi@kamzik.brq.redhat.com> References: <1553864452-15080-1-git-send-email-Dave.Martin@arm.com> <1553864452-15080-27-git-send-email-Dave.Martin@arm.com> <20190403202746.yoxwokr5uitli5q4@kamzik.brq.redhat.com> <20190404083526.GZ3567@e103592.cambridge.arm.com> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <20190404083526.GZ3567@e103592.cambridge.arm.com> User-Agent: NeoMutt/20180716 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.32]); Thu, 04 Apr 2019 09:34:20 +0000 (UTC) X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20190404_023423_674248_AA0269C2 X-CRM114-Status: GOOD ( 27.48 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Okamoto Takayuki , Christoffer Dall , Ard Biesheuvel , Marc Zyngier , Catalin Marinas , Will Deacon , Zhang Lei , Julien Grall , kvmarm@lists.cs.columbia.edu, linux-arm-kernel@lists.infradead.org Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+infradead-linux-arm-kernel=archiver.kernel.org@lists.infradead.org On Thu, Apr 04, 2019 at 09:35:26AM +0100, Dave Martin wrote: > On Wed, Apr 03, 2019 at 10:27:46PM +0200, Andrew Jones wrote: > > On Fri, Mar 29, 2019 at 01:00:51PM +0000, Dave Martin wrote: > > > KVM_GET_ONE_REG and KVM_SET_ONE_REG return some error codes that > > > are not documented (but hopefully not surprising either). To give > > > an indication of what these may mean, this patch adds brief > > > documentation. > > > = > > > Signed-off-by: Dave Martin > > > --- > > > Documentation/virtual/kvm/api.txt | 6 ++++++ > > > 1 file changed, 6 insertions(+) > > > = > > > diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtua= l/kvm/api.txt > > > index 2d4f7ce..cd920dd 100644 > > > --- a/Documentation/virtual/kvm/api.txt > > > +++ b/Documentation/virtual/kvm/api.txt > > > @@ -1871,6 +1871,9 @@ Architectures: all > > > Type: vcpu ioctl > > > Parameters: struct kvm_one_reg (in) > > > Returns: 0 on success, negative value on failure > > > +Errors: > > > + =A0ENOENT: =A0=A0no such register > > > + =A0EINVAL: =A0=A0other errors, such as bad size encoding for a know= n register > > > = > > > struct kvm_one_reg { > > > __u64 id; > > > @@ -2192,6 +2195,9 @@ Architectures: all > > > Type: vcpu ioctl > > > Parameters: struct kvm_one_reg (in and out) > > > Returns: 0 on success, negative value on failure > > > +Errors: > > > + =A0ENOENT: =A0=A0no such register > > > + =A0EINVAL: =A0=A0other errors, such as bad size encoding for a know= n register > > > = > > > This ioctl allows to receive the value of a single register implemen= ted > > > in a vcpu. The register to read is indicated by the "id" field of the > > > -- = > > > 2.1.4 > > > > > = > > Are we sure all architectures have these, and only these errors? A quick > > grep indicates not. I'm not sure we can document this easily here due to > > it addressing all architectures at once. Maybe we could add arch-specif= ic > > subsections, but I'm not sure it's worth it. > = > Error codes are generally indicative at best, and rarely mutually > exclusive in a given situation. > = > Writing a caveat to say that you shouldn't make assumptions about > precisely what error code will be returned in a given situation would > look odd: that really applies widely all over the kernel/user ABI, not > just here. > = > _Maybe_ everything is exhaustively correct in this file already, but > given the size of it, and the fact that many things are implemented > per-arch, the chance of this seems zero. > = > I could add "invalid register ID" for EINVAL. This allows some > ambiguity about which error code applies for a nonexistent register. > = > Alternatively, we could revert this documentation instead. Yeah, I vote we just drop this patch. It could add more confusion when people start here to determine what to grep and then, when grepping for it, can't find any occurrences, as would be the case for ENOENT on at least a couple arches. Thanks, drew > = > It seemed appropriate to document the EPERM error for finalization > ordering (added later), but since correct userspace code should never > see this maybe it's reasonable to leave it undocumented(?) > = > Cheers > ---Dave _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel