Re: [PATCH] tee: clean up tee_core.h kernel-doc

[Jens Wiklander]

On Thu, Mar 12, 2026 at 10:05 AM Sumit Garg <sumit.garg@xxxxxxxxxx> 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@xxxxxxxxxxxxx>
> > ---
> > Cc: Jens Wiklander <jens.wiklander@xxxxxxxxxx>
> > Cc: Sumit Garg <sumit.garg@xxxxxxxxxx>
> > Cc: op-tee@xxxxxxxxxxxxxxxxxxxxxxxxx
> >
> >  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@xxxxxxxxxxxxxxxx>

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);
> >