tee: clean up tee_core.h kernel-doc

Use the correct struct member name and function parameter name in
kernel-doc comments.
Move a macro that was between a struct's documentation and its
declaration.
These eliminate the following kernel-doc warnings:

Warning: include/linux/tee_core.h:73 struct member 'c_no_users' not
 described in 'tee_device'
Warning: include/linux/tee_core.h:132 #define TEE_DESC_PRIVILEGED
     0x1; error: Cannot parse struct or union!
Warning: include/linux/tee_core.h:257 function parameter 'connection_data'
 not described in 'tee_session_calc_client_uuid'
Warning: include/linux/tee_core.h:320 function parameter 'teedev'
 not described in 'tee_get_drvdata'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Sumit Garg <sumit.garg@oss.qualcomm.com>
Signed-off-by: Jens Wiklander <jens.wiklander@linaro.org>

diff --git a/include/linux/tee_core.h b/include/linux/tee_core.h
index ee5f0bd41f43aaaf6a18111dc53bfdb81b16abaf..f993d5118eddabcc55205fca8542c47eb73550cb 100644 (file)
--- a/include/linux/tee_core.h
+++ b/include/linux/tee_core.h
@@ -50,7 +50,7 @@ enum tee_dma_heap_id {
  * @dev:       embedded basic device structure
  * @cdev:      embedded cdev
  * @num_users: number of active users of this device
- * @c_no_user: completion used when unregistering the device
+ * @c_no_users:        completion used when unregistering the device
  * @mutex:     mutex protecting @num_users and @idr
  * @idr:       register of user space shared memory objects allocated or
  *             registered on this device
@@ -132,6 +132,7 @@ struct tee_driver_ops {
 /* Size for TEE revision string buffer used by get_tee_revision(). */
 #define TEE_REVISION_STR_SIZE  128
 
+#define TEE_DESC_PRIVILEGED    0x1
 /**
  * struct tee_desc - Describes the TEE driver to the subsystem
  * @name:      name of driver
@@ -139,7 +140,6 @@ struct tee_driver_ops {
  * @owner:     module providing the driver
  * @flags:     Extra properties of driver, defined by TEE_DESC_* below
  */
-#define TEE_DESC_PRIVILEGED    0x1
 struct tee_desc {
        const char *name;
        const struct tee_driver_ops *ops;
@@ -187,7 +187,7 @@ struct tee_protmem_pool_ops {
  * Allocates a new struct tee_device instance. The device is
  * removed by tee_device_unregister().
  *
- * @returns a pointer to a 'struct tee_device' or an ERR_PTR on failure
+ * @returns: a pointer to a 'struct tee_device' or an ERR_PTR on failure
  */
 struct tee_device *tee_device_alloc(const struct tee_desc *teedesc,
                                    struct device *dev,
@@ -201,7 +201,7 @@ struct tee_device *tee_device_alloc(const struct tee_desc *teedesc,
  * tee_device_unregister() need to be called to remove the @teedev if
  * this function fails.
  *
- * @returns < 0 on failure
+ * @returns: < 0 on failure
  */
 int tee_device_register(struct tee_device *teedev);
 
@@ -254,14 +254,14 @@ void tee_device_set_dev_groups(struct tee_device *teedev,
  * tee_session_calc_client_uuid() - Calculates client UUID for session
  * @uuid:              Resulting UUID
  * @connection_method: Connection method for session (TEE_IOCTL_LOGIN_*)
- * @connectuon_data:   Connection data for opening session
+ * @connection_data:   Connection data for opening session
  *
  * Based on connection method calculates UUIDv5 based client UUID.
  *
  * For group based logins verifies that calling process has specified
  * credentials.
  *
- * @return < 0 on failure
+ * @returns: < 0 on failure
  */
 int tee_session_calc_client_uuid(uuid_t *uuid, u32 connection_method,
                                 const u8 connection_data[TEE_IOCTL_UUID_LEN]);
@@ -295,7 +295,7 @@ struct tee_shm_pool_ops {
  * @paddr:     Physical address of start of pool
  * @size:      Size in bytes of the pool
  *
- * @returns pointer to a 'struct tee_shm_pool' or an ERR_PTR on failure.
+ * @returns: pointer to a 'struct tee_shm_pool' or an ERR_PTR on failure.
  */
 struct tee_shm_pool *tee_shm_pool_alloc_res_mem(unsigned long vaddr,
                                                phys_addr_t paddr, size_t size,
@@ -318,14 +318,16 @@ static inline void tee_shm_pool_free(struct tee_shm_pool *pool)
  * @paddr:     Physical address of start of pool
  * @size:      Size in bytes of the pool
  *
- * @returns pointer to a 'struct tee_protmem_pool' or an ERR_PTR on failure.
+ * @returns: pointer to a 'struct tee_protmem_pool' or an ERR_PTR on failure.
  */
 struct tee_protmem_pool *tee_protmem_static_pool_alloc(phys_addr_t paddr,
                                                       size_t size);
 
 /**
  * tee_get_drvdata() - Return driver_data pointer
- * @returns the driver_data pointer supplied to tee_register().
+ * @teedev: Pointer to the tee_device
+ *
+ * @returns: the driver_data pointer supplied to tee_register().
  */
 void *tee_get_drvdata(struct tee_device *teedev);
 
@@ -334,7 +336,7 @@ void *tee_get_drvdata(struct tee_device *teedev);
  *                            TEE driver
  * @ctx:       The TEE context for shared memory allocation
  * @size:      Shared memory allocation size
- * @returns a pointer to 'struct tee_shm' on success or an ERR_PTR on failure
+ * @returns: a pointer to 'struct tee_shm' on success or an ERR_PTR on failure
  */
 struct tee_shm *tee_shm_alloc_priv_buf(struct tee_context *ctx, size_t size);
 
@@ -354,7 +356,7 @@ void tee_dyn_shm_free_helper(struct tee_shm *shm,
 /**
  * tee_shm_is_dynamic() - Check if shared memory object is of the dynamic kind
  * @shm:       Shared memory handle
- * @returns true if object is dynamic shared memory
+ * @returns: true if object is dynamic shared memory
  */
 static inline bool tee_shm_is_dynamic(struct tee_shm *shm)
 {
@@ -370,7 +372,7 @@ void tee_shm_put(struct tee_shm *shm);
 /**
  * tee_shm_get_id() - Get id of a shared memory object
  * @shm:       Shared memory handle
- * @returns id
+ * @returns: id
  */
 static inline int tee_shm_get_id(struct tee_shm *shm)
 {
@@ -382,7 +384,7 @@ static inline int tee_shm_get_id(struct tee_shm *shm)
  * count
  * @ctx:       Context owning the shared memory
  * @id:                Id of shared memory object
- * @returns a pointer to 'struct tee_shm' on success or an ERR_PTR on failure
+ * @returns: a pointer to 'struct tee_shm' on success or an ERR_PTR on failure
  */
 struct tee_shm *tee_shm_get_from_id(struct tee_context *ctx, int id);
 
@@ -402,7 +404,7 @@ static inline bool tee_param_is_memref(struct tee_param *param)
  * teedev_open() - Open a struct tee_device
  * @teedev:    Device to open
  *
- * @return a pointer to struct tee_context on success or an ERR_PTR on failure.
+ * @returns: pointer to struct tee_context on success or an ERR_PTR on failure.
  */
 struct tee_context *teedev_open(struct tee_device *teedev);