On Thu, Jul 11, 2019 at 08:42:31AM -0700, Sean Christopherson wrote:
> On Thu, Jul 11, 2019 at 12:53:17PM +0300, Jarkko Sakkinen wrote:
> > On Wed, Jul 10, 2019 at 09:21:32PM -0700, Cedric Xing wrote:
> > > -#ifdef SGX_KERNEL_DOC
> >
> > Why is this removed?
> >
> > > + * int __vdso_sgx_enter_enclave(int leaf, void *tcs,
> > > + * struct sgx_enclave_exinfo *exinfo,
> > > + * sgx_callback callback)
> > > + * {
> > > + * while (leaf == EENTER || leaf == ERESUME) {
> > > + * int rc;
> > > + * try {
> > > + * ENCLU[leaf];
> > > + * rc = 0;
> > > + * if (exinfo)
> > > + * exinfo->leaf = EEXIT;
> > > + * } catch (exception) {
> > > + * rc = -EFAULT;
> > > + * if (exinfo)
> > > + * *exinfo = exception;
> > > + * }
> > > + *
> > > + * leaf = !callback ? rc: (*callback)(rdi, rsi, rdx, exinfo,
> > > + * r8, r9, tcs, ursp);
> > > + * }
> > > + *
> > > + * return leaf > 0 ? -EINVAL : leaf;
> > > + * }
> > > */
> >
> > What is this? C++ and anyway there is already a source code. No need
> > to duplicate with pseudo-code. Only adds maintenance burde. Please get
> > rid of this.
>
> Adding C pseudo-code was my idea, e.g. it already exists in v20. Declaring
> a psuedo-C function coerces kernel-doc into generating documentation for
> the asm routine. IIRC, fully defining the function is not required for
> docs, but IMO it's significantly easier to gain an understanding of a blob
> of asm if there is higher level pseudocode.
The way to do this right would be to write a documentation block before
kdoc's for the functions. It is described in the last section of
https://www.kernel.org/doc/Documentation/kernel-doc-nano-HOWTO.txt0
I.e. organize the file as
1. Documentation block describing the theory of operation.
2. Functions and their associated documentations.
/Jarkko
