History

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

Showing the changes to include/uapi (1 of 1 file). Show all

Unified · Split

include/uapi/drm/i915_drm.h+55−14
@@ -2218,53 +2218,94 @@ struct drm_i915_perf_oa_config { · 2217 unmodified lines
22182218 __u64 flex_regs_ptr;
22192219 };
22202220
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+ */
22212227 struct drm_i915_query_item {
2228+ /** @query_id: The id for this query */
22222229 __u64 query_id;
22232230 #define DRM_I915_QUERY_TOPOLOGY_INFO 1
22242231 #define DRM_I915_QUERY_ENGINE_INFO 2
22252232 #define DRM_I915_QUERY_PERF_CONFIG 3
22262233 /* Must be kept compact -- no holes and well documented */
22272234
2228− /*
2235+ /**
2236+ * @length:
2237+ *
22292238 * 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
22312240 * value to a negative value to signal an error on a particular query
22322241 * item.
22332242 */
22342243 __s32 length;
22352244
2236− /*
2245+ /**
2246+ * @flags:
2247+ *
22372248 * When query_id == DRM_I915_QUERY_TOPOLOGY_INFO, must be 0.
22382249 *
22392250 * 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
22442256 */
22452257 __u32 flags;
22462258 #define DRM_I915_QUERY_PERF_CONFIG_LIST 1
22472259 #define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID 2
22482260 #define DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID 3
22492261
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
22532267 * kernel.
22542268 */
22552269 __u64 data_ptr;
22562270 };
22572271
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+ */
22582295 struct drm_i915_query {
2296+ /** @num_items: The number of elements in the @items_ptr array */
22592297 __u32 num_items;
22602298
2261− /*
2262− * Unused for now. Must be cleared to zero.
2299+ /**
2300+ * @flags: Unused for now. Must be cleared to zero.
22632301 */
22642302 __u32 flags;
22652303
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.
22682309 */
22692310 __u64 items_ptr;
22702311 };