drm/i915/doc: Convert perf UAPI comments to kerneldoc

Convert the comments for  drm_i915_query_perf_config and
drm_i915_perf_oa_config to kerneldoc so that they will show up in the
generated documentation.  Also correct a couple places that referred to
query_id when they actually meant to refer to query_item.flags.

Signed-off-by: Matt Roper <matthew.d.roper@intel.com>
Reviewed-by: Francisco Jerez <currojerez@riseup.net>
Link: https://patchwork.freedesktop.org/patch/msgid/20220414192230.749771-2-matthew.d.roper@intel.com

diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h
index 73e1c6180ddb981fa0b96548fc64ce06068ba90e..787dab98f7b0d766e3f73d339131c1c7ae7f9757 100644 (file)
--- a/include/uapi/drm/i915_drm.h
+++ b/include/uapi/drm/i915_drm.h
@@ -2657,24 +2657,65 @@ enum drm_i915_perf_record_type {
        DRM_I915_PERF_RECORD_MAX /* non-ABI */
 };
 
-/*
+/**
+ * struct drm_i915_perf_oa_config
+ *
  * Structure to upload perf dynamic configuration into the kernel.
  */
 struct drm_i915_perf_oa_config {
-       /** String formatted like "%08x-%04x-%04x-%04x-%012x" */
+       /**
+        * @uuid:
+        *
+        * String formatted like "%\08x-%\04x-%\04x-%\04x-%\012x"
+        */
        char uuid[36];
 
+       /**
+        * @n_mux_regs:
+        *
+        * Number of mux regs in &mux_regs_ptr.
+        */
        __u32 n_mux_regs;
+
+       /**
+        * @n_boolean_regs:
+        *
+        * Number of boolean regs in &boolean_regs_ptr.
+        */
        __u32 n_boolean_regs;
+
+       /**
+        * @n_flex_regs:
+        *
+        * Number of flex regs in &flex_regs_ptr.
+        */
        __u32 n_flex_regs;
 
-       /*
-        * These fields are pointers to tuples of u32 values (register address,
-        * value). For example the expected length of the buffer pointed by
-        * mux_regs_ptr is (2 * sizeof(u32) * n_mux_regs).
+       /**
+        * @mux_regs_ptr:
+        *
+        * Pointer to tuples of u32 values (register address, value) for mux
+        * registers.  Expected length of buffer is (2 * sizeof(u32) *
+        * &n_mux_regs).
         */
        __u64 mux_regs_ptr;
+
+       /**
+        * @boolean_regs_ptr:
+        *
+        * Pointer to tuples of u32 values (register address, value) for mux
+        * registers.  Expected length of buffer is (2 * sizeof(u32) *
+        * &n_boolean_regs).
+        */
        __u64 boolean_regs_ptr;
+
+       /**
+        * @flex_regs_ptr:
+        *
+        * Pointer to tuples of u32 values (register address, value) for mux
+        * registers.  Expected length of buffer is (2 * sizeof(u32) *
+        * &n_flex_regs).
+        */
        __u64 flex_regs_ptr;
 };
 
@@ -3001,52 +3042,67 @@ struct drm_i915_query_engine_info {
        struct drm_i915_engine_info engines[];
 };
 
-/*
- * Data written by the kernel with query DRM_I915_QUERY_PERF_CONFIG.
+/**
+ * struct drm_i915_query_perf_config
+ *
+ * Data written by the kernel with query %DRM_I915_QUERY_PERF_CONFIG.
  */
 struct drm_i915_query_perf_config {
        union {
-               /*
-                * When query_item.flags == DRM_I915_QUERY_PERF_CONFIG_LIST, i915 sets
-                * this fields to the number of configurations available.
+               /**
+                * @n_configs:
+                *
+                * When &drm_i915_query_item.flags ==
+                * %DRM_I915_QUERY_PERF_CONFIG_LIST, i915 sets this fields to
+                * the number of configurations available.
                 */
                __u64 n_configs;
 
-               /*
-                * When query_id == DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID,
-                * i915 will use the value in this field as configuration
-                * identifier to decide what data to write into config_ptr.
+               /**
+                * @config:
+                *
+                * When &drm_i915_query_item.flags ==
+                * %DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_ID, i915 will use the
+                * value in this field as configuration identifier to decide
+                * what data to write into config_ptr.
                 */
                __u64 config;
 
-               /*
-                * When query_id == DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID,
-                * i915 will use the value in this field as configuration
-                * identifier to decide what data to write into config_ptr.
+               /**
+                * @uuid:
+                *
+                * When &drm_i915_query_item.flags ==
+                * %DRM_I915_QUERY_PERF_CONFIG_DATA_FOR_UUID, i915 will use the
+                * value in this field as configuration identifier to decide
+                * what data to write into config_ptr.
                 *
                 * String formatted like "%08x-%04x-%04x-%04x-%012x"
                 */
                char uuid[36];
        };
 
-       /*
+       /**
+        * @flags:
+        *
         * Unused for now. Must be cleared to zero.
         */
        __u32 flags;
 
-       /*
-        * When query_item.flags == DRM_I915_QUERY_PERF_CONFIG_LIST, i915 will
-        * write an array of __u64 of configuration identifiers.
+       /**
+        * @data:
+        *
+        * When &drm_i915_query_item.flags == %DRM_I915_QUERY_PERF_CONFIG_LIST,
+        * i915 will write an array of __u64 of configuration identifiers.
         *
-        * When query_item.flags == DRM_I915_QUERY_PERF_CONFIG_DATA, i915 will
-        * write a struct drm_i915_perf_oa_config. If the following fields of
-        * drm_i915_perf_oa_config are set not set to 0, i915 will write into
-        * the associated pointers the values of submitted when the
+        * When &drm_i915_query_item.flags == %DRM_I915_QUERY_PERF_CONFIG_DATA,
+        * i915 will write a struct drm_i915_perf_oa_config. If the following
+        * fields of struct drm_i915_perf_oa_config are not set to 0, i915 will
+        * write into the associated pointers the values of submitted when the
         * configuration was created :
         *
-        *         - n_mux_regs
-        *         - n_boolean_regs
-        *         - n_flex_regs
+        *  - &drm_i915_perf_oa_config.n_mux_regs
+        *  - &drm_i915_perf_oa_config.n_boolean_regs
+        *  - &drm_i915_perf_oa_config.n_flex_regs
         */
        __u8 data[];
 };