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

13 Apr 2026

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

    

2026

2025

2024

2023

2022

2021

2020

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

Signed-off-by: Rodrigo Zaiden rodrigoffzz@gmail.com