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(-)
--- 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);
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);
On Thu, Mar 12, 2026 at 10:05 AM Sumit Garg sumit.garg@kernel.org wrote:
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
I'm picking up this.
Thanks, Jens
-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);
op-tee@lists.trustedfirmware.org
-
Jens Wiklander -
Randy Dunlap -
Sumit Garg