Commit a5a3dd42 authored by Matthew Auld's avatar Matthew Auld Committed by Christian König
Browse files

drm/ttm: add some kernel-doc for TTM_TT_FLAG_* 



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.

v2(Christian):
  - Add a note that FLAG_SWAPPED shouldn't need to be touched by drivers.
  - Mention what FLAG_POPULATED does.

Signed-off-by: default avatarMatthew Auld <matthew.auld@intel.com>
Cc: Thomas Hellström <thomas.hellstrom@linux.intel.com>
Cc: Christian König <christian.koenig@amd.com>
Reviewed-by: default avatarChristian König <christian.koenig@amd.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20210929132629.353541-2-matthew.auld@intel.com


Signed-off-by: default avatarChristian König <christian.koenig@amd.com>
parent 43d46f0b

include/drm/ttm/ttm_tt.h

+41 −19
Original line number Diff line number Diff line
@@ -38,35 +38,57 @@ 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 by TTM when the pages have been unpopulated

	 * and swapped out by TTM.  Calling ttm_tt_populate() will then swap the

	 * pages back in, and unset the flag. Drivers should in general never

	 * need to touch this.

	 *

	 * 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. This is

	 * set by TTM after ttm_tt_populate() has successfully returned, and is

	 * then unset when TTM calls ttm_tt_unpopulate().

	 */

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

};