Commit e3bdccaf authored by Matthew Auld's avatar Matthew Auld
Browse files

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



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: default avatarDaniel Vetter <daniel@ffwll.ch>
Signed-off-by: default avatarMatthew 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: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Reviewed-by: default avatarJason Ekstrand <jason@jlekstrand.net>
Link: https://patchwork.freedesktop.org/patch/msgid/20210419105741.27844-4-matthew.auld@intel.com
parent 19d053d4

include/uapi/drm/i915_drm.h

+55 −14
Original line number Diff line number Diff line
@@ -2218,26 +2218,38 @@ 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

	 * 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

	 * 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
@@ -2247,24 +2259,53 @@ struct drm_i915_query_item { 
#define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID 2

#define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID   3



	/*

	 * 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

	/**

	 * @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.

	 */

	__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 {

	/** @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:

	 *

	 * Pointer to an array of struct drm_i915_query_item. The number of

	 * array elements is @num_items.

	 */

	__u64 items_ptr;

};