[PATCH v1 03/14] drm/xe/uapi: Document use of size in drm_xe_device_query

[Rodrigo Vivi]

On Thu, Dec 07, 2023 at 01:49:58PM +0000, Francois Dugast wrote:
> Document the behavior of the driver for IOCTL DRM_IOCTL_XE_DEVICE_QUERY
> depending on the size value provided in struct drm_xe_device_query.
> 
> Signed-off-by: Francois Dugast <francois.dugast at intel.com>

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

> ---
>  include/uapi/drm/xe_drm.h | 12 +++++++++---
>  1 file changed, 9 insertions(+), 3 deletions(-)
> 
> diff --git a/include/uapi/drm/xe_drm.h b/include/uapi/drm/xe_drm.h
> index d6cd76385e2c..7b18844401fd 100644
> --- a/include/uapi/drm/xe_drm.h
> +++ b/include/uapi/drm/xe_drm.h
> @@ -469,9 +469,15 @@ struct drm_xe_query_topology_mask {
>   * 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,
> - * the queried information is copied into data.
> + * The user selects the type of data to query among DRM_XE_DEVICE_QUERY_*
> + * and sets the value in the query member. This determines the type of
> + * the structure provided by the driver in data, among struct drm_xe_query_*.
> + *
> + * 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, the queried information is copied into data. If size is set to
> + * a value different from 0 and different from the required size, the
> + * IOCTL call returns -EINVAL.
>   *
>   * For example the following code snippet allows retrieving and printing
>   * information about the device engines with DRM_XE_DEVICE_QUERY_ENGINES:
> -- 
> 2.34.1
>