Re: [PATCH] tee: optee: fix kernel-doc warnings

[Sumit Garg via OP-TEE <op-tee@lists.trustedfirmware.org>]

On Sun, Mar 22, 2026 at 01:31:14PM -0300, Rodrigo Zaiden wrote:
> Fix kernel-doc issues in optee_private.h and optee_msg.h:
> 
> - Add missing documentation for struct members: optee_msg_param_value,
>   optee_msg_param, optee_msg_arg, optee, and optee_ffa;
> - Ensure member descriptions follow the order of declaration;
> - Use consistent formatting (lowercase descriptions and ':' after
>   member names);
> - Adjust indentation for better alignment;
> 
> This resolves kernel-doc warnings such as missing member descriptions
> and incorrect prototype documentation.
> No functional changes.
> 
> Signed-off-by: Rodrigo Zaiden <rodrigoffzz@gmail.com>
> ---
>  drivers/tee/optee/optee_msg.h     |  50 +++++++------
>  drivers/tee/optee/optee_private.h | 120 ++++++++++++++++--------------
>  2 files changed, 92 insertions(+), 78 deletions(-)

Thanks for doc fixes, FWIW:

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

-Sumit

> 
> diff --git a/drivers/tee/optee/optee_msg.h b/drivers/tee/optee/optee_msg.h
> index 838e1d4a22f0..7d9b12e71c03 100644
> --- a/drivers/tee/optee/optee_msg.h
> +++ b/drivers/tee/optee/optee_msg.h
> @@ -103,9 +103,9 @@
>  
>  /**
>   * struct optee_msg_param_tmem - temporary memory reference parameter
> - * @buf_ptr:	Address of the buffer
> - * @size:	Size of the buffer
> - * @shm_ref:	Temporary shared memory reference, pointer to a struct tee_shm
> + * @buf_ptr:	address of the buffer
> + * @size:	size of the buffer
> + * @shm_ref:	temporary shared memory reference, pointer to a struct tee_shm
>   *
>   * Secure and normal world communicates pointers as physical address
>   * instead of the virtual address. This is because secure and normal world
> @@ -122,9 +122,9 @@ struct optee_msg_param_tmem {
>  
>  /**
>   * struct optee_msg_param_rmem - registered memory reference parameter
> - * @offs:	Offset into shared memory reference
> - * @size:	Size of the buffer
> - * @shm_ref:	Shared memory reference, pointer to a struct tee_shm
> + * @offs:	offset into shared memory reference
> + * @size:	size of the buffer
> + * @shm_ref:	shared memory reference, pointer to a struct tee_shm
>   */
>  struct optee_msg_param_rmem {
>  	u64 offs;
> @@ -134,12 +134,12 @@ struct optee_msg_param_rmem {
>  
>  /**
>   * struct optee_msg_param_fmem - FF-A memory reference parameter
> - * @offs_lower:	   Lower bits of offset into shared memory reference
> - * @offs_upper:	   Upper bits of offset into shared memory reference
> - * @internal_offs: Internal offset into the first page of shared memory
> - *		   reference
> - * @size:	   Size of the buffer
> - * @global_id:	   Global identifier of the shared memory
> + * @offs_low:		lower bits of offset into shared memory reference
> + * @offs_high:		higher bits of offset into shared memory reference
> + * @internal_offs:	internal offset into the first page of shared memory
> + *			reference
> + * @size:		size of the buffer
> + * @global_id:		global identifier of the shared memory
>   */
>  struct optee_msg_param_fmem {
>  	u32 offs_low;
> @@ -151,6 +151,9 @@ struct optee_msg_param_fmem {
>  
>  /**
>   * struct optee_msg_param_value - opaque value parameter
> + * @a: first opaque value
> + * @b: second opaque value
> + * @c: third opaque value
>   *
>   * Value parameters are passed unchecked between normal and secure world.
>   */
> @@ -168,6 +171,7 @@ struct optee_msg_param_value {
>   * @fmem:	parameter by FF-A registered memory reference
>   * @value:	parameter by opaque value
>   * @octets:	parameter by octet string
> + * @u:		union holding OP-TEE msg parameter
>   *
>   * @attr & OPTEE_MSG_ATTR_TYPE_MASK indicates if tmem, rmem or value is used in
>   * the union. OPTEE_MSG_ATTR_TYPE_VALUE_* indicates value or octets,
> @@ -189,16 +193,18 @@ struct optee_msg_param {
>  
>  /**
>   * struct optee_msg_arg - call argument
> - * @cmd: Command, one of OPTEE_MSG_CMD_* or OPTEE_MSG_RPC_CMD_*
> - * @func: Trusted Application function, specific to the Trusted Application,
> - *	     used if cmd == OPTEE_MSG_CMD_INVOKE_COMMAND
> - * @session: In parameter for all OPTEE_MSG_CMD_* except
> - *	     OPTEE_MSG_CMD_OPEN_SESSION where it's an output parameter instead
> - * @cancel_id: Cancellation id, a unique value to identify this request
> - * @ret: return value
> - * @ret_origin: origin of the return value
> - * @num_params: number of parameters supplied to the OS Command
> - * @params: the parameters supplied to the OS Command
> + * @cmd:	command, one of OPTEE_MSG_CMD_* or OPTEE_MSG_RPC_CMD_*
> + * @func:	Trusted Application function, specific to the Trusted
> + *		Application, used if cmd == OPTEE_MSG_CMD_INVOKE_COMMAND
> + * @session:	in parameter for all OPTEE_MSG_CMD_* except
> + *		OPTEE_MSG_CMD_OPEN_SESSION where it's an output parameter
> + *		instead
> + * @cancel_id:	cancellation id, a unique value to identify this request
> + * @pad:	padding for alignment
> + * @ret:	return value
> + * @ret_origin:	origin of the return value
> + * @num_params:	number of parameters supplied to the OS Command
> + * @params:	the parameters supplied to the OS Command
>   *
>   * All normal calls to Trusted OS uses this struct. If cmd requires further
>   * information than what these fields hold it can be passed as a parameter
> diff --git a/drivers/tee/optee/optee_private.h b/drivers/tee/optee/optee_private.h
> index acd3051c4879..aefe1e6f5689 100644
> --- a/drivers/tee/optee/optee_private.h
> +++ b/drivers/tee/optee/optee_private.h
> @@ -47,11 +47,11 @@ typedef void (optee_invoke_fn)(unsigned long, unsigned long, unsigned long,
>  				unsigned long, unsigned long,
>  				struct arm_smccc_res *);
>  
> -/*
> +/**
>   * struct optee_call_waiter - TEE entry may need to wait for a free TEE thread
> - * @list_node		Reference in waiters list
> - * @c			Waiting completion reference
> - * @sys_thread		True if waiter belongs to a system thread
> + * @list_node:	reference in waiters list
> + * @c:		waiting completion reference
> + * @sys_thread:	true if waiter belongs to a system thread
>   */
>  struct optee_call_waiter {
>  	struct list_head list_node;
> @@ -59,13 +59,13 @@ struct optee_call_waiter {
>  	bool sys_thread;
>  };
>  
> -/*
> +/**
>   * struct optee_call_queue - OP-TEE call queue management
> - * @mutex			Serializes access to this struct
> - * @waiters			List of threads waiting to enter OP-TEE
> - * @total_thread_count		Overall number of thread context in OP-TEE or 0
> - * @free_thread_count		Number of threads context free in OP-TEE
> - * @sys_thread_req_count	Number of registered system thread sessions
> + * @mutex:			serializes access to this struct
> + * @waiters:			list of threads waiting to enter OP-TEE
> + * @total_thread_count:		overall number of thread context in OP-TEE or 0
> + * @free_thread_count:		number of threads context free in OP-TEE
> + * @sys_thread_req_count:	number of registered system thread sessions
>   */
>  struct optee_call_queue {
>  	/* Serializes access to this struct */
> @@ -96,17 +96,17 @@ struct optee_shm_arg_cache {
>  
>  /**
>   * struct optee_supp - supplicant synchronization struct
> - * @ctx			the context of current connected supplicant.
> - *			if !NULL the supplicant device is available for use,
> - *			else busy
> - * @mutex:		held while accessing content of this struct
> - * @req_id:		current request id if supplicant is doing synchronous
> - *			communication, else -1
> - * @reqs:		queued request not yet retrieved by supplicant
> - * @idr:		IDR holding all requests currently being processed
> - *			by supplicant
> - * @reqs_c:		completion used by supplicant when waiting for a
> - *			request to be queued.
> + * @mutex:	held while accessing content of this struct
> + * @ctx:	the context of current connected supplicant.
> + *		if !NULL the supplicant device is available for use,
> + *		else busy
> + * @req_id:	current request id if supplicant is doing synchronous
> + *		communication, else -1
> + * @reqs:	queued request not yet retrieved by supplicant
> + * @idr:	IDR holding all requests currently being processed
> + *		by supplicant
> + * @reqs_c:	completion used by supplicant when waiting for a
> + *		request to be queued.
>   */
>  struct optee_supp {
>  	/* Serializes access to this struct */
> @@ -119,25 +119,25 @@ struct optee_supp {
>  	struct completion reqs_c;
>  };
>  
> -/*
> +/**
>   * struct optee_pcpu - per cpu notif private struct passed to work functions
> - * @optee		optee device reference
> + * @optee:	optee device reference
>   */
>  struct optee_pcpu {
>  	struct optee *optee;
>  };
>  
> -/*
> +/**
>   * struct optee_smc - optee smc communication struct
> - * @invoke_fn		handler function to invoke secure monitor
> - * @memremaped_shm	virtual address of memory in shared memory pool
> + * @invoke_fn:		handler function to invoke secure monitor
> + * @memremaped_shm:	virtual address of memory in shared memory pool
>   * @sec_caps:		secure world capabilities defined by
>   *			OPTEE_SMC_SEC_CAP_* in optee_smc.h
> - * @notif_irq		interrupt used as async notification by OP-TEE or 0
> - * @optee_pcpu		per_cpu optee instance for per cpu work or NULL
> - * @notif_pcpu_wq	workqueue for per cpu asynchronous notification or NULL
> - * @notif_pcpu_work	work for per cpu asynchronous notification
> - * @notif_cpuhp_state   CPU hotplug state assigned for pcpu interrupt management
> + * @notif_irq:		interrupt used as async notification by OP-TEE or 0
> + * @optee_pcpu:		per_cpu optee instance for per cpu work or NULL
> + * @notif_pcpu_wq:	workqueue for per cpu asynchronous notification or NULL
> + * @notif_pcpu_work:	work for per cpu asynchronous notification
> + * @notif_cpuhp_state:	CPU hotplug state assigned for pcpu interrupt management
>   */
>  struct optee_smc {
>  	optee_invoke_fn *invoke_fn;
> @@ -151,13 +151,15 @@ struct optee_smc {
>  };
>  
>  /**
> - * struct optee_ffa_data -  FFA communication struct
> - * @ffa_dev		FFA device, contains the destination id, the id of
> + * struct optee_ffa -  FFA communication struct
> + * @ffa_dev:		FFA device, contains the destination id, the id of
>   *			OP-TEE in secure world
> - * @bottom_half_value	Notification ID used for bottom half signalling or
> + * @bottom_half_value:	notification ID used for bottom half signalling or
>   *			U32_MAX if unused
> - * @mutex		Serializes access to @global_ids
> - * @global_ids		FF-A shared memory global handle translation
> + * @mutex:		serializes access to @global_ids
> + * @global_ids:		FF-A shared memory global handle translation
> + * @notif_wq:		workqueue for FF-A asynchronous notification
> + * @notif_work:		work for FF-A asynchronous notification
>   */
>  struct optee_ffa {
>  	struct ffa_device *ffa_dev;
> @@ -222,26 +224,32 @@ struct optee_ops {
>  
>  /**
>   * struct optee - main service struct
> - * @supp_teedev:	supplicant device
> - * @teedev:		client device
> - * @ops:		internal callbacks for different ways to reach secure
> - *			world
> - * @ctx:		driver internal TEE context
> - * @smc:		specific to SMC ABI
> - * @ffa:		specific to FF-A ABI
> - * @call_queue:		queue of threads waiting to call @invoke_fn
> - * @notif:		notification synchronization struct
> - * @supp:		supplicant synchronization struct for RPC to supplicant
> - * @pool:		shared memory pool
> - * @mutex:		mutex protecting @rpmb_dev
> - * @rpmb_dev:		current RPMB device or NULL
> - * @rpmb_scan_bus_done	flag if device registation of RPMB dependent devices
> - *			was already done
> - * @rpmb_scan_bus_work	workq to for an RPMB device and to scan optee bus
> - *			and register RPMB dependent optee drivers
> - * @rpc_param_count:	If > 0 number of RPC parameters to make room for
> - * @scan_bus_done	flag if device registation was already done.
> - * @scan_bus_work	workq to scan optee bus and register optee drivers
> + * @supp_teedev:		supplicant device
> + * @teedev:			client device
> + * @ops:			internal callbacks for different ways to reach
> + *				secure world
> + * @ctx:			driver internal TEE context
> + * @smc:			specific to SMC ABI
> + * @ffa:			specific to FF-A ABI
> + * @shm_arg_cache:		shared memory cache argument
> + * @call_queue:			queue of threads waiting to call @invoke_fn
> + * @notif:			notification synchronization struct
> + * @supp:			supplicant synchronization struct for RPC to
> + *				supplicant
> + * @pool:			shared memory pool
> + * @rpmb_dev_mutex:		mutex protecting @rpmb_dev
> + * @rpmb_dev:			current RPMB device or NULL
> + * @rpmb_intf:			RPMB notifier block
> + * @rpc_param_count:		if > 0 number of RPC parameters to make room for
> + * @scan_bus_done:		flag if device registation was already done
> + * @rpmb_scan_bus_done:		flag if device registation of RPMB dependent
> + *				devices was already done
> + * @in_kernel_rpmb_routing:	flag if OP-TEE supports in-kernel RPMB routing
> + * @scan_bus_work:		workq to scan optee bus and register optee
> + *				drivers
> + * @rpmb_scan_bus_work:		workq to for an RPMB device and to scan optee
> + *				bus and register RPMB dependent optee drivers
> + * @revision:			OP-TEE OS revision
>   */
>  struct optee {
>  	struct tee_device *supp_teedev;
> -- 
> 2.43.0
>