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

Matthew Auld committed 5 years ago

Commit e3bdcca1 parent 19d053d1 file · +55 −14Browse files

Unified · Split

include/uapi/drm/i915_drm.h+55−14

@@ -2218,53 +2218,94 @@ struct drm_i915_perf_oa_config { · 2217 unmodified lines
2218	2218	__u64 flex_regs_ptr;
2219	2219	};
2220	2220
	2221	+/**
	2222	+ * struct drm_i915_query_item - An individual query for the kernel to process.
	2223	+ *
	2224	+ * The behaviour is determined by the @query_id. Note that exactly what
	2225	+ * @data_ptr is also depends on the specific @query_id.
	2226	+ */
2221	2227	struct drm_i915_query_item {
	2228	+ /** @query_id: The id for this query */
2222	2229	__u64 query_id;
2223	2230	#define DRM_I915_QUERY_TOPOLOGY_INFO 1
2224	2231	#define DRM_I915_QUERY_ENGINE_INFO 2
2225	2232	#define DRM_I915_QUERY_PERF_CONFIG 3
2226	2233	/* Must be kept compact -- no holes and well documented */
2227	2234
2228		− /*
	2235	+ /**
	2236	+ * @length:
	2237	+ *
2229	2238	* When set to zero by userspace, this is filled with the size of the
2230		− * data to be written at the data_ptr pointer. The kernel sets this
	2239	+ * data to be written at the @data_ptr pointer. The kernel sets this
2231	2240	* value to a negative value to signal an error on a particular query
2232	2241	* item.
2233	2242	*/
2234	2243	__s32 length;
2235	2244
2236		− /*
	2245	+ /**
	2246	+ * @flags:
	2247	+ *
2237	2248	* When query_id == DRM_I915_QUERY_TOPOLOGY_INFO, must be 0.
2238	2249	*
2239	2250	* When query_id == DRM_I915_QUERY_PERF_CONFIG, must be one of the
2240		− * following :
2241		− * - DRM_I915_QUERY_PERF_CONFIG_LIST
2242		− * - DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID
2243		− * - DRM_I915_QUERY_PERF_CONFIG_FOR_UUID
	2251	+ * following:
	2252	+ *
	2253	+ * - DRM_I915_QUERY_PERF_CONFIG_LIST
	2254	+ * - DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID
	2255	+ * - DRM_I915_QUERY_PERF_CONFIG_FOR_UUID
2244	2256	*/
2245	2257	__u32 flags;
2246	2258	#define DRM_I915_QUERY_PERF_CONFIG_LIST 1
2247	2259	#define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID 2
2248	2260	#define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID 3
2249	2261
2250		− /*
2251		− * Data will be written at the location pointed by data_ptr when the
2252		− * value of length matches the length of the data to be written by the
	2262	+ /**
	2263	+ * @data_ptr:
	2264	+ *
	2265	+ * Data will be written at the location pointed by @data_ptr when the
	2266	+ * value of @length matches the length of the data to be written by the
2253	2267	* kernel.
2254	2268	*/
2255	2269	__u64 data_ptr;
2256	2270	};
2257	2271
	2272	+/**
	2273	+ * struct drm_i915_query - Supply an array of struct drm_i915_query_item for the
	2274	+ * kernel to fill out.
	2275	+ *
	2276	+ * Note that this is generally a two step process for each struct
	2277	+ * drm_i915_query_item in the array:
	2278	+ *
	2279	+ * 1. Call the DRM_IOCTL_I915_QUERY, giving it our array of struct
	2280	+ * drm_i915_query_item, with &drm_i915_query_item.length set to zero. The
	2281	+ * kernel will then fill in the size, in bytes, which tells userspace how
	2282	+ * memory it needs to allocate for the blob(say for an array of properties).
	2283	+ *
	2284	+ * 2. Next we call DRM_IOCTL_I915_QUERY again, this time with the
	2285	+ * &drm_i915_query_item.data_ptr equal to our newly allocated blob. Note that
	2286	+ * the &drm_i915_query_item.length should still be the same as what the
	2287	+ * kernel previously set. At this point the kernel can fill in the blob.
	2288	+ *
	2289	+ * Note that for some query items it can make sense for userspace to just pass
	2290	+ * in a buffer/blob equal to or larger than the required size. In this case only
	2291	+ * a single ioctl call is needed. For some smaller query items this can work
	2292	+ * quite well.
	2293	+ *
	2294	+ */
2258	2295	struct drm_i915_query {
	2296	+ /** @num_items: The number of elements in the @items_ptr array */
2259	2297	__u32 num_items;
2260	2298
2261		− /*
2262		− * Unused for now. Must be cleared to zero.
	2299	+ /**
	2300	+ * @flags: Unused for now. Must be cleared to zero.
2263	2301	*/
2264	2302	__u32 flags;
2265	2303
2266		− /*
2267		− * This points to an array of num_items drm_i915_query_item structures.
	2304	+ /**
	2305	+ * @items_ptr:
	2306	+ *
	2307	+ * Pointer to an array of struct drm_i915_query_item. The number of
	2308	+ * array elements is @num_items.
2268	2309	*/
2269	2310	__u64 items_ptr;
2270	2311	};