From: Sumit Garg via OP-TEE <op-tee@lists.trustedfirmware.org>
To: Randy Dunlap <rdunlap@infradead.org>
Cc: linux-kernel@vger.kernel.org, op-tee@lists.trustedfirmware.org
Subject: Re: [PATCH] tee: clean up tee_core.h kernel-doc
Date: Thu, 12 Mar 2026 14:35:00 +0530 [thread overview]
Message-ID: <abKBvHRsJkeAm_Hq@sumit-xelite> (raw)
In-Reply-To: <20260311052953.313121-1-rdunlap@infradead.org>
On Tue, Mar 10, 2026 at 10:29:53PM -0700, Randy Dunlap wrote:
> 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>
> ---
> Cc: Jens Wiklander <jens.wiklander@linaro.org>
> Cc: Sumit Garg <sumit.garg@kernel.org>
> Cc: op-tee@lists.trustedfirmware.org
>
> include/linux/tee_core.h | 30 ++++++++++++++++--------------
> 1 file changed, 16 insertions(+), 14 deletions(-)
Thanks for the kernel-doc warnings fixes, FWIW:
Reviewed-by: Sumit Garg <sumit.garg@oss.qualcomm.com>
-Sumit
>
> --- linux-next-20260309.orig/include/linux/tee_core.h
> +++ linux-next-20260309/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(cons
> * 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 te
> * 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(str
> * @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
> * 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_
> /**
> * 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
> * 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(s
> * 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);
>
WARNING: multiple messages have this Message-ID (diff)
From: Sumit Garg <sumit.garg@kernel.org>
To: Randy Dunlap <rdunlap@infradead.org>
Cc: linux-kernel@vger.kernel.org,
Jens Wiklander <jens.wiklander@linaro.org>,
op-tee@lists.trustedfirmware.org
Subject: Re: [PATCH] tee: clean up tee_core.h kernel-doc
Date: Thu, 12 Mar 2026 14:35:00 +0530 [thread overview]
Message-ID: <abKBvHRsJkeAm_Hq@sumit-xelite> (raw)
In-Reply-To: <20260311052953.313121-1-rdunlap@infradead.org>
On Tue, Mar 10, 2026 at 10:29:53PM -0700, Randy Dunlap wrote:
> 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>
> ---
> Cc: Jens Wiklander <jens.wiklander@linaro.org>
> Cc: Sumit Garg <sumit.garg@kernel.org>
> Cc: op-tee@lists.trustedfirmware.org
>
> include/linux/tee_core.h | 30 ++++++++++++++++--------------
> 1 file changed, 16 insertions(+), 14 deletions(-)
Thanks for the kernel-doc warnings fixes, FWIW:
Reviewed-by: Sumit Garg <sumit.garg@oss.qualcomm.com>
-Sumit
>
> --- linux-next-20260309.orig/include/linux/tee_core.h
> +++ linux-next-20260309/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(cons
> * 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 te
> * 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(str
> * @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
> * 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_
> /**
> * 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
> * 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(s
> * 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);
>
next prev parent reply other threads:[~2026-03-12 9:05 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-03-11 5:29 [PATCH] tee: clean up tee_core.h kernel-doc Randy Dunlap
2026-03-11 5:29 ` Randy Dunlap
2026-03-12 9:05 ` Sumit Garg via OP-TEE [this message]
2026-03-12 9:05 ` Sumit Garg
2026-03-13 11:11 ` Jens Wiklander
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=abKBvHRsJkeAm_Hq@sumit-xelite \
--to=op-tee@lists.trustedfirmware.org \
--cc=linux-kernel@vger.kernel.org \
--cc=rdunlap@infradead.org \
--cc=sumit.garg@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.