linux-kernel - Re: [PATCH] tee: <uapi/linux/tee.h: fix all kernel-doc issues

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <aQNj_24YgDicCLOa@sumit-X1>
Date: Thu, 30 Oct 2025 18:41:27 +0530
From: Sumit Garg <sumit.garg@...nel.org>
To: Randy Dunlap <rdunlap@...radead.org>
Cc: linux-kernel@...r.kernel.org,
	Jens Wiklander <jens.wiklander@...aro.org>,
	op-tee@...ts.trustedfirmware.org
Subject: Re: [PATCH] tee: <uapi/linux/tee.h: fix all kernel-doc issues

On Thu, Oct 23, 2025 at 10:21:02PM -0700, Randy Dunlap wrote:
> Fix kernel-doc warnings so that there no other kernel-doc issues
> in <uapi/linux/tee.h>:
> 
> - add ending ':' to some struct members as needed for kernel-doc
> - change struct name in kernel-doc to match the actual struct name (2x)
> - add a @params: kernel-doc entry multiple times
> 
> Warning: tee.h:265 struct member 'ret_origin' not described
>  in 'tee_ioctl_open_session_arg'
> Warning: tee.h:265 struct member 'num_params' not described
>  in 'tee_ioctl_open_session_arg'
> Warning: tee.h:265 struct member 'params' not described
>  in 'tee_ioctl_open_session_arg'
> Warning: tee.h:351 struct member 'num_params' not described
>  in 'tee_iocl_supp_recv_arg'
> Warning: tee.h:351 struct member 'params' not described
>  in 'tee_iocl_supp_recv_arg'
> Warning: tee.h:372 struct member 'num_params' not described
>  in 'tee_iocl_supp_send_arg'
> Warning: tee.h:372 struct member 'params' not described
>  in 'tee_iocl_supp_send_arg'
> Warning: tee.h:298: expecting prototype for struct
>  tee_ioctl_invoke_func_arg. Prototype was for
>  struct tee_ioctl_invoke_arg instead
> Warning: tee.h:473: expecting prototype for struct
>  tee_ioctl_invoke_func_arg. Prototype was for struct
>  tee_ioctl_object_invoke_arg instead
> 
> Signed-off-by: Randy Dunlap <rdunlap@...radead.org>
> ---
> Cc: Jens Wiklander <jens.wiklander@...aro.org>
> Cc: Sumit Garg <sumit.garg@...nel.org>
> Cc: op-tee@...ts.trustedfirmware.org
> ---
>  include/uapi/linux/tee.h |   23 ++++++++++++++---------
>  1 file changed, 14 insertions(+), 9 deletions(-)

Thanks for the fixes, FWIW:

Reviewed-by: Sumit Garg <sumit.garg@....qualcomm.com>

-Sumit

> 
> --- linux-next-20251022.orig/include/uapi/linux/tee.h
> +++ linux-next-20251022/include/uapi/linux/tee.h
> @@ -249,8 +249,9 @@ struct tee_ioctl_param {
>   * @cancel_id:	[in] Cancellation id, a unique value to identify this request
>   * @session:	[out] Session id
>   * @ret:	[out] return value
> - * @ret_origin	[out] origin of the return value
> - * @num_params	[in] number of parameters following this struct
> + * @ret_origin:	[out] origin of the return value
> + * @num_params:	[in] number of &struct tee_ioctl_param entries in @params
> + * @params:	array of ioctl parameters
>   */
>  struct tee_ioctl_open_session_arg {
>  	__u8 uuid[TEE_IOCTL_UUID_LEN];
> @@ -276,14 +277,14 @@ struct tee_ioctl_open_session_arg {
>  				     struct tee_ioctl_buf_data)
>  
>  /**
> - * struct tee_ioctl_invoke_func_arg - Invokes a function in a Trusted
> - * Application
> + * struct tee_ioctl_invoke_arg - Invokes a function in a Trusted Application
>   * @func:	[in] Trusted Application function, specific to the TA
>   * @session:	[in] Session id
>   * @cancel_id:	[in] Cancellation id, a unique value to identify this request
>   * @ret:	[out] return value
> - * @ret_origin	[out] origin of the return value
> - * @num_params	[in] number of parameters following this struct
> + * @ret_origin:	[out] origin of the return value
> + * @num_params:	[in] number of parameters following this struct
> + * @params:	array of ioctl parameters
>   */
>  struct tee_ioctl_invoke_arg {
>  	__u32 func;
> @@ -338,7 +339,8 @@ struct tee_ioctl_close_session_arg {
>  /**
>   * struct tee_iocl_supp_recv_arg - Receive a request for a supplicant function
>   * @func:	[in] supplicant function
> - * @num_params	[in/out] number of parameters following this struct
> + * @num_params:	[in/out] number of &struct tee_ioctl_param entries in @params
> + * @params:	array of ioctl parameters
>   *
>   * @num_params is the number of params that tee-supplicant has room to
>   * receive when input, @num_params is the number of actual params
> @@ -363,7 +365,8 @@ struct tee_iocl_supp_recv_arg {
>  /**
>   * struct tee_iocl_supp_send_arg - Send a response to a received request
>   * @ret:	[out] return value
> - * @num_params	[in] number of parameters following this struct
> + * @num_params:	[in] number of &struct tee_ioctl_param entries in @params
> + * @params:	array of ioctl parameters
>   */
>  struct tee_iocl_supp_send_arg {
>  	__u32 ret;
> @@ -454,11 +457,13 @@ struct tee_ioctl_shm_register_fd_data {
>   */
>  
>  /**
> - * struct tee_ioctl_invoke_func_arg - Invokes an object in a Trusted Application
> + * struct tee_ioctl_object_invoke_arg - Invokes an object in a
> + *   Trusted Application
>   * @id:		[in] Object id
>   * @op:		[in] Object operation, specific to the object
>   * @ret:	[out] return value
>   * @num_params:	[in] number of parameters following this struct
> + * @params:	array of ioctl parameters
>   */
>  struct tee_ioctl_object_invoke_arg {
>  	__u64 id;