On Thu, Jul 11, 2019 at 08:55:50PM +0300, Jarkko Sakkinen wrote:
> 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.
The kernel doc parser straight up doesn't work on asm functions, hence the
shenanigans to coerce it into thinking it's parsing a normal C function.
