[PATCH] x86/sgx: Fix typos and formatting in function comments

[PATCH] x86/sgx: Fix typos and formatting in function comments

[Thorsten Blum]

Fix typos and formatting in function comments to clarify that
sgx_set_attribute() returns 0, not -0, to avoid confusion and to be
consistent.

Signed-off-by: Thorsten Blum <thorsten.blum@linux.dev>
---
 arch/x86/kernel/cpu/sgx/main.c | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/arch/x86/kernel/cpu/sgx/main.c b/arch/x86/kernel/cpu/sgx/main.c
index 2de01b379aa3..c33e2b56a3fc 100644
--- a/arch/x86/kernel/cpu/sgx/main.c
+++ b/arch/x86/kernel/cpu/sgx/main.c
@@ -465,11 +465,11 @@ static struct sgx_epc_page *__sgx_alloc_epc_page_from_node(int nid)
 /**
  * __sgx_alloc_epc_page() - Allocate an EPC page
  *
- * Iterate through NUMA nodes and reserve ia free EPC page to the caller. Start
+ * Iterate through NUMA nodes and reserve a free EPC page to the caller. Start
  * from the NUMA node, where the caller is executing.
  *
  * Return:
- * - an EPC page:	A borrowed EPC pages were available.
+ * - an EPC page:	A borrowed EPC page if available.
  * - NULL:		Out of EPC pages.
  */
 struct sgx_epc_page *__sgx_alloc_epc_page(void)
