Skip to contentSkip to conversation

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

PATCH In review Robert Bragg 6 participants 8 messages Nov 29, 2016 – Dec 2, 2016

Subsystems (4)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 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

---
 Documentation/gpu/i915.rst       |  92 +++++++++++++
 drivers/gpu/drm/i915/i915_drv.h  | 151 ++++++++++++++++----
 drivers/gpu/drm/i915/i915_perf.c | 289 +++++++++++++++++++++++++++++++++++----
 3 files changed, 478 insertions(+), 54 deletions(-)
Documentation/gpu/i915.rst +92 -0
index 117d2ab..714bd4b 100644
@@ -356,4 +356,96 @@ switch_mm
 .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
    :doc: switch_mm tracepoint
 
+Perf
+====
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :doc: i915 Perf Overview
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :doc: i915 Perf History and Comparison with Core Perf
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :doc: i915 Perf File Operations
+
+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_unlocked
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :functions: i915_perf_destroy_unlocked
+.. 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_unlocked
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :functions: i915_perf_disable_unlocked
+.. 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_unlocked
+
+i915 Perf Observation Architecture Stream
+-----------------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :functions: OA_BUFFER_SIZE
+.. 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

213 lines not on this page · raw message

drivers/gpu/drm/i915/i915_perf.c +262 -27

454 lines not on this page · raw message

Signature · 6 lines
2.10.2

_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
#1 lore raw

✗ Fi.CI.BAT: warning for drm/i915/perf: More documentation hooked to i915.rst

== Series Details ==

== Series Details ==

Series: drm/i915/perf: More documentation hooked to i915.rst
URL : https://patchwork.freedesktop.org/series/16114/
State : warning

== Summary ==

Series 16114v1 drm/i915/perf: More documentation hooked to i915.rst
https://patchwork.freedesktop.org/api/1.0/series/16114/revisions/1/mbox/

Test kms_flip:

        Subgroup basic-flip-vs-wf_vblank:
                pass       -> DMESG-WARN (fi-skl-6770hq)
fi-bdw-5557u     total:245  pass:230  dwarn:0   dfail:0   fail:0   skip:15 
fi-bsw-n3050     total:245  pass:205  dwarn:0   dfail:0   fail:0   skip:40 
fi-bxt-t5700     total:245  pass:217  dwarn:0   dfail:0   fail:0   skip:28 
fi-byt-j1900     total:245  pass:217  dwarn:0   dfail:0   fail:0   skip:28 
fi-byt-n2820     total:245  pass:213  dwarn:0   dfail:0   fail:0   skip:32 
fi-hsw-4770      total:245  pass:225  dwarn:0   dfail:0   fail:0   skip:20 
fi-hsw-4770r     total:245  pass:225  dwarn:0   dfail:0   fail:0   skip:20 
fi-ilk-650       total:245  pass:192  dwarn:0   dfail:0   fail:0   skip:53 
fi-ivb-3520m     total:245  pass:223  dwarn:0   dfail:0   fail:0   skip:22 
fi-ivb-3770      total:245  pass:223  dwarn:0   dfail:0   fail:0   skip:22 
fi-kbl-7500u     total:245  pass:223  dwarn:0   dfail:0   fail:0   skip:22 
fi-skl-6260u     total:245  pass:231  dwarn:0   dfail:0   fail:0   skip:14 
fi-skl-6700hq    total:245  pass:224  dwarn:0   dfail:0   fail:0   skip:21 
fi-skl-6700k     total:245  pass:223  dwarn:1   dfail:0   fail:0   skip:21 
fi-skl-6770hq    total:245  pass:230  dwarn:1   dfail:0   fail:0   skip:14 
fi-snb-2520m     total:245  pass:213  dwarn:0   dfail:0   fail:0   skip:32 
fi-snb-2600      total:245  pass:212  dwarn:0   dfail:0   fail:0   skip:33 

0d603327c63630327b2a4a09ae6ea521dd21513d drm-tip: 2016y-11m-29d-18h-00m-53s UTC integration manifest d10f3f3 drm/i915/perf: More documentation hooked to i915.rst

== Logs ==

For more details see: https://intel-gfx-ci.01.org/CI/Patchwork_3146/
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

#2 lore raw

Re: ✗ Fi.CI.BAT: warning for drm/i915/perf: More documentation hooked to i915.rst

Quoted 8 lines

== Series Details ==

Series: drm/i915/perf: More documentation hooked to i915.rst
URL : https://patchwork.freedesktop.org/series/16114/
State : warning

== Summary ==

Quoted 7 lines

Series 16114v1 drm/i915/perf: More documentation hooked to i915.rst
https://patchwork.freedesktop.org/api/1.0/series/16114/revisions/1/mbo
x/

Test kms_flip:

        Subgroup basic-flip-vs-wf_vblank:
                pass       -> DMESG-WARN (fi-skl-6770hq)

Two issues seen:
*ERROR* failed to inform PCU about cdclk change => https://bugs.freedesktop.org/show_bug.cgi?id=97929
*ERROR* CPU pipe A FIFO underrun => https://bugs.freedesktop.org/show_bug.cgi?id=94605

Quoted 19 lines
fi-bdw-5557u     total:245  pass:230  dwarn:0   dfail:0   fail:0   skip:15
fi-bsw-n3050     total:245  pass:205  dwarn:0   dfail:0   fail:0   skip:40
fi-bxt-t5700     total:245  pass:217  dwarn:0   dfail:0   fail:0   skip:28
fi-byt-j1900     total:245  pass:217  dwarn:0   dfail:0   fail:0   skip:28
fi-byt-n2820     total:245  pass:213  dwarn:0   dfail:0   fail:0   skip:32
fi-hsw-4770      total:245  pass:225  dwarn:0   dfail:0   fail:0   skip:20
fi-hsw-4770r     total:245  pass:225  dwarn:0   dfail:0   fail:0   skip:20
fi-ilk-650       total:245  pass:192  dwarn:0   dfail:0   fail:0   skip:53
fi-ivb-3520m     total:245  pass:223  dwarn:0   dfail:0   fail:0   skip:22
fi-ivb-3770      total:245  pass:223  dwarn:0   dfail:0   fail:0   skip:22
fi-kbl-7500u     total:245  pass:223  dwarn:0   dfail:0   fail:0   skip:22
fi-skl-6260u     total:245  pass:231  dwarn:0   dfail:0   fail:0   skip:14
fi-skl-6700hq    total:245  pass:224  dwarn:0   dfail:0   fail:0   skip:21
fi-skl-6700k     total:245  pass:223  dwarn:1   dfail:0   fail:0   skip:21
fi-skl-6770hq    total:245  pass:230  dwarn:1   dfail:0   fail:0   skip:14
fi-snb-2520m     total:245  pass:213  dwarn:0   dfail:0   fail:0   skip:32
fi-snb-2600      total:245  pass:212  dwarn:0   dfail:0   fail:0   skip:33
Quoted 7 lines

0d603327c63630327b2a4a09ae6ea521dd21513d drm-tip: 2016y-11m- 29d-18h-00m-53s UTC integration manifest
d10f3f3 drm/i915/perf: More documentation hooked to i915.rst

== Logs ==

For more details see: https://intel-gfx-ci.01.org/CI/Patchwork_3146/

Jani Saarinen
Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo

_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

#3 lore raw
In reply to Robert Bragg
Quoted 25 lines · Robert Bragg

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

---
 Documentation/gpu/i915.rst       |  92 +++++++++++++
 drivers/gpu/drm/i915/i915_drv.h  | 151 ++++++++++++++++----
 drivers/gpu/drm/i915/i915_perf.c | 289 +++++++++++++++++++++++++++++++++++----
 3 files changed, 478 insertions(+), 54 deletions(-)
Documentation/gpu/i915.rst +1 -0
index 117d2ab..714bd4b 100644
@@ -356,4 +356,96 @@ switch_mm
 .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
    :doc: switch_mm tracepoint
 
+Perf

Documentation/gpu/i915.rst switch_mm · line 369

Quoted 10 lines
Documentation/gpu/i915.rst +10 -0
+====
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :doc: i915 Perf Overview
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :doc: i915 Perf History and Comparison with Core Perf
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :doc: i915 Perf File Operations

I see no such :DOC entry in i915_perf.c.

Quoted 9 lines
Documentation/gpu/i915.rst +9 -0
+
+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

Documentation/gpu/i915.rst switch_mm · line 388

Quoted 10 lines
Documentation/gpu/i915.rst +10 -0
+.. 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

I see no kernel doc for this.

Quoted 6 lines
Documentation/gpu/i915.rst +6 -0
+
+i915 Perf Stream
+----------------
+
+This section covers the stream-semantics-agnostic structures and functions
+for representing an i915 perf stream FD and associated file operations.

Documentation/gpu/i915.rst switch_mm · line 404

Quoted 10 lines
Documentation/gpu/i915.rst +10 -0
+
+.. 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_unlocked

i915_perf_open_ioctl_locked, and there is no kernel doc for it.

Documentation/gpu/i915.rst switch_mm · line 406

Quoted 2 lines
Documentation/gpu/i915.rst +2 -0
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :functions: i915_perf_destroy_unlocked

i915_perf_destroy_locked, and there is no kernel doc for it.

Documentation/gpu/i915.rst switch_mm · line 410

Quoted 4 lines
Documentation/gpu/i915.rst +4 -0
+.. 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

I see no kernel doc for this.

Documentation/gpu/i915.rst switch_mm · line 412

Quoted 2 lines
Documentation/gpu/i915.rst +2 -0
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :functions: i915_perf_enable_unlocked

i915_perf_enable_locked, and there is no kernel doc for it.

Documentation/gpu/i915.rst switch_mm · line 414

Quoted 2 lines
Documentation/gpu/i915.rst +2 -0
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :functions: i915_perf_disable_unlocked

i915_perf_disable_locked, and there is no kernel doc for it.

Documentation/gpu/i915.rst switch_mm · line 418

Quoted 4 lines
Documentation/gpu/i915.rst +4 -0
+.. 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_unlocked

i915_perf_poll_locked, and there is no kernel doc for it

Documentation/gpu/i915.rst switch_mm · line 424

Quoted 6 lines
Documentation/gpu/i915.rst +6 -0
+
+i915 Perf Observation Architecture Stream
+-----------------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :functions: OA_BUFFER_SIZE

hmm, but this is not a function, enum, union, struct or typedef, so can we actually add kernel doc for preprocessor directives ? Also OA_BUFFER_SIZE lacks the proper formatting to get picked up anyway.

Quoted 81 lines
Documentation/gpu/i915.rst +26 -0
+.. 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 +16 -13
index 1ec9619..9f92755 100644
@@ -1827,89 +1827,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

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg { · line 1869

Quoted 10 lines
drivers/gpu/drm/i915/i915_drv.h +7 -3
-        *          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.

So there's no proper way of documenting the parameters of a function pointer which happens to also be a member of a struct ? I guess you would have to do a typedef, but then that's a bit ugly...

Quoted 314 lines
drivers/gpu/drm/i915/i915_drv.h +101 -11
         *
-        * 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 +74 -8
index 68b7c27..0be8cef 100644
@@ -26,7 +26,10 @@
 
 
 /**
- * DOC: i915 Perf, streaming API for GPU metrics
+ * DOC: i915 Perf Overview
+ *
+ * Overview
+ * --------
  *
  * Gen graphics supports a large number of performance counters that can help
  * driver and application developers understand and optimize their use of the
@@ -45,6 +48,13 @@
  * privileges by default, unless changed via the dev.i915.perf_event_paranoid
  * sysctl option.
  *
+ */
+
+/**
+ * DOC: i915 Perf History and Comparison with Core Perf
+ *
+ * Comparison with Core Perf
+ * -------------------------
  *
  * The interface was initially inspired by the core Perf infrastructure but
  * some notable differences are:
@@ -75,8 +85,8 @@
  * gets copied from the GPU mapped buffers to userspace buffers.
  *
  *
- * Some notes regarding Linux Perf:
- * --------------------------------
+ * Issues hit with first prototype based on Core Perf
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  *
  * The first prototype of this driver was based on the core perf
  * infrastructure, and while we did make that mostly work, with some changes to
@@ -135,7 +145,7 @@
  *   for combining with the side-band raw reports it captures using
  *   MI_REPORT_PERF_COUNT commands.
  *
- *   _ As a side note on perf's grouping feature; there was also some concern
+ *   - As a side note on perf's grouping feature; there was also some concern
  *     that using PERF_FORMAT_GROUP as a way to pack together counter values
  *     would quite drastically inflate our sample sizes, which would likely
  *     lower the effective sampling resolutions we could use when the available
@@ -277,6 +287,20 @@ static struct i915_oa_format hsw_oa_formats[I915_OA_FORMAT_MAX] = {
 
 #define SAMPLE_OA_REPORT      (1<<0)
 
+/**
+ * struct perf_open_properties - for validated properties given to open a stream
+ * @sample_flags: `DRM_I915_PERF_PROP_SAMPLE_*` properties are tracked as flags
+ * @single_context: Whether a single or all gpu contexts should be monitored
+ * @ctx_handle: A gem ctx handle for use with @single_context
+ * @metrics_set: An ID for an OA unit metric set advertised via sysfs
+ * @oa_format: An OA unit HW report format
+ * @oa_periodic: Whether to enable periodic OA unit sampling
+ * @oa_period_exponent: The OA unit sampling period is derived from this
+ *
+ * As read_properties_unlocked() enumerates and validates the properties given
+ * to open a stream of metrics the configuration is built up in the structure
+ * which starts out zero initialized.
+ */
 struct perf_open_properties {
        u32 sample_flags;
 
@@ -314,7 +338,19 @@ static bool gen7_oa_buffer_is_empty_fop_unlocked(struct drm_i915_private *dev_pr
 }
 
 /**
- * Appends a status record to a userspace read() buffer.
+ * append_oa_status - Appends a status record to a userspace read() buffer.
+ * @stream: An i915-perf stream opened for OA metrics
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @offset: (inout): the current position for writing into @buf
+ * @type: The kind of status to report to userspace
+ *
+ * Writes a status record (such as `DRM_I915_PERF_RECORD_OA_REPORT_LOST`)
+ * into the userspace read() buffer.
+ *
+ * The @buf @offset will only be updated on success.
+ *
+ * Returns: 0 on success, negative error code on failure.
  */
 static int append_oa_status(struct i915_perf_stream *stream,
                            char __user *buf,
@@ -336,7 +372,21 @@ static int append_oa_status(struct i915_perf_stream *stream,
 }
 
 /**
- * Copies single OA report into userspace read() buffer.
+ * append_oa_sample - Copies single OA report into userspace read() buffer.
+ * @stream: An i915-perf stream opened for OA metrics
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @offset: (inout): the current position for writing into @buf
+ * @report: A single OA report to (optionally) include as part of the sample
+ *
+ * The contents of a sample are configured through `DRM_I915_PERF_PROP_SAMPLE_*`
+ * properties when opening a stream, tracked as `stream->sample_flags`. This
+ * function copies the requested components of a single sample to the given
+ * read() @buf.
+ *
+ * The @buf @offset will only be updated on success.
+ *
+ * Returns: 0 on success, negative error code on failure.
  */
 static int append_oa_sample(struct i915_perf_stream *stream,
                            char __user *buf,
@@ -380,8 +430,6 @@ static int append_oa_sample(struct i915_perf_stream *stream,
  * @head_ptr: (inout): the current oa buffer cpu read position
  * @tail: the current oa buffer gpu write position
  *
- * Returns 0 on success, negative error code on failure.
- *
  * Notably any error condition resulting in a short read (-ENOSPC or
  * -EFAULT) will be returned even though one or more records may
  * have been successfully copied. In this case it's up to the caller
@@ -392,6 +440,8 @@ static int append_oa_sample(struct i915_perf_stream *stream,
  * tail, so the head chases the tail?... If you think that's mad
  * and back-to-front you're not alone, but this follows the
  * Gen PRM naming convention.
+ *
+ * Returns: 0 on success, negative error code on failure.
  */
 static int gen7_append_oa_reports(struct i915_perf_stream *stream,
                                  char __user *buf,
@@ -496,6 +546,22 @@ static int gen7_append_oa_reports(struct i915_perf_stream *stream,
        return ret;
 }
 
+/**
+ * gen7_oa_read - copy status records then buffered OA reports
+ * @stream: An i915-perf stream opened for OA metrics
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @offset: (inout): the current position for writing into @buf
+ *
+ * Checks Gen 7 specific OA unit status registers and if necessary appends
+ * corresponding status records for userspace (such as for a buffer full
+ * condition) and then initiate appending any buffered OA reports.
+ *
+ * Updates @offset according to the number of bytes successfully copied into
+ * the userspace buffer.
+ *
+ * Returns: zero on success or a negative error code
+ */
 static int gen7_oa_read(struct i915_perf_stream *stream,
                        char __user *buf,
                        size_t count,
@@ -597,6 +663,20 @@ static int gen7_oa_read(struct i915_perf_stream *stream,
        return ret;
 }
 

drivers/gpu/drm/i915/i915_perf.c static int gen7_oa_read(struct i915_perf_stream *stream, · line 675

Quoted 10 lines
drivers/gpu/drm/i915/i915_perf.c +10 -0
+/**
+ * i915_oa_wait_unlocked - handles blocking IO until OA data available
+ * @stream: An i915-perf stream opened for OA metrics
+ *
+ * Called when userspace tries to read() from a blocking stream FD opened
+ * for OA metrics. It waits until the hrtimer callback finds a non-empty
+ * OA buffer and wakes us.
+ *
+ * Note: it's acceptable to have this return with some false positives
+ * since any subsequent read handling will return EAGAIN if there isn't

s/EAGAIN/-EAGAIN/

Quoted 25 lines
drivers/gpu/drm/i915/i915_perf.c +14 -0
+ * really data ready for userspace yet.
+ *
+ * Returns: zero on success or a negative error code
+ */
 static int i915_oa_wait_unlocked(struct i915_perf_stream *stream)
 {
        struct drm_i915_private *dev_priv = stream->dev_priv;
@@ -615,6 +695,16 @@ static int i915_oa_wait_unlocked(struct i915_perf_stream *stream)
                                        !dev_priv->perf.oa.ops.oa_buffer_is_empty(dev_priv));
 }
 
+/**
+ * i915_oa_poll_wait - call poll_wait() for an OA stream poll()
+ * @stream: An i915-perf stream opened for OA metrics
+ * @file: An i915 perf stream file
+ * @wait: poll() state table
+ *
+ * For handling userspace polling on an i915 perf stream opened for OA metrics,
+ * this starts a poll_wait with the wait queue that our hrtimer callback wakes
+ * when it sees data ready to read in the circular OA buffer.
+ */
 static void i915_oa_poll_wait(struct i915_perf_stream *stream,
                              struct file *file,
                              poll_table *wait)

drivers/gpu/drm/i915/i915_perf.c static void i915_oa_poll_wait(struct i915_perf_stream *stream, · line 718

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
@@ -624,6 +714,18 @@ static void i915_oa_poll_wait(struct i915_perf_stream *stream,
        poll_wait(file, &dev_priv->perf.oa.poll_wq, wait);
 }
 
+/**
+ * i915_oa_read - just calls through to ``&i915_oa_ops->read``

I've got no idea what ``&i915_oa_ops->read`` is supposed to generate, but it spews out :c:type:i915_oa_ops->read <i915_oa_ops> for me...

Quoted 101 lines
drivers/gpu/drm/i915/i915_perf.c +59 -1
+ * @stream: An i915-perf stream opened for OA metrics
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @offset: (inout): the current position for writing into @buf
+ *
+ * Updates @offset according to the number of bytes successfully copied into
+ * the userspace buffer.
+ *
+ * Returns: zero on success or a negative error code
+ */
 static int i915_oa_read(struct i915_perf_stream *stream,
                        char __user *buf,
                        size_t count,
@@ -634,9 +736,15 @@ static int i915_oa_read(struct i915_perf_stream *stream,
        return dev_priv->perf.oa.ops.read(stream, buf, count, offset);
 }
 
-/* Determine the render context hw id, and ensure it remains fixed for the
+/**
+ * oa_get_render_ctx_id - determine and hold ctx hw id
+ * @stream: An i915-perf stream opened for OA metrics
+ *
+ * Determine the render context hw id, and ensure it remains fixed for the
  * lifetime of the stream. This ensures that we don't have to worry about
  * updating the context ID in OACONTROL on the fly.
+ *
+ * Returns: zero on success or a negative error code
  */
 static int oa_get_render_ctx_id(struct i915_perf_stream *stream)
 {
@@ -673,6 +781,13 @@ static int oa_get_render_ctx_id(struct i915_perf_stream *stream)
        return ret;
 }
 
+/**
+ * oa_put_render_ctx_id - counterpart to oa_get_render_ctx_id releases hold
+ * @stream: An i915-perf stream opened for OA metrics
+ *
+ * In case anything needed doing to ensure the context HW ID would remain valid
+ * for the lifetime of the stream, then that can be undone here.
+ */
 static void oa_put_render_ctx_id(struct i915_perf_stream *stream)
 {
        struct drm_i915_private *dev_priv = stream->dev_priv;
@@ -945,6 +1060,15 @@ static void gen7_oa_enable(struct drm_i915_private *dev_priv)
        spin_unlock_irqrestore(&dev_priv->perf.hook_lock, flags);
 }
 
+/**
+ * i915_oa_stream_enable - handle I915_PERF_IOCTL_ENABLE for OA stream
+ * @stream: An i915 perf stream opened for OA metrics
+ *
+ * [Re]enables hardware periodic sampling according to the period configured
+ * when opening the stream. This also starts a hrtimer that will periodically
+ * check for data in the circular OA buffer for notifying userspace (e.g.
+ * during a read() or poll()).
+ */
 static void i915_oa_stream_enable(struct i915_perf_stream *stream)
 {
        struct drm_i915_private *dev_priv = stream->dev_priv;
@@ -962,6 +1086,14 @@ static void gen7_oa_disable(struct drm_i915_private *dev_priv)
        I915_WRITE(GEN7_OACONTROL, 0);
 }
 
+/**
+ * i915_oa_stream_disable - handle I915_PERF_IOCTL_DISABLE for OA stream
+ * @stream: An i915 perf stream opened for OA metrics
+ *
+ * Stops the OA unit from periodically writing counter reports into the
+ * circular OA buffer. This also stops the hrtimer that periodically checks for
+ * data in the circular OA buffer, for notifying userspace.
+ */
 static void i915_oa_stream_disable(struct i915_perf_stream *stream)
 {
        struct drm_i915_private *dev_priv = stream->dev_priv;
@@ -987,6 +1119,24 @@ static const struct i915_perf_stream_ops i915_oa_stream_ops = {
        .read = i915_oa_read,
 };
 
+/**
+ * i915_oa_stream_init - validate combined props for OA stream and init
+ * @stream: An i915 perf stream
+ * @param: The open parameters passed to 'DRM_I915_PERF_OPEN`
+ * @props: The property state that configures stream (individually validated)
+ *
+ * While read_properties_unlocked() validates properties in isolation it
+ * doesn't ensure that the combination necessarily makes sense.
+ *
+ * At this point it has been determined that userspace wants a stream of
+ * OA metrics, but still we need to further validate the combined
+ * properties are OK.
+ *
+ * If the configuration makes sense then we can allocate memory for
+ * a circular OA buffer and apply the requested metric set configuration.
+ *
+ * Returns: zero on success or a negative error code.
+ */
 static int i915_oa_stream_init(struct i915_perf_stream *stream,
                               struct drm_i915_perf_open_param *param,
                               struct perf_open_properties *props)

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_stream_init(struct i915_perf_stream *stream, · line 1264

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
@@ -1110,6 +1260,31 @@ static int i915_oa_stream_init(struct i915_perf_stream *stream,
        return ret;
 }
 
+/**
+ * i915_perf_read_locked - wrap stream->ops->read with error notmalisation

notmalisation? normalisation? nationalisation?

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_stream_init(struct i915_perf_stream *stream, · line 1271

Quoted 7 lines
drivers/gpu/drm/i915/i915_perf.c +7 -0
+ * @stream: An i915 perf stream
+ * @file: An i915 perf stream file
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @ppos: (inout) file seek position (unused)
+ *
+ * Besides wrapping stream->ops->read() this provides a common place to ensure

This generates stream->ops->:c:func:read() for me...hmm, so maybe we don't want the brackets ?

Quoted 42 lines
drivers/gpu/drm/i915/i915_perf.c +16 -16
+ * that if we've successfully copied any data then reporting that takes
+ * precedence over any internal error status, so the data isn't lost.
+ *
+ * For example ret will be -ENOSPC whenever there is more buffered data than
+ * can be copied to userspace, but that's only interesting if we weren't able
+ * to copy some data because it implies the userspace buffer is too small to
+ * receive a single record (and we never split records).
+ *
+ * Another case with ret == -EFAULT is more of a grey area since it would seem
+ * like bad form for userspace to ask us to overrun its buffer, but the user
+ * knows best:
+ *
+ *   http://yarchive.net/comp/linux/partial_reads_writes.html
+ *
+ * Returns: The number of bytes copied or a negative error code on failure.
+ */
 static ssize_t i915_perf_read_locked(struct i915_perf_stream *stream,
                                     struct file *file,
                                     char __user *buf,
@@ -1125,25 +1300,27 @@ static ssize_t i915_perf_read_locked(struct i915_perf_stream *stream,
        size_t offset = 0;
        int ret = stream->ops->read(stream, buf, count, &offset);
 
-       /* If we've successfully copied any data then reporting that
-        * takes precedence over any internal error status, so the
-        * data isn't lost.
-        *
-        * For example ret will be -ENOSPC whenever there is more
-        * buffered data than can be copied to userspace, but that's
-        * only interesting if we weren't able to copy some data
-        * because it implies the userspace buffer is too small to
-        * receive a single record (and we never split records).
-        *
-        * Another case with ret == -EFAULT is more of a grey area
-        * since it would seem like bad form for userspace to ask us
-        * to overrun its buffer, but the user knows best:
-        *
-        *   http://yarchive.net/comp/linux/partial_reads_writes.html
-        */
        return offset ?: (ret ?: -EAGAIN);
 }
 

drivers/gpu/drm/i915/i915_perf.c static ssize_t i915_perf_read_locked(struct i915_perf_stream *stream, · line 1315

Quoted 10 lines
drivers/gpu/drm/i915/i915_perf.c +10 -0
+/**
+ * i915_perf_read - handles read() FOP for i915 perf stream FDs
+ * @file: An i915 perf stream file
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @ppos: (inout) file seek position (unused)
+ *
+ * The entry point for handling a read() on a stream file descriptor from
+ * userspace. Most of the work is left to the i915_perf_read_locked() and
+ * stream->op->read() but to save having stream implementations (of which

s/stream->op->read()/stream->ops->read

drivers/gpu/drm/i915/i915_perf.c static ssize_t i915_perf_read_locked(struct i915_perf_stream *stream, · line 1318

Quoted 3 lines
drivers/gpu/drm/i915/i915_perf.c +3 -0
+ * we might have multiple later) we handle blocking read here.
+ *
+ * We can also consistently treat trying to read from a disable stream

s/disable/disabled

Quoted 74 lines
drivers/gpu/drm/i915/i915_perf.c +43 -2
+ * as an IO error so implementations can assume the stream is enabled
+ * while reading.
+ *
+ * Returns: The number of bytes copied or a negative error code on failure.
+ */
 static ssize_t i915_perf_read(struct file *file,
                              char __user *buf,
                              size_t count,
@@ -1458,12 +1635,20 @@ i915_perf_open_ioctl_locked(struct drm_i915_private *dev_priv,
        return ret;
 }
 
-/* Note we copy the properties from userspace outside of the i915 perf
- * mutex to avoid an awkward lockdep with mmap_sem.
+/**
+ * read_properties_unlocked - validate + copy userspace stream open properties
+ * @dev_priv: i915 device instance
+ * @uprops: The array of u64 key value pairs given by userspace
+ * @n_props: The number of key value pairs expected in @uprops
+ * @props: The stream configuration built up while validating properties
  *
  * Note this function only validates properties in isolation it doesn't
  * validate that the combination of properties makes sense or that all
  * properties necessary for a particular kind of stream have been set.
+ *
+ * Note that there currently aren't any ordering requirements for properties so
+ * we shouldn't validate or assume anything about ordering here. This doesn't
+ * rule out defining new properties with ordering requirements in the future.
  */
 static int read_properties_unlocked(struct drm_i915_private *dev_priv,
                                    u64 __user *uprops,
@@ -1585,6 +1770,26 @@ static int read_properties_unlocked(struct drm_i915_private *dev_priv,
        return 0;
 }
 
+/**
+ * i915_perf_open_ioctl - DRM ioctl() for userspace to open a stream FD
+ * @dev: drm device
+ * @data: ioctl data copied from userspace (unvalidated)
+ * @file: drm file
+ *
+ * Validates the stream open parameters given by userspace including flags
+ * and an array of u64 key, value pair properties.
+ *
+ * Very little is assumed up front about the nature of the stream being
+ * opened (for instance we don't assume it's for periodic OA unit metrics). An
+ * i915-perf stream is expected to be a suitable interface for other forms of
+ * buffered data written by the GPU besides periodic OA metrics.
+ *
+ * Note we copy the properties from userspace outside of the i915 perf
+ * mutex to avoid an awkward lockdep with mmap_sem.
+ *
+ * Return: A newly opened i915 Perf stream file descriptor or negative
+ * error code on failure.
+ */
 int i915_perf_open_ioctl(struct drm_device *dev, void *data,
                         struct drm_file *file)
 {
@@ -1621,6 +1826,14 @@ int i915_perf_open_ioctl(struct drm_device *dev, void *data,
        return ret;
 }
 
+/**
+ * i915_perf_register - exposes i915-perf to userspace
+ * @dev_priv: i915 device instance
+ *
+ * In particular OA metric sets are advertised under a sysfs metrics/
+ * directory allowing userspace to enumerate valid IDs that can be
+ * used to open an i915-perf stream.
+ */
 void i915_perf_register(struct drm_i915_private *dev_priv)
 {
        if (!IS_HASWELL(dev_priv))

drivers/gpu/drm/i915/i915_perf.c void i915_perf_register(struct drm_i915_private *dev_priv) · line 1867

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
@@ -1650,6 +1863,15 @@ void i915_perf_register(struct drm_i915_private *dev_priv)
        mutex_unlock(&dev_priv->perf.lock);
 }
 
+/**
+ * i915_perf_register - hide i915-perf from userspace

i915_perf_unregister

Quoted 11 lines
drivers/gpu/drm/i915/i915_perf.c +7 -0
+ * @dev_priv: i915 device instance
+ *
+ * i915-perf state cleanup is split up into an 'unregister' and
+ * 'deinit' phase where the interface is first hidden from
+ * userspace by i915_perf_unregister() before cleaning up
+ * remaining state in i915_perf_fini().
+ */
 void i915_perf_unregister(struct drm_i915_private *dev_priv)
 {
        if (!IS_HASWELL(dev_priv))

drivers/gpu/drm/i915/i915_perf.c static struct ctl_table dev_root[] = { · line 1935

Quoted 8 lines
drivers/gpu/drm/i915/i915_perf.c +5 -0
@@ -1706,6 +1928,15 @@ static struct ctl_table dev_root[] = {
        {}
 };
 
+/**
+ * i915_perf_init - initialize i915-perf state on module load
+ * @dev_priv: i915 device instance
+ *
+ * Initializes state i915-perf state without exposing anything to userspace.

s/state i915-perf state/i915-perf state/

Other than that it all looks good.
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

#4 lore raw
In reply to Robert Bragg
Quoted 10 lines · Robert Bragg

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

Two style bikesheds below, feel free to ignore.

Quoted 15 lines
---
 Documentation/gpu/i915.rst       |  92 +++++++++++++
 drivers/gpu/drm/i915/i915_drv.h  | 151 ++++++++++++++++----
 drivers/gpu/drm/i915/i915_perf.c | 289 +++++++++++++++++++++++++++++++++++----
 3 files changed, 478 insertions(+), 54 deletions(-)
Documentation/gpu/i915.rst +1 -0
index 117d2ab..714bd4b 100644
@@ -356,4 +356,96 @@ switch_mm
 .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
    :doc: switch_mm tracepoint
 
+Perf

Documentation/gpu/i915.rst switch_mm · line 369

Quoted 10 lines
Documentation/gpu/i915.rst +10 -0
+====
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :doc: i915 Perf Overview
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :doc: i915 Perf History and Comparison with Core Perf
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :doc: i915 Perf File Operations

You have the headings in the DOC comments itself, which works until someone reorganizes stuff. Then it tends to fall apart badly.

Quoted 9 lines
Documentation/gpu/i915.rst +9 -0
+
+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

Documentation/gpu/i915.rst switch_mm · line 388

Quoted 10 lines
Documentation/gpu/i915.rst +10 -0
+.. 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

One potential issue with listing everything explicitly is that if someone ever (and this is bound to happen) adds a new function, they'll forget to add it. Hence we just pull them all in, and if you want to refernce some specifically, do that in the overview sections. And also sprinkle lots of cross-references all over to make groups of functions easier to discover.

But in the end your docs, your turf ;-)
-Daniel

Quoted 768 lines
Documentation/gpu/i915.rst +62 -0
+
+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_unlocked
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :functions: i915_perf_destroy_unlocked
+.. 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_unlocked
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :functions: i915_perf_disable_unlocked
+.. 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_unlocked
+
+i915 Perf Observation Architecture Stream
+-----------------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :functions: OA_BUFFER_SIZE
+.. 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
index 1ec9619..9f92755 100644
@@ -1827,89 +1827,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 +262 -27
index 68b7c27..0be8cef 100644
@@ -26,7 +26,10 @@
 
 
 /**
- * DOC: i915 Perf, streaming API for GPU metrics
+ * DOC: i915 Perf Overview
+ *
+ * Overview
+ * --------
  *
  * Gen graphics supports a large number of performance counters that can help
  * driver and application developers understand and optimize their use of the
@@ -45,6 +48,13 @@
  * privileges by default, unless changed via the dev.i915.perf_event_paranoid
  * sysctl option.
  *
+ */
+
+/**
+ * DOC: i915 Perf History and Comparison with Core Perf
+ *
+ * Comparison with Core Perf
+ * -------------------------
  *
  * The interface was initially inspired by the core Perf infrastructure but
  * some notable differences are:
@@ -75,8 +85,8 @@
  * gets copied from the GPU mapped buffers to userspace buffers.
  *
  *
- * Some notes regarding Linux Perf:
- * --------------------------------
+ * Issues hit with first prototype based on Core Perf
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  *
  * The first prototype of this driver was based on the core perf
  * infrastructure, and while we did make that mostly work, with some changes to
@@ -135,7 +145,7 @@
  *   for combining with the side-band raw reports it captures using
  *   MI_REPORT_PERF_COUNT commands.
  *
- *   _ As a side note on perf's grouping feature; there was also some concern
+ *   - As a side note on perf's grouping feature; there was also some concern
  *     that using PERF_FORMAT_GROUP as a way to pack together counter values
  *     would quite drastically inflate our sample sizes, which would likely
  *     lower the effective sampling resolutions we could use when the available
@@ -277,6 +287,20 @@ static struct i915_oa_format hsw_oa_formats[I915_OA_FORMAT_MAX] = {
 
 #define SAMPLE_OA_REPORT      (1<<0)
 
+/**
+ * struct perf_open_properties - for validated properties given to open a stream
+ * @sample_flags: `DRM_I915_PERF_PROP_SAMPLE_*` properties are tracked as flags
+ * @single_context: Whether a single or all gpu contexts should be monitored
+ * @ctx_handle: A gem ctx handle for use with @single_context
+ * @metrics_set: An ID for an OA unit metric set advertised via sysfs
+ * @oa_format: An OA unit HW report format
+ * @oa_periodic: Whether to enable periodic OA unit sampling
+ * @oa_period_exponent: The OA unit sampling period is derived from this
+ *
+ * As read_properties_unlocked() enumerates and validates the properties given
+ * to open a stream of metrics the configuration is built up in the structure
+ * which starts out zero initialized.
+ */
 struct perf_open_properties {
 	u32 sample_flags;
 
@@ -314,7 +338,19 @@ static bool gen7_oa_buffer_is_empty_fop_unlocked(struct drm_i915_private *dev_pr
 }
 
 /**
- * Appends a status record to a userspace read() buffer.
+ * append_oa_status - Appends a status record to a userspace read() buffer.
+ * @stream: An i915-perf stream opened for OA metrics
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @offset: (inout): the current position for writing into @buf
+ * @type: The kind of status to report to userspace
+ *
+ * Writes a status record (such as `DRM_I915_PERF_RECORD_OA_REPORT_LOST`)
+ * into the userspace read() buffer.
+ *
+ * The @buf @offset will only be updated on success.
+ *
+ * Returns: 0 on success, negative error code on failure.
  */
 static int append_oa_status(struct i915_perf_stream *stream,
 			    char __user *buf,
@@ -336,7 +372,21 @@ static int append_oa_status(struct i915_perf_stream *stream,
 }
 
 /**
- * Copies single OA report into userspace read() buffer.
+ * append_oa_sample - Copies single OA report into userspace read() buffer.
+ * @stream: An i915-perf stream opened for OA metrics
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @offset: (inout): the current position for writing into @buf
+ * @report: A single OA report to (optionally) include as part of the sample
+ *
+ * The contents of a sample are configured through `DRM_I915_PERF_PROP_SAMPLE_*`
+ * properties when opening a stream, tracked as `stream->sample_flags`. This
+ * function copies the requested components of a single sample to the given
+ * read() @buf.
+ *
+ * The @buf @offset will only be updated on success.
+ *
+ * Returns: 0 on success, negative error code on failure.
  */
 static int append_oa_sample(struct i915_perf_stream *stream,
 			    char __user *buf,
@@ -380,8 +430,6 @@ static int append_oa_sample(struct i915_perf_stream *stream,
  * @head_ptr: (inout): the current oa buffer cpu read position
  * @tail: the current oa buffer gpu write position
  *
- * Returns 0 on success, negative error code on failure.
- *
  * Notably any error condition resulting in a short read (-ENOSPC or
  * -EFAULT) will be returned even though one or more records may
  * have been successfully copied. In this case it's up to the caller
@@ -392,6 +440,8 @@ static int append_oa_sample(struct i915_perf_stream *stream,
  * tail, so the head chases the tail?... If you think that's mad
  * and back-to-front you're not alone, but this follows the
  * Gen PRM naming convention.
+ *
+ * Returns: 0 on success, negative error code on failure.
  */
 static int gen7_append_oa_reports(struct i915_perf_stream *stream,
 				  char __user *buf,
@@ -496,6 +546,22 @@ static int gen7_append_oa_reports(struct i915_perf_stream *stream,
 	return ret;
 }
 
+/**
+ * gen7_oa_read - copy status records then buffered OA reports
+ * @stream: An i915-perf stream opened for OA metrics
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @offset: (inout): the current position for writing into @buf
+ *
+ * Checks Gen 7 specific OA unit status registers and if necessary appends
+ * corresponding status records for userspace (such as for a buffer full
+ * condition) and then initiate appending any buffered OA reports.
+ *
+ * Updates @offset according to the number of bytes successfully copied into
+ * the userspace buffer.
+ *
+ * Returns: zero on success or a negative error code
+ */
 static int gen7_oa_read(struct i915_perf_stream *stream,
 			char __user *buf,
 			size_t count,
@@ -597,6 +663,20 @@ static int gen7_oa_read(struct i915_perf_stream *stream,
 	return ret;
 }
 
+/**
+ * i915_oa_wait_unlocked - handles blocking IO until OA data available
+ * @stream: An i915-perf stream opened for OA metrics
+ *
+ * Called when userspace tries to read() from a blocking stream FD opened
+ * for OA metrics. It waits until the hrtimer callback finds a non-empty
+ * OA buffer and wakes us.
+ *
+ * Note: it's acceptable to have this return with some false positives
+ * since any subsequent read handling will return EAGAIN if there isn't
+ * really data ready for userspace yet.
+ *
+ * Returns: zero on success or a negative error code
+ */
 static int i915_oa_wait_unlocked(struct i915_perf_stream *stream)
 {
 	struct drm_i915_private *dev_priv = stream->dev_priv;
@@ -615,6 +695,16 @@ static int i915_oa_wait_unlocked(struct i915_perf_stream *stream)
 					!dev_priv->perf.oa.ops.oa_buffer_is_empty(dev_priv));
 }
 
+/**
+ * i915_oa_poll_wait - call poll_wait() for an OA stream poll()
+ * @stream: An i915-perf stream opened for OA metrics
+ * @file: An i915 perf stream file
+ * @wait: poll() state table
+ *
+ * For handling userspace polling on an i915 perf stream opened for OA metrics,
+ * this starts a poll_wait with the wait queue that our hrtimer callback wakes
+ * when it sees data ready to read in the circular OA buffer.
+ */
 static void i915_oa_poll_wait(struct i915_perf_stream *stream,
 			      struct file *file,
 			      poll_table *wait)
@@ -624,6 +714,18 @@ static void i915_oa_poll_wait(struct i915_perf_stream *stream,
 	poll_wait(file, &dev_priv->perf.oa.poll_wq, wait);
 }
 
+/**
+ * i915_oa_read - just calls through to ``&i915_oa_ops->read``
+ * @stream: An i915-perf stream opened for OA metrics
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @offset: (inout): the current position for writing into @buf
+ *
+ * Updates @offset according to the number of bytes successfully copied into
+ * the userspace buffer.
+ *
+ * Returns: zero on success or a negative error code
+ */
 static int i915_oa_read(struct i915_perf_stream *stream,
 			char __user *buf,
 			size_t count,
@@ -634,9 +736,15 @@ static int i915_oa_read(struct i915_perf_stream *stream,
 	return dev_priv->perf.oa.ops.read(stream, buf, count, offset);
 }
 
-/* Determine the render context hw id, and ensure it remains fixed for the
+/**
+ * oa_get_render_ctx_id - determine and hold ctx hw id
+ * @stream: An i915-perf stream opened for OA metrics
+ *
+ * Determine the render context hw id, and ensure it remains fixed for the
  * lifetime of the stream. This ensures that we don't have to worry about
  * updating the context ID in OACONTROL on the fly.
+ *
+ * Returns: zero on success or a negative error code
  */
 static int oa_get_render_ctx_id(struct i915_perf_stream *stream)
 {
@@ -673,6 +781,13 @@ static int oa_get_render_ctx_id(struct i915_perf_stream *stream)
 	return ret;
 }
 
+/**
+ * oa_put_render_ctx_id - counterpart to oa_get_render_ctx_id releases hold
+ * @stream: An i915-perf stream opened for OA metrics
+ *
+ * In case anything needed doing to ensure the context HW ID would remain valid
+ * for the lifetime of the stream, then that can be undone here.
+ */
 static void oa_put_render_ctx_id(struct i915_perf_stream *stream)
 {
 	struct drm_i915_private *dev_priv = stream->dev_priv;
@@ -945,6 +1060,15 @@ static void gen7_oa_enable(struct drm_i915_private *dev_priv)
 	spin_unlock_irqrestore(&dev_priv->perf.hook_lock, flags);
 }
 
+/**
+ * i915_oa_stream_enable - handle I915_PERF_IOCTL_ENABLE for OA stream
+ * @stream: An i915 perf stream opened for OA metrics
+ *
+ * [Re]enables hardware periodic sampling according to the period configured
+ * when opening the stream. This also starts a hrtimer that will periodically
+ * check for data in the circular OA buffer for notifying userspace (e.g.
+ * during a read() or poll()).
+ */
 static void i915_oa_stream_enable(struct i915_perf_stream *stream)
 {
 	struct drm_i915_private *dev_priv = stream->dev_priv;
@@ -962,6 +1086,14 @@ static void gen7_oa_disable(struct drm_i915_private *dev_priv)
 	I915_WRITE(GEN7_OACONTROL, 0);
 }
 
+/**
+ * i915_oa_stream_disable - handle I915_PERF_IOCTL_DISABLE for OA stream
+ * @stream: An i915 perf stream opened for OA metrics
+ *
+ * Stops the OA unit from periodically writing counter reports into the
+ * circular OA buffer. This also stops the hrtimer that periodically checks for
+ * data in the circular OA buffer, for notifying userspace.
+ */
 static void i915_oa_stream_disable(struct i915_perf_stream *stream)
 {
 	struct drm_i915_private *dev_priv = stream->dev_priv;
@@ -987,6 +1119,24 @@ static const struct i915_perf_stream_ops i915_oa_stream_ops = {
 	.read = i915_oa_read,
 };
 
+/**
+ * i915_oa_stream_init - validate combined props for OA stream and init
+ * @stream: An i915 perf stream
+ * @param: The open parameters passed to 'DRM_I915_PERF_OPEN`
+ * @props: The property state that configures stream (individually validated)
+ *
+ * While read_properties_unlocked() validates properties in isolation it
+ * doesn't ensure that the combination necessarily makes sense.
+ *
+ * At this point it has been determined that userspace wants a stream of
+ * OA metrics, but still we need to further validate the combined
+ * properties are OK.
+ *
+ * If the configuration makes sense then we can allocate memory for
+ * a circular OA buffer and apply the requested metric set configuration.
+ *
+ * Returns: zero on success or a negative error code.
+ */
 static int i915_oa_stream_init(struct i915_perf_stream *stream,
 			       struct drm_i915_perf_open_param *param,
 			       struct perf_open_properties *props)
@@ -1110,6 +1260,31 @@ static int i915_oa_stream_init(struct i915_perf_stream *stream,
 	return ret;
 }
 
+/**
+ * i915_perf_read_locked - wrap stream->ops->read with error notmalisation
+ * @stream: An i915 perf stream
+ * @file: An i915 perf stream file
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @ppos: (inout) file seek position (unused)
+ *
+ * Besides wrapping stream->ops->read() this provides a common place to ensure
+ * that if we've successfully copied any data then reporting that takes
+ * precedence over any internal error status, so the data isn't lost.
+ *
+ * For example ret will be -ENOSPC whenever there is more buffered data than
+ * can be copied to userspace, but that's only interesting if we weren't able
+ * to copy some data because it implies the userspace buffer is too small to
+ * receive a single record (and we never split records).
+ *
+ * Another case with ret == -EFAULT is more of a grey area since it would seem
+ * like bad form for userspace to ask us to overrun its buffer, but the user
+ * knows best:
+ *
+ *   http://yarchive.net/comp/linux/partial_reads_writes.html
+ *
+ * Returns: The number of bytes copied or a negative error code on failure.
+ */
 static ssize_t i915_perf_read_locked(struct i915_perf_stream *stream,
 				     struct file *file,
 				     char __user *buf,
@@ -1125,25 +1300,27 @@ static ssize_t i915_perf_read_locked(struct i915_perf_stream *stream,
 	size_t offset = 0;
 	int ret = stream->ops->read(stream, buf, count, &offset);
 
-	/* If we've successfully copied any data then reporting that
-	 * takes precedence over any internal error status, so the
-	 * data isn't lost.
-	 *
-	 * For example ret will be -ENOSPC whenever there is more
-	 * buffered data than can be copied to userspace, but that's
-	 * only interesting if we weren't able to copy some data
-	 * because it implies the userspace buffer is too small to
-	 * receive a single record (and we never split records).
-	 *
-	 * Another case with ret == -EFAULT is more of a grey area
-	 * since it would seem like bad form for userspace to ask us
-	 * to overrun its buffer, but the user knows best:
-	 *
-	 *   http://yarchive.net/comp/linux/partial_reads_writes.html
-	 */
 	return offset ?: (ret ?: -EAGAIN);
 }
 
+/**
+ * i915_perf_read - handles read() FOP for i915 perf stream FDs
+ * @file: An i915 perf stream file
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @ppos: (inout) file seek position (unused)
+ *
+ * The entry point for handling a read() on a stream file descriptor from
+ * userspace. Most of the work is left to the i915_perf_read_locked() and
+ * stream->op->read() but to save having stream implementations (of which
+ * we might have multiple later) we handle blocking read here.
+ *
+ * We can also consistently treat trying to read from a disable stream
+ * as an IO error so implementations can assume the stream is enabled
+ * while reading.
+ *
+ * Returns: The number of bytes copied or a negative error code on failure.
+ */
 static ssize_t i915_perf_read(struct file *file,
 			      char __user *buf,
 			      size_t count,
@@ -1458,12 +1635,20 @@ i915_perf_open_ioctl_locked(struct drm_i915_private *dev_priv,
 	return ret;
 }
 
-/* Note we copy the properties from userspace outside of the i915 perf
- * mutex to avoid an awkward lockdep with mmap_sem.
+/**
+ * read_properties_unlocked - validate + copy userspace stream open properties
+ * @dev_priv: i915 device instance
+ * @uprops: The array of u64 key value pairs given by userspace
+ * @n_props: The number of key value pairs expected in @uprops
+ * @props: The stream configuration built up while validating properties
  *
  * Note this function only validates properties in isolation it doesn't
  * validate that the combination of properties makes sense or that all
  * properties necessary for a particular kind of stream have been set.
+ *
+ * Note that there currently aren't any ordering requirements for properties so
+ * we shouldn't validate or assume anything about ordering here. This doesn't
+ * rule out defining new properties with ordering requirements in the future.
  */
 static int read_properties_unlocked(struct drm_i915_private *dev_priv,
 				    u64 __user *uprops,
@@ -1585,6 +1770,26 @@ static int read_properties_unlocked(struct drm_i915_private *dev_priv,
 	return 0;
 }
 
+/**
+ * i915_perf_open_ioctl - DRM ioctl() for userspace to open a stream FD
+ * @dev: drm device
+ * @data: ioctl data copied from userspace (unvalidated)
+ * @file: drm file
+ *
+ * Validates the stream open parameters given by userspace including flags
+ * and an array of u64 key, value pair properties.
+ *
+ * Very little is assumed up front about the nature of the stream being
+ * opened (for instance we don't assume it's for periodic OA unit metrics). An
+ * i915-perf stream is expected to be a suitable interface for other forms of
+ * buffered data written by the GPU besides periodic OA metrics.
+ *
+ * Note we copy the properties from userspace outside of the i915 perf
+ * mutex to avoid an awkward lockdep with mmap_sem.
+ *
+ * Return: A newly opened i915 Perf stream file descriptor or negative
+ * error code on failure.
+ */
 int i915_perf_open_ioctl(struct drm_device *dev, void *data,
 			 struct drm_file *file)
 {
@@ -1621,6 +1826,14 @@ int i915_perf_open_ioctl(struct drm_device *dev, void *data,
 	return ret;
 }
 
+/**
+ * i915_perf_register - exposes i915-perf to userspace
+ * @dev_priv: i915 device instance
+ *
+ * In particular OA metric sets are advertised under a sysfs metrics/
+ * directory allowing userspace to enumerate valid IDs that can be
+ * used to open an i915-perf stream.
+ */
 void i915_perf_register(struct drm_i915_private *dev_priv)
 {
 	if (!IS_HASWELL(dev_priv))
@@ -1650,6 +1863,15 @@ void i915_perf_register(struct drm_i915_private *dev_priv)
 	mutex_unlock(&dev_priv->perf.lock);
 }
 
+/**
+ * i915_perf_register - hide i915-perf from userspace
+ * @dev_priv: i915 device instance
+ *
+ * i915-perf state cleanup is split up into an 'unregister' and
+ * 'deinit' phase where the interface is first hidden from
+ * userspace by i915_perf_unregister() before cleaning up
+ * remaining state in i915_perf_fini().
+ */
 void i915_perf_unregister(struct drm_i915_private *dev_priv)
 {
 	if (!IS_HASWELL(dev_priv))
@@ -1706,6 +1928,15 @@ static struct ctl_table dev_root[] = {
 	{}
 };
 
+/**
+ * i915_perf_init - initialize i915-perf state on module load
+ * @dev_priv: i915 device instance
+ *
+ * Initializes state i915-perf state without exposing anything to userspace.
+ *
+ * Note: i915-perf initialization is split into an 'init' and 'register'
+ * phase with the i915_perf_register() exposing state to userspace.
+ */
 void i915_perf_init(struct drm_i915_private *dev_priv)
 {
 	if (!IS_HASWELL(dev_priv))
@@ -1741,6 +1972,10 @@ void i915_perf_init(struct drm_i915_private *dev_priv)
 	dev_priv->perf.initialized = true;
 }
 
+/**
+ * i915_perf_fini - Counter part to i915_perf_init()
+ * @dev_priv: i915 device instance
+ */
 void i915_perf_fini(struct drm_i915_private *dev_priv)
 {
 	if (!dev_priv->perf.initialized)
Signature · 1 line
2.10.2
Signature · 7 lines
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
maintainer
#5 lore raw
Quoted 14 lines · Daniel Vetter

Documentation/gpu/i915.rst switch_mm · line 388

Quoted 12 lines · Robert Bragg

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

Documentation/gpu/i915.rst +11 -0
+   :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
Quoted 4 lines

One potential issue with listing everything explicitly is that if someone ever (and this is bound to happen) adds a new function, they'll forget to add it. Hence we just pull them all in, and if you want to refernce some specifically, do that in the overview sections.

One real issue with listing everything separately is that kernel-doc parses the source file once per every kernel-doc directive.

Also, doesn't Sphinx complain about not having a blank line to end the indented block after the directive? It might not, but I thought it might.

BR,
Jani.

Signature · 5 lines
Jani Nikula, Intel Open Source Technology Center
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
#6 lore raw
Quoted 15 lines · Jani Nikula
Quoted 14 lines · Daniel Vetter
Quoted 12 lines · Robert Bragg

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

Documentation/gpu/i915.rst +11 -0
+   :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
Quoted 8 lines
Quoted 4 lines

One potential issue with listing everything explicitly is that if someone ever (and this is bound to happen) adds a new function, they'll forget to add it. Hence we just pull them all in, and if you want to refernce some specifically, do that in the overview sections.

One real issue with listing everything separately is that kernel-doc parses the source file once per every kernel-doc directive.

Yeah, this is unfortunate and I'd originally hoped I could pass an ordered list which could reduce how often kernel-doc is run. In practice I haven't seen a performance problem with doing this though.

Quoted 5 lines

Also, doesn't Sphinx complain about not having a blank line to end the indented block after the directive? It might not, but I thought it might.

Apparently it's ok, I've been generating and previewing the documentation and haven't seen a warning about this.

Quoted 1 line

From the restructure text spec, regarding white space:

"Blank lines may be omitted when the markup makes element separation unambiguous, in conjunction with indentation."

Regards,
- Robert

Quoted 8 lines

BR,
Jani.

--
Jani Nikula, Intel Open Source Technology Center

_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

#7 lore raw
In reply to Daniel Vetter
Quoted 10 lines · Daniel Vetter
Quoted 8 lines · Robert Bragg

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

Quoted 9 lines
Quoted 2 lines

Two style bikesheds below, feel free to ignore.

Quoted 4 lines
---
 Documentation/gpu/i915.rst       |  92 +++++++++++++
 drivers/gpu/drm/i915/i915_drv.h  | 151 ++++++++++++++++----
 drivers/gpu/drm/i915/i915_perf.c | 289 ++++++++++++++++++++++++++++++

+++++----

Quoted 10 lines
Quoted 10 lines
 3 files changed, 478 insertions(+), 54 deletions(-)
Documentation/gpu/i915.rst +0 -0
index 117d2ab..714bd4b 100644
@@ -356,4 +356,96 @@ switch_mm
 .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
    :doc: switch_mm tracepoint
 
Quoted 14 lines

Documentation/gpu/i915.rst switch_mm · line 369

Quoted 11 lines
Documentation/gpu/i915.rst +11 -0
+Perf
+====
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :doc: i915 Perf Overview
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :doc: i915 Perf History and Comparison with Core Perf
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :doc: i915 Perf File Operations

You have the headings in the DOC comments itself, which works until someone reorganizes stuff. Then it tends to fall apart badly.

Yeah, could be better.

Quoted 18 lines
Quoted 18 lines
Documentation/gpu/i915.rst +17 -0
+
+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
Quoted 8 lines

Documentation/gpu/i915.rst switch_mm · line 388

Quoted 2 lines
Documentation/gpu/i915.rst +2 -0
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :functions: i915_perf_release

One potential issue with listing everything explicitly is that if someone ever (and this is bound to happen) adds a new function, they'll forget to add it. Hence we just pull them all in, and if you want to refernce some specifically, do that in the overview sections. And also sprinkle lots of cross-references all over to make groups of functions easier to discover.

Without any structure it just didn't seem like documentation; just a dump of internals info which didn't look that helpful to me.

There are some fairly noteworthy separations of responsibilities between functions providing the i915 perf stream infrastructure and then the code for OA unit streams, and then code specifically for Haswell. Splitting them into sections seems worthwhile to me.

I don't think it's that big a deal listing symbols individually and maintaining this when adding new symbols. Having maintained Cogl using gtk-doc where symbols had to be explicitly listed in a -sections.txt file to added them to the documentation, that wasn't too bad. It's true that slip ups happen, but having control over the order symbols are presented seems good to me. It could be nice if an ordered list could be passed to :functions: to reduce how many times the corresponding perl script runs.

It could maybe be good if there was some way to tag/label symbols in kerneldoc for selection in restructured text. It would also be nice if the tooling understood what symbols were in the document so far, so it could somehow be possible to have a dumping ground section for 'everything else' at the end.

Regards,
- Robert

Quoted 9 lines

But in the end your docs, your turf ;-)
-Daniel

Documentation/gpu/i915.rst switch_mm

Quoted 5 lines
Documentation/gpu/i915.rst +5 -0
+
+i915 Perf Stream
+----------------
+
+This section covers the stream-semantics-agnostic structures and

functions

Quoted 43 lines
Quoted 43 lines
Documentation/gpu/i915.rst +43 -0
+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_unlocked
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :functions: i915_perf_destroy_unlocked
+.. 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_unlocked
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :functions: i915_perf_disable_unlocked
+.. 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_unlocked
+
+i915 Perf Observation Architecture Stream
+-----------------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
+   :functions: OA_BUFFER_SIZE
+.. 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
Quoted 8 lines

Documentation/gpu/i915.rst switch_mm

Quoted 8 lines
Documentation/gpu/i915.rst +8 -0
+   :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

Quoted 1 line

Documentation/gpu/i915.rst switch_mm · line 445

Quoted 1 line
Documentation/gpu/i915.rst +1 -0
+no particular order, but may include some more minor utilities or

platform

Quoted 6 lines

Documentation/gpu/i915.rst switch_mm

Quoted 6 lines
Documentation/gpu/i915.rst +5 -0
+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

Quoted 1 line

Review

Quoted 1 line
(quoted diff) +0 -0

b/drivers/gpu/drm/i915/i915_drv.h

Quoted 9 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg { · line 1831

Quoted 9 lines

index 1ec9619..9f92755 100644

drivers/gpu/drm/i915/i915_drv.h +2 -0
@@ -1827,89 +1827,186 @@ struct i915_oa_reg {
 
 struct i915_perf_stream;
 
+/**
+ * struct i915_perf_stream_ops - the OPs to support a specific stream

type

Quoted 7 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 7 lines
drivers/gpu/drm/i915/i915_drv.h +3 -3
+ */
 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

Quoted 1 line

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg { · line 1836

Quoted 1 line
drivers/gpu/drm/i915/i915_drv.h +1 -0
+      * I915_PERF_IOCTL_ENABLE or implicitly called when stream is

opened

Quoted 9 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 9 lines
drivers/gpu/drm/i915/i915_drv.h +3 -3
+      * 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

Quoted 1 line

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg { · line 1843

Quoted 1 line
drivers/gpu/drm/i915/i915_drv.h +1 -0
+      * to I915_PERF_IOCTL_DISABLE or implicitly called before

destroying

Quoted 7 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 7 lines
drivers/gpu/drm/i915/i915_drv.h +3 -1
+      * 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

Quoted 10 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 10 lines
drivers/gpu/drm/i915/i915_drv.h +2 -2
       * 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

Quoted 1 line

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg { · line 1858

Quoted 1 line
drivers/gpu/drm/i915/i915_drv.h +1 -0
+      * something to ready to read() for the stream. E.g. wait on the

same

Quoted 4 lines
Quoted 4 lines
drivers/gpu/drm/i915/i915_drv.h +0 -0
       * wait queue that would be passed to poll_wait().
       */
      int (*wait_unlocked)(struct i915_perf_stream *stream);
 
Quoted 13 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 13 lines
drivers/gpu/drm/i915/i915_drv.h +6 -7
-     /* 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

Quoted 5 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 5 lines
drivers/gpu/drm/i915/i915_drv.h +2 -2
+      * 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

Quoted 5 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 5 lines
drivers/gpu/drm/i915/i915_drv.h +2 -2
+      * 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

Quoted 32 lines
Quoted 32 lines
drivers/gpu/drm/i915/i915_drv.h +12 -4
+      * 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;
 
Quoted 7 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 7 lines
drivers/gpu/drm/i915/i915_drv.h +5 -0
+     /**
+      * @link: Links the stream into ``&drm_i915_private->streams``
+      */
      struct list_head link;
 
+     /**
+      * @sample_flags: Flags representing the

DRM_I915_PERF_PROP_SAMPLE_*

Quoted 1 line

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg { · line 1910

Quoted 1 line
drivers/gpu/drm/i915/i915_drv.h +1 -0
+      * properties given when opening a stream, representing the

contents

Quoted 11 lines
Quoted 11 lines
drivers/gpu/drm/i915/i915_drv.h +8 -0
+      * 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;
 
Quoted 10 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 10 lines
drivers/gpu/drm/i915/i915_drv.h +9 -0
+     /**
+      * @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.

Quoted 5 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 5 lines
drivers/gpu/drm/i915/i915_drv.h +3 -0
+      */
      bool enabled;
 
+     /**
+      * @ops: The callbacks providing the implementation of this

specific

Quoted 7 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 7 lines
drivers/gpu/drm/i915/i915_drv.h +4 -0
+      * type of configured stream.
+      */
      const struct i915_perf_stream_ops *ops;
 };
 
+/**
+ * struct i915_oa_ops - Gen specific implementation of an OA unit

stream

Quoted 7 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 7 lines
drivers/gpu/drm/i915/i915_drv.h +6 -0
+ */
 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

Quoted 4 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 4 lines
drivers/gpu/drm/i915/i915_drv.h +4 -0
+      * 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

Quoted 2 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg { · line 1956

Quoted 2 lines
drivers/gpu/drm/i915/i915_drv.h +2 -0
+      * maintaining the invariable that new reports must be written to
+      * zeroed memory for us to be able to reliable detect if an

expected

Quoted 1 line

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg { · line 1957

Quoted 1 line
drivers/gpu/drm/i915/i915_drv.h +1 -0
+      * report has not yet landed in memory.  (At least on Haswell the

OA

Quoted 1 line

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg { · line 1958

Quoted 1 line
drivers/gpu/drm/i915/i915_drv.h +1 -0
+      * buffer tail pointer is not synchronized with reports being

visible

Quoted 6 lines
Quoted 6 lines
drivers/gpu/drm/i915/i915_drv.h +5 -0
+      * to the CPU)
+      */
      void (*init_oa_buffer)(struct drm_i915_private *dev_priv);
+
+     /**
+      * @enable_metric_set: Applies any MUX configuration to set up the
Quoted 8 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 8 lines
drivers/gpu/drm/i915/i915_drv.h +7 -0
+      * 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

Quoted 11 lines
Quoted 11 lines
drivers/gpu/drm/i915/i915_drv.h +9 -0
+      * 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
Quoted 8 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 8 lines
drivers/gpu/drm/i915/i915_drv.h +4 -3
+      */
      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

Quoted 9 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 9 lines
drivers/gpu/drm/i915/i915_drv.h +5 -0
+      * 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)

Quoted 2 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg { · line 1999

Quoted 2 lines
drivers/gpu/drm/i915/i915_drv.h +2 -0
+      *
+      * This is either called via fops or the poll check hrtimer

(atomic

Quoted 3 lines

drivers/gpu/drm/i915/i915_drv.h struct i915_oa_reg {

Quoted 3 lines
drivers/gpu/drm/i915/i915_drv.h +3 -0
+      * ctx) without any locks taken.
+      *
+      * It's safe to read OA config state here unlocked, assuming that

this

Quoted 11 lines

Review

Quoted 11 lines
drivers/gpu/drm/i915/i915_drv.h +7 -0
+      * 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);
 };
 
(quoted diff) +0 -0

b/drivers/gpu/drm/i915/i915_perf.c

Quoted 6 lines
Quoted 6 lines

index 68b7c27..0be8cef 100644

drivers/gpu/drm/i915/i915_perf.c +0 -0
@@ -26,7 +26,10 @@
 
 
Quoted 8 lines

drivers/gpu/drm/i915/i915_perf.c

Quoted 8 lines
drivers/gpu/drm/i915/i915_perf.c +4 -1
 /**
- * DOC: i915 Perf, streaming API for GPU metrics
+ * DOC: i915 Perf Overview
+ *
+ * Overview
+ * --------
  *
  * Gen graphics supports a large number of performance counters that

can help

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c line 35

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +0 -0
  * driver and application developers understand and optimize their use

of the

Quoted 2 lines

drivers/gpu/drm/i915/i915_perf.c line 48

Quoted 2 lines
drivers/gpu/drm/i915/i915_perf.c +0 -0
@@ -45,6 +48,13 @@
  * privileges by default, unless changed via the

dev.i915.perf_event_paranoid

Quoted 11 lines

drivers/gpu/drm/i915/i915_perf.c

Quoted 11 lines
drivers/gpu/drm/i915/i915_perf.c +7 -0
  * sysctl option.
  *
+ */
+
+/**
+ * DOC: i915 Perf History and Comparison with Core Perf
+ *
+ * Comparison with Core Perf
+ * -------------------------
  *
  * The interface was initially inspired by the core Perf

infrastructure but

Quoted 4 lines
Quoted 4 lines
drivers/gpu/drm/i915/i915_perf.c +0 -0
  * some notable differences are:
@@ -75,8 +85,8 @@
  * gets copied from the GPU mapped buffers to userspace buffers.
  *
Quoted 8 lines

drivers/gpu/drm/i915/i915_perf.c

Quoted 8 lines
drivers/gpu/drm/i915/i915_perf.c +2 -2
  *
- * Some notes regarding Linux Perf:
- * --------------------------------
+ * Issues hit with first prototype based on Core Perf
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  *
  * The first prototype of this driver was based on the core perf
  * infrastructure, and while we did make that mostly work, with some

changes to

Quoted 5 lines

drivers/gpu/drm/i915/i915_perf.c line 138

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +0 -1
@@ -135,7 +145,7 @@
  *   for combining with the side-band raw reports it captures using
  *   MI_REPORT_PERF_COUNT commands.
  *
- *   _ As a side note on perf's grouping feature; there was also some

concern

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c line 148

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ *   - As a side note on perf's grouping feature; there was also some

concern

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c line 149

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +0 -0
  *     that using PERF_FORMAT_GROUP as a way to pack together counter

values

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c line 150

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +0 -0
  *     would quite drastically inflate our sample sizes, which would

likely

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c line 151

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +0 -0
  *     lower the effective sampling resolutions we could use when the

available

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static struct i915_oa_format

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +0 -0
@@ -277,6 +287,20 @@ static struct i915_oa_format

hsw_oa_formats[I915_OA_FORMAT_MAX] = {

Quoted 5 lines

drivers/gpu/drm/i915/i915_perf.c static struct i915_oa_format hsw_oa_formats[I915_OA_FORMAT_MAX] = {

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
 #define SAMPLE_OA_REPORT      (1<<0)
 
+/**
+ * struct perf_open_properties - for validated properties given to

open a stream

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static struct i915_oa_format · line 291

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * @sample_flags: `DRM_I915_PERF_PROP_SAMPLE_*` properties are tracked

as flags

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static struct i915_oa_format · line 292

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * @single_context: Whether a single or all gpu contexts should be

monitored

Quoted 5 lines

drivers/gpu/drm/i915/i915_perf.c static struct i915_oa_format hsw_oa_formats[I915_OA_FORMAT_MAX] = {

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +5 -0
+ * @ctx_handle: A gem ctx handle for use with @single_context
+ * @metrics_set: An ID for an OA unit metric set advertised via sysfs
+ * @oa_format: An OA unit HW report format
+ * @oa_periodic: Whether to enable periodic OA unit sampling
+ * @oa_period_exponent: The OA unit sampling period is derived from

this

Quoted 2 lines

drivers/gpu/drm/i915/i915_perf.c static struct i915_oa_format · line 299

Quoted 2 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
+ *
+ * As read_properties_unlocked() enumerates and validates the

properties given

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static struct i915_oa_format · line 300

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * to open a stream of metrics the configuration is built up in the

structure

Quoted 6 lines

drivers/gpu/drm/i915/i915_perf.c static bool gen7_oa_buffer_is_empty_fop_unlocked(struct

Quoted 6 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
+ * which starts out zero initialized.
+ */
 struct perf_open_properties {
      u32 sample_flags;
 
@@ -314,7 +338,19 @@ static bool gen7_oa_buffer_is_empty_fop_unlocked(struct

drm_i915_private *dev_pr

Quoted 5 lines

drivers/gpu/drm/i915/i915_perf.c static bool gen7_oa_buffer_is_empty_fop_unlocked(struct drm_i915_private *dev_pr

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +1 -1
 }
 
 /**
- * Appends a status record to a userspace read() buffer.
+ * append_oa_status - Appends a status record to a userspace read()

buffer.

Quoted 7 lines

drivers/gpu/drm/i915/i915_perf.c static bool gen7_oa_buffer_is_empty_fop_unlocked(struct drm_i915_private *dev_pr

Quoted 7 lines
drivers/gpu/drm/i915/i915_perf.c +7 -0
+ * @stream: An i915-perf stream opened for OA metrics
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @offset: (inout): the current position for writing into @buf
+ * @type: The kind of status to report to userspace
+ *
+ * Writes a status record (such as `DRM_I915_PERF_RECORD_OA_

REPORT_LOST`)

Quoted 9 lines

drivers/gpu/drm/i915/i915_perf.c static int append_oa_status(struct

Quoted 9 lines
drivers/gpu/drm/i915/i915_perf.c +5 -0
+ * into the userspace read() buffer.
+ *
+ * The @buf @offset will only be updated on success.
+ *
+ * Returns: 0 on success, negative error code on failure.
  */
 static int append_oa_status(struct i915_perf_stream *stream,
                          char __user *buf,
@@ -336,7 +372,21 @@ static int append_oa_status(struct

i915_perf_stream *stream,

Quoted 5 lines

drivers/gpu/drm/i915/i915_perf.c static int append_oa_status(struct i915_perf_stream *stream,

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +1 -1
 }
 
 /**
- * Copies single OA report into userspace read() buffer.
+ * append_oa_sample - Copies single OA report into userspace read()

buffer.

Quoted 5 lines

drivers/gpu/drm/i915/i915_perf.c static bool gen7_oa_buffer_is_empty_fop_unlocked(struct drm_i915_private *dev_pr

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +5 -0
+ * @stream: An i915-perf stream opened for OA metrics
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @offset: (inout): the current position for writing into @buf
+ * @report: A single OA report to (optionally) include as part of the

sample

Quoted 2 lines

drivers/gpu/drm/i915/i915_perf.c static int append_oa_status(struct · line 382

Quoted 2 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
+ *
+ * The contents of a sample are configured through

DRM_I915_PERF_PROP_SAMPLE_*

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static int append_oa_status(struct · line 383

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * properties when opening a stream, tracked as

stream->sample_flags. This

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static int append_oa_status(struct · line 384

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * function copies the requested components of a single sample to the

given

Quoted 9 lines

drivers/gpu/drm/i915/i915_perf.c static int append_oa_sample(struct i915_perf_stream

Quoted 9 lines
drivers/gpu/drm/i915/i915_perf.c +5 -0
+ * read() @buf.
+ *
+ * The @buf @offset will only be updated on success.
+ *
+ * Returns: 0 on success, negative error code on failure.
  */
 static int append_oa_sample(struct i915_perf_stream *stream,
                          char __user *buf,
@@ -380,8 +430,6 @@ static int append_oa_sample(struct i915_perf_stream

*stream,

Quoted 9 lines

drivers/gpu/drm/i915/i915_perf.c static int append_oa_sample(struct i915_perf_stream

Quoted 9 lines
drivers/gpu/drm/i915/i915_perf.c +0 -2
  * @head_ptr: (inout): the current oa buffer cpu read position
  * @tail: the current oa buffer gpu write position
  *
- * Returns 0 on success, negative error code on failure.
- *
  * Notably any error condition resulting in a short read (-ENOSPC or
  * -EFAULT) will be returned even though one or more records may
  * have been successfully copied. In this case it's up to the caller
@@ -392,6 +440,8 @@ static int append_oa_sample(struct i915_perf_stream

*stream,

Quoted 9 lines

drivers/gpu/drm/i915/i915_perf.c static int gen7_append_oa_reports(struct

Quoted 9 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
  * tail, so the head chases the tail?... If you think that's mad
  * and back-to-front you're not alone, but this follows the
  * Gen PRM naming convention.
+ *
+ * Returns: 0 on success, negative error code on failure.
  */
 static int gen7_append_oa_reports(struct i915_perf_stream *stream,
                                char __user *buf,
@@ -496,6 +546,22 @@ static int gen7_append_oa_reports(struct

i915_perf_stream *stream,

Quoted 11 lines

drivers/gpu/drm/i915/i915_perf.c static int gen7_append_oa_reports(struct i915_perf_stream *stream,

Quoted 11 lines
drivers/gpu/drm/i915/i915_perf.c +8 -0
      return ret;
 }
 
+/**
+ * gen7_oa_read - copy status records then buffered OA reports
+ * @stream: An i915-perf stream opened for OA metrics
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @offset: (inout): the current position for writing into @buf
+ *
+ * Checks Gen 7 specific OA unit status registers and if necessary

appends

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static int gen7_append_oa_reports(struct · line 557

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * corresponding status records for userspace (such as for a buffer

full

Quoted 3 lines

drivers/gpu/drm/i915/i915_perf.c static int gen7_append_oa_reports(struct i915_perf_stream *stream,

Quoted 3 lines
drivers/gpu/drm/i915/i915_perf.c +3 -0
+ * condition) and then initiate appending any buffered OA reports.
+ *
+ * Updates @offset according to the number of bytes successfully

copied into

Quoted 8 lines

drivers/gpu/drm/i915/i915_perf.c static int gen7_oa_read(struct i915_perf_stream

Quoted 8 lines
drivers/gpu/drm/i915/i915_perf.c +4 -0
+ * the userspace buffer.
+ *
+ * Returns: zero on success or a negative error code
+ */
 static int gen7_oa_read(struct i915_perf_stream *stream,
                      char __user *buf,
                      size_t count,
@@ -597,6 +663,20 @@ static int gen7_oa_read(struct i915_perf_stream

*stream,

Quoted 8 lines

drivers/gpu/drm/i915/i915_perf.c static int gen7_oa_read(struct i915_perf_stream *stream,

Quoted 8 lines
drivers/gpu/drm/i915/i915_perf.c +5 -0
      return ret;
 }
 
+/**
+ * i915_oa_wait_unlocked - handles blocking IO until OA data available
+ * @stream: An i915-perf stream opened for OA metrics
+ *
+ * Called when userspace tries to read() from a blocking stream FD

opened

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static int gen7_oa_read(struct i915_perf_stream · line 671

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * for OA metrics. It waits until the hrtimer callback finds a

non-empty

Quoted 4 lines
Quoted 4 lines
drivers/gpu/drm/i915/i915_perf.c +4 -0
+ * OA buffer and wakes us.
+ *
+ * Note: it's acceptable to have this return with some false positives
+ * since any subsequent read handling will return EAGAIN if there isn't
Quoted 8 lines

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_wait_unlocked(struct

Quoted 8 lines
drivers/gpu/drm/i915/i915_perf.c +4 -0
+ * really data ready for userspace yet.
+ *
+ * Returns: zero on success or a negative error code
+ */
 static int i915_oa_wait_unlocked(struct i915_perf_stream *stream)
 {
      struct drm_i915_private *dev_priv = stream->dev_priv;
@@ -615,6 +695,16 @@ static int i915_oa_wait_unlocked(struct

i915_perf_stream *stream)

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_wait_unlocked(struct · line 695

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +0 -0
                                      !dev_priv->perf.oa.ops.oa_

buffer_is_empty(dev_priv));

Quoted 9 lines

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_wait_unlocked(struct i915_perf_stream *stream)

Quoted 9 lines
drivers/gpu/drm/i915/i915_perf.c +7 -0
 }
 
+/**
+ * i915_oa_poll_wait - call poll_wait() for an OA stream poll()
+ * @stream: An i915-perf stream opened for OA metrics
+ * @file: An i915 perf stream file
+ * @wait: poll() state table
+ *
+ * For handling userspace polling on an i915 perf stream opened for OA

metrics,

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_wait_unlocked(struct · line 705

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * this starts a poll_wait with the wait queue that our hrtimer

callback wakes

Quoted 6 lines

drivers/gpu/drm/i915/i915_perf.c static void i915_oa_poll_wait(struct

Quoted 6 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
+ * when it sees data ready to read in the circular OA buffer.
+ */
 static void i915_oa_poll_wait(struct i915_perf_stream *stream,
                            struct file *file,
                            poll_table *wait)
@@ -624,6 +714,18 @@ static void i915_oa_poll_wait(struct

i915_perf_stream *stream,

Quoted 11 lines

drivers/gpu/drm/i915/i915_perf.c static void i915_oa_poll_wait(struct i915_perf_stream *stream,

Quoted 11 lines
drivers/gpu/drm/i915/i915_perf.c +8 -0
      poll_wait(file, &dev_priv->perf.oa.poll_wq, wait);
 }
 
+/**
+ * i915_oa_read - just calls through to ``&i915_oa_ops->read``
+ * @stream: An i915-perf stream opened for OA metrics
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @offset: (inout): the current position for writing into @buf
+ *
+ * Updates @offset according to the number of bytes successfully

copied into

Quoted 8 lines

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_read(struct i915_perf_stream

Quoted 8 lines
drivers/gpu/drm/i915/i915_perf.c +4 -0
+ * the userspace buffer.
+ *
+ * Returns: zero on success or a negative error code
+ */
 static int i915_oa_read(struct i915_perf_stream *stream,
                      char __user *buf,
                      size_t count,
@@ -634,9 +736,15 @@ static int i915_oa_read(struct i915_perf_stream

*stream,

Quoted 4 lines

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_read(struct i915_perf_stream *stream,

Quoted 4 lines
drivers/gpu/drm/i915/i915_perf.c +0 -1
      return dev_priv->perf.oa.ops.read(stream, buf, count, offset);
 }
 
-/* Determine the render context hw id, and ensure it remains fixed for

the

Quoted 5 lines

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_read(struct i915_perf_stream *stream,

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +5 -0
+/**
+ * oa_get_render_ctx_id - determine and hold ctx hw id
+ * @stream: An i915-perf stream opened for OA metrics
+ *
+ * Determine the render context hw id, and ensure it remains fixed for

the

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_read(struct i915_perf_stream · line 744

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +0 -0
  * lifetime of the stream. This ensures that we don't have to worry

about

Quoted 7 lines

drivers/gpu/drm/i915/i915_perf.c static int oa_get_render_ctx_id(struct

Quoted 7 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
  * updating the context ID in OACONTROL on the fly.
+ *
+ * Returns: zero on success or a negative error code
  */
 static int oa_get_render_ctx_id(struct i915_perf_stream *stream)
 {
@@ -673,6 +781,13 @@ static int oa_get_render_ctx_id(struct

i915_perf_stream *stream)

Quoted 5 lines

drivers/gpu/drm/i915/i915_perf.c static int gen7_append_oa_reports(struct i915_perf_stream *stream,

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
      return ret;
 }
 
+/**
+ * oa_put_render_ctx_id - counterpart to oa_get_render_ctx_id releases

hold

Quoted 3 lines

drivers/gpu/drm/i915/i915_perf.c static bool gen7_oa_buffer_is_empty_fop_unlocked(struct drm_i915_private *dev_pr

Quoted 3 lines
drivers/gpu/drm/i915/i915_perf.c +3 -0
+ * @stream: An i915-perf stream opened for OA metrics
+ *
+ * In case anything needed doing to ensure the context HW ID would

remain valid

Quoted 6 lines

drivers/gpu/drm/i915/i915_perf.c static void gen7_oa_enable(struct

Quoted 6 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
+ * for the lifetime of the stream, then that can be undone here.
+ */
 static void oa_put_render_ctx_id(struct i915_perf_stream *stream)
 {
      struct drm_i915_private *dev_priv = stream->dev_priv;
@@ -945,6 +1060,15 @@ static void gen7_oa_enable(struct

drm_i915_private *dev_priv)

Quoted 8 lines

drivers/gpu/drm/i915/i915_perf.c static void gen7_oa_enable(struct drm_i915_private *dev_priv)

Quoted 8 lines
drivers/gpu/drm/i915/i915_perf.c +5 -0
      spin_unlock_irqrestore(&dev_priv->perf.hook_lock, flags);
 }
 
+/**
+ * i915_oa_stream_enable - handle I915_PERF_IOCTL_ENABLE for OA stream
+ * @stream: An i915 perf stream opened for OA metrics
+ *
+ * [Re]enables hardware periodic sampling according to the period

configured

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static void gen7_oa_enable(struct · line 1068

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * when opening the stream. This also starts a hrtimer that will

periodically

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static void gen7_oa_enable(struct · line 1069

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * check for data in the circular OA buffer for notifying userspace

(e.g.

Quoted 6 lines

drivers/gpu/drm/i915/i915_perf.c static void gen7_oa_disable(struct

Quoted 6 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
+ * during a read() or poll()).
+ */
 static void i915_oa_stream_enable(struct i915_perf_stream *stream)
 {
      struct drm_i915_private *dev_priv = stream->dev_priv;
@@ -962,6 +1086,14 @@ static void gen7_oa_disable(struct

drm_i915_private *dev_priv)

Quoted 5 lines

drivers/gpu/drm/i915/i915_perf.c static void gen7_oa_disable(struct drm_i915_private *dev_priv)

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
      I915_WRITE(GEN7_OACONTROL, 0);
 }
 
+/**
+ * i915_oa_stream_disable - handle I915_PERF_IOCTL_DISABLE for OA

stream

Quoted 4 lines

drivers/gpu/drm/i915/i915_perf.c static void gen7_oa_disable(struct drm_i915_private *dev_priv)

Quoted 4 lines
drivers/gpu/drm/i915/i915_perf.c +4 -0
+ * @stream: An i915 perf stream opened for OA metrics
+ *
+ * Stops the OA unit from periodically writing counter reports into the
+ * circular OA buffer. This also stops the hrtimer that periodically

checks for

Quoted 6 lines

drivers/gpu/drm/i915/i915_perf.c static const struct i915_perf_stream_ops

Quoted 6 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
+ * data in the circular OA buffer, for notifying userspace.
+ */
 static void i915_oa_stream_disable(struct i915_perf_stream *stream)
 {
      struct drm_i915_private *dev_priv = stream->dev_priv;
@@ -987,6 +1119,24 @@ static const struct i915_perf_stream_ops

i915_oa_stream_ops = {

Quoted 8 lines

drivers/gpu/drm/i915/i915_perf.c static const struct i915_perf_stream_ops i915_oa_stream_ops = {

Quoted 8 lines
drivers/gpu/drm/i915/i915_perf.c +5 -0
      .read = i915_oa_read,
 };
 
+/**
+ * i915_oa_stream_init - validate combined props for OA stream and init
+ * @stream: An i915 perf stream
+ * @param: The open parameters passed to 'DRM_I915_PERF_OPEN`
+ * @props: The property state that configures stream (individually

validated)

Quoted 2 lines

drivers/gpu/drm/i915/i915_perf.c static const struct i915_perf_stream_ops · line 1128

Quoted 2 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
+ *
+ * While read_properties_unlocked() validates properties in isolation

it

Quoted 3 lines

drivers/gpu/drm/i915/i915_perf.c static const struct i915_perf_stream_ops i915_oa_stream_ops = {

Quoted 3 lines
drivers/gpu/drm/i915/i915_perf.c +3 -0
+ * doesn't ensure that the combination necessarily makes sense.
+ *
+ * At this point it has been determined that userspace wants a stream

of

Quoted 5 lines

drivers/gpu/drm/i915/i915_perf.c static const struct i915_perf_stream_ops i915_oa_stream_ops = {

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +5 -0
+ * OA metrics, but still we need to further validate the combined
+ * properties are OK.
+ *
+ * If the configuration makes sense then we can allocate memory for
+ * a circular OA buffer and apply the requested metric set

configuration.

Quoted 7 lines

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_stream_init(struct

Quoted 7 lines
drivers/gpu/drm/i915/i915_perf.c +3 -0
+ *
+ * Returns: zero on success or a negative error code.
+ */
 static int i915_oa_stream_init(struct i915_perf_stream *stream,
                             struct drm_i915_perf_open_param *param,
                             struct perf_open_properties *props)
@@ -1110,6 +1260,31 @@ static int i915_oa_stream_init(struct

i915_perf_stream *stream,

Quoted 5 lines

drivers/gpu/drm/i915/i915_perf.c static int gen7_append_oa_reports(struct i915_perf_stream *stream,

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
      return ret;
 }
 
+/**
+ * i915_perf_read_locked - wrap stream->ops->read with error

notmalisation

Quoted 7 lines

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_stream_init(struct i915_perf_stream *stream,

Quoted 7 lines
drivers/gpu/drm/i915/i915_perf.c +7 -0
+ * @stream: An i915 perf stream
+ * @file: An i915 perf stream file
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @ppos: (inout) file seek position (unused)
+ *
+ * Besides wrapping stream->ops->read() this provides a common place

to ensure

Quoted 4 lines

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_stream_init(struct i915_perf_stream *stream,

Quoted 4 lines
drivers/gpu/drm/i915/i915_perf.c +4 -0
+ * that if we've successfully copied any data then reporting that takes
+ * precedence over any internal error status, so the data isn't lost.
+ *
+ * For example ret will be -ENOSPC whenever there is more buffered

data than

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_stream_init(struct · line 1276

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * can be copied to userspace, but that's only interesting if we

weren't able

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_stream_init(struct · line 1277

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * to copy some data because it implies the userspace buffer is too

small to

Quoted 3 lines

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_stream_init(struct i915_perf_stream *stream,

Quoted 3 lines
drivers/gpu/drm/i915/i915_perf.c +3 -0
+ * receive a single record (and we never split records).
+ *
+ * Another case with ret == -EFAULT is more of a grey area since it

would seem

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_stream_init(struct · line 1281

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * like bad form for userspace to ask us to overrun its buffer, but

the user

Quoted 5 lines

drivers/gpu/drm/i915/i915_perf.c static int i915_oa_stream_init(struct i915_perf_stream *stream,

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +5 -0
+ * knows best:
+ *
+ *   http://yarchive.net/comp/linux/partial_reads_writes.html
+ *
+ * Returns: The number of bytes copied or a negative error code on

failure.

Quoted 5 lines

drivers/gpu/drm/i915/i915_perf.c static ssize_t i915_perf_read_locked(struct

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ */
 static ssize_t i915_perf_read_locked(struct i915_perf_stream *stream,
                                   struct file *file,
                                   char __user *buf,
@@ -1125,25 +1300,27 @@ static ssize_t i915_perf_read_locked(struct

i915_perf_stream *stream,

Quoted 22 lines
Quoted 22 lines
drivers/gpu/drm/i915/i915_perf.c +0 -16
      size_t offset = 0;
      int ret = stream->ops->read(stream, buf, count, &offset);
 
-     /* If we've successfully copied any data then reporting that
-      * takes precedence over any internal error status, so the
-      * data isn't lost.
-      *
-      * For example ret will be -ENOSPC whenever there is more
-      * buffered data than can be copied to userspace, but that's
-      * only interesting if we weren't able to copy some data
-      * because it implies the userspace buffer is too small to
-      * receive a single record (and we never split records).
-      *
-      * Another case with ret == -EFAULT is more of a grey area
-      * since it would seem like bad form for userspace to ask us
-      * to overrun its buffer, but the user knows best:
-      *
-      *   http://yarchive.net/comp/linux/partial_reads_writes.html
-      */
      return offset ?: (ret ?: -EAGAIN);
 }
 
Quoted 8 lines

drivers/gpu/drm/i915/i915_perf.c static ssize_t i915_perf_read_locked(struct i915_perf_stream *stream,

Quoted 8 lines
drivers/gpu/drm/i915/i915_perf.c +8 -0
+/**
+ * i915_perf_read - handles read() FOP for i915 perf stream FDs
+ * @file: An i915 perf stream file
+ * @buf: destination buffer given by userspace
+ * @count: the number of bytes userspace wants to read
+ * @ppos: (inout) file seek position (unused)
+ *
+ * The entry point for handling a read() on a stream file descriptor

from

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static ssize_t i915_perf_read_locked(struct · line 1314

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * userspace. Most of the work is left to the i915_perf_read_locked()

and

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static ssize_t i915_perf_read_locked(struct · line 1315

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * stream->op->read() but to save having stream implementations (of

which

Quoted 7 lines

drivers/gpu/drm/i915/i915_perf.c static ssize_t i915_perf_read_locked(struct i915_perf_stream *stream,

Quoted 7 lines
drivers/gpu/drm/i915/i915_perf.c +7 -0
+ * we might have multiple later) we handle blocking read here.
+ *
+ * We can also consistently treat trying to read from a disable stream
+ * as an IO error so implementations can assume the stream is enabled
+ * while reading.
+ *
+ * Returns: The number of bytes copied or a negative error code on

failure.

Quoted 5 lines

drivers/gpu/drm/i915/i915_perf.c i915_perf_open_ioctl_locked(struct

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ */
 static ssize_t i915_perf_read(struct file *file,
                            char __user *buf,
                            size_t count,
@@ -1458,12 +1635,20 @@ i915_perf_open_ioctl_locked(struct

drm_i915_private *dev_priv,

Quoted 7 lines

drivers/gpu/drm/i915/i915_perf.c i915_perf_open_ioctl_locked(struct drm_i915_private *dev_priv,

Quoted 7 lines
drivers/gpu/drm/i915/i915_perf.c +2 -2
      return ret;
 }
 
-/* Note we copy the properties from userspace outside of the i915 perf
- * mutex to avoid an awkward lockdep with mmap_sem.
+/**
+ * read_properties_unlocked - validate + copy userspace stream open

properties

Quoted 4 lines

drivers/gpu/drm/i915/i915_perf.c i915_perf_open_ioctl_locked(struct drm_i915_private *dev_priv,

Quoted 4 lines
drivers/gpu/drm/i915/i915_perf.c +4 -0
+ * @dev_priv: i915 device instance
+ * @uprops: The array of u64 key value pairs given by userspace
+ * @n_props: The number of key value pairs expected in @uprops
+ * @props: The stream configuration built up while validating

properties

Quoted 6 lines

drivers/gpu/drm/i915/i915_perf.c i915_perf_open_ioctl_locked(struct drm_i915_private *dev_priv,

Quoted 6 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
  *
  * Note this function only validates properties in isolation it doesn't
  * validate that the combination of properties makes sense or that all
  * properties necessary for a particular kind of stream have been set.
+ *
+ * Note that there currently aren't any ordering requirements for

properties so

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c i915_perf_open_ioctl_locked(struct · line 1650

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * we shouldn't validate or assume anything about ordering here. This

doesn't

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c i915_perf_open_ioctl_locked(struct · line 1651

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * rule out defining new properties with ordering requirements in the

future.

Quoted 4 lines

drivers/gpu/drm/i915/i915_perf.c static int read_properties_unlocked(struct

Quoted 4 lines
drivers/gpu/drm/i915/i915_perf.c +0 -0
  */
 static int read_properties_unlocked(struct drm_i915_private *dev_priv,
                                  u64 __user *uprops,
@@ -1585,6 +1770,26 @@ static int read_properties_unlocked(struct

drm_i915_private *dev_priv,

Quoted 10 lines

drivers/gpu/drm/i915/i915_perf.c static int read_properties_unlocked(struct drm_i915_private *dev_priv,

Quoted 10 lines
drivers/gpu/drm/i915/i915_perf.c +7 -0
      return 0;
 }
 
+/**
+ * i915_perf_open_ioctl - DRM ioctl() for userspace to open a stream FD
+ * @dev: drm device
+ * @data: ioctl data copied from userspace (unvalidated)
+ * @file: drm file
+ *
+ * Validates the stream open parameters given by userspace including

flags

Quoted 4 lines

drivers/gpu/drm/i915/i915_perf.c static int read_properties_unlocked(struct drm_i915_private *dev_priv,

Quoted 4 lines
drivers/gpu/drm/i915/i915_perf.c +4 -0
+ * and an array of u64 key, value pair properties.
+ *
+ * Very little is assumed up front about the nature of the stream being
+ * opened (for instance we don't assume it's for periodic OA unit

metrics). An

Quoted 1 line

drivers/gpu/drm/i915/i915_perf.c static int read_properties_unlocked(struct · line 1784

Quoted 1 line
drivers/gpu/drm/i915/i915_perf.c +1 -0
+ * i915-perf stream is expected to be a suitable interface for other

forms of

Quoted 4 lines
Quoted 4 lines
drivers/gpu/drm/i915/i915_perf.c +4 -0
+ * buffered data written by the GPU besides periodic OA metrics.
+ *
+ * Note we copy the properties from userspace outside of the i915 perf
+ * mutex to avoid an awkward lockdep with mmap_sem.
Quoted 8 lines

drivers/gpu/drm/i915/i915_perf.c int i915_perf_open_ioctl(struct drm_device *dev,

Quoted 8 lines
drivers/gpu/drm/i915/i915_perf.c +4 -0
+ *
+ * Return: A newly opened i915 Perf stream file descriptor or negative
+ * error code on failure.
+ */
 int i915_perf_open_ioctl(struct drm_device *dev, void *data,
                       struct drm_file *file)
 {
@@ -1621,6 +1826,14 @@ int i915_perf_open_ioctl(struct drm_device *dev,

void *data,

Quoted 15 lines

drivers/gpu/drm/i915/i915_perf.c void i915_perf_register(struct drm_i915_private

Quoted 15 lines
drivers/gpu/drm/i915/i915_perf.c +8 -0
      return ret;
 }
 
+/**
+ * i915_perf_register - exposes i915-perf to userspace
+ * @dev_priv: i915 device instance
+ *
+ * In particular OA metric sets are advertised under a sysfs metrics/
+ * directory allowing userspace to enumerate valid IDs that can be
+ * used to open an i915-perf stream.
+ */
 void i915_perf_register(struct drm_i915_private *dev_priv)
 {
      if (!IS_HASWELL(dev_priv))
@@ -1650,6 +1863,15 @@ void i915_perf_register(struct drm_i915_private

*dev_priv)

Quoted 19 lines
Quoted 19 lines
drivers/gpu/drm/i915/i915_perf.c +9 -0
      mutex_unlock(&dev_priv->perf.lock);
 }
 
+/**
+ * i915_perf_register - hide i915-perf from userspace
+ * @dev_priv: i915 device instance
+ *
+ * i915-perf state cleanup is split up into an 'unregister' and
+ * 'deinit' phase where the interface is first hidden from
+ * userspace by i915_perf_unregister() before cleaning up
+ * remaining state in i915_perf_fini().
+ */
 void i915_perf_unregister(struct drm_i915_private *dev_priv)
 {
      if (!IS_HASWELL(dev_priv))
@@ -1706,6 +1928,15 @@ static struct ctl_table dev_root[] = {
      {}
 };
 
Quoted 5 lines

drivers/gpu/drm/i915/i915_perf.c static struct ctl_table dev_root[] = {

Quoted 5 lines
drivers/gpu/drm/i915/i915_perf.c +5 -0
+/**
+ * i915_perf_init - initialize i915-perf state on module load
+ * @dev_priv: i915 device instance
+ *
+ * Initializes state i915-perf state without exposing anything to

userspace.

Quoted 2 lines

drivers/gpu/drm/i915/i915_perf.c static struct ctl_table dev_root[] = { · line 1937

Quoted 2 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
+ *
+ * Note: i915-perf initialization is split into an 'init' and

'register'

Quoted 6 lines

drivers/gpu/drm/i915/i915_perf.c void i915_perf_init(struct drm_i915_private

Quoted 6 lines
drivers/gpu/drm/i915/i915_perf.c +2 -0
+ * phase with the i915_perf_register() exposing state to userspace.
+ */
 void i915_perf_init(struct drm_i915_private *dev_priv)
 {
      if (!IS_HASWELL(dev_priv))
@@ -1741,6 +1972,10 @@ void i915_perf_init(struct drm_i915_private

*dev_priv)

Quoted 14 lines
Quoted 11 lines
drivers/gpu/drm/i915/i915_perf.c +4 -1
      dev_priv->perf.initialized = true;
 }
 
+/**
+ * i915_perf_fini - Counter part to i915_perf_init()
+ * @dev_priv: i915 device instance
+ */
 void i915_perf_fini(struct drm_i915_private *dev_priv)
 {
      if (!dev_priv->perf.initialized)
--
Quoted 2 lines

2.10.2

Quoted 4 lines

--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx