From: Ian Romanick <idr@freedesktop.org>
To: Matthew Auld <matthew.auld@intel.com>, intel-gfx@lists.freedesktop.org
Cc: mesa-dev@lists.freedesktop.org,
Kenneth Graunke <kenneth@whitecape.org>,
dri-devel@lists.freedesktop.org,
Daniel Vetter <daniel.vetter@intel.com>
Subject: Re: [Mesa-dev] [PATCH v3 3/4] drm/i915/uapi: convert i915_query and friend to kernel doc
Date: Thu, 15 Apr 2021 15:25:32 -0700 [thread overview]
Message-ID: <5de63e24-51f0-71eb-b992-484da998e65f@freedesktop.org> (raw)
In-Reply-To: <20210415155958.391624-3-matthew.auld@intel.com>
On 4/15/21 8:59 AM, Matthew Auld wrote:
> Add a note about the two-step process.
>
> Suggested-by: Daniel Vetter <daniel@ffwll.ch>
> Signed-off-by: Matthew Auld <matthew.auld@intel.com>
> Cc: Joonas Lahtinen <joonas.lahtinen@linux.intel.com>
> Cc: Jordan Justen <jordan.l.justen@intel.com>
> Cc: Daniel Vetter <daniel.vetter@intel.com>
> Cc: Kenneth Graunke <kenneth@whitecape.org>
> Cc: Jason Ekstrand <jason@jlekstrand.net>
> Cc: Dave Airlie <airlied@gmail.com>
> Cc: dri-devel@lists.freedesktop.org
> Cc: mesa-dev@lists.freedesktop.org
> ---
> include/uapi/drm/i915_drm.h | 57 ++++++++++++++++++++++++++++++-------
> 1 file changed, 46 insertions(+), 11 deletions(-)
>
> diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h
> index d9c954a5a456..ef36f1a0adde 100644
> --- a/include/uapi/drm/i915_drm.h
> +++ b/include/uapi/drm/i915_drm.h
> @@ -2210,14 +2210,23 @@ struct drm_i915_perf_oa_config {
> __u64 flex_regs_ptr;
> };
>
> +/**
> + * struct drm_i915_query_item - An individual query for the kernel to process.
> + *
> + * The behaviour is determined by the @query_id. Note that exactly what
Since we just had a big discussion about this on mesa-dev w.r.t. Mesa
code and documentation... does the kernel have a policy about which
flavor (pun intended) of English should be used?
> + * @data_ptr is also depends on the specific @query_id.
> + */
> struct drm_i915_query_item {
> + /** @query_id: The id for this query */
> __u64 query_id;
> #define DRM_I915_QUERY_TOPOLOGY_INFO 1
> #define DRM_I915_QUERY_ENGINE_INFO 2
> #define DRM_I915_QUERY_PERF_CONFIG 3
> /* Must be kept compact -- no holes and well documented */
>
> - /*
> + /**
> + * @length:
> + *
> * When set to zero by userspace, this is filled with the size of the
> * data to be written at the data_ptr pointer. The kernel sets this
> * value to a negative value to signal an error on a particular query
> @@ -2225,21 +2234,26 @@ struct drm_i915_query_item {
> */
> __s32 length;
>
> - /*
> + /**
> + * @flags:
> + *
> * When query_id == DRM_I915_QUERY_TOPOLOGY_INFO, must be 0.
> *
> * When query_id == DRM_I915_QUERY_PERF_CONFIG, must be one of the
> - * following :
> - * - DRM_I915_QUERY_PERF_CONFIG_LIST
> - * - DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID
> - * - DRM_I915_QUERY_PERF_CONFIG_FOR_UUID
> + * following:
> + *
> + * - DRM_I915_QUERY_PERF_CONFIG_LIST
> + * - DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID
> + * - DRM_I915_QUERY_PERF_CONFIG_FOR_UUID
> */
> __u32 flags;
> #define DRM_I915_QUERY_PERF_CONFIG_LIST 1
> #define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID 2
> #define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID 3
>
> - /*
> + /**
> + * @data_ptr:
> + *
> * Data will be written at the location pointed by data_ptr when the
> * value of length matches the length of the data to be written by the
> * kernel.
> @@ -2247,16 +2261,37 @@ struct drm_i915_query_item {
> __u64 data_ptr;
> };
>
> +/**
> + * struct drm_i915_query - Supply an array of drm_i915_query_item for the kernel
> + * to fill out.
> + *
> + * Note that this is generally a two step process for each drm_i915_query_item
> + * in the array:
> + *
> + * 1.) Call the DRM_IOCTL_I915_QUERY, giving it our array of
> + * drm_i915_query_item, with drm_i915_query_item.size set to zero. The
> + * kernel will then fill in the size, in bytes, which tells userspace how
> + * memory it needs to allocate for the blob(say for an array of
> + * properties).
> + *
> + * 2.) Next we call DRM_IOCTL_I915_QUERY again, this time with the
> + * drm_i915_query_item.data_ptr equal to our newly allocated blob. Note
> + * that the i915_query_item.size should still be the same as what the
> + * kernel previously set. At this point the kernel can fill in the blob.
> + *
> + */
> struct drm_i915_query {
> + /** @num_items: The number of elements in the @items_ptr array */
> __u32 num_items;
>
> - /*
> - * Unused for now. Must be cleared to zero.
> + /**
> + * @flags: Unused for now. Must be cleared to zero.
> */
> __u32 flags;
>
> - /*
> - * This points to an array of num_items drm_i915_query_item structures.
> + /**
> + * @items_ptr: This points to an array of num_items drm_i915_query_item
> + * structures.
> */
> __u64 items_ptr;
> };
>
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
next prev parent reply other threads:[~2021-04-16 6:06 UTC|newest]
Thread overview: 27+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-04-15 15:59 [PATCH v3 1/4] drm/i915/uapi: hide kernel doc warnings Matthew Auld
2021-04-15 15:59 ` [PATCH v3 2/4] drm/i915/uapi: convert i915_user_extension to kernel doc Matthew Auld
2021-04-16 8:46 ` Daniel Vetter
2021-04-15 15:59 ` [PATCH v3 3/4] drm/i915/uapi: convert i915_query and friend " Matthew Auld
2021-04-15 22:25 ` Ian Romanick [this message]
2021-04-16 8:59 ` [Mesa-dev] " Daniel Vetter
2021-04-16 19:04 ` Jonathan Corbet
2021-04-16 7:57 ` [Intel-gfx] " Tvrtko Ursulin
2021-04-16 8:49 ` Daniel Vetter
2021-04-15 15:59 ` [PATCH v3 4/4] drm/doc/rfc: i915 DG1 uAPI Matthew Auld
2021-04-16 9:15 ` Daniel Vetter
2021-04-16 16:38 ` Jason Ekstrand
2021-04-16 17:02 ` Daniel Vetter
2021-04-16 17:33 ` Daniele Ceraolo Spurio
2021-04-19 12:02 ` Matthew Auld
2021-04-19 15:19 ` Jason Ekstrand
2021-04-20 16:34 ` Tvrtko Ursulin
2021-04-20 17:00 ` Jason Ekstrand
2021-04-21 8:22 ` Tvrtko Ursulin
2021-04-21 13:54 ` Jason Ekstrand
2021-04-21 14:25 ` Tvrtko Ursulin
2021-04-21 17:17 ` Jason Ekstrand
2021-04-21 18:28 ` Tvrtko Ursulin
2021-04-21 19:23 ` [Mesa-dev] " Daniel Vetter
2021-04-26 15:22 ` Jason Ekstrand
2021-04-16 8:44 ` [PATCH v3 1/4] drm/i915/uapi: hide kernel doc warnings Daniel Vetter
2021-04-16 8:54 ` Daniel Vetter
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=5de63e24-51f0-71eb-b992-484da998e65f@freedesktop.org \
--to=idr@freedesktop.org \
--cc=daniel.vetter@intel.com \
--cc=dri-devel@lists.freedesktop.org \
--cc=intel-gfx@lists.freedesktop.org \
--cc=kenneth@whitecape.org \
--cc=matthew.auld@intel.com \
--cc=mesa-dev@lists.freedesktop.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).