leandrof/linux
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

drm/i915/uapi: convert i915_query and friend to kernel doc

Browse Source 
Add a note about the two-step process.

v2(Tvrtko):
  - Also document the other method of just passing in a buffer which is
    large enough, which avoids two ioctl calls. Can make sense for
    smaller query items.
v3: prefer kernel-doc references for structs and members

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: Tvrtko Ursulin <tvrtko.ursulin@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
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Reviewed-by: Jason Ekstrand <jason@jlekstrand.net>
Link: https://patchwork.freedesktop.org/patch/msgid/20210419105741.27844-4-matthew.auld@intel.com
This commit is contained in:
Matthew Auld 2021-04-19 11:57:41 +01:00
parent 19d053d477
commit e3bdccafb5
1 changed files with 55 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
include/uapi/drm/i915_drm.h
View File

@ -2218,53 +2218,94 @@ struct drm_i915_perf_oa_config {
__u64 flex_regs_ptr; __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 { struct drm_i915_query_item {
/** @query_id: The id for this query */
__u64 query_id; __u64 query_id;
#define DRM_I915_QUERY_TOPOLOGY_INFO 1 #define DRM_I915_QUERY_TOPOLOGY_INFO 1
#define DRM_I915_QUERY_ENGINE_INFO 2 #define DRM_I915_QUERY_ENGINE_INFO 2
#define DRM_I915_QUERY_PERF_CONFIG 3 #define DRM_I915_QUERY_PERF_CONFIG 3
/* Must be kept compact -- no holes and well documented */ /* Must be kept compact -- no holes and well documented */
/* /**
* @length:
*
* When set to zero by userspace, this is filled with the size of the * 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 * 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 * value to a negative value to signal an error on a particular query
* item. * item.
*/ */
__s32 length; __s32 length;
/* /**
* @flags:
*
* When query_id == DRM_I915_QUERY_TOPOLOGY_INFO, must be 0. * When query_id == DRM_I915_QUERY_TOPOLOGY_INFO, must be 0.
* *
* When query_id == DRM_I915_QUERY_PERF_CONFIG, must be one of the * When query_id == DRM_I915_QUERY_PERF_CONFIG, must be one of the
* following : * following:
* - DRM_I915_QUERY_PERF_CONFIG_LIST *
* - DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID * - DRM_I915_QUERY_PERF_CONFIG_LIST
* - DRM_I915_QUERY_PERF_CONFIG_FOR_UUID * - DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID
* - DRM_I915_QUERY_PERF_CONFIG_FOR_UUID
*/ */
__u32 flags; __u32 flags;
#define DRM_I915_QUERY_PERF_CONFIG_LIST 1 #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_UUID 2
#define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID 3 #define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID 3
/* /**
* Data will be written at the location pointed by data_ptr when the * @data_ptr:
* value of length matches the length of the data to be written by the *
* 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. * kernel.
*/ */
__u64 data_ptr; __u64 data_ptr;
}; };
/**
* struct drm_i915_query - Supply an array of struct drm_i915_query_item for the
* kernel to fill out.
*
* Note that this is generally a two step process for each struct
* drm_i915_query_item in the array:
*
* 1. Call the DRM_IOCTL_I915_QUERY, giving it our array of struct
* drm_i915_query_item, with &drm_i915_query_item.length 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 &drm_i915_query_item.length should still be the same as what the
* kernel previously set. At this point the kernel can fill in the blob.
*
* Note that for some query items it can make sense for userspace to just pass
* in a buffer/blob equal to or larger than the required size. In this case only
* a single ioctl call is needed. For some smaller query items this can work
* quite well.
*
*/
struct drm_i915_query { struct drm_i915_query {
/** @num_items: The number of elements in the @items_ptr array */
__u32 num_items; __u32 num_items;
/* /**
* Unused for now. Must be cleared to zero. * @flags: Unused for now. Must be cleared to zero.
*/ */
__u32 flags; __u32 flags;
/* /**
* This points to an array of num_items drm_i915_query_item structures. * @items_ptr:
*
* Pointer to an array of struct drm_i915_query_item. The number of
* array elements is @num_items.
*/ */
__u64 items_ptr; __u64 items_ptr;
}; };