Re: [PATCH v1 01/14] drm/xe/uapi: Add a comment to each struct

[Rodrigo Vivi <rodrigo.vivi@intel.com>]

On Thu, Dec 07, 2023 at 01:49:56PM +0000, Francois Dugast wrote:
> Add a comment to each struct to complete documentation, ensure all
> struct appear in the kernel doc, and bind structs to IOCTLs.
> 
> Signed-off-by: Francois Dugast <francois.dugast@intel.com>

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>

> ---
>  include/uapi/drm/xe_drm.h | 43 ++++++++++++++++++++++++++++++++++++---
>  1 file changed, 40 insertions(+), 3 deletions(-)
> 
> diff --git a/include/uapi/drm/xe_drm.h b/include/uapi/drm/xe_drm.h
> index 0895e4d2a981..be58cd641324 100644
> --- a/include/uapi/drm/xe_drm.h
> +++ b/include/uapi/drm/xe_drm.h
> @@ -466,7 +466,8 @@ struct drm_xe_query_topology_mask {
>  };
>  
>  /**
> - * struct drm_xe_device_query - main structure to query device information
> + * struct drm_xe_device_query - Input of &DRM_IOCTL_XE_DEVICE_QUERY - main
> + * structure to query device information
>   *
>   * If size is set to 0, the driver fills it with the required size for the
>   * requested type of data to query. If size is equal to the required size,
> @@ -528,6 +529,10 @@ struct drm_xe_device_query {
>  	__u64 reserved[2];
>  };
>  
> +/**
> + * struct drm_xe_gem_create - Input of &DRM_IOCTL_XE_GEM_CREATE - A structure for
> + * gem creation
> + */
>  struct drm_xe_gem_create {
>  	/** @extensions: Pointer to the first extension struct, if any */
>  	__u64 extensions;
> @@ -606,6 +611,9 @@ struct drm_xe_gem_create {
>  	__u64 reserved[2];
>  };
>  
> +/**
> + * struct drm_xe_gem_mmap_offset - Input of &DRM_IOCTL_XE_GEM_MMAP_OFFSET
> + */
>  struct drm_xe_gem_mmap_offset {
>  	/** @extensions: Pointer to the first extension struct, if any */
>  	__u64 extensions;
> @@ -623,7 +631,9 @@ struct drm_xe_gem_mmap_offset {
>  	__u64 reserved[2];
>  };
>  
> -/** struct drm_xe_ext_set_property - XE set property extension */
> +/**
> + * struct drm_xe_ext_set_property - XE set property extension
> + */
>  struct drm_xe_ext_set_property {
>  	/** @base: base user extension */
>  	struct xe_user_extension base;
> @@ -641,6 +651,9 @@ struct drm_xe_ext_set_property {
>  	__u64 reserved[2];
>  };
>  
> +/**
> + * struct drm_xe_vm_create - Input of &DRM_IOCTL_XE_VM_CREATE
> + */
>  struct drm_xe_vm_create {
>  	/** @extensions: Pointer to the first extension struct, if any */
>  	__u64 extensions;
> @@ -680,6 +693,9 @@ struct drm_xe_vm_create {
>  	__u64 reserved[2];
>  };
>  
> +/**
> + * struct drm_xe_vm_destroy - Input of &DRM_IOCTL_XE_VM_DESTROY
> + */
>  struct drm_xe_vm_destroy {
>  	/** @vm_id: VM ID */
>  	__u32 vm_id;
> @@ -691,6 +707,9 @@ struct drm_xe_vm_destroy {
>  	__u64 reserved[2];
>  };
>  
> +/**
> + * struct drm_xe_vm_bind_op
> + */
>  struct drm_xe_vm_bind_op {
>  	/** @extensions: Pointer to the first extension struct, if any */
>  	__u64 extensions;
> @@ -808,6 +827,9 @@ struct drm_xe_vm_bind_op {
>  	__u64 reserved[3];
>  };
>  
> +/**
> + * struct drm_xe_vm_bind - Input of &DRM_IOCTL_XE_VM_BIND
> + */
>  struct drm_xe_vm_bind {
>  	/** @extensions: Pointer to the first extension struct, if any */
>  	__u64 extensions;
> @@ -866,6 +888,9 @@ struct drm_xe_vm_bind {
>  /* Monitor 64MB contiguous region with 2M sub-granularity */
>  #define DRM_XE_ACC_GRANULARITY_64M 3
>  
> +/**
> + * struct drm_xe_exec_queue_create - Input of &DRM_IOCTL_XE_EXEC_QUEUE_CREATE
> + */
>  struct drm_xe_exec_queue_create {
>  #define DRM_XE_EXEC_QUEUE_EXTENSION_SET_PROPERTY		0
>  #define   DRM_XE_EXEC_QUEUE_SET_PROPERTY_PRIORITY		0
> @@ -908,6 +933,9 @@ struct drm_xe_exec_queue_create {
>  	__u64 reserved[2];
>  };
>  
> +/**
> + * struct drm_xe_exec_queue_get_property - Input of &DRM_IOCTL_XE_EXEC_QUEUE_GET_PROPERTY
> + */
>  struct drm_xe_exec_queue_get_property {
>  	/** @extensions: Pointer to the first extension struct, if any */
>  	__u64 extensions;
> @@ -926,6 +954,9 @@ struct drm_xe_exec_queue_get_property {
>  	__u64 reserved[2];
>  };
>  
> +/**
> + * struct drm_xe_exec_queue_destroy - Input of &DRM_IOCTL_XE_EXEC_QUEUE_DESTROY
> + */
>  struct drm_xe_exec_queue_destroy {
>  	/** @exec_queue_id: Exec queue ID */
>  	__u32 exec_queue_id;
> @@ -937,6 +968,9 @@ struct drm_xe_exec_queue_destroy {
>  	__u64 reserved[2];
>  };
>  
> +/**
> + * struct drm_xe_sync
> + */
>  struct drm_xe_sync {
>  	/** @extensions: Pointer to the first extension struct, if any */
>  	__u64 extensions;
> @@ -971,6 +1005,9 @@ struct drm_xe_sync {
>  	__u64 reserved[2];
>  };
>  
> +/**
> + * struct drm_xe_exec - Input of &DRM_IOCTL_XE_EXEC
> + */
>  struct drm_xe_exec {
>  	/** @extensions: Pointer to the first extension struct, if any */
>  	__u64 extensions;
> @@ -1004,7 +1041,7 @@ struct drm_xe_exec {
>  };
>  
>  /**
> - * struct drm_xe_wait_user_fence - wait user fence
> + * struct drm_xe_wait_user_fence - Input of &DRM_IOCTL_XE_WAIT_USER_FENCE
>   *
>   * Wait on user fence, XE will wake-up on every HW engine interrupt in the
>   * instances list and check if user fence is complete::
> -- 
> 2.34.1
>