Re: [Intel-xe] [PATCH v3 2/5] drm/xe/uapi: add some kernel-doc for region query

[Gwan-gyeong Mun <gwan-gyeong.mun@intel.com>]

Reviewed-by: Gwan-gyeong Mun <gwan-gyeong.mun@intel.com>

On 3/27/23 3:48 PM, Matthew Auld wrote:
> Since we need to extend this, we should also take the time to add some
> basic kernel-doc here for the existing bits. Note that this is all still
> subject to change when upstreaming.
> 
> Also convert XE_MEM_REGION_CLASS_* into an enum, so we can more easily
> create links to it from other parts of the uapi.
> 
> Suggested-by: Gwan-gyeong Mun <gwan-gyeong.mun@intel.com>
> Signed-off-by: Matthew Auld <matthew.auld@intel.com>
> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
> Cc: Thomas Hellström <thomas.hellstrom@linux.intel.com>
> Cc: Lucas De Marchi <lucas.demarchi@intel.com>
> Cc: José Roberto de Souza <jose.souza@intel.com>
> Cc: Filip Hazubski <filip.hazubski@intel.com>
> Cc: Carl Zhang <carl.zhang@intel.com>
> Cc: Effie Yu <effie.yu@intel.com>
> ---
>   include/uapi/drm/xe_drm.h | 74 ++++++++++++++++++++++++++++++++++++---
>   1 file changed, 70 insertions(+), 4 deletions(-)
> 
> diff --git a/include/uapi/drm/xe_drm.h b/include/uapi/drm/xe_drm.h
> index b0b80aae3ee8..8cb3324221f2 100644
> --- a/include/uapi/drm/xe_drm.h
> +++ b/include/uapi/drm/xe_drm.h
> @@ -154,21 +154,84 @@ struct drm_xe_engine_class_instance {
>   	__u16 gt_id;
>   };
>   
> -#define XE_MEM_REGION_CLASS_SYSMEM	0
> -#define XE_MEM_REGION_CLASS_VRAM	1
>   
> +/**
> + * enum drm_xe_memory_class - Supported memory classes.
> + */
> +enum drm_xe_memory_class {
> +	/** @XE_MEM_REGION_CLASS_SYSMEM: Represents system memory. */
> +	XE_MEM_REGION_CLASS_SYSMEM = 0,
> +	/**
> +	 * @XE_MEM_REGION_CLASS_VRAM: On discrete platforms, this
> +	 * represents the memory that is local to the device, which we
> +	 * call VRAM. Not valid on integrated platforms.
> +	 */
> +	XE_MEM_REGION_CLASS_VRAM
> +};
> +
> +/**
> + * struct drm_xe_query_mem_usage - The region info query enumerates all regions
> + * known to the driver by filling in an array of struct drm_xe_query_mem_region
> + * structures.
> + */
>   struct drm_xe_query_mem_usage {
> +	/**
> +	 * @num_regions: Number of supported memory regions for this device.
> +	 *
> +	 * The @regions will contain @num_regions entries.
> +	 */
>   	__u32 num_regions;
> +	/** @pad: MBZ */
>   	__u32 pad;
> -
> +	/**
> +	 * struct drm_xe_query_mem_region - Describes some region as known to
> +	 * the driver.
> +	 */
>   	struct drm_xe_query_mem_region {
> +		/**
> +		 * @mem_class: The memory class describing this region.
> +		 *
> +		 * See enum drm_xe_memory_class for supported values.
> +		 */
>   		__u16 mem_class;
> -		__u16 instance;	/* unique ID even among different classes */
> +		/**
> +		 * @instance: The instance for this region.
> +		 *
> +		 * The @mem_class and @instance taken together will always give
> +		 * a unique pair.
> +		 */
> +		__u16 instance;
> +		/** @pad: MBZ */
>   		__u32 pad;
> +		/**
> +		 * @min_page_size: Min page-size in bytes for this region.
> +		 *
> +		 * When the kernel allocates memory for this region, the
> +		 * underlying pages will be at least @min_page_size in size.
> +		 *
> +		 * Important note: When userspace allocates a GTT address which
> +		 * can point to memory allocated from this region, it must also
> +		 * respect this minimum alignment. This is enforced by the
> +		 * kernel.
> +		 */
>   		__u32 min_page_size;
> +		/**
> +		 * @max_page_size: Max page-size in bytes for this region.
> +		 */
>   		__u32 max_page_size;
> +		/**
> +		 * @total_size: The usable size in bytes for this region.
> +		 */
>   		__u64 total_size;
> +		/**
> +		 * @used: Estimate of the memory used in bytes for this region.
> +		 *
> +		 * Requires CAP_PERFMON or CAP_SYS_ADMIN to get reliable
> +		 * accounting.  Without this the value here will always equal
> +		 * the @total_size.
> +		 */
>   		__u64 used;
> +		/** @reserved: MBZ */
>   		__u64 reserved[8];
>   	} regions[];
>   };
> @@ -760,6 +823,9 @@ struct drm_xe_vm_madvise {
>   	 * Setting the preferred location will trigger a migrate of the VMA
>   	 * backing store to new location if the backing store is already
>   	 * allocated.
> +	 *
> +	 * For DRM_XE_VM_MADVISE_PREFERRED_MEM_CLASS usage, see enum
> +	 * drm_xe_memory_class.
>   	 */
>   #define DRM_XE_VM_MADVISE_PREFERRED_MEM_CLASS	0
>   #define DRM_XE_VM_MADVISE_PREFERRED_GT		1