Re: [Intel-gfx] [PATCH v4 06/14] drm/ttm: add some kernel-doc for TTM_TT_FLAG_*

Christian König
2021-09-21T11:33:21Z

Am 21.09.21 um 13:01 schrieb Matthew Auld:
> Move it to inline kernel-doc, otherwise we can't add empty lines it
> seems. Also drop the kernel-doc for pages_list, which doesn't seem to
> exist.
>
> Signed-off-by: Matthew Auld <matthew.auld@intel.com>
> Cc: Thomas Hellström <thomas.hellstrom@linux.intel.com>
> Cc: Christian König <christian.koenig@amd.com>

One comment below, with that fixed Reviewed-by: Christian König
<christian.koenig@amd.com>

> ---
> include/drm/ttm/ttm_tt.h | 57 ++++++++++++++++++++++++++--------------
> 1 file changed, 38 insertions(+), 19 deletions(-)
>
> diff --git a/include/drm/ttm/ttm_tt.h b/include/drm/ttm/ttm_tt.h
> index b023cd58ff38..f3ef568da651 100644
> --- a/include/drm/ttm/ttm_tt.h
> +++ b/include/drm/ttm/ttm_tt.h
> @@ -38,35 +38,54 @@ struct ttm_resource;
> struct ttm_buffer_object;
> struct ttm_operation_ctx;
>
> -#define TTM_TT_FLAG_SWAPPED (1 << 0)
> -#define TTM_TT_FLAG_ZERO_ALLOC (1 << 1)
> -#define TTM_TT_FLAG_EXTERNAL (1 << 2)
> -
> -#define TTM_TT_FLAG_PRIV_POPULATED (1 << 31)
> -
> /**
> - * struct ttm_tt
> - *
> - * @pages: Array of pages backing the data.
> - * @page_flags: see TTM_TT_FLAG_*
> - * @num_pages: Number of pages in the page array.
> - * @sg: for SG objects via dma-buf
> - * @dma_address: The DMA (bus) addresses of the pages
> - * @swap_storage: Pointer to shmem struct file for swap storage.
> - * @pages_list: used by some page allocation backend
> - * @caching: The current caching state of the pages, see enum ttm_caching.
> - *
> - * This is a structure holding the pages, caching- and aperture binding
> - * status for a buffer object that isn't backed by fixed (VRAM / AGP)
> + * struct ttm_tt - This is a structure holding the pages, caching- and aperture
> + * binding status for a buffer object that isn't backed by fixed (VRAM / AGP)
> * memory.
> */
> struct ttm_tt {
> + /** @pages: Array of pages backing the data. */
> struct page **pages;
> + /**
> + * @page_flags: The page flags.
> + *
> + * Supported values:
> + *
> + * TTM_TT_FLAG_SWAPPED: Set if the pages have been swapped out.
> + * Calling ttm_tt_populate() will swap the pages back in, and unset the
> + * flag.
> + *
> + * TTM_TT_FLAG_ZERO_ALLOC: Set if the pages will be zeroed on
> + * allocation.
> + *
> + * TTM_TT_FLAG_EXTERNAL: Set if the underlying pages were allocated
> + * externally, like with dma-buf or userptr. This effectively disables
> + * TTM swapping out such pages. Also important is to prevent TTM from
> + * ever directly mapping these pages.
> + *
> + * Note that enum ttm_bo_type.ttm_bo_type_sg objects will always enable
> + * this flag.
> + *
> + * TTM_TT_FLAG_PRIV_POPULATED: TTM internal only. DO NOT USE.

The swapped flag should probably not be touched by the drivers either.

Better just describe what this is good for.

Christian.

> + */
> +#define TTM_TT_FLAG_SWAPPED (1 << 0)
> +#define TTM_TT_FLAG_ZERO_ALLOC (1 << 1)
> +#define TTM_TT_FLAG_EXTERNAL (1 << 2)
> +
> +#define TTM_TT_FLAG_PRIV_POPULATED (1 << 31)
> uint32_t page_flags;
> + /** @num_pages: Number of pages in the page array. */
> uint32_t num_pages;
> + /** @sg: for SG objects via dma-buf. */
> struct sg_table *sg;
> + /** @dma_address: The DMA (bus) addresses of the pages. */
> dma_addr_t *dma_address;
> + /** @swap_storage: Pointer to shmem struct file for swap storage. */
> struct file *swap_storage;
> + /**
> + * @caching: The current caching state of the pages, see enum
> + * ttm_caching.
> + */
> enum ttm_caching caching;
> };
>