linux-sgx.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Jarkko Sakkinen <jarkko@kernel.org>
To: Kai Huang <kai.huang@intel.com>
Cc: linux-sgx@vger.kernel.org, kvm@vger.kernel.org, x86@kernel.org,
	seanjc@google.com, luto@kernel.org, dave.hansen@intel.com,
	haitao.huang@intel.com, pbonzini@redhat.com, bp@alien8.de,
	tglx@linutronix.de, mingo@redhat.com, hpa@zytor.com
Subject: Re: [RFC PATCH v2 11/26] x86/sgx: Add encls_faulted() helper
Date: Thu, 21 Jan 2021 03:08:18 +0200	[thread overview]
Message-ID: <YAjUAldgNUtrx6sE@kernel.org> (raw)
In-Reply-To: <20210121124359.7fff8c6d6f90182d8d13062f@intel.com>

On Thu, Jan 21, 2021 at 12:43:59PM +1300, Kai Huang wrote:
> On Wed, 20 Jan 2021 14:03:08 +0200 Jarkko Sakkinen wrote:
> > On Mon, Jan 18, 2021 at 04:28:04PM +1300, Kai Huang wrote:
> > > From: Sean Christopherson <sean.j.christopherson@intel.com>
> > > 
> > > Add a helper to extract the fault indicator from an encoded ENCLS return
> > > value.  SGX virtualization will also need to detect ENCLS faults.
> > > 
> > > Signed-off-by: Sean Christopherson <sean.j.christopherson@intel.com>
> > > Acked-by: Dave Hansen <dave.hansen@intel.com>
> > > Signed-off-by: Kai Huang <kai.huang@intel.com>
> > > ---
> > >  arch/x86/kernel/cpu/sgx/encls.h | 14 +++++++++++++-
> > >  arch/x86/kernel/cpu/sgx/ioctl.c |  2 +-
> > >  2 files changed, 14 insertions(+), 2 deletions(-)
> > > 
> > > diff --git a/arch/x86/kernel/cpu/sgx/encls.h b/arch/x86/kernel/cpu/sgx/encls.h
> > > index be5c49689980..55919a2b01b0 100644
> > > --- a/arch/x86/kernel/cpu/sgx/encls.h
> > > +++ b/arch/x86/kernel/cpu/sgx/encls.h
> > > @@ -40,6 +40,18 @@
> > >  	} while (0);							  \
> > >  }
> > >  
> > > +/*
> > > + * encls_faulted() - Check if an ENCLS leaf faulted given an error code
> > > + * @ret		the return value of an ENCLS leaf function call
> > > + *
> > > + * Return:
> > > + *	%true if @ret indicates a fault, %false otherwise
> > 
> > Follow here the style of commenting as in ioctl.c, for the return value.
> > It has optimal readability both as text, and also when converted to HTML.
> > See sgx_ioc_enclave_add_pages() for an example.
> 
> You mean something like below?
> 
> Return:
> - %true:  @ret indicates a fault.
> - %false: @ret indicates no fault.

Yeah, with '\t' indentation. I'd remove also '%'. Also '@ret' is redudant.

To put this all together:

* Return:
* - true:       ENCLS leaf faulted.
* - false:      Otherwise.

I tried various ways and this was the best way to document return values
that i've found. It's easy to read as plain text, and also has the benefit
that return values get nicely lined up in htmldocs.

I've been even considering a patch for

https://www.kernel.org/doc/Documentation/kernel-doc-nano-HOWTO.txt

The only advice given ATM is: "Take a look around the source tree for
examples."

/Jarkko

  reply	other threads:[~2021-01-21  1:11 UTC|newest]

Thread overview: 91+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-01-18  3:26 [RFC PATCH v2 00/26] KVM SGX virtualization support Kai Huang
2021-01-18  3:26 ` [RFC PATCH v2 01/26] x86/cpufeatures: Add SGX1 and SGX2 sub-features Kai Huang
2021-01-19 16:19   ` Borislav Petkov
2021-01-19 18:03     ` Sean Christopherson
2021-01-19 22:54       ` Kai Huang
2021-01-20 10:28       ` Borislav Petkov
2021-01-20 11:50   ` Jarkko Sakkinen
2021-01-20 23:23     ` Kai Huang
2021-01-21  1:01       ` Jarkko Sakkinen
2021-01-18  3:26 ` [RFC PATCH v2 02/26] x86/sgx: Remove a warn from sgx_free_epc_page() Kai Huang
2021-01-19  8:32   ` Jarkko Sakkinen
2021-01-20  0:42     ` Kai Huang
2021-01-18  3:26 ` [RFC PATCH v2 03/26] x86/sgx: Wipe out EREMOVE " Kai Huang
2021-01-18  3:26 ` [RFC PATCH v2 04/26] x86/sgx: Add SGX_CHILD_PRESENT hardware error code Kai Huang
2021-01-20 11:51   ` Jarkko Sakkinen
2021-01-18  3:26 ` [RFC PATCH v2 05/26] x86/sgx: Introduce virtual EPC for use by KVM guests Kai Huang
2021-01-20 11:54   ` Jarkko Sakkinen
2021-01-20 17:40     ` Sean Christopherson
2021-01-21  0:54       ` Jarkko Sakkinen
2021-01-21  0:55         ` Jarkko Sakkinen
2021-01-18  3:27 ` [RFC PATCH v2 06/26] x86/cpu/intel: Allow SGX virtualization without Launch Control support Kai Huang
2021-01-20 21:02   ` Dave Hansen
2021-01-20 22:36     ` Sean Christopherson
2021-01-20 23:27       ` Dave Hansen
2021-01-20 23:48         ` Kai Huang
2021-01-20 23:51           ` Dave Hansen
2021-01-21  1:53             ` Kai Huang
2021-01-21 14:35               ` Jarkko Sakkinen
2021-01-21  1:12         ` Jarkko Sakkinen
2021-01-20 23:50     ` Kai Huang
2021-01-21  1:11     ` Jarkko Sakkinen
2021-01-18  3:27 ` [RFC PATCH v2 07/26] x86/sgx: Initialize virtual EPC driver even when SGX driver is disabled Kai Huang
2021-01-18  3:27 ` [RFC PATCH v2 08/26] x86/sgx: Expose SGX architectural definitions to the kernel Kai Huang
2021-01-20 11:58   ` Jarkko Sakkinen
2021-01-20 23:53     ` Kai Huang
2021-01-18  3:27 ` [RFC PATCH v2 09/26] x86/sgx: Move ENCLS leaf definitions to sgx_arch.h Kai Huang
2021-01-20 11:59   ` Jarkko Sakkinen
2021-01-18  3:28 ` [RFC PATCH v2 10/26] x86/sgx: Add SGX2 ENCLS leaf definitions (EAUG, EMODPR and EMODT) Kai Huang
2021-01-20 11:59   ` Jarkko Sakkinen
2021-01-18  3:28 ` [RFC PATCH v2 11/26] x86/sgx: Add encls_faulted() helper Kai Huang
2021-01-20 12:03   ` Jarkko Sakkinen
2021-01-20 23:43     ` Kai Huang
2021-01-21  1:08       ` Jarkko Sakkinen [this message]
2021-01-21  1:12         ` Kai Huang
2021-01-21 14:38           ` Jarkko Sakkinen
2021-01-18  3:28 ` [RFC PATCH v2 12/26] x86/sgx: Add helper to update SGX_LEPUBKEYHASHn MSRs Kai Huang
2021-01-20 12:03   ` Jarkko Sakkinen
2021-01-20 18:36     ` Dave Hansen
2021-01-20 23:36       ` Kai Huang
2021-01-20 23:50         ` Dave Hansen
2021-01-21  1:06           ` Kai Huang
2021-01-21  1:15             ` Dave Hansen
2021-01-21  1:44               ` Kai Huang
2021-01-21 14:36                 ` Jarkko Sakkinen
2021-01-21  1:18             ` Kai Huang
2021-01-21  1:09         ` Jarkko Sakkinen
2021-01-21  1:08       ` Jarkko Sakkinen
2021-01-18  3:28 ` [RFC PATCH v2 13/26] x86/sgx: Add helpers to expose ECREATE and EINIT to KVM Kai Huang
2021-01-20 12:04   ` Jarkko Sakkinen
2021-01-20 23:29     ` Kai Huang
2021-01-18  3:28 ` [RFC PATCH v2 14/26] x86/sgx: Move provisioning device creation out of SGX driver Kai Huang
2021-01-20 14:09   ` Jarkko Sakkinen
2021-01-20 23:24     ` Kai Huang
2021-01-18  3:28 ` [RFC PATCH v2 15/26] KVM: VMX: Convert vcpu_vmx.exit_reason to a union Kai Huang
2021-01-20 14:18   ` Jarkko Sakkinen
2021-01-20 16:39     ` Sean Christopherson
2021-01-21  0:47       ` Jarkko Sakkinen
2021-01-21 16:33         ` Sean Christopherson
2021-01-22 17:29           ` Jarkko Sakkinen
2021-01-18  3:28 ` [RFC PATCH v2 16/26] KVM: x86: Export kvm_mmu_gva_to_gpa_{read,write}() for SGX (VMX) Kai Huang
2021-01-20 14:19   ` Jarkko Sakkinen
2021-01-18  3:28 ` [RFC PATCH v2 17/26] KVM: x86: Define new #PF SGX error code bit Kai Huang
2021-01-18  3:28 ` [RFC PATCH v2 18/26] KVM: x86: Add support for reverse CPUID lookup of scattered features Kai Huang
2021-01-18  3:28 ` [RFC PATCH v2 19/26] KVM: x86: Add reverse-CPUID lookup support for scattered SGX features Kai Huang
2021-01-18  3:28 ` [RFC PATCH v2 20/26] KVM: VMX: Add basic handling of VM-Exit from SGX enclave Kai Huang
2021-01-18  3:28 ` [RFC PATCH v2 21/26] KVM: VMX: Frame in ENCLS handler for SGX virtualization Kai Huang
2021-01-18  3:28 ` [RFC PATCH v2 22/26] KVM: VMX: Add SGX ENCLS[ECREATE] handler to enforce CPUID restrictions Kai Huang
2021-01-18  3:28 ` [RFC PATCH v2 23/26] KVM: VMX: Add emulation of SGX Launch Control LE hash MSRs Kai Huang
2021-01-18  3:28 ` [RFC PATCH v2 24/26] KVM: VMX: Add ENCLS[EINIT] handler to support SGX Launch Control (LC) Kai Huang
2021-01-18  3:28 ` [RFC PATCH v2 25/26] KVM: VMX: Enable SGX virtualization for SGX1, SGX2 and LC Kai Huang
2021-01-18  3:29 ` [RFC PATCH v2 26/26] KVM: x86: Add capability to grant VM access to privileged SGX attribute Kai Huang
2021-01-19  8:23 ` [RFC PATCH v2 00/26] KVM SGX virtualization support Jarkko Sakkinen
2021-01-20  0:52   ` Kai Huang
2021-01-20 16:35     ` Sean Christopherson
2021-01-20 16:39       ` Paolo Bonzini
2021-01-21  1:28         ` Kai Huang
2021-01-20 23:43     ` Jarkko Sakkinen
2021-01-20 23:52       ` Kai Huang
2021-01-21  1:16         ` Jarkko Sakkinen
2021-01-21  1:27           ` Kai Huang
2021-01-21 14:34             ` Jarkko Sakkinen

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=YAjUAldgNUtrx6sE@kernel.org \
    --to=jarkko@kernel.org \
    --cc=bp@alien8.de \
    --cc=dave.hansen@intel.com \
    --cc=haitao.huang@intel.com \
    --cc=hpa@zytor.com \
    --cc=kai.huang@intel.com \
    --cc=kvm@vger.kernel.org \
    --cc=linux-sgx@vger.kernel.org \
    --cc=luto@kernel.org \
    --cc=mingo@redhat.com \
    --cc=pbonzini@redhat.com \
    --cc=seanjc@google.com \
    --cc=tglx@linutronix.de \
    --cc=x86@kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).