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

[Tomeu Vizoso]

Thanks for doing this.

Reviewed-by: Tomeu Vizoso <tomeu.vizoso at collabora.com>

On 22 March 2017 at 09:36, Daniel Vetter <daniel.vetter at ffwll.ch> wrote:
> 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
>
> _______________________________________________
> Intel-gfx mailing list
> Intel-gfx at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/intel-gfx