Commit 16d98b31 authored by Robert Bragg's avatar Robert Bragg Committed by Daniel Vetter
Browse files

drm/i915/perf: More documentation hooked to i915.rst 



This adds a 'Perf' section to i915.rst with the following sub sections:
- Overview
- Comparison with Core Perf
- i915 Driver Entry Points
- i915 Perf Stream
- i915 Perf Observation Architecture Stream
- All i915 Perf Internals

v2:
    section headers in i915.rst (Daniel Vetter)
    missing symbol docs + other fixups (Matthew Auld)

Signed-off-by: default avatarRobert Bragg <robert@sixbynine.org>
Reviewed-by: default avatarMatthew Auld <matthew.auld@intel.com>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/20161207214033.3581-1-robert@sixbynine.org
parent b3b8e999

Documentation/gpu/i915.rst

+91 −0
Original line number Diff line number Diff line
@@ -356,4 +356,95 @@ switch_mm 
.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h

   :doc: switch_mm tracepoint



Perf

====



Overview

--------

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :doc: i915 Perf Overview



Comparison with Core Perf

-------------------------

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :doc: i915 Perf History and Comparison with Core Perf



i915 Driver Entry Points

------------------------



This section covers the entrypoints exported outside of i915_perf.c to

integrate with drm/i915 and to handle the `DRM_I915_PERF_OPEN` ioctl.



.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_perf_init

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_perf_fini

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_perf_register

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_perf_unregister

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_perf_open_ioctl

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_perf_release



i915 Perf Stream

----------------



This section covers the stream-semantics-agnostic structures and functions

for representing an i915 perf stream FD and associated file operations.



.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h

   :functions: i915_perf_stream

.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h

   :functions: i915_perf_stream_ops



.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: read_properties_unlocked

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_perf_open_ioctl_locked

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_perf_destroy_locked

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_perf_read

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_perf_ioctl

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_perf_enable_locked

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_perf_disable_locked

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_perf_poll

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_perf_poll_locked



i915 Perf Observation Architecture Stream

-----------------------------------------



.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h

   :functions: i915_oa_ops



.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_oa_stream_init

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_oa_read

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_oa_stream_enable

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_oa_stream_disable

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_oa_wait_unlocked

.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :functions: i915_oa_poll_wait



All i915 Perf Internals

-----------------------



This section simply includes all currently documented i915 perf internals, in

no particular order, but may include some more minor utilities or platform

specific details than found in the more high-level sections.



.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c

   :internal:



.. WARNING: DOCPROC directive not supported: !Cdrivers/gpu/drm/i915/i915_irq.c

drivers/gpu/drm/i915/i915_drv.h

+124 −27
Original line number Diff line number Diff line
@@ -1930,89 +1930,186 @@ struct i915_oa_reg { 


struct i915_perf_stream;



/**

 * struct i915_perf_stream_ops - the OPs to support a specific stream type

 */

struct i915_perf_stream_ops {

	/* Enables the collection of HW samples, either in response to

	 * I915_PERF_IOCTL_ENABLE or implicitly called when stream is

	 * opened without I915_PERF_FLAG_DISABLED.

	/**

	 * @enable: Enables the collection of HW samples, either in response to

	 * `I915_PERF_IOCTL_ENABLE` or implicitly called when stream is opened

	 * without `I915_PERF_FLAG_DISABLED`.

	 */

	void (*enable)(struct i915_perf_stream *stream);



	/* Disables the collection of HW samples, either in response to

	 * I915_PERF_IOCTL_DISABLE or implicitly called before

	 * destroying the stream.

	/**

	 * @disable: Disables the collection of HW samples, either in response

	 * to `I915_PERF_IOCTL_DISABLE` or implicitly called before destroying

	 * the stream.

	 */

	void (*disable)(struct i915_perf_stream *stream);



	/* Call poll_wait, passing a wait queue that will be woken

	/**

	 * @poll_wait: Call poll_wait, passing a wait queue that will be woken

	 * once there is something ready to read() for the stream

	 */

	void (*poll_wait)(struct i915_perf_stream *stream,

			  struct file *file,

			  poll_table *wait);



	/* For handling a blocking read, wait until there is something

	 * to ready to read() for the stream. E.g. wait on the same

	/**

	 * @wait_unlocked: For handling a blocking read, wait until there is

	 * something to ready to read() for the stream. E.g. wait on the same

	 * wait queue that would be passed to poll_wait().

	 */

	int (*wait_unlocked)(struct i915_perf_stream *stream);



	/* read - Copy buffered metrics as records to userspace

	 * @buf: the userspace, destination buffer

	 * @count: the number of bytes to copy, requested by userspace

	 * @offset: zero at the start of the read, updated as the read

	 *          proceeds, it represents how many bytes have been

	 *          copied so far and the buffer offset for copying the

	 *          next record.

	/**

	 * @read: Copy buffered metrics as records to userspace

	 * **buf**: the userspace, destination buffer

	 * **count**: the number of bytes to copy, requested by userspace

	 * **offset**: zero at the start of the read, updated as the read

	 * proceeds, it represents how many bytes have been copied so far and

	 * the buffer offset for copying the next record.

	 *

	 * Copy as many buffered i915 perf samples and records for

	 * this stream to userspace as will fit in the given buffer.

	 * Copy as many buffered i915 perf samples and records for this stream

	 * to userspace as will fit in the given buffer.

	 *

	 * Only write complete records; returning -ENOSPC if there

	 * isn't room for a complete record.

	 * Only write complete records; returning -%ENOSPC if there isn't room

	 * for a complete record.

	 *

	 * Return any error condition that results in a short read

	 * such as -ENOSPC or -EFAULT, even though these may be

	 * squashed before returning to userspace.

	 * Return any error condition that results in a short read such as

	 * -%ENOSPC or -%EFAULT, even though these may be squashed before

	 * returning to userspace.

	 */

	int (*read)(struct i915_perf_stream *stream,

		    char __user *buf,

		    size_t count,

		    size_t *offset);



	/* Cleanup any stream specific resources.

	/**

	 * @destroy: Cleanup any stream specific resources.

	 *

	 * The stream will always be disabled before this is called.

	 */

	void (*destroy)(struct i915_perf_stream *stream);

};



/**

 * struct i915_perf_stream - state for a single open stream FD

 */

struct i915_perf_stream {

	/**

	 * @dev_priv: i915 drm device

	 */

	struct drm_i915_private *dev_priv;



	/**

	 * @link: Links the stream into ``&drm_i915_private->streams``

	 */

	struct list_head link;



	/**

	 * @sample_flags: Flags representing the `DRM_I915_PERF_PROP_SAMPLE_*`

	 * properties given when opening a stream, representing the contents

	 * of a single sample as read() by userspace.

	 */

	u32 sample_flags;



	/**

	 * @sample_size: Considering the configured contents of a sample

	 * combined with the required header size, this is the total size

	 * of a single sample record.

	 */

	int sample_size;



	/**

	 * @ctx: %NULL if measuring system-wide across all contexts or a

	 * specific context that is being monitored.

	 */

	struct i915_gem_context *ctx;



	/**

	 * @enabled: Whether the stream is currently enabled, considering

	 * whether the stream was opened in a disabled state and based

	 * on `I915_PERF_IOCTL_ENABLE` and `I915_PERF_IOCTL_DISABLE` calls.

	 */

	bool enabled;



	/**

	 * @ops: The callbacks providing the implementation of this specific

	 * type of configured stream.

	 */

	const struct i915_perf_stream_ops *ops;

};



/**

 * struct i915_oa_ops - Gen specific implementation of an OA unit stream

 */

struct i915_oa_ops {

	/**

	 * @init_oa_buffer: Resets the head and tail pointers of the

	 * circular buffer for periodic OA reports.

	 *

	 * Called when first opening a stream for OA metrics, but also may be

	 * called in response to an OA buffer overflow or other error

	 * condition.

	 *

	 * Note it may be necessary to clear the full OA buffer here as part of

	 * maintaining the invariable that new reports must be written to

	 * zeroed memory for us to be able to reliable detect if an expected

	 * report has not yet landed in memory.  (At least on Haswell the OA

	 * buffer tail pointer is not synchronized with reports being visible

	 * to the CPU)

	 */

	void (*init_oa_buffer)(struct drm_i915_private *dev_priv);



	/**

	 * @enable_metric_set: Applies any MUX configuration to set up the

	 * Boolean and Custom (B/C) counters that are part of the counter

	 * reports being sampled. May apply system constraints such as

	 * disabling EU clock gating as required.

	 */

	int (*enable_metric_set)(struct drm_i915_private *dev_priv);



	/**

	 * @disable_metric_set: Remove system constraints associated with using

	 * the OA unit.

	 */

	void (*disable_metric_set)(struct drm_i915_private *dev_priv);



	/**

	 * @oa_enable: Enable periodic sampling

	 */

	void (*oa_enable)(struct drm_i915_private *dev_priv);



	/**

	 * @oa_disable: Disable periodic sampling

	 */

	void (*oa_disable)(struct drm_i915_private *dev_priv);

	void (*update_oacontrol)(struct drm_i915_private *dev_priv);

	void (*update_hw_ctx_id_locked)(struct drm_i915_private *dev_priv,

					u32 ctx_id);



	/**

	 * @read: Copy data from the circular OA buffer into a given userspace

	 * buffer.

	 */

	int (*read)(struct i915_perf_stream *stream,

		    char __user *buf,

		    size_t count,

		    size_t *offset);



	/**

	 * @oa_buffer_is_empty: Check if OA buffer empty (false positives OK)

	 *

	 * This is either called via fops or the poll check hrtimer (atomic

	 * ctx) without any locks taken.

	 *

	 * It's safe to read OA config state here unlocked, assuming that this

	 * is only called while the stream is enabled, while the global OA

	 * configuration can't be modified.

	 *

	 * Efficiency is more important than avoiding some false positives

	 * here, which will be handled gracefully - likely resulting in an

	 * %EAGAIN error for userspace.

	 */

	bool (*oa_buffer_is_empty)(struct drm_i915_private *dev_priv);

};

drivers/gpu/drm/i915/i915_perf.c

+383 −29

File changed.

Preview size limit exceeded, changes collapsed.

CRA Git | Maintained and supported by SUSTech CRA and CCSE