Commit a2e54026 authored by Matt Roper's avatar Matt Roper
Browse files

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: default avatarMatt Roper <matthew.d.roper@intel.com>
Reviewed-by: default avatarFrancisco Jerez <currojerez@riseup.net>
Link: https://patchwork.freedesktop.org/patch/msgid/20220414192230.749771-2-matthew.d.roper@intel.com
parent 462ac1cd

include/uapi/drm/i915_drm.h

+86 −30
Original line number Diff line number Diff line
@@ -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[];

};