Commit 462ac1cd authored by Matt Roper's avatar Matt Roper

drm/i915/doc: Convert drm_i915_query_topology_info comment to kerneldoc

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: default avatarMatt Roper <matthew.d.roper@intel.com>
Reviewed-by: default avatarFrancisco Jerez <currojerez@riseup.net>
Link: https://patchwork.freedesktop.org/patch/msgid/20220414192230.749771-1-matthew.d.roper@intel.com
parent 2584b354
...@@ -2775,66 +2775,112 @@ struct drm_i915_query { ...@@ -2775,66 +2775,112 @@ struct drm_i915_query {
__u64 items_ptr; __u64 items_ptr;
}; };
/* /**
* Data written by the kernel with query DRM_I915_QUERY_TOPOLOGY_INFO : * struct 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 :
* *
* (data[eu_offset + * Describes slice/subslice/EU information queried by
* (X * max_subslices + Y) * eu_stride + * %DRM_I915_QUERY_TOPOLOGY_INFO
* Z / 8] >> (Z % 8)) & 1
*/ */
struct drm_i915_query_topology_info { struct drm_i915_query_topology_info {
/* /**
* @flags:
*
* Unused for now. Must be cleared to zero. * Unused for now. Must be cleared to zero.
*/ */
__u16 flags; __u16 flags;
/**
* @max_slices:
*
* The number of bits used to express the slice mask.
*/
__u16 max_slices; __u16 max_slices;
/**
* @max_subslices:
*
* The number of bits used to express the subslice mask.
*/
__u16 max_subslices; __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; __u16 max_eus_per_subslice;
/* /**
* @subslice_offset:
*
* Offset in data[] at which the subslice masks are stored. * Offset in data[] at which the subslice masks are stored.
*/ */
__u16 subslice_offset; __u16 subslice_offset;
/* /**
* @subslice_stride:
*
* Stride at which each of the subslice masks for each slice are * Stride at which each of the subslice masks for each slice are
* stored. * stored.
*/ */
__u16 subslice_stride; __u16 subslice_stride;
/* /**
* @eu_offset:
*
* Offset in data[] at which the EU masks are stored. * Offset in data[] at which the EU masks are stored.
*/ */
__u16 eu_offset; __u16 eu_offset;
/* /**
* @eu_stride:
*
* Stride at which each of the EU masks for each subslice are stored. * Stride at which each of the EU masks for each subslice are stored.
*/ */
__u16 eu_stride; __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[]; __u8 data[];
}; };
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment