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

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
...@@ -356,4 +356,95 @@ switch_mm ...@@ -356,4 +356,95 @@ switch_mm
.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
:doc: switch_mm tracepoint :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 .. WARNING: DOCPROC directive not supported: !Cdrivers/gpu/drm/i915/i915_irq.c
...@@ -1930,89 +1930,186 @@ struct i915_oa_reg { ...@@ -1930,89 +1930,186 @@ struct i915_oa_reg {
struct i915_perf_stream; struct i915_perf_stream;
/**
* struct i915_perf_stream_ops - the OPs to support a specific stream type
*/
struct i915_perf_stream_ops { 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 * @enable: Enables the collection of HW samples, either in response to
* opened without I915_PERF_FLAG_DISABLED. * `I915_PERF_IOCTL_ENABLE` or implicitly called when stream is opened
* without `I915_PERF_FLAG_DISABLED`.
*/ */
void (*enable)(struct i915_perf_stream *stream); 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 * @disable: Disables the collection of HW samples, either in response
* destroying the stream. * to `I915_PERF_IOCTL_DISABLE` or implicitly called before destroying
* the stream.
*/ */
void (*disable)(struct i915_perf_stream *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 * once there is something ready to read() for the stream
*/ */
void (*poll_wait)(struct i915_perf_stream *stream, void (*poll_wait)(struct i915_perf_stream *stream,
struct file *file, struct file *file,
poll_table *wait); 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(). * wait queue that would be passed to poll_wait().
*/ */
int (*wait_unlocked)(struct i915_perf_stream *stream); int (*wait_unlocked)(struct i915_perf_stream *stream);
/* read - Copy buffered metrics as records to userspace /**
* @buf: the userspace, destination buffer * @read: Copy buffered metrics as records to userspace
* @count: the number of bytes to copy, requested by userspace * **buf**: the userspace, destination buffer
* @offset: zero at the start of the read, updated as the read * **count**: the number of bytes to copy, requested by userspace
* proceeds, it represents how many bytes have been * **offset**: zero at the start of the read, updated as the read
* copied so far and the buffer offset for copying the * proceeds, it represents how many bytes have been copied so far and
* next record. * the buffer offset for copying the next record.
* *
* Copy as many buffered i915 perf samples and records for * Copy as many buffered i915 perf samples and records for this stream
* this stream to userspace as will fit in the given buffer. * to userspace as will fit in the given buffer.
* *
* Only write complete records; returning -ENOSPC if there * Only write complete records; returning -%ENOSPC if there isn't room
* isn't room for a complete record. * for a complete record.
* *
* Return any error condition that results in a short read * Return any error condition that results in a short read such as
* such as -ENOSPC or -EFAULT, even though these may be * -%ENOSPC or -%EFAULT, even though these may be squashed before
* squashed before returning to userspace. * returning to userspace.
*/ */
int (*read)(struct i915_perf_stream *stream, int (*read)(struct i915_perf_stream *stream,
char __user *buf, char __user *buf,
size_t count, size_t count,
size_t *offset); size_t *offset);
/* Cleanup any stream specific resources. /**
* @destroy: Cleanup any stream specific resources.
* *
* The stream will always be disabled before this is called. * The stream will always be disabled before this is called.
*/ */
void (*destroy)(struct i915_perf_stream *stream); void (*destroy)(struct i915_perf_stream *stream);
}; };
/**
* struct i915_perf_stream - state for a single open stream FD
*/
struct i915_perf_stream { struct i915_perf_stream {
/**
* @dev_priv: i915 drm device
*/
struct drm_i915_private *dev_priv; struct drm_i915_private *dev_priv;
/**
* @link: Links the stream into ``&drm_i915_private->streams``
*/
struct list_head link; 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; 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; 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; 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; bool enabled;
/**
* @ops: The callbacks providing the implementation of this specific
* type of configured stream.
*/
const struct i915_perf_stream_ops *ops; const struct i915_perf_stream_ops *ops;
}; };
/**
* struct i915_oa_ops - Gen specific implementation of an OA unit stream
*/
struct i915_oa_ops { 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); 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); 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); void (*disable_metric_set)(struct drm_i915_private *dev_priv);
/**
* @oa_enable: Enable periodic sampling
*/
void (*oa_enable)(struct drm_i915_private *dev_priv); void (*oa_enable)(struct drm_i915_private *dev_priv);
/**
* @oa_disable: Disable periodic sampling
*/
void (*oa_disable)(struct drm_i915_private *dev_priv); 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, int (*read)(struct i915_perf_stream *stream,
char __user *buf, char __user *buf,
size_t count, size_t count,
size_t *offset); 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); bool (*oa_buffer_is_empty)(struct drm_i915_private *dev_priv);
}; };
......
This diff is collapsed.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment