[PATCH 1/4] drm/i915/doc: Convert drm_i915_query_topology_info comment to kerneldoc

[Francisco Jerez]

Looks good to me, series is:

Reviewed-by: Francisco Jerez <currojerez at riseup.net>

Matt Roper <matthew.d.roper at intel.com> writes:

> This structure has a great comment describing the fields, but it's not
> currently in kerneldoc form and does not show up in the generated
> documentation.  Let's fix that and also clarify the description of what
> "subslice" refers to on gen12 platforms and beyond and that "slice" is
> no longer meaningful on Xe_HP and beyond.
>
> Signed-off-by: Matt Roper <matthew.d.roper at intel.com>
> ---
>  include/uapi/drm/i915_drm.h | 110 +++++++++++++++++++++++++-----------
>  1 file changed, 78 insertions(+), 32 deletions(-)
>
> diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h
> index 9ab021c4d632..73e1c6180ddb 100644
> --- a/include/uapi/drm/i915_drm.h
> +++ b/include/uapi/drm/i915_drm.h
> @@ -2775,66 +2775,112 @@ struct drm_i915_query {
>  	__u64 items_ptr;
>  };
>  
> -/*
> - * Data written by the kernel with query DRM_I915_QUERY_TOPOLOGY_INFO :
> - *
> - * data: contains the 3 pieces of information :
> - *
> - * - the slice mask with one bit per slice telling whether a slice is
> - *   available. The availability of slice X can be queried with the following
> - *   formula :
> - *
> - *           (data[X / 8] >> (X % 8)) & 1
> - *
> - * - the subslice mask for each slice with one bit per subslice telling
> - *   whether a subslice is available. Gen12 has dual-subslices, which are
> - *   similar to two gen11 subslices. For gen12, this array represents dual-
> - *   subslices. The availability of subslice Y in slice X can be queried
> - *   with the following formula :
> - *
> - *           (data[subslice_offset +
> - *                 X * subslice_stride +
> - *                 Y / 8] >> (Y % 8)) & 1
> - *
> - * - the EU mask for each subslice in each slice with one bit per EU telling
> - *   whether an EU is available. The availability of EU Z in subslice Y in
> - *   slice X can be queried with the following formula :
> +/**
> + * struct drm_i915_query_topology_info
>   *
> - *           (data[eu_offset +
> - *                 (X * max_subslices + Y) * eu_stride +
> - *                 Z / 8] >> (Z % 8)) & 1
> + * Describes slice/subslice/EU information queried by
> + * %DRM_I915_QUERY_TOPOLOGY_INFO
>   */
>  struct drm_i915_query_topology_info {
> -	/*
> +	/**
> +	 * @flags:
> +	 *
>  	 * Unused for now. Must be cleared to zero.
>  	 */
>  	__u16 flags;
>  
> +	/**
> +	 * @max_slices:
> +	 *
> +	 * The number of bits used to express the slice mask.
> +	 */
>  	__u16 max_slices;
> +
> +	/**
> +	 * @max_subslices:
> +	 *
> +	 * The number of bits used to express the subslice mask.
> +	 */
>  	__u16 max_subslices;
> +
> +	/**
> +	 * @max_eus_per_subslice:
> +	 *
> +	 * The number of bits in the EU mask that correspond to a single
> +	 * subslice's EUs.
> +	 */
>  	__u16 max_eus_per_subslice;
>  
> -	/*
> +	/**
> +	 * @subslice_offset:
> +	 *
>  	 * Offset in data[] at which the subslice masks are stored.
>  	 */
>  	__u16 subslice_offset;
>  
> -	/*
> +	/**
> +	 * @subslice_stride:
> +	 *
>  	 * Stride at which each of the subslice masks for each slice are
>  	 * stored.
>  	 */
>  	__u16 subslice_stride;
>  
> -	/*
> +	/**
> +	 * @eu_offset:
> +	 *
>  	 * Offset in data[] at which the EU masks are stored.
>  	 */
>  	__u16 eu_offset;
>  
> -	/*
> +	/**
> +	 * @eu_stride:
> +	 *
>  	 * Stride at which each of the EU masks for each subslice are stored.
>  	 */
>  	__u16 eu_stride;
>  
> +	/**
> +	 * @data:
> +	 *
> +	 * Contains 3 pieces of information :
> +	 *
> +	 * - The slice mask with one bit per slice telling whether a slice is
> +	 *   available. The availability of slice X can be queried with the
> +	 *   following formula :
> +	 *
> +	 *   .. code:: c
> +	 *
> +	 *      (data[X / 8] >> (X % 8)) & 1
> +	 *
> +	 *   Starting with Xe_HP platforms, Intel hardware no longer has
> +	 *   traditional slices so i915 will always report a single slice
> +	 *   (hardcoded slicemask = 0x1) which contains all of the platform's
> +	 *   subslices.  I.e., the mask here does not reflect any of the newer
> +	 *   hardware concepts such as "gslices" or "cslices" since userspace
> +	 *   is capable of inferring those from the subslice mask.
> +	 *
> +	 * - The subslice mask for each slice with one bit per subslice telling
> +	 *   whether a subslice is available.  Starting with Gen12 we use the
> +	 *   term "subslice" to refer to what the hardware documentation
> +	 *   describes as a "dual-subslices."  The availability of subslice Y
> +	 *   in slice X can be queried with the following formula :
> +	 *
> +	 *   .. code:: c
> +	 *
> +	 *      (data[subslice_offset + X * subslice_stride + Y / 8] >> (Y % 8)) & 1
> +	 *
> +	 * - The EU mask for each subslice in each slice, with one bit per EU
> +	 *   telling whether an EU is available. The availability of EU Z in
> +	 *   subslice Y in slice X can be queried with the following formula :
> +	 *
> +	 *   .. code:: c
> +	 *
> +	 *      (data[eu_offset +
> +	 *            (X * max_subslices + Y) * eu_stride +
> +	 *            Z / 8
> +	 *       ] >> (Z % 8)) & 1
> +	 */
>  	__u8 data[];
>  };
>  
> -- 
> 2.34.1