From: Tvrtko Ursulin <tvrtko.ursulin@linux.intel.com> 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: [Intel-gfx] [PATCH v3 3/4] drm/i915/uapi: convert i915_query and friend to kernel doc Date: Fri, 16 Apr 2021 08:57:10 +0100 [thread overview] Message-ID: <05b49a99-05cf-6056-2552-b893e1715f60@linux.intel.com> (raw) In-Reply-To: <20210415155958.391624-3-matthew.auld@intel.com> On 15/04/2021 16:59, 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 > + * @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. I'd also document the one step alternative where userspace passes in a buffer equal or larger than the required size. For many small queries (most?) this actually works just as well and with one ioctl only. Regards, Tvrtko > + * > + */ > 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
WARNING: multiple messages have this Message-ID (diff)
From: Tvrtko Ursulin <tvrtko.ursulin@linux.intel.com> 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: [Intel-gfx] [PATCH v3 3/4] drm/i915/uapi: convert i915_query and friend to kernel doc Date: Fri, 16 Apr 2021 08:57:10 +0100 [thread overview] Message-ID: <05b49a99-05cf-6056-2552-b893e1715f60@linux.intel.com> (raw) In-Reply-To: <20210415155958.391624-3-matthew.auld@intel.com> On 15/04/2021 16:59, 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 > + * @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. I'd also document the one step alternative where userspace passes in a buffer equal or larger than the required size. For many small queries (most?) this actually works just as well and with one ioctl only. Regards, Tvrtko > + * > + */ > 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; > }; > _______________________________________________ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
next prev parent reply other threads:[~2021-04-16 7:57 UTC|newest] Thread overview: 61+ 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 ` [Intel-gfx] " 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-15 15:59 ` [Intel-gfx] " Matthew Auld 2021-04-16 8:46 ` Daniel Vetter 2021-04-16 8:46 ` [Intel-gfx] " Daniel Vetter 2021-04-15 15:59 ` [PATCH v3 3/4] drm/i915/uapi: convert i915_query and friend " Matthew Auld 2021-04-15 15:59 ` [Intel-gfx] " Matthew Auld 2021-04-15 22:25 ` [Mesa-dev] " Ian Romanick 2021-04-15 22:25 ` [Intel-gfx] " Ian Romanick 2021-04-16 8:59 ` Daniel Vetter 2021-04-16 8:59 ` [Intel-gfx] " Daniel Vetter 2021-04-16 8:59 ` Daniel Vetter 2021-04-16 19:04 ` Jonathan Corbet 2021-04-16 19:04 ` [Intel-gfx] " Jonathan Corbet 2021-04-16 19:04 ` Jonathan Corbet 2021-04-16 7:57 ` Tvrtko Ursulin [this message] 2021-04-16 7:57 ` [Intel-gfx] " Tvrtko Ursulin 2021-04-16 8:49 ` Daniel Vetter 2021-04-16 8:49 ` [Intel-gfx] " Daniel Vetter 2021-04-15 15:59 ` [PATCH v3 4/4] drm/doc/rfc: i915 DG1 uAPI Matthew Auld 2021-04-15 15:59 ` [Intel-gfx] " Matthew Auld 2021-04-16 9:15 ` Daniel Vetter 2021-04-16 9:15 ` [Intel-gfx] " Daniel Vetter 2021-04-16 16:38 ` Jason Ekstrand 2021-04-16 16:38 ` [Intel-gfx] " Jason Ekstrand 2021-04-16 17:02 ` Daniel Vetter 2021-04-16 17:02 ` [Intel-gfx] " Daniel Vetter 2021-04-16 17:33 ` Daniele Ceraolo Spurio 2021-04-16 17:33 ` [Intel-gfx] " Daniele Ceraolo Spurio 2021-04-19 12:02 ` Matthew Auld 2021-04-19 12:02 ` [Intel-gfx] " Matthew Auld 2021-04-19 15:19 ` Jason Ekstrand 2021-04-19 15:19 ` [Intel-gfx] " Jason Ekstrand 2021-04-20 16:34 ` Tvrtko Ursulin 2021-04-20 16:34 ` [Intel-gfx] " Tvrtko Ursulin 2021-04-20 17:00 ` Jason Ekstrand 2021-04-20 17:00 ` [Intel-gfx] " Jason Ekstrand 2021-04-21 8:22 ` Tvrtko Ursulin 2021-04-21 8:22 ` [Intel-gfx] " Tvrtko Ursulin 2021-04-21 13:54 ` Jason Ekstrand 2021-04-21 13:54 ` [Intel-gfx] " Jason Ekstrand 2021-04-21 14:25 ` Tvrtko Ursulin 2021-04-21 14:25 ` [Intel-gfx] " Tvrtko Ursulin 2021-04-21 17:17 ` Jason Ekstrand 2021-04-21 17:17 ` [Intel-gfx] " Jason Ekstrand 2021-04-21 18:28 ` Tvrtko Ursulin 2021-04-21 18:28 ` [Intel-gfx] " Tvrtko Ursulin 2021-04-21 19:23 ` [Mesa-dev] " Daniel Vetter 2021-04-21 19:23 ` [Intel-gfx] " Daniel Vetter 2021-04-26 15:22 ` Jason Ekstrand 2021-04-26 15:22 ` [Intel-gfx] " Jason Ekstrand 2021-04-15 16:32 ` [Intel-gfx] ✗ Fi.CI.CHECKPATCH: warning for series starting with [v3,1/4] drm/i915/uapi: hide kernel doc warnings Patchwork 2021-04-15 16:34 ` [Intel-gfx] ✗ Fi.CI.SPARSE: " Patchwork 2021-04-15 16:37 ` [Intel-gfx] ✗ Fi.CI.DOCS: " Patchwork 2021-04-15 16:59 ` [Intel-gfx] ✓ Fi.CI.BAT: success " Patchwork 2021-04-15 18:17 ` [Intel-gfx] ✓ Fi.CI.IGT: " Patchwork 2021-04-16 8:44 ` [PATCH v3 1/4] " Daniel Vetter 2021-04-16 8:44 ` [Intel-gfx] " Daniel Vetter 2021-04-16 8:54 ` Daniel Vetter 2021-04-16 8:54 ` [Intel-gfx] " 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=05b49a99-05cf-6056-2552-b893e1715f60@linux.intel.com \ --to=tvrtko.ursulin@linux.intel.com \ --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: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.