Re: [PATCH v2 09/16] drm/ttm: fix ttm_bo.h kernel-doc warnings

["Christian König" <christian.koenig@amd.com>]

Am 08.03.24 um 12:55 schrieb Jani Nikula:
> Some renames, some formatting fixes, add some missing documentation.
>
> Cc: Christian Koenig <christian.koenig@amd.com>
> Cc: Huang Rui <ray.huang@amd.com>
> Acked-by: Thomas Zimmermann <tzimmermann@suse.de>
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> ---
>   include/drm/ttm/ttm_bo.h | 18 ++++++++++++------
>   1 file changed, 12 insertions(+), 6 deletions(-)
>
> diff --git a/include/drm/ttm/ttm_bo.h b/include/drm/ttm/ttm_bo.h
> index 0223a41a64b2..59151ecb2db3 100644
> --- a/include/drm/ttm/ttm_bo.h
> +++ b/include/drm/ttm/ttm_bo.h
> @@ -83,6 +83,9 @@ enum ttm_bo_type {
>    * @resource: structure describing current placement.
>    * @ttm: TTM structure holding system pages.
>    * @deleted: True if the object is only a zombie and already deleted.
> + * @bulk_move: The bulk move object.
> + * @priority: Priority for LRU, BOs with lower priority are evicted first.
> + * @pin_count: Pin count.
>    *
>    * Base class for TTM buffer object, that deals with data placement and CPU
>    * mappings. GPU mappings are really up to the driver, but for simpler GPUs
> @@ -128,26 +131,28 @@ struct ttm_buffer_object {
>   	struct work_struct delayed_delete;
>   
>   	/**
> -	 * Special members that are protected by the reserve lock
> -	 * and the bo::lock when written to. Can be read with
> -	 * either of these locks held.
> +	 * @sg: Special members that are protected by the reserve lock and the
> +	 * bo::lock when written to. Can be read with either of these locks
> +	 * held.

Actually that is completely outdated since the bo::lock was removed 
years ago.

I would just write that as "@sg: external source of pages and DMA 
addresses, protected by the reservation lock." (or something like this).

With that fixed feel free to add Reviewed-by: Christian König 
<christian.koenig@amd.com> to this patch and the other TTM cleanup 
patches in this series.

Regards,
Christian.

>   	 */
>   	struct sg_table *sg;
>   };
>   
> +#define TTM_BO_MAP_IOMEM_MASK 0x80
> +
>   /**
>    * struct ttm_bo_kmap_obj
>    *
>    * @virtual: The current kernel virtual address.
>    * @page: The page when kmap'ing a single page.
>    * @bo_kmap_type: Type of bo_kmap.
> + * @bo: The TTM BO.
>    *
>    * Object describing a kernel mapping. Since a TTM bo may be located
>    * in various memory types with various caching policies, the
>    * mapping can either be an ioremap, a vmap, a kmap or part of a
>    * premapped region.
>    */
> -#define TTM_BO_MAP_IOMEM_MASK 0x80
>   struct ttm_bo_kmap_obj {
>   	void *virtual;
>   	struct page *page;
> @@ -171,6 +176,7 @@ struct ttm_bo_kmap_obj {
>    * @force_alloc: Don't check the memory account during suspend or CPU page
>    * faults. Should only be used by TTM internally.
>    * @resv: Reservation object to allow reserved evictions with.
> + * @bytes_moved: Statistics on how many bytes have been moved.
>    *
>    * Context for TTM operations like changing buffer placement or general memory
>    * allocation.
> @@ -264,7 +270,7 @@ static inline int ttm_bo_reserve(struct ttm_buffer_object *bo,
>    * ttm_bo_reserve_slowpath:
>    * @bo: A pointer to a struct ttm_buffer_object.
>    * @interruptible: Sleep interruptible if waiting.
> - * @sequence: Set (@bo)->sequence to this value after lock
> + * @ticket: Ticket used to acquire the ww_mutex.
>    *
>    * This is called after ttm_bo_reserve returns -EAGAIN and we backed off
>    * from all our other reservations. Because there are no other reservations
> @@ -303,7 +309,7 @@ static inline void ttm_bo_assign_mem(struct ttm_buffer_object *bo,
>   }
>   
>   /**
> - * ttm_bo_move_null = assign memory for a buffer object.
> + * ttm_bo_move_null - assign memory for a buffer object.
>    * @bo: The bo to assign the memory to
>    * @new_mem: The memory to be assigned.
>    *