tee: optee: fix kernel-doc warnings

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>
Reviewed-by: Sumit Garg <sumit.garg@oss.qualcomm.com>
Signed-off-by: Jens Wiklander <jens.wiklander@linaro.org>

diff --git a/drivers/tee/optee/optee_msg.h b/drivers/tee/optee/optee_msg.h
index 838e1d4a22f04fab70bc4b0382fe91576b49cbd5..7d9b12e71c0354ffc195443a8342c4f6698d621b 100644 (file)
--- 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 acd3051c4879d941f6110f6170c1cb3861c08b14..aefe1e6f568915b3bb23eca9a9759519ebb6b92b 100644 (file)
--- 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;