@@ -898,8 +898,8 @@ static struct miscdevice sgx_dev_provision = {
  * /dev/sgx_provision is supported.
  *
  * Return:
- * -0:		SGX_ATTR_PROVISIONKEY is appended to allowed_attributes
- * -EINVAL:	Invalid, or not supported file descriptor
+ * - 0:		SGX_ATTR_PROVISIONKEY is appended to allowed_attributes
+ * - -EINVAL:	Invalid, or not supported file descriptor
  */
 int sgx_set_attribute(unsigned long *allowed_attributes,
 		      unsigned int attribute_fd)
-- 
2.51.1

Re: [PATCH] x86/sgx: Fix typos and formatting in function comments

[Huang, Kai]

On Mon, 2025-11-03 at 10:01 +0100, Thorsten Blum wrote:
> Fix typos and formatting in function comments to clarify that
> sgx_set_attribute() returns 0, not -0, to avoid confusion and to be
> consistent.
> 
> Signed-off-by: Thorsten Blum <thorsten.blum@linux.dev>
> ---
>  arch/x86/kernel/cpu/sgx/main.c | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/arch/x86/kernel/cpu/sgx/main.c b/arch/x86/kernel/cpu/sgx/main.c
> index 2de01b379aa3..c33e2b56a3fc 100644
> --- a/arch/x86/kernel/cpu/sgx/main.c
> +++ b/arch/x86/kernel/cpu/sgx/main.c
> @@ -465,11 +465,11 @@ static struct sgx_epc_page *__sgx_alloc_epc_page_from_node(int nid)
>  /**
>   * __sgx_alloc_epc_page() - Allocate an EPC page
>   *
> - * Iterate through NUMA nodes and reserve ia free EPC page to the caller. Start
> + * Iterate through NUMA nodes and reserve a free EPC page to the caller. Start
>   * from the NUMA node, where the caller is executing.
>   *
>   * Return:
> - * - an EPC page:	A borrowed EPC pages were available.
> + * - an EPC page:	A borrowed EPC page if available.
>   * - NULL:		Out of EPC pages.
>   */

Ack for fixing the typos.

>  struct sgx_epc_page *__sgx_alloc_epc_page(void)
> @@ -898,8 +898,8 @@ static struct miscdevice sgx_dev_provision = {
>   * /dev/sgx_provision is supported.
>   *
>   * Return:
> - * -0:		SGX_ATTR_PROVISIONKEY is appended to allowed_attributes
> - * -EINVAL:	Invalid, or not supported file descriptor
> + * - 0:		SGX_ATTR_PROVISIONKEY is appended to allowed_attributes
> + * - -EINVAL:	Invalid, or not supported file descriptor
>   */
>  int sgx_set_attribute(unsigned long *allowed_attributes,
>  		      unsigned int attribute_fd)

It seems we don't have a consistent way of describing return values in the
k-doc comments in sgx/main.c.  E.g.,

/**
 * sgx_unmark_page_reclaimable() - Remove a page from the reclaim list     

 ...

 * Return:
 *   0 on success,
 *   -EBUSY if the page is in the process of being reclaimed               
 */ 


/**
 * sgx_alloc_epc_page() - Allocate an EPC page                             

 ...

 * Return:
 *   an EPC page,
 *   -errno on error                                                       
 */

Perhaps we should make them consistent in format.

But I think this can be done separately from fixing the typos.  Maybe you 
can split out the typo fixing as a separate patch, and have another patch to
fixing the return value description?

Re: [PATCH] x86/sgx: Fix typos and formatting in function comments

[Thorsten Blum]

On 4. Nov 2025, at 00:47, Huang, Kai wrote:
> It seems we don't have a consistent way of describing return values in the
> k-doc comments in sgx/main.c.  E.g.,
> 
> /**
> * sgx_unmark_page_reclaimable() - Remove a page from the reclaim list
> 
> ...
> 
> * Return:
> *   0 on success,
> *   -EBUSY if the page is in the process of being reclaimed
> */
> 
> 
> /**
> * sgx_alloc_epc_page() - Allocate an EPC page
> 
> ...
> 
> * Return:
> *   an EPC page,
> *   -errno on error
> */
> 
> Perhaps we should make them consistent in format.
> 
> But I think this can be done separately from fixing the typos.  Maybe you 
> can split out the typo fixing as a separate patch, and have another patch to
> fixing the return value description?

I used the style mostly found in main.c and ioctl.c - would that be the
"correct" format for the others as well? Happy to submit a separate
patch if it's worth it.

Thanks,
Thorsten

Re: [PATCH] x86/sgx: Fix typos and formatting in function comments

[Huang, Kai]

On Tue, 2025-11-04 at 20:13 +0100, Thorsten Blum wrote:
> On 4. Nov 2025, at 00:47, Huang, Kai wrote:
> > It seems we don't have a consistent way of describing return values in the
> > k-doc comments in sgx/main.c.  E.g.,
> > 
> > /**
> > * sgx_unmark_page_reclaimable() - Remove a page from the reclaim list
> > 
> > ...
> > 
> > * Return:
> > *   0 on success,
> > *   -EBUSY if the page is in the process of being reclaimed
> > */
> > 
> > 
> > /**
> > * sgx_alloc_epc_page() - Allocate an EPC page
> > 
> > ...
> > 
> > * Return:
> > *   an EPC page,
> > *   -errno on error
> > */
> > 
> > Perhaps we should make them consistent in format.
> > 
> > But I think this can be done separately from fixing the typos.  Maybe you 
> > can split out the typo fixing as a separate patch, and have another patch to
> > fixing the return value description?
> 
> I used the style mostly found in main.c and ioctl.c - would that be the
> "correct" format for the others as well? Happy to submit a separate
> patch if it's worth it.

I found a link documenting that (please search "Return values"):

https://docs.kernel.org/doc-guide/kernel-doc.html

In short, the doc suggested to use a "ReST list", e.g.,:

	* Return:
	* * %0            - OK to runtime suspend the device
	* * %-EBUSY       - Device should not be runtime suspended

But I am not a fan of cleaning up all the existing SGX comments to it, since
this will just be a burden to maintainers I suppose.  And I bet there are
other places in the kernel not following this "ReST list", i.e., I view this
as a suggestion but not a requirement.

Another option is you can just change to follow the quoted two examples
above (e.g., sgx_unmark_page_reclaimable()) so that at least in sgx/main.c
they are consistent.

Or just leave the comment as is.

That's my 2cents, and in any way, I will be happy to review.