[Intel-gfx] [PATCH 03/16] drm: document driver interface for CRC capturing

[Daniel Vetter]

This was missed in Tomeu's patch. Also remove the kerneldoc for the
internal function, we don't document that in general.

While at it word-smith the docs slightly for more clarity.

Cc: Tomeu Vizoso <tomeu.vizoso at collabora.com>
Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
---
 Documentation/gpu/drm-uapi.rst    |  3 +++
 drivers/gpu/drm/drm_debugfs_crc.c | 17 ++++++-----------
 include/drm/drm_crtc.h            |  5 ++++-
 3 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
index 352652810dab..369e8ca12b8e 100644
--- a/Documentation/gpu/drm-uapi.rst
+++ b/Documentation/gpu/drm-uapi.rst
@@ -207,6 +207,9 @@ Display CRC Support
 .. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c
    :doc: CRC ABI
 
+.. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c
+   :export:
+
 VBlank event handling
 =====================
 
diff --git a/drivers/gpu/drm/drm_debugfs_crc.c b/drivers/gpu/drm/drm_debugfs_crc.c
index 96891c4a6e23..1722d8f21449 100644
--- a/drivers/gpu/drm/drm_debugfs_crc.c
+++ b/drivers/gpu/drm/drm_debugfs_crc.c
@@ -36,7 +36,7 @@
  * DOC: CRC ABI
  *
  * DRM device drivers can provide to userspace CRC information of each frame as
- * it reached a given hardware component (a "source").
+ * it reached a given hardware component (a CRC sampling "source").
  *
  * Userspace can control generation of CRCs in a given CRTC by writing to the
  * file dri/0/crtc-N/crc/control in debugfs, with N being the index of the CRTC.
@@ -57,6 +57,11 @@
  * rely on being able to generate matching CRC values for the frame contents that
  * it submits. In this general case, the maximum userspace can do is to compare
  * the reported CRCs of frames that should have the same contents.
+ *
+ * On the driver side the implementation effort is minimal, drivers only need to
+ * implement &drm_crtc_funcs.set_crc_source. The debugfs files are automatically
+ * set up if that vfunc is set. CRC samples need to be captured in the driver by
+ * calling drm_crtc_add_crc_entry().
  */
 
 static int crc_control_show(struct seq_file *m, void *data)
@@ -280,16 +285,6 @@ static const struct file_operations drm_crtc_crc_data_fops = {
 	.release = crtc_crc_release,
 };
 
-/**
- * drm_debugfs_crtc_crc_add - Add files to debugfs for capture of frame CRCs
- * @crtc: CRTC to whom the frames will belong
- *
- * Adds files to debugfs directory that allows userspace to control the
- * generation of frame CRCs and to read them.
- *
- * Returns:
- * Zero on success, error code on failure.
- */
 int drm_debugfs_crtc_crc_add(struct drm_crtc *crtc)
 {
 	struct dentry *crc_ent, *ent;
diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
index 6ef59da3fd8e..24dcb121bad4 100644
--- a/include/drm/drm_crtc.h
+++ b/include/drm/drm_crtc.h
@@ -590,9 +590,12 @@ struct drm_crtc_funcs {
 	 * When CRC generation is enabled, the driver should call
 	 * drm_crtc_add_crc_entry() at each frame, providing any information
 	 * that characterizes the frame contents in the crcN arguments, as
-	 * provided from the configured source. Drivers must accept a "auto"
+	 * provided from the configured source. Drivers must accept an "auto"
 	 * source name that will select a default source for this CRTC.
 	 *
+	 * Note that "auto" can depend upon the current modeset configuration,
+	 * e.g. it could pick an encoder or output specific CRC sampling point.
+	 *
 	 * This callback is optional if the driver does not support any CRC
 	 * generation functionality.
 	 *
-- 
2.11.0