On Thu, 21 Jan 2021 03:08:18 +0200 Jarkko Sakkinen wrote: > 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@xxxxxxxxx> > > > > > > > > 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@xxxxxxxxx> > > > > Acked-by: Dave Hansen <dave.hansen@xxxxxxxxx> > > > > Signed-off-by: Kai Huang <kai.huang@xxxxxxxxx> > > > > --- > > > > 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." OK. Will change to yours. Thanks for the info. > > /Jarkko